Use the NetMon API

Overview

An API is an Application Programming Interface. External programs can make requests to API endpoints (URLs) and receive responses that detail whether the requests were successful and return requested information.

The NetMon API allows for automation and programmatic interaction with the NetMon system. Users can leverage the NetMon API for configuration, as well as for retrieving PCAPs, reconstructed files, and metadata from the system for external use. In this guide, you will find practical information for interacting with the NetMon API using several common tools.

Authentication

The NetMon REST API uses HTTP basic access authentication over HTTPS. The username is the same username used to log in to the NetMon Web Management interface, and the password is that user's API key. To access the API key:

Open the NetMon Web Management interface.
On the top navigation bar, click Configuration, and the click the User tab.
The API Key panel appears at the top of the page.
Copy the API key from the field and paste it into your script or application.

If you click New Api Key, NetMon generates a new API key, invalidating the current key and disabling access from any applications that are using it.

Request Bodies

In most cases, the NetMon API expects request bodies for POST and PUT requests to contain JSON. In such cases, the parameter content type in the API route documentation is listed as application/json. For example, a PUT request to the /api/me route wants the UserDetails object as JSON. The UserDetails object has a string called firstName, a string called lastName, and a string called email. The following is an example of what the JSON body for a PUT request to /api/me might look like:

JSON Request Body Example

JS

{
   "firstName": "John",
   "lastName": "Doe",
   "email": "john.doe@company.com"
}

You might also notice other content types on some routes, such as application/x-7z-compressed for the /api/session/{sessionID}/pcap download route. You can use headers to specify content type, as shown in the examples on this page of how to make API calls.

API Calls

Here are a few examples of how to make NetMon API calls with several tools.

Postman

When using any of the following examples, be sure to replace any variables such as API key, NetMon IP address, and session ID with valid values for your deployment.

If you do not have Postman already, download and install it, and then create an account.
If you are using a default NetMon self-signed SSL certificate, open the Postman settings and set the SSL certificate verification to OFF.
From the menu to the left of the request URL, select the proper request method. The default is GET.
Type the NetMon URL into the request URL bar, https://<IP Address>/api/<route>, replacing <IP Address> with the IP address of your NetMon, reachable from the machine running Postman, and <route> with the NetMon API route to make your request against.
Click the Authorization tab for the request, and then select Basic Auth from the TYPE menu.
1. In the Username field, type the NetMon username.
2. In the Password field, type the NetMon user's API key.
(Optional) To include a body with your request:
1. If your request body includes JSON, click the Headers tab, and then add a Content-Type key where the value for that key is application/json. Then click the Body tab, select raw, and type your request JSON body in the field.
2. If your request body includes a file, click the Body tab, and then add a file key. Point to the key field, click the Text menu, and then select File. In the value field, click Select Files, and then select the file to include in your request.
If you expect to download a file, such as with the /api/session/{sessionID}/pcap route, click the Send drop-down, and then select Send and Download. Otherwise, click Send.

curl

When using any of the following examples, be sure to replace any variables such as API key, NetMon IP address, and session ID with valid values for your deployment.
This guide assumes that you are familiar with bash variables.

curl for linux

NetMon API curl for Linux - Bash Prompt Examples

BASH

netmonAPIKey=abcdef0123456789
netmonIP=1.2.3.4

# Make a GET request to systemInfo for details about the target NetMon deployment
# The --insecure flag must be included if you are using the default NetMon self-signed ssl cert,
# if you have added a trusted certificate to NetMon, the --insecure flag can be omitted in your curl calls
curl --insecure --user admin:$netmonAPIKey -X GET https://${netmonIP}/api/systemInfo -o NetMon${netmonIP}SystemInfoResponse.json

# Make a POST request to the search route for a specific session's metadata
sessionID=abcdef0123456789

curl --insecure --user admin:$netmonAPIKey --header 'Content-Type: application/json' -X POST https://${netmonIP}/api/search --data '{"query":{"term":{"Session":"'$sessionID'"}}}' > SessionMetadata-${sessionID}.json

# Make a POST request to upload a license file
curl --insecure --user admin:$netmonAPIKey --form 'file=@/path/to/LicenseFile.lic' -X POST https://${netmonIP}/api/licenses -o NetMon${netmonIP}LicenseUploadResponse.json

# Make another POST to reboot the NetMon to apply the license
curl --insecure --user admin:$netmonAPIKey -X POST https://${netmonIP}/api/system/actions/reboot -o NetMon${netmonIP}RebootResponse.json

# Make a PUT to restart the NetMon services
curl --insecure --user admin:$netmonAPIKey -X PUT https://${netmonIP}/api/services/actions/restart -o NetMon${netmonIP}RestartServicesResponse.json

# Make a GET request to download a PCAP .zip for a session (NOTE: it takes time for the PCAP .zip to be
# constructed before the download will start, please be patient)
curl --insecure --user admin:$netmonAPIKey -X GET https://${netmonIP}/api/session/${sessionID}/pcap -o NetMon${netmonIP}PCAPForSession-${sessionID}.zip

curl for windows

This guide assumes that you have downloaded the proper Windows curl version for your OS (32 or 64-bit) and have added the path to the folder containing the curl.exe executable to your Windows Path environment variable. Alternatively, you can make these calls from within the folder that contains curl.exe.

NetMon API curl for Windows - PowerShell Prompt Examples

POWERSHELL

$netmonAPIKey="abcdef0123456789"
$netmonIP="1.2.3.4"

# Make a GET request to systemInfo for details about the target NetMon deployment
# The --insecure flag must be included if you are using the default NetMon self-signed ssl cert,
# if you have added a trusted certificate to NetMon, the --insecure flag can be omitted in your curl calls
curl.exe --insecure --user admin:$netmonAPIKey -X GET https://${netmonIP}/api/systemInfo -o NetMon${netmonIP}SystemInfoResponse.json

# Make a POST request to the search route for a specific session's metadata
$sessionID="abcdef0123456789"

curl.exe --insecure --user admin:$netmonAPIKey --header "Content-Type: application/json" -X POST https://${netmonIP}/api/search --data "{\"query\":{\"term\":{\"Session\":\"$sessionID\"}}}" -o SessionMetadata-${sessionID}.json

# Make a POST request to upload a license file
curl.exe --insecure --user admin:$netmonAPIKey --form "file=@D:\path\to\LicenseFile.lic" -X POST https://${netmonIP}/api/licenses -o NetMon${netmonIP}LicenseUploadResponse.json

# Make another POST to reboot the NetMon to apply the license
curl.exe --insecure --user admin:$netmonAPIKey -X POST https://${netmonIP}/api/system/actions/reboot -o NetMon${netmonIP}RebootResponse.json

# Make a PUT to restart the NetMon services
curl.exe --insecure --user admin:$netmonAPIKey -X PUT https://${netmonIP}/api/services/actions/restart -o NetMon${netmonIP}RestartServicesResponse.json

# Make a GET request to download a PCAP .zip for a session (NOTE: it takes time for the PCAP .zip to be
# constructed before the download will start, please be patient)
curl.exe --insecure --user admin:$netmonAPIKey -X GET https://${netmonIP}/api/session/${sessionID}/pcap -o NetMon${netmonIP}PCAPForSession-${sessionID}.zip

wget

This section covers use of the CLI tool wget for linux. In most cases, curl is a better tool for interacting with the NetMon API.

When using any of the following examples, be sure to replace any variables such as API key, NetMon IP address, and session ID with valid values for your deployment.
This guide assumes that you are familiar with bash variables.
At the time of this writing, wget does not support multipart/form-data, so it cannot be used to upload files to the NetMon API.

NetMon API wget - Bash Prompt Examples

BASH

netmonAPIKey=abcdef0123456789
netmonIP=1.2.3.4
outputFilename=NetMon${netmonIP}SystemInfoResponse.json

# Make a GET request to systemInfo for details about the target NetMon deployment
# The --no-check-certificate flag must be included if you are using the default NetMon self-signed ssl cert,
# if you have added a trusted certificate to NetMon, the --no-check-certificate flag can be omitted in your wget calls
wget --no-check-certificate --auth-no-challenge --user=admin --password=$netmonAPIKey http://${netmonIP}/api/systemInfo -O NetMon${netmonIP}SystemInfoResponse.json


# Make a POST request to the search route for a specific session's metadata
sessionID=abcdef0123456789

wget --no-check-certificate --auth-no-challenge --user=admin --password=$netmonAPIKey --header="Content-Type: application/json" --post-data='{"query":{"term":{"Session":"'$sessionID'"}}}' https://${netmonIP}/api/search -O SessionMetadata-${sessionID}.json


# Make a POST to reboot the NetMon to apply the license
wget --no-check-certificate --auth-no-challenge --user=admin --password=$netmonAPIKey --method=POST  https://${netmonIP}/api/system/actions/reboot -O NetMon${netmonIP}RebootResponse.json

# Make a PUT to restart the NetMon services
wget --no-check-certificate --auth-no-challenge --user=admin --password=$netmonAPIKey --method=PUT  https://${netmonIP}/api/services/actions/restart -O NetMon${netmonIP}RestartServicesResponse.json

# Make a GET request to download a PCAP .zip for a session (NOTE: it takes time for the PCAP .zip to be
# constructed before the download will start, please be patient)
wget --no-check-certificate --auth-no-challenge --user=admin --password=$netmonAPIKey http://${netmonIP}/api/session/${sessionID}/pcap -O NetMon${netmonIP}PCAPForSession-${sessionID}.zip

Python

When using any of the following examples, be sure to replace any variables such as API key, NetMon IP address, and session ID with valid values for your deployment.
This guide assumes that you already have Python and PIP installed and are familiar with Python scripting. The following examples work with both Python 2.x and Python 3.x.
Before you start, you need to install python requests:
python -m pip install requests
If you already have python requests, you may want to update it to the latest version (2.22.0 at the time of this writing):
python -m pip install --upgrade requests

NetMon API Python - Request Examples

PY

import os # we will use this in a later example
import requests
from pprint import pprint
 
# If you are using the default NetMon self-signed ssl cert, you will probably want to disable
# python-requests' internal urllib3 insecure request warnings
from requests.packages.urllib3.exceptions import InsecureRequestWarning
from requests.packages.urllib3 import disable_warnings
disable_warnings(InsecureRequestWarning)
 
application_json_header = {'Content-Type': 'application/json'}
 
netmon_ip = '1.2.3.4'
username = 'admin'
api_key = 'abcdef0123456789'
session_id = 'abcdef0123456789'
 
auth = requests.auth.HTTPBasicAuth(username, api_key)
 
# Make a GET request to systemInfo for details about the target NetMon deployment
system_info_route = 'https://{}/api/systemInfo'.format(netmon_ip)
 
# The verify parameter must be set to False if you are using the default NetMon self-signed ssl cert,
# if you have added a trusted certificate to NetMon, the verify=False can be omitted in your request calls
response = requests.get(system_info_route, auth=auth, verify=False)
 
pprint(response.json())
 
# Make a POST request to the search route to retrieve a specific session's metadata
search_route = 'https://{}/api/search'.format(netmon_ip)
query_body = {
                'query': {
                    'term': {
                        'Session': session_id
                    }
                }
            }
 
response = requests.post(search_route, auth=auth, json=query_body, headers=application_json_header, verify=False)
  
pprint(response.json())
 
# Make a POST request to upload a license file
licenses_route = 'https://{}/api/licenses'.format(netmon_ip)
filepath = '/path/to/LicenseFile.lic'
with open(filepath, 'rb') as file_to_upload:
    files = {'file': file_to_upload}
    response = requests.post(licenses_route, auth=auth, files=files, verify=False)
 
pprint(response.json())
 
# Make another POST to reboot the NetMon to apply the license
reboot_route = 'https://{}/api/system/actions/reboot'.format(netmon_ip)
 
response = requests.post(reboot_route, auth=auth, verify=False)
 
pprint(response.json())
 
# Make a PUT to restart the NetMon services
restart_services_route = 'https://{}/api/services/actions/restart'.format(netmon_ip)
 
response = requests.put(restart_services_route, auth=auth, verify=False)
 
pprint(response.json())
 
# Make a GET request to download a PCAP .zip for a session
pcap_route = 'https://{0}/api/session/{1}/pcap'.format(netmon_ip, session_id)
application_7z_header = {'Content-Type': 'application/x-7z-compressed'}
download_filename = 'NetMon{0}PCAPForSession-{1}.zip'.format(netmon_ip, session_id)
 
with requests.get(pcap_route, auth=auth, headers=application_7z_header, stream=True, verify=False) as response:
    response.raise_for_status()
    with open(download_filename, 'wb') as outfile:
        for chunk in response.iter_content(chunk_size=4096):
            if chunk:
                outfile.write(chunk)
print('PCAP .zip for session {0} saved to {1}'.format(session_id, os.path.join(os.getcwd(), download_filename)))