OpenAPI data

API users

Nozomi Networks recommends the practice of creating a user specifically for the purpose of OpenAPI access. This provides a straightforward demarcation of responsibilities for auditing and tracing.

Best Practice: Create a user specifically to access OpenAPI.

Authentication

Each call to an OpenAPI method requires authentication. OpenAPI currently supports basic authentication. For example, when using CURL, if you have a username and password for your OpenAPI user, you would use the following header along with your query:

-H "Authorization: Basic <AUTH_TOKEN>"

Where <AUTH_TOKEN> is the base64 encoding of Username:Password.

Note that the language and method of implementation (e.g. CURL vs. Java) dictates how basic authentication is performed.

Note:

When you query OpenAPI for data, the -k –user Username:Password option may be used for basic authentication.

Querying Nozomi Networks sensors

Data retrieved from the OpenAPI is done by calling the OpenAPI HTTP interface on either a Guardian or Central Management Console (CMC) sensor.

The query endpoint is powerful and allows the integrator to manipulate data through the use of queries. A full list of the available query data sources, commands, and functions is available in the N2OS User Manual.

Simple query example

This query retrieves the nodes in the Nozomi Networks sensor:

curl -k -H “Authorization: Basic <AUTH_TOKEN>” https://<YourHost>/api/open/query/do?query=nodes

If there are two nodes; the results will be similar to this:

{
    "header": [
        All of the headers…
    ],
    "result": [
        { First Node data },
        { Second Node data }
    ],
    "total": 2
}

Complex query example

Ensure that the complex query commands are properly uniform resource identifier (URI) encoded. The following query retrieves the node count in the Nozomi Networks sensor:

curl -k -H “Authorization: Basic <AUTH_TOKEN>” https://<YourHost>/api/open/query/do?query=nodes%20%7C%20count

Note that the original query text “nodes | count” has been URI encoded to nodes%20%7C%20count.

Note that the language and method of implementation dictate how the URI encoding is accomplished.

Uploading asset information to the Nozomi Networks sensor

Data can also be uploaded into Guardian or CMC via an upload or enhanced asset information. This is referred to as importing in the OpenAPI.

The import endpoint is simple and allows the integrator to upload node data through the use of import statements. The command list is available in the N2OS User Manual.

Note:

The credentials of the user performing the OpenAPI call to import data must be in the admin group to upload information into a Nozomi Networks sensor.

Import example using CURL with a CSV file

Using a sample comma-separated value (CSV) file, assets.csv looks like this:


             ip,label,firmware_version,vendor,product_name,serial_number,mac_address
             192.168.1.60,CSV Uploaded Asset 1,1.2.2,ACME,ACME Product  1,abcdefge,00:01:02:03:04:06 
             192.168.1.61,CSV Uploaded Asset 2,1.2.2,ACME,ACME Product 2,abcdefge,00:11:12:13:14:16

The following command will upload these assets into the Guardian or CMC:

curl -k -X POST https://<YourHost>/api/open/nodes/import -H "Authorization: Basic <AUTH_TOKEN>" -F file=@<PathTo>/assets.csv

Import example using CURL with JSON file

Using a sample JavaScript Object Notation (JSON) file, assets.json looks like this:

{
    "nodes": [
        {
            "ip": "1.2.3.8",
            "label": "JSON_Uploaded_Asset_1",
            "mac_address": "00:00:00:11:11:11",
            "firmware_version": "1.2.3",
            "product_name": "ACME_PLC_2",
            "serial_number": "1-789A10-2",
            "vendor": "ACME"
        },
        {
            "ip": "1.2.3.3",
            "label": "JSON_Uploaded_Asset_2",
            "mac_address": "00:00:00:11:11:15",
            "firmware_version": "1.2.2",
            "product_name": "ACME_PLC_1",
            "serial_number": "1-789A10-6",
            "vendor": "ACME"
        }
    ]
}

Depending on your CURL implementation, the file may have to be submitted using -d as in the example below.

The following command uploads these assets into the Guardian or CMC:

curl -k -X POST https://<YourHost>/api/open/nodes/import_from_json -H
"Authorization: Basic <AUTH_TOKEN>" -H "Content-Type: application/json" -d
{"nodes":[{"ip":"1.2.3.8","label":"JSON_Uploaded_Asset_1","mac_address":"00:00:00:11:11:11",
"firmware_version":"1.2.3","product_name":"ACME_PLC_2","serial_number":"1-789A10-2",
"vendor":"ACME"},{"ip":"1.2.3.3","label":"JSON_Uploaded_Asset_2",
"mac_address":"00:00:00:11:11:15","firmware_version":"1.2.2",
"product_name":"ACME_PLC_1","serial_number":"1-789A10-6","vendor":"ACME"}]}

Import commands


Command	HTTP Parameters	Description
`import_from_csv_file`	-F file=@`</path/to/CSV_FILE>`	This command allows the import of asset information from a CSV file. The CSV file must have the appropriate column headers present in the first line.
`import_from_json`	-H 'Content-Type: application/json' -d `<JSON_DATA>`	This command allows the import of asset information from JSON data. Note that the JSON data is specified in the hypertext transfer protocol (HTTP) headers directly.

Downloading traces

Traces associated with an alert can be downloaded via the application programming interface (API) as well. You need the alert ID in order to accomplish this. The following command downloads a trace associated with an alert identifier (ID) <YourAlertID> to the file specified by <YourTraceFile>:

curl -k -X GET https://<YourHost>/api/open/alerts/<YourAlertID>/trace -H "Authorization: Basic <AUTH_TOKEN>" -H "Content-Type: application/js on" --output <YourTraceFile>