API Guide

OneDDI 3.7.1

Introduction
Authentication
Examples
API Specification

Introduction

The VendorN Ltd OneDDI product (OneDDI) is a centralised software application which hosts several modules. The Vision module provides long-term access to DNS activity history. The ReDNS module allows service owners to control their DNS records. The IPMeye module provides centralised remote power management and console access using the IPMI protocol. The SerialEyes module provides centralised remote physical serial port access via non-dedicated hardware.

The OneDDI API currently provides access to DNS activity history search features provided by the Vision module, namely:

The ability to search for devices, queries, records, the queries a device has made or the devices which made a specific query
The ability to export to CSV devices, queries, records, the queries a device has made or the devices which made a specific query

Authentication

Only authenticated users can access the OneDDI API. Users authenticate with the API by passing an Authorization HTTP header with each request. Users pass their credentials using the Basic authentication method, e.g. the username apiuser and password password are joined using a colon as apiuser:password, base64 encoded and then placed in the header like so:

Authorization: Basic YXBpdXNlcjpwYXNzd29yZA==

All OneDDI users can query the OneDDI API, including Active Directory based users. For Active Directory users, append the relvevant Active Directory domain configured in OneDDI to the username like when accessing the OneDDI user interface, i.e. apiuser:password becomes apiuser@vendorn.com:password before it is base64 encoded.

A users’ assigned groups control what they can access. A HTTP 403 status code identifies if a user has not been assigned a permission to access a resource.

Examples

Find history for a query name

In the following example query history is obtained for the FQDN global-view.vendorn.com and the jq command is used to obtain the queries ID:

curl -s -k -H "Authorization: Basic YXBpdXNlcjpwYXNzd29yZA==" -X POST "https://127.0.0.1:8000/api/v1/dns-activity-item-searches/query" -d '{
    "query": {
        "searchFilter": {
            "filterType":"query-name-equals",
            "value":"global-view.vendorn.com"
        }
    },
    "limit": 1,
    "sortBy":"query-name"
}' | jq -r .items[0].id
cS1tb2MubnJvZG5ldi53ZWl2LWxhYm9sZw==

The history database contained an entry and returned the ID cS1tb2MubnJvZG5ldi53ZWl2LWxhYm9sZw==. This will be used in the next example.

Find devices which resolved a specific query name

In this example the ID cS1tb2MubnJvZG5ldi53ZWl2LWxhYm9sZw== obtained in the previous example is used to identify the devices which resolved the query name and the jq command used to show the device IPs:

curl -s -k -H "Authorization: Basic YXBpdXNlcjpwYXNzd29yZA==" -X POST "https://127.0.0.1:8000/api/v1/dns-activity-item-searches/query-device" -d '{
    "query": {
        "queryId": "cS1tb2MubnJvZG5ldi53ZWl2LWxhYm9sZw==",
        "searchFilter": {
            "filterType":"device-ip-matches-network",
            "value":""
        }
    },
    "limit": 25,
    "sortBy":"device-ip"
}' | jq -r .items[].meta.deviceIp
192.168.68.110
192.168.68.164
192.168.68.167

Export devices which resolved a specific query name to CSV

In this example the ID cS1tb2MubnJvZG5ldi53ZWl2LWxhYm9sZw== used in the previous example is used to identify the devices which resolved the query name and the results exported to CSV:

curl -s -k -H "Authorization: Basic YXBpdXNlcjpwYXNzd29yZA==" -X GET 'https://127.0.0.1:8000/csv/v1/dns-activity-item-searches/query-device?query=%7B%22queryId%22%3A%22cS1tb2MubnJvZG5ldi53ZWl2LWxhYm9sZw%3D%3D%22%2C%22searchFilter%22%3A%7B%22filterType%22%3A%22device-ip-matches-network%22%2C%22value%22%3A%22%22%7D%7D'
Network view,Device group,Device IP,Query name,Query types,Response codes,DNS servers,First seen,Last seen,Seen count,Last 24 hours
Internal,Smart Hub,192.168.68.110,global-view.vendorn.com,HTTPS|2024-02-14T19:53:17Z|2024-02-19T22:23:16Z|5;A|2024-02-14T19:53:17Z|2024-02-19T22:23:16Z|5,NOERROR|2024-02-14T19:53:17Z|2024-02-19T22:23:16Z|10,bdds-uk-long-1.internal.vendorn.com|2024-02-14T19:53:17Z|2024-02-19T22:23:16Z|10|0,2024-02-14T19:53:17Z,2024-02-19T22:23:16Z,10,0
Internal,Critical Device,192.168.68.164,global-view.vendorn.com,A|2024-01-25T12:36:27Z|2024-02-25T11:24:49Z|74;HTTPS|2024-01-25T12:36:27Z|2024-02-25T11:24:49Z|38;AAAA|2024-02-13T20:51:44Z|2024-02-14T11:28:44Z|2,NOERROR|2024-01-25T12:36:27Z|2024-02-25T11:24:49Z|114,bdds-uk-long-1.internal.vendorn.com|2024-01-25T12:36:27Z|2024-02-25T11:24:49Z|110|2;windows2012r2|2024-02-13T20:51:44Z|2024-02-14T11:28:44Z|4|0,2024-01-25T12:36:27Z,2024-02-25T11:24:49Z,114,2
Internal,Default (Live),192.168.68.167,global-view.vendorn.com,A|2024-02-13T18:38:28Z|2024-02-13T21:13:44Z|2,NOERROR|2024-02-13T18:38:28Z|2024-02-13T21:13:44Z|2,bdds-uk-long-1.internal.vendorn.com|2024-02-13T18:38:28Z|2024-02-13T21:13:44Z|2|0,2024-02-13T18:38:28Z,2024-02-13T21:13:44Z,2,0

Note how the the query part of the request content body provided in previous examples was serialised to a JSON string, URI encoded, and then passed in a query parameter.

Contents