OpenAPI data

API users

Nozomi Networks recommends that you create 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 you use cURL, if you have a username and password for your OpenAPI user, you would use the header below along with your query:

-H "Authorization: Basic <AUTH_TOKEN>"

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

The language and method of implementation (e.g. cURL vs. Java) dictates how basic authentication is performed.

Querying Nozomi Networks sensors

Data retrieved from the OpenAPI is done by calling the OpenAPI hypertext transfer protocol (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 this documentation.

Simple query example

This query retrieves the nodes in the Nozomi Networks sensor:

curl -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

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

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

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 this documentation.

Import example using cURL with a CSV file

This is an example comma-separated value (CSV) file, assets.csv:

             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 command below will upload these assets into the Guardian or CMC:

curl -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

This is an example JavaScript Object Notation (JSON) file, assets.json:

{
    "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, you might have to submit the file using -d as in the example below.

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

curl -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

Downloading traces

You can also download traces that are related to an alert via the application programming interface (API). To do this, you need the alert identifier (ID). The command below downloads a trace related to an alert ID <YourAlertID> to the file specified by <YourTraceFile>:

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