1. RESTful API v2 Specification

1.1. Authentication

The HTTP/HTTPS authentication should be used, for example with curl it is possible to specify username and password with -u <user>:<password>

Using HTTPS is recommended for security. See this post to enable HTTPS.

1.2. Request Format

Parameters can be provided both using GET with a query string or POST using JSON (in this case please make sure the correct Content Type is provided). For example, to download data for a host you can use the below curl command line using GET:

curl -s -u admin:admin "http://192.168.1.1:3000/lua/rest/v2/get/host/data.lua?ifid=1&host=192.168.1.2"

or the below curl command line using POST:

curl -s -u admin:admin -H "Content-Type: application/json" -d '{"ifid": "1", "host": "192.168.1.2"}' "http://192.168.1.1:3000/lua/rest/v2/get/host/data.lua"

Please check the Examples section for more examples.

1.3. Response Format

An API response is usually represented by a JSON message matching a standard structure. This JSON message consists of an envelope containing:

  • a return code rc

  • a human-readable string rc_str describing the return code

  • the actual response in rsp

Example:

{
 "rc": 0
 "rc_str": "OK",
 "rsp": {
    ...
 }
}

1.4. API

1.4.1. Interfaces

POST /lua/pro/rest/v2/add/interface/db_flows.lua

Analyse historical flows as live flows

  • Description: Loads the historical flows matching the time range and the flow filters (the same parameters of the Historical Flows page) into a runtime interface named Database, limited by the flow cache size. Answers { new_ifid, max_num_flows }. Administrators only, ClickHouse.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

Responses

0 - OK

-2 - INVALID_INTERFACE or NOT_ENABLED (no ClickHouse)

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR (the interface could not be created)

GET /lua/pro/rest/v2/get/lightview/aggregate.lua

Aggregate a REST endpoint across all interfaces (Overview)

  • Description: Used by the Overview (lightview) mode: forwards the request to the specified REST endpoint once per local interface (setting ifid accordingly) and merges the results according to the dashboard component type. All the other query parameters are forwarded to the endpoint, except ifid. Enterprise only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

endpoint

query

Path of the REST endpoint to query on each interface (e.g. /lua/rest/v2/get/interface/l7/stats.lua)

string

component

query

How to merge the per-interface results: pie, badge, table, sankey or timeseries. When omitted, the result of the endpoint is returned as is (the last interface queried).

string

max_values

query

Maximum number of slices for the pie component (default 10)

integer

Responses

0 - OK. Merged data, in the same format as the forwarded endpoint (empty if endpoint is not set)

POST /lua/pro/rest/v2/get/lightview/aggregate.lua

Aggregate a REST endpoint across all interfaces (Overview), with a request body

  • Description: Same as GET, for endpoints that take a JSON body. With endpoint=/lua/rest/v2/get/timeseries/batch.lua, each query in the body is run on every interface (the ifid in ts_query is replaced) and the series are summed into one serie per query; queries with “split”: true also return one serie per interface (split_series).

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

endpoint

query

Path of the REST endpoint to query on each interface

string

component

query

How to merge the per-interface results (see GET)

string

payload

body

JSON body forwarded to the endpoint (e.g. the queries of timeseries/batch.lua)

Responses

0 - OK. Merged data, in the same format as the forwarded endpoint

GET /lua/pro/rest/v2/get/traffic_report/data.lua

Get the traffic report of an interface, network or host

  • Description: Traffic of each hour (report=daily) or day (weekly, monthly) of the period containing epoch_begin, next to the same bucket of the previous period: rows [{ tstamp, bytes, activity (active seconds), prev_bytes, prev_activity }], with epoch_begin/epoch_end of the period and the start of the previous/next period. Reads the RRD timeseries: Enterprise M, RRD timeseries driver, not on pcap files.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

Host (IP, with @vlan for the VLAN hosts); default the interface

string

network

query

Local network identifier; default the interface

integer

report

query

Period

string

epoch_begin

query

An epoch inside the period (default now)

integer

Responses

0 - OK

-1 - NOT_FOUND (no traffic timeseries for the entity)

-2 - INVALID_INTERFACE (missing ifid, or an interface the user cannot see) or NOT_ENABLED (no RRD driver, or pcap file)

-3 - NOT_GRANTED (license, or a host/network outside the allowed networks of the user)

-5 - INVALID_ARGUMENTS (unknown report or network)

1.4.2. Hosts

GET /lua/pro/rest/v2/charts/host/map.lua

Get the hosts map data of an interface

  • Description: Enterprise only. Up to 64 local and 64 remote active hosts placed by the chosen criteria. rsp.series: [{name: local|remote, base_url (host details page), data: [{x, y, z (bubble radius in px, 3-33, from the host traffic), meta: {label (host name or IP), url_query (host=<ip>@<vlan>)}}]}]. x/y per bubble_mode: 0 flows as server/client, 1 unreachable flows as server/client, 2 alerted flows as server/client, 3 DNS positive replies/sent queries, 4 SYN sent/received, 5 SYN sent/RST received, 6 SYN sent/SYN-ACK received, 7 TCP packets sent/received, 8 TCP bytes sent/received, 9 active alerted flows as server/client, 10 bytes/packets ratio, 11 client/server score, 12 blacklisted flows as client/server, 13 unidirectional TCP flows as client/server. Modes 4-6 need a packet interface.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

bubble_mode

query

Criteria, 0-13 (default 0)

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/interface/local_hosts_report.lua

Get the local hosts activity report

  • Description: Traffic of the local hosts (assets) in a time range, from the host timeseries (live data when epoch_begin = epoch_end): one row per asset, with the traffic of its host on the VLAN seen last (the VLAN is not part of the identity of an asset). Each row: ip, vlan (the VLAN seen last), host (ip@vlan, the host whose traffic is reported), host_key, name, online, bytes_sent, bytes_rcvd, local_traffic, remote_traffic, total_traffic, availability (traffic per time slot) and max_value_per_point (max of each slot over the page). Enterprise M only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start of the time range (epoch seconds). Equal to epoch_end = live data

integer

epoch_end

query

End of the time range (epoch seconds)

integer

preset

query

Time range preset, sets the number of availability points: hour (12), day (24), week (7), month (30), year (12) (optional)

string

host_visibility

query

Hosts listed: only_traffic (default), no_traffic, visible, hidden (optional)

string

start

query

Pagination: index of the first host

integer

length

query

Pagination: number of hosts

integer

sort

query

Sort column: ip, name, bytes_sent, bytes_rcvd, local_traffic, remote_traffic, total_traffic (optional)

string

order

query

Sort order: asc or desc (optional)

string

Responses

0 - OK

-1 - NOT_FOUND (not Enterprise M)

-2 - INVALID_INTERFACE (missing time range, or an interface the user cannot access)

POST /lua/pro/rest/v2/edit/host/visibility.lua

Hide or show a host in the local hosts activity report

  • Description: Hides a host from the local hosts activity report (listed again with host_visibility=hidden) or shows it again. Enterprise M and administrators only.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

Responses

0 - OK

-3 - NOT_GRANTED (Enterprise M and administrators only)

-4 - INVALID_HOST

GET /lua/pro/rest/v2/get/host/asset_details.lua

Get the details of an asset

  • Description: Details of an asset of the inventory as raw values: ifid, key, ip, vlan (the VLAN seen last), vlans [{ id, name, online }] (the VLANs where the IP of a host asset has been seen: the VLAN is not part of its identity), mac, name, title, device_type (id), manufacturer, model, os_id/os_name, first_seen/last_seen (epochs), online (the host of any of its VLANs is), dhcp, snmp_name, network { id, name }, tags [{ id, name, color, description, reserved, protocols, risks, ttl }] (the definition of the tags, see rest/v2/get/tag/tags_list.lua), names [{ source, name }], switch { ip, name, port, port_name, trunk, num_ports }, server_ports { tcp, udp: [{ port, name }] }, wazuh (agent: status, version, os, cpu, ram, open_ports, ifaces). Enterprise M; assets of hosts outside the allowed networks are not shown. Needs the historical flows capability (non-admin users).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

serial_key

query

Asset key (key field of rest/v2/get/host/assets.lua)

string

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (no serial_key)

GET /lua/pro/rest/v2/get/geo_map/hosts.lua

Get hosts location

  • Description: Get hosts location and other info

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/pro/rest/v2/get/interface/top/local/talkers.lua

Get Top local talkers

  • Description: Get the Top 10 local talkers

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface ID

number

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/pro/rest/v2/get/interface/top/remote/talkers.lua

Get Top remote talkers

  • Description: Get the Top 10 remote talkers

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface ID

number

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/pro/rest/v2/get/interface/top/ts_stats.lua

Get Top Timeseries stats

  • Description: Get the Top timeseries stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

Start time (epoch)

integer

ts_query

query

data used to get the timeseries; e.g. format: ‘ifid:1,protocol:DNS’ , where ‘ifid:1’ stands for interface ID 1 and ‘protocol:DNS’ stands for DNS protocol information

string

detail_view

query

Top information requested, currently available: top_protocols -> Top Application data, top_categories -> Top Categories data, top_senders -> Top Local Senders data, top_receivers -> Top Local Receivers data

string

Responses

0 - OK

-2 - INVALID_INTERFACE

1.4.3. Alerts

GET /lua/pro/rest/v2/acknowledge/snmp/device/alerts.lua

Acknowledge SNMP device alerts

  • Description: DEPRECATED: alerts are acknowledged through the issues (edit/issue/acknowledge.lua, Enterprise XXL+). Acknowledge SNMP device historical alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

label

query

Describe why the alert was ackowledge, it can be an empty string

string

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

row_id

query

Alert identifier of the exact alert

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

snmp_interface

query

SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/add/alert/exclusion.lua

Add an alert exclusion

  • Description: Add an alert exclusion

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

type

query

Type of the host to exclude (currently available: ‘host’, ‘domain’, ‘certificate’)

string

alert_addr

query

Host IP of the address to exclude (with type: ‘host’)

string

alert_domain

query

Domain to exclude (with type ‘host’)

string

alert_certificate

query

Certificate to exclude (with type ‘certificate’)

string

subdir

query

Type of alert to exclude (currently available: ‘flow’ or ‘host’

string

flow_alert_key

query

Flow alert identifier

string

host_alert_key

query

Host alert identifier

string

delete_alerts

query

Return true to delete the excluded alerts, false otherwise

boolean

Responses

0 - OK

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

POST /lua/pro/rest/v2/add/device/exclusion.lua

Authorize devices

  • Description: Set to authorized the listed devices (MAC addresses) already seen by the Device/MAC Address Tracking. Enterprise M, administrators only.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED (not an administrator or no Enterprise M license)

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/delete/alert/exclusion.lua

Delete an alert exclusion

  • Description: Delete an alert exclusion

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

type

query

Type of the host to exclude (currently available: ‘host’, ‘domain’, ‘certificate’)

string

alert_addr

query

Host IP of the address to exclude (with type: ‘host’)

string

alert_domain

query

Domain to exclude (with type ‘host’)

string

alert_certificate

query

Certificate to exclude (with type ‘certificate’)

string

subdir

query

Type of alert to exclude (currently available: ‘flow’ or ‘host’

string

flow_alert_key

query

Flow alert identifier

string

host_alert_key

query

Host alert identifier

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/pro/rest/v2/delete/all/alert/exclusions.lua

Delete all alert exclusions

  • Description: Delete all configured host or flow alert exclusions for a specific host

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

type

query

Either ‘host’ or ‘flow’

string

host

query

The IP address of the host

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

POST /lua/pro/rest/v2/delete/device/exclusion.lua

Remove a device

  • Description: Remove a device (or all of them) from the Device/MAC Address Tracking: if it connects again it is unauthorized. Enterprise M, administrators only.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED (not an administrator or no Enterprise M license)

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/delete/flow/alert/exclusions.lua

Delete flow alert exclusions

  • Description: Delete flow alert exclusions

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

alert_addr

query

The host IP address

string

alert_key

query

The flow alert key to exclude from flow alerts

integer

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/delete/host/alert/exclusions.lua

Delete host alert exclusions

  • Description: Delete host alert exclusions

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

alert_addr

query

The host IP address

string

alert_key

query

The host alert key to exclude from host alerts

integer

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/delete/snmp/device/alerts.lua

Delete SNMP device alerts

  • Description: Delete SNMP device alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

snmp_interface

query

SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

0 - OK

-3 - NOT_GRANTED

POST /lua/pro/rest/v2/edit/device/exclusion.lua

Edit a device

  • Description: Edit the status of a device (or of all of them) of the Device/MAC Address Tracking. Enterprise M, administrators only.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED (not an administrator or no Enterprise M license)

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/alert/exclusion.lua

Get the alert exclusions

  • Description: Get all the available alert exclusions

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

type

query

Type of the host to exclude (currently available: ‘host’, ‘domain’, ‘certificate’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/pro/rest/v2/get/all/alert/top.lua

Get all alert stats

  • Description: Get all alert stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

Start time (epoch)

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/am_host/alert/top.lua

Get Active Monitoring alert stats

  • Description: Get Active Monitoring alert stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/device/exclusion.lua

List of tracked devices

  • Description: Devices (MAC addresses) seen by the Device/MAC Address Tracking, with their status. Enterprise M, administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

start

query

First row (paging)

integer

length

query

Number of rows (default: all)

integer

sort

query

string

order

query

string

map_search

query

Text searched in the MAC address and manufacturer

string

Responses

0 - OK: rsp = [{ mac, name?, ip? (first host with this MAC), num_hosts, manufacturer, status (allowed|denied|undecided), trigger_alert (bool), first_seen, last_seen (epoch), is_online }], recordsTotal

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED (not an administrator or no Enterprise M license)

GET /lua/pro/rest/v2/get/domain/alert/exclusions.lua

Get domain alert exclusions

  • Description: Get domain alert exclusions

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/flow/alert/exclusions.lua

Get flow alert exclusions

  • Description: Get flow alert exclusions

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

The host IP address

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/flow/alert/top.lua

Get flow alert stats

  • Description: Get flow alert stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

ip_version

query

IP version (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_ip

query

Client IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_ip

query

Server IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_name

query

Client Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

srv_name

query

Server Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

cli_port

query

Client port (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_port

query

Server port (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

vlan_id

query

VLAN ID (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

l7proto

query

Application protocol identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_country

query

Client Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_country

query

Server Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

probe_ip

query

Probe IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

input_snmp

query

Input SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

output_snmp

query

Output SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

snmp_interface

query

SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_host_pool_id

query

Client Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

srv_host_pool_id

query

Server Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

cli_network

query

Client Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_network

query

Server Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

l7_error_id

query

Application layer error identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

traffic_direction

query

Traffic direction identifier, currently available: 0 -> remote only, 1 -> local only, 2 -> remote to local, 3 -> local to remote (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

format

query

Format of the return data (json or txt)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/alert/preset/consts.lua

Get the alert query presets

  • Description: The query presets of an alert page: [{id: ‘builtin’, list}, {id: ‘queries’, list}] (empty when the page has none). Enterprise L.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

page

query

Alert page (all, host, flow, …)

string

Responses

0 - OK

-3 - NOT_GRANTED: no Enterprise L license or no alerts capability

-5 - INVALID_ARGUMENTS: unknown page

GET /lua/pro/rest/v2/get/flowdevices/stats.lua

Get flow devices stats

  • Description: get flow devices stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/host/alert/exclusions.lua

Get host alert exclusions

  • Description: Get host alert exclusions

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

The host IP address

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/charts/alert/analysis.lua

Get flow alerts bubble chart data

  • Description: Flow alerts of the last timeframe grouped by client/server/alert type (at most 100 groups): one series per alert type (or one series for the score modes), each point x/y/z (z = bubble radius) with meta.label and meta.url_query (filters for /lua/alert_stats.lua). Enterprise, requires the alerts capability

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

bubble_mode

query

Grouping: 0 score client/server, 1 alert type client/server, 2 alert type client, 3 alert type server, 4 score client, 5 score server (default 0)

integer

timeframe

query

Seconds back from now (default 3600)

integer

vlan

query

VLAN ID (empty: all VLANs)

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/alert/graph/alerts.lua

Get flow alerts graph edges

  • Description: Historical flow alerts aggregated by client, server and alert type (ClickHouse, one table scan, the 2000 groups with the highest total score): src/dst IP, name, country, ASN, local flag, alert (id and label), alerts_count, total_score, severity_id and severity_color (highest severity of the group), first_seen and last_seen (epoch). Enterprise L or nEdge Enterprise, requires the historical flows capability

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

score

query

Score (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

status

query

Alert status: ‘any’ to include all the alerts, otherwise only the ones requiring attention

string

cli_ip

query

Client IP (format: ‘ip;eq’, op: ‘eq’, ‘neq’)

string

srv_ip

query

Server IP (format: ‘ip;eq’, op: ‘eq’, ‘neq’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR (ClickHouse not enabled)

GET /lua/pro/rest/v2/get/alert/graph/host_info.lua

Get flow alerts summary of a host

  • Description: Historical flow alerts of a host (ClickHouse): host_info.info (ip, name, country, ASN) and host_info.client / host_info.server (first/last seen, alerts_count, total_score, total_traffic_bytes); severity_info.client / severity_info.server: severity distribution in percent. Enterprise L or nEdge Enterprise, requires the historical flows capability

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

ip

query

Host IP address

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-59 - MISSING_PARAMETERS

-6 - INTERNAL_ERROR (ClickHouse not enabled)

GET /lua/pro/rest/v2/get/host/alert/top.lua

Get host alert stats

  • Description: Get host alert stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

vlan_id

query

VLAN ID (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

ip_version

query

IP version (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

name

query

Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

host_pool_id

query

Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

network

query

Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/interface/alert/top.lua

Get interface alert stats

  • Description: Get interface alert stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

subtype

query

Alert subtype

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/mac/alert/top.lua

Get MAC alert stats

  • Description: Get MAC alert stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/network/alert/top.lua

Get network alert stats

  • Description: Get network alert stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

network_name

query

Network Name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/sflowdevice/stats.lua

Get sFlow device stats

  • Description: get sFlow device stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

ip

query

The IP address of the device

string

ifIdx

query

The interface index

integer

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/sflowdevices/stats.lua

Get sFlow devices stats

  • Description: get sFlow devices stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/snmp/device/alert/list.lua

Get SNMP device alerts list

  • Description: Get SNMP device alerts list

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

start

query

Starting record (e.g. start=100, it will start returning records from the 101st)

integer

length

query

Maximum number of records to get

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

snmp_interface

query

SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

format

query

Format of the return data (json or txt)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/snmp/device/alert/top.lua

Get SNMP device alert stats

  • Description: Get SNMP device alert stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

snmp_interface

query

SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/snmp/device/alert/ts.lua

Get SNMP device alerts timeseries

  • Description: Get SNMP device alerts timeseries

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

snmp_interface

query

SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/system/alert/top.lua

Get system alert stats

  • Description: Get system alert stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/user/alert/top.lua

Get user alert stats

  • Description: Get user alert stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/acknowledge/am_host/alerts.lua

Acknowledge Active Monitoring alerts

  • Description: DEPRECATED: alerts are acknowledged through the issues (edit/issue/acknowledge.lua, Enterprise XXL+). Acknowledge Active Monitoring historical alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

label

query

Describe why the alert was ackowledge, it can be an empty string

string

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

row_id

query

Alert identifier of the exact alert

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/acknowledge/flow/alerts.lua

Acknowledge flow alerts

  • Description: DEPRECATED: alerts are acknowledged through the issues (edit/issue/acknowledge.lua, Enterprise XXL+). Acknowledge flow historical alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

label

query

Describe why the alert was ackowledge, it can be an empty string

string

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

row_id

query

Alert identifier of the exact alert

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

ip_version

query

IP version (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_ip

query

Client IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_ip

query

Server IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_name

query

Client Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

srv_name

query

Server Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

cli_port

query

Client port (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_port

query

Server port (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

vlan_id

query

VLAN ID (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

l7proto

query

Application protocol identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_country

query

Client Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_country

query

Server Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

probe_ip

query

Probe IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

input_snmp

query

Input SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

output_snmp

query

Output SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

snmp_interface

query

SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_host_pool_id

query

Client Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

srv_host_pool_id

query

Server Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

cli_network

query

Client Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_network

query

Server Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

l7_error_id

query

Application layer error identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

traffic_direction

query

Traffic direction identifier, currently available: 0 -> remote only, 1 -> local only, 2 -> remote to local, 3 -> local to remote (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/acknowledge/host/alerts.lua

Acknowledge host alerts

  • Description: DEPRECATED: alerts are acknowledged through the issues (edit/issue/acknowledge.lua, Enterprise XXL+). Acknowledge host historical alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

label

query

Describe why the alert was ackowledge, it can be an empty string

string

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

row_id

query

Alert identifier of the exact alert

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

vlan_id

query

VLAN ID (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

ip_version

query

IP version (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

name

query

Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

host_pool_id

query

Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

network

query

Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/acknowledge/interface/alerts.lua

Acknowledge interface alerts

  • Description: DEPRECATED: alerts are acknowledged through the issues (edit/issue/acknowledge.lua, Enterprise XXL+). Acknowledge interface historical alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

label

query

Describe why the alert was ackowledge, it can be an empty string

string

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

row_id

query

Alert identifier of the exact alert

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

subtype

query

Alert subtype

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/acknowledge/mac/alerts.lua

Acknowledge MAC alerts

  • Description: DEPRECATED: alerts are acknowledged through the issues (edit/issue/acknowledge.lua, Enterprise XXL+). Acknowledge MAC historical alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

label

query

Describe why the alert was ackowledge, it can be an empty string

string

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

row_id

query

Alert identifier of the exact alert

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/acknowledge/network/alerts.lua

Acknowledge network alerts

  • Description: DEPRECATED: alerts are acknowledged through the issues (edit/issue/acknowledge.lua, Enterprise XXL+). Acknowledge network historical alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

label

query

Describe why the alert was ackowledge, it can be an empty string

string

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

row_id

query

Alert identifier of the exact alert

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

network_name

query

Network Name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/acknowledge/system/alerts.lua

Acknowledge system alerts

  • Description: DEPRECATED: alerts are acknowledged through the issues (edit/issue/acknowledge.lua, Enterprise XXL+). Acknowledge system historical alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

label

query

Describe why the alert was ackowledge, it can be an empty string

string

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

row_id

query

Alert identifier of the exact alert

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/acknowledge/user/alerts.lua

Acknowledge user alerts

  • Description: DEPRECATED: alerts are acknowledged through the issues (edit/issue/acknowledge.lua, Enterprise XXL+). Acknowledge user historical alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

label

query

Describe why the alert was ackowledge, it can be an empty string

string

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

row_id

query

Alert identifier of the exact alert

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/delete/all/alerts.lua

Delete all alerts

  • Description: Delete all historical alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/delete/am_host/alerts.lua

Delete active monitoring hosts alerts

  • Description: Delete active monitoring hosts historical alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/delete/flow/alerts.lua

Delete flow alerts

  • Description: Delete flow historical alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

ip_version

query

IP version (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_ip

query

Client IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_ip

query

Server IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_name

query

Client Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

srv_name

query

Server Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

cli_port

query

Client port (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_port

query

Server port (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

vlan_id

query

VLAN ID (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

l7proto

query

Application protocol identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_country

query

Client Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_country

query

Server Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

probe_ip

query

Probe IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

input_snmp

query

Input SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

output_snmp

query

Output SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

snmp_interface

query

SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_host_pool_id

query

Client Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

srv_host_pool_id

query

Server Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

cli_network

query

Client Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_network

query

Server Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

l7_error_id

query

Application layer error identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

traffic_direction

query

Traffic direction identifier, currently available: 0 -> remote only, 1 -> local only, 2 -> remote to local, 3 -> local to remote (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/delete/host/alerts.lua

Delete host alerts

  • Description: Delete historical host alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

vlan_id

query

VLAN ID (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

ip_version

query

IP version (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

name

query

Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

host_pool_id

query

Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

network

query

Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/delete/host/new_devices.lua

Delete all new devices

  • Description: Delete all new devices learned by ntopng

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

GET /lua/rest/v2/delete/interface/alerts.lua

Delete interface alerts

  • Description: Delete historical interface alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

subtype

query

Alert subtype

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/delete/mac/alerts.lua

Delete MAC alerts

  • Description: Delete MAC historical alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/delete/network/alerts.lua

Delete network alerts

  • Description: Delete historical network alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

network_name

query

Network Name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/delete/system/alerts.lua

Delete system alerts

  • Description: Delete system historical alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/delete/user/alerts.lua

Delete user alerts

  • Description: Delete user historical alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

1.4.4. Issues

1.4.5. Flows

POST /lua/pro/rest/v2/get/flow/nedge/block_flow.lua

Drop the traffic of a live flow

  • Description: Drops the traffic of an active flow (inline interfaces, e.g. nEdge). Administrators only. rsp.status: BLOCKED, NOTFOUND or NOTALLOWED.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/pro/rest/v2/get/db/columns_info.lua

Get Clickhouse available columns

  • Description: Executes a query to the flows database and return all the available columns the DB has

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

-6 - INTERNAL_ERROR

GET /lua/pro/rest/v2/get/flow/historical/overview.lua

Get the details of a historical flow

  • Description: One flow stored in ClickHouse: rsp.flow is the record (raw columns, e.g. SRC2DST_BYTES, IPV4_SRC_ADDR, CLIENT_NW_LATENCY_US), rsp.proto_info the decoded PROTOCOL_INFO_JSON (protocol fields, TCP flags analysis, QoE, exporters, BGP), rsp.info the formatted fields (host names, ports, AS, countries, pools, connection states) and rsp.ext what the server resolves: tags, MAC manufacturers, AS/site/exporter/observation point names, the issues (alert id, nDPI risk id, source, score, title, info, MITRE id and tactic), the additional exported fields and the protocol views of the flow (views: modbus, s7comm, profinet, bgp, hr_charts; view_reasons: view -> license or no_data for the views shown disabled). Needs ClickHouse and the historical flows permission; flows of hosts outside the allowed networks of the user are not found.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

row_id

query

Row id of the flow (rowid of the historical flows list)

integer

tstamp

query

Timestamp of the flow (tstamp of the historical flows list)

integer

instance_name

query

ntopng instance that stored the flow (NTOPNG_INSTANCE_NAME)

string

bgp

query

true: also rsp.ext.bgp_info (BGP/BMP information of the peers)

boolean

llm

query

true: also rsp.ext.llm_flow_data (the flow for the nAnalyst assistant)

boolean

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/db/flows.lua

Get flows data. Columns include (but are not limited to) IP_PROTOCOL_VERSION, FLOW_TIME, FIRST_SEEN, LAST_SEEN, VLAN_ID, PACKETS, TOTAL_BYTES, SRC2DST_BYTES, DST2SRC_BYTES, IPV4_SRC_ADDR, IPV4_DST_ADDR, IPV6_SRC_ADDR, IPV6_DST_ADDR, PROTOCOL, L7_PROTO.

  • Description: Executes a query to the flows database

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

begin_time_clause

query

Start time (epoch)

integer

end_time_clause

query

Start time (epoch)

integer

select_clause

query

Select clause (default: *)

string

where_clause

query

Where clause (default: none). IP values should be double-quoted and between parenthesis (e.g. IPV4_SRC_ADDR = (“192.168.1.1”)).

string

maxhits_clause

query

Max hits (default: 10)

integer

order_by_clause

query

Order by clause (default: no order)

string

group_by_clause

query

Group by clause (default: no group)

string

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/pro/rest/v2/get/db/topk_flows.lua

Get Top-K flows data. Columns include (but are not limited to) IP_PROTOCOL_VERSION, FLOW_TIME, FIRST_SEEN, LAST_SEEN, VLAN_ID, PACKETS, TOTAL_BYTES, SRC2DST_BYTES, DST2SRC_BYTES, IPV4_SRC_ADDR, IPV4_DST_ADDR, IPV6_SRC_ADDR, IPV6_DST_ADDR, PROTOCOL, L7_PROTO

  • Description: Executes a top-k query to the flows database

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

begin_time_clause

query

Start time (epoch)

integer

end_time_clause

query

End time (epoch)

integer

select_keys_clause

query

Select comma-separated keys list (default: IPV4_SRC_ADDR,IPV4_DST_ADDR,L7_PROTO)

string

select_values_clause

query

Select value (default: BYTES)

string

where_clause

query

Where clause (default: none)

string

topk_clause

query

Top-K clause (default: SUM)

string

approx_search

query

Approximate search (default: true)

string

maxhits_clause

query

Max hits (default: 10)

integer

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

1.4.6. PCAP

GET /lua/pro/rest/v2/get/db/filter/bpf.lua

BPF filter generation

  • Description: Convert tags used to extract data from the database into the equivalent BPF filter, suitable for traffic extraction

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

l7proto

query

Application protocol identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

l7proto_master

query

Application protocol identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

l7cat

query

Application category identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

flow_risk

query

Flow risk identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

l4proto

query

Transport protocol identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

ip_version

query

IP version (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_ip

query

Client IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_ip

query

Server IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

traffic_direction

query

Traffic direction identifier, currently available: 0 -> remote only, 1 -> local only, 2 -> remote to local, 3 -> local to remote (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

name

query

Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

cli_name

query

Client Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

srv_name

query

Server Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

network_name

query

Network Name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

src2dst_dscp

query

Client to Server DSCP identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_port

query

Client port (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_port

query

Server port (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

country

query

Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_country

query

Client Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_country

query

Server Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_asn

query

Client ASN identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_asn

query

Server ASN identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_nw_latency

query

Client network latency (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

srv_nw_latency

query

Server network latency (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

observation_point_id

query

Observation point identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

probe_ip

query

Probe IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

vlan_id

query

VLAN ID (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

snmp_interface

query

SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

input_snmp

query

Input SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

output_snmp

query

Output SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

src2dst_tcp_flags

query

Client to Server TCP Flags (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

dst2src_tcp_flags

query

Server to Client TCP Flags (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

mac

query

MAC Address (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_mac

query

Client MAC Address (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_mac

query

Server MAC Address (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

network

query

Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_network

query

Client Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_network

query

Server Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

info

query

Info field (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

bytes

query

Total Bytes (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

packets

query

Total Packets (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

host_pool_id

query

Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

cli_host_pool_id

query

Client Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

srv_host_pool_id

query

Server Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

l7_error_id

query

Application layer error identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_proc_name

query

Client process name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_proc_name

query

Server process name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_user_name

query

Client user name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_user_name

query

Server user name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

FILE - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

-7 - BAD_FORMAT

1.4.7. Users

POST /lua/rest/v2/add/ntopng/user.lua

Add ntopng user

  • Description: Add a ntopng user

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

username

formData

Username

string

full_name

formData

Full name

string

password

formData

Password

string

confirm_password

formData

Confirmed password

string

user_role

formData

User role (unprivileged / administrator)

string

allowed_networks

formData

Allowed networks (e.g. 0.0.0.0/0,::/0)

string

allowed_interface

formData

Allowed interfaces (empty for all)

string

user_language

formData

Language (en, it, de, jp, pt, cz)

string

allow_pcap_download

formData

Allow PCAPs download (1 to allow)

string

allow_historical_flows

formData

Allow Historical Flows page (1 to allow, 0 to deny)

string

allow_alerts

formData

Allow Alerts page (1 to allow, 0 to deny)

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-19 - PASSWORD_MISMATCH

-20 - ADD_USER_FAILED

-23 - USER_ALREADY_EXISTING

POST /lua/rest/v2/create/ntopng/session.lua

Create a new ntopng user session Cookie

  • Description: Generate a new user session to be used as session Cookie

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

username

formData

Username

string

auth_session_duration

formData

Session duration (seconds). Default: 0 (no expiration).

integer

Responses

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

POST /lua/rest/v2/delete/ntopng/user.lua

Delete ntopng user

  • Description: Delete a ntopng user

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

username

formData

Username

string

Responses

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-21 - DELETE_USER_FAILED

POST /lua/rest/v2/edit/ntopng/user.lua

Edit a ntopng user

  • Description: Edit an existing ntopng user

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

username

formData

Username

string

full_name

formData

Full name

string

password

formData

Password

string

confirm_password

formData

Confirmed password

string

user_role

formData

User role (unprivileged / administrator)

string

allowed_networks

formData

Allowed networks (e.g. 0.0.0.0/0,::/0)

string

allowed_interface

formData

Allowed interfaces (empty for all)

string

user_language

formData

Language (en, it, de, jp, pt, cz)

string

allow_pcap_download

formData

Allow PCAPs download (1 to allow)

string

allow_historical_flows

formData

Allow Historical Flows page (1 to allow, 0 to deny)

string

allow_alerts

formData

Allow Alerts page (1 to allow, 0 to deny)

string

Responses

-5 - INVALID_ARGUMENTS

-21 - DELETE_USER_FAILED

-23 - USER_DOES_NOT_EXIST

-24 - EDIT_USER_FAILED

1.4.8. Infrastructures

POST /lua/pro/rest/v2/add/infrastructure/instance.lua

Add a new infrastructure configuration

  • Description: Add a new infrastructure configuration. Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

url

formData

The URL of the ntopng in the infrastructure (http or https, stored as scheme://host:port)

string

alias

formData

An alias for the infrastructure

string

token

formData

The REST API Token for the authentication

string

rtt_threshold

formData

RTT threshold of the active monitoring, in seconds (1-10)

integer

bandwidth_threshold

formData

Bandwidth threshold of the active monitoring, in Mbps (0-1000)

integer

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-34 - INFRASTRUCTURE_INSTANCE_EMPTY_ALIAS

-35 - INFRASTRUCTURE_INSTANCE_EMPTY_URL

-36 - INFRASTRUCTURE_INSTANCE_EMPTY_TOKEN

-37 - INFRASTRUCTURE_INSTANCE_EMPTY_RTT_THRESHOLD

-39 - INFRASTRUCTURE_INSTANCE_SAME_ALIAS

-40 - INFRASTRUCTURE_INSTANCE_SAME_URL

-41 - INFRASTRUCTURE_INSTANCE_SAME_TOKEN

-42 - INFRASTRUCTURE_INSTANCE_ALREADY_EXISTING

-47 - INFRASTRUCTURE_INSTANCE_EMPTY_BANDWIDTH_THRESHOLD

POST /lua/pro/rest/v2/check/infrastructure/config.lua

Test an infrastructure configuration

  • Description: Connects to the REST API of an ntopng in the infrastructure with the url and token: parameters in the JSON body (query string accepted for compatibility). Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

url

formData

The URL of the ntopng in the infrastructure

string

token

formData

The REST API Token for the authentication

string

Responses

0 - OK

-42 - INFRASTRUCTURE_INSTANCE_ALREADY_EXISTING

-43 - INFRASTRUCTURE_INSTANCE_CHECK_FAILED

-24 - INFRASTRUCTURE_INSTANCE_CHECK_NOT_FOUND

-45 - INFRASTRUCTURE_INSTANCE_CHECK_INVALID_RESPONSE

-46 - INFRASTRUCTURE_INSTANCE_CHECK_AUTH_FAILED

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

POST /lua/pro/rest/v2/delete/infrastructure/instance.lua

Delete an existing infrastructure configuration

  • Description: Delete an existing infrastructure configuration. Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

instance_id

formData

The ID of the infrastructure to delete

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-32 - INFRASTRUCTURE_INSTANCE_NOT_FOUND

-33 - INFRASTRUCTURE_INSTANCE_EMPTY_ID

POST /lua/pro/rest/v2/edit/infrastructure/instance.lua

Edit an existing infrastructure configuration

  • Description: Edit an existing infrastructure configuration. Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

instance_id

formData

The ID of the infrastructure configuration to edit

string

url

formData

The URL of the ntopng in the infrastructure (http or https, stored as scheme://host:port)

string

alias

formData

An alias for the infrastructure

string

token

formData

The REST API Token for the authentication

string

rtt_threshold

formData

RTT threshold of the active monitoring, in seconds (1-10)

integer

bandwidth_threshold

formData

Bandwidth threshold of the active monitoring, in Mbps (0-1000)

integer

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-32 - INFRASTRUCTURE_INSTANCE_NOT_FOUND

-33 - INFRASTRUCTURE_INSTANCE_EMPTY_ID

-34 - INFRASTRUCTURE_INSTANCE_EMPTY_ALIAS

-35 - INFRASTRUCTURE_INSTANCE_EMPTY_URL

-36 - INFRASTRUCTURE_INSTANCE_EMPTY_TOKEN

-37 - INFRASTRUCTURE_INSTANCE_EMPTY_RTT_THRESHOLD

-39 - INFRASTRUCTURE_INSTANCE_SAME_ALIAS

-40 - INFRASTRUCTURE_INSTANCE_SAME_URL

-41 - INFRASTRUCTURE_INSTANCE_SAME_TOKEN

-47 - INFRASTRUCTURE_INSTANCE_EMPTY_BANDWIDTH_THRESHOLD

GET /lua/pro/rest/v2/get/infrastructure/instance.lua

Get one or all infrastructure configs

  • Description: Get one or all infrastructure configs. Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

instance_id

query

ID of the infrastructure configuration (all of them when empty)

string

stats

query

Add the statistics collected by the active monitoring module

boolean

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-32 - INFRASTRUCTURE_INSTANCE_NOT_FOUND

GET /lua/rest/v2/export/infrastructure/config.lua

Export the Infrastructure configurations as a JSON file

  • Description: Export the configuration for the infrastructure configurations

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

download

query

Download as file (no REST envelope)

boolean

Responses

0 - OK

-3 - NOT_GRANTED

1.4.9. Health

GET /lua/pro/rest/v2/get/system/health/clickhouse.lua

Get Clickhouse Stats

  • Description: ClickHouse status: version, health (green when a query works, else red), status (UP or DISABLED), size in bytes and rows of the flows (flows_size, flows_number), hourly flows (hourly_flows_size, hourly_flows_number) and alert tables (alerts_size, alerts_number), system_errors (last errors, already formatted with their date). Needs access to the system interface

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED: the user cannot access the system interface

-6 - INTERNAL_ERROR

1.4.10. Configurations

1.4.11. Vulnerability Scan

GET /lua/pro/rest/v2/get/host/scan_port_list.lua

Open ports found by the scans

  • Description: Open ports found by the last scans, with the hosts that have them open. Enterprise L. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

epoch_end

query

Report time: the ports as they were in that report

integer

protocol

query

Only this L4 protocol (id)

integer

Responses

0 - OK

-3 - NOT_GRANTED (administrators only)

POST /lua/rest/v2/delete/host/delete_host_to_scan.lua

Remove hosts to scan

  • Description: Remove one host (host + scan_type), all the hosts (delete_all_scan_hosts=true) or the hosts whose last scan failed (delete_failed_scan_hosts=true). Write: JSON POST body with the csrf (or Basic auth), parameters in the query string are ignored. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

formData

Host address

string

scan_type

formData

Scan type: tcp_portscan, udp_portscan, ipv4_netscan (the ids of get/host/active_scan_type_list.lua)

string

delete_all_scan_hosts

formData

true: remove every host

boolean

delete_failed_scan_hosts

formData

true: remove the hosts whose last scan failed

boolean

Responses

0 - OK

-3 - NOT_GRANTED (administrators only)

-6 - INTERNAL_ERROR

-8 - BAD_CONTENT

GET /lua/rest/v2/get/host/active_scan_result.lua

Result of a host scan

  • Description: The nmap output of the last scan of a host: as JSON (rsp.rsp) with scan_return_result=true, else as a text file download. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

Host address

string

scan_type

query

Scan type: tcp_portscan, udp_portscan, ipv4_netscan (the ids of get/host/active_scan_type_list.lua)

string

epoch

query

Time of the scan (with ClickHouse the result is read from the database)

integer

scan_return_result

query

true: JSON answer, false: file download

boolean

Responses

0 - OK

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/host/active_scan_status.lua

Scans in progress

  • Description: rsp.rsp: { total: hosts to scan, total_in_progress: scheduled or being scanned, total_in_success }. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED (administrators only)

POST /lua/pro/rest/v2/delete/vs/report.lua

Delete a stored report

  • Description: Delete a report (ClickHouse). Write: JSON POST body with the csrf (or Basic auth), parameters in the query string are ignored. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

epoch

formData

Report time (epoch of the list)

integer

Responses

0 - OK

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

POST /lua/pro/rest/v2/edit/vs/report.lua

Rename a stored report

  • Description: Rename a report (ClickHouse). Write: JSON POST body with the csrf (or Basic auth), parameters in the query string are ignored. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

epoch_end

formData

Report time (epoch of the list)

integer

report_title

formData

New name: spaces as _

string

Responses

0 - OK

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/pro/rest/v2/get/vs/report_list.lua

List the stored reports

  • Description: Reports saved at the end of each periodic scan (ClickHouse): name, epoch, report_date, tcp_ports, udp_ports, num_hosts. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

map_search

query

Only the reports whose name contains this text

string

Responses

0 - OK

-3 - NOT_GRANTED (administrators only)

POST /lua/rest/v2/add/host/to_scan.lua

Add a host to scan

  • Description: Add a host (or the active hosts of a network with vs_cidr, or a network scan with ipv4_netscan) to the Active Scan list and schedule its first scan; is_edit=true changes an entry. rsp.rsp: 1 added/updated, 2 already in the list, 3 no active host in the network. Write: JSON POST body with the csrf (or Basic auth), parameters in the query string are ignored. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

formData

Host IP address (IPv4 or IPv6)

string

scan_type

formData

Scan type: tcp_portscan, udp_portscan, ipv4_netscan (the ids of get/host/active_scan_type_list.lua)

string

scan_ports

formData

Ports to scan, comma separated or ranges (e.g. 22,80,1000-2000); empty: all

string

scan_frequency

formData

Periodic scan (Enterprise L): disabled, 1day (every night), 1week (every week)

string

vs_cidr

formData

Network prefix length: 24-30, 32 or 128

integer

discovered_host_scan_type

formData

ipv4_netscan: scan types to run on the discovered hosts, comma separated

string

is_edit

formData

true: change an existing entry

boolean

Responses

0 - OK

-3 - NOT_GRANTED (administrators only)

-6 - INTERNAL_ERROR

-8 - BAD_CONTENT

-2 - NOT_ENABLED (nmap is not installed)

POST /lua/rest/v2/edit/host/update_va_scan_period.lua

Change the periodicity of every scan

  • Description: Set the same periodic scan on all the hosts of the list (Enterprise L). Write: JSON POST body with the csrf (or Basic auth), parameters in the query string are ignored. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

scan_frequency

formData

disabled, 1day (every night) or 1week (every week)

string

Responses

0 - OK

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

POST /lua/rest/v2/exec/host/schedule_active_scan.lua

Scan now

  • Description: Schedule the scan of one host of the list (scan_single_host=true) or of all of them. Write: JSON POST body with the csrf (or Basic auth), parameters in the query string are ignored. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

scan_single_host

formData

true: one host, false: every host

boolean

host

formData

Host IP address (scan_single_host=true)

string

scan_type

formData

Scan type: tcp_portscan, udp_portscan, ipv4_netscan (the ids of get/host/active_scan_type_list.lua) (scan_single_host=true)

string

scan_ports

formData

Ports to scan

string

scan_id

formData

Id of the list entry

string

vs_cidr

formData

Network prefix length

integer

Responses

0 - OK

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

-2 - NOT_ENABLED (nmap is not installed)

1.4.12. nEdge

1.4.13. AI Dashboards

GET /lua/pro/rest/v2/get/dashboard/list.lua

List the AI dashboards

  • Description: List of the saved AI dashboards: [{ id, name, description }]. Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/dashboard/dashboard.lua

Get an AI dashboard

  • Description: Definition of a dashboard: { id, name, description, widgets: [{ id, type, title, config: { sql_query, unit, label_field, value_field, … }, layout: { x, y, w, h } }] }. Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

dashboard_id

query

Dashboard id (letters, digits, ‘_’ and ‘-‘), as returned by get/dashboard/list.lua

string

Responses

0 - OK

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS

-1 - NOT_FOUND

GET /lua/pro/rest/v2/get/dashboard/widget_data.lua

Get the data of a widget

  • Description: Runs the SQL query of a saved widget on ClickHouse and returns its result, shaped for the widget type (e.g. stat: { value }). The placeholders $EPOCH_BEGIN$, $EPOCH_END$, $IFID$ and $FILTERS$ of the query are replaced with the parameters below; on the flows tables the flow filters (same parameters as the Historical Flows explorer, e.g. l7proto=7;eq) are applied too. Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

dashboard_id

query

Dashboard id

string

widget_id

query

Widget id, as in the dashboard definition

string

epoch_begin

query

Begin of the time range (epoch, seconds). Default: epoch_end - 24 hours

integer

epoch_end

query

End of the time range (epoch, seconds). Default: now

integer

ifid

query

Interface id. Default: the current interface

integer

Responses

0 - OK

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR (query failed: the error is in rsp.error)

POST /lua/pro/rest/v2/set/dashboard/dashboard.lua

Create or update an AI dashboard

  • Description: Creates a dashboard (id derived from the name) or, when dashboard_id matches an existing one, replaces it. Returns { success, id, dashboard }. The field names differ from the stored ones: dashboard_name (not name), widget_id (not id) and layout { pos_x, pos_y, grid_w, grid_h }. Widget types: timeseries, table, bar_chart, pie_chart, stat, heatmap, bubble_chart, sankey, chord. Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

payload

body

JSON body, e.g. { “dashboard_name”: “Network overview”, “description”: “”, “widgets”: [{ “widget_id”: “w1”, “type”: “stat”, “title”: “Flows”, “config”: { “sql_query”: “SELECT count() AS value FROM flows WHERE FIRST_SEEN >= $EPOCH_BEGIN$ AND FIRST_SEEN <= $EPOCH_END$ AND INTERFACE_ID = $IFID$ AND $FILTERS$”, “value_field”: “value”, “unit”: “number” }, “layout”: { “pos_x”: 0, “pos_y”: 0, “grid_w”: 4, “grid_h”: 3 } }] }. Add “dashboard_id” to update an existing dashboard.

Responses

0 - OK

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS

-59 - MISSING_PARAMETERS

-8 - BAD_CONTENT (invalid definition, the reason is in rsp.error)

POST /lua/pro/rest/v2/delete/dashboard/dashboard.lua

Delete an AI dashboard

  • Description: Deletes a dashboard. Returns { success }. Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

payload

body

JSON body: { “dashboard_id”: “network-overview” } (dashboard_id is also accepted as query parameter)

Responses

0 - OK

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS

-1 - NOT_FOUND

-59 - MISSING_PARAMETERS

1.4.14. Syslog Rules

GET /lua/pro/rest/v2/get/syslog/messages.lua

Get the syslog messages

  • Description: Syslog messages collected in ClickHouse, paginated: [{ ts, ip, hostname, facility, severity, app_name, message }], recordsTotal. Enterprise XL, administrators only

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

epoch_begin

query

Begin of the time range (epoch)

integer

epoch_end

query

End of the time range (epoch)

integer

syslog_ip

query

Only the messages sent by this IP

string

syslog_severity

query

Only this severity (0-7)

integer

syslog_hostname

query

Only this hostname

string

syslog_app_name

query

Only this application

string

syslog_facility

query

Only this facility

string

map_search

query

Text searched in message, IP, hostname, application, facility, severity

string

start

query

First record

integer

length

query

Number of records (max 500)

integer

sort

query

ts, ip, hostname, facility, severity, app_name, message

string

order

query

asc or desc

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/syslog/facets.lua

Get the syslog facets

  • Description: Most frequent values (max 15) of every facet with their message count: [{ id: severity|ip|hostname|app_name|facility, items: [{ value, count }] }]. The filter of a facet is not applied to the facet itself. Enterprise XL, administrators only

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

epoch_begin

query

Begin of the time range (epoch)

integer

epoch_end

query

End of the time range (epoch)

integer

syslog_ip

query

Only the messages sent by this IP

string

syslog_severity

query

Only this severity (0-7)

integer

syslog_hostname

query

Only this hostname

string

syslog_app_name

query

Only this application

string

syslog_facility

query

Only this facility

string

map_search

query

Text searched in message, IP, hostname, application, facility, severity

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/syslog/rules.lua

List the syslog rules

  • Description: Syslog collector rules, evaluated before a message is stored: the first matching rule wins and a message matching no rule is kept. Returns an array of { id, enabled, min_severity, max_severity, source, pattern, comment, updated_at }. Enterprise XL and administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

-3 - NOT_GRANTED (Enterprise XL and administrators only)

-5 - INVALID_ARGUMENTS

0 - OK

POST /lua/pro/rest/v2/add/syslog/rule.lua

Add a syslog rule

  • Description: Adds a syslog rule. Fails if a rule with the same id already exists. Enterprise XL and administrators only.

  • Consumes: [‘application/x-www-form-urlencoded’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

syslog_rule_id

formData

Rule id (UUID, e.g. generated client side). For edit and delete it must identify an existing rule

string

syslog_rule_enabled

formData

1 = rule enabled, 0 = disabled

integer

syslog_rule_min_severity

formData

Inclusive lower severity bound: 0 = Emergency, 1 = Alert, 2 = Critical, 3 = Error, 4 = Warning, 5 = Notice, 6 = Informational, 7 = Debug

integer

syslog_rule_discard

formData

true: the matching messages are discarded, false: they are kept

boolean

syslog_rule_source

formData

Sender IPv4/IPv6 address or network in CIDR notation (e.g. 10.0.0.0/24): only messages coming from it match the rule. Empty (default) matches any sender

string

syslog_rule_pattern

formData

RE2 regular expression the message must match. Empty (default) matches any message. Max 512 characters, no control characters

string

syslog_rule_comment

formData

Free-text description. Max 255 characters, no control characters

string

Responses

0 - OK. The outcome of the operation is in the ‘result’ field of the response: ‘ok’ on success, otherwise the error message

-3 - NOT_GRANTED (Enterprise XL and administrators only)

-5 - INVALID_ARGUMENTS

POST /lua/pro/rest/v2/edit/syslog/rule.lua

Edit a syslog rule

  • Description: Replaces all the fields of an existing syslog rule. Fails if the rule does not exist. Enterprise XL and administrators only.

  • Consumes: [‘application/x-www-form-urlencoded’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

syslog_rule_id

formData

Rule id (UUID, e.g. generated client side). For edit and delete it must identify an existing rule

string

syslog_rule_enabled

formData

1 = rule enabled, 0 = disabled

integer

syslog_rule_min_severity

formData

Inclusive lower severity bound: 0 = Emergency, 1 = Alert, 2 = Critical, 3 = Error, 4 = Warning, 5 = Notice, 6 = Informational, 7 = Debug

integer

syslog_rule_discard

formData

true: the matching messages are discarded, false: they are kept

boolean

syslog_rule_source

formData

Sender IPv4/IPv6 address or network in CIDR notation (e.g. 10.0.0.0/24): only messages coming from it match the rule. Empty (default) matches any sender

string

syslog_rule_pattern

formData

RE2 regular expression the message must match. Empty (default) matches any message. Max 512 characters, no control characters

string

syslog_rule_comment

formData

Free-text description. Max 255 characters, no control characters

string

Responses

0 - OK. The outcome of the operation is in the ‘result’ field of the response: ‘ok’ on success, otherwise the error message

-3 - NOT_GRANTED (Enterprise XL and administrators only)

-5 - INVALID_ARGUMENTS

POST /lua/pro/rest/v2/delete/syslog/rule.lua

Delete a syslog rule

  • Description: Deletes a syslog rule. Fails if the rule does not exist. Enterprise XL and administrators only.

  • Consumes: [‘application/x-www-form-urlencoded’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

syslog_rule_id

formData

Rule id (UUID, e.g. generated client side). For edit and delete it must identify an existing rule

string

Responses

0 - OK. The outcome of the operation is in the ‘result’ field of the response: ‘ok’ on success, otherwise the error message

-3 - NOT_GRANTED (Enterprise XL and administrators only)

-5 - INVALID_ARGUMENTS

1.4.15. Wazuh

GET /lua/pro/rest/v2/get/wazuh/alerts.lua

Get the Wazuh alerts

  • Description: Page of the Wazuh alerts stored in ClickHouse, newest first by default. Only the alerts whose agent, source or destination IP is in the user allowed networks. Enterprise L, ClickHouse, Wazuh integration enabled, alerts capability (and historical flows capability for non-admin users).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

start

query

Row offset

integer

length

query

Page size (default 50, max 500)

integer

sort

query

Column to sort by (e.g. timestamp, rule_level, agent_name)

string

order

query

asc or desc

string

map_search

query

Text searched in description, agent, IPs, user name, domain and command

string

epoch_begin

query

Only alerts from this time (epoch)

integer

epoch_end

query

Only alerts up to this time (epoch)

integer

min_level

query

Only alerts with a rule level >= this

integer

Responses

0 - OK. rsp: the alerts; recordsTotal/recordsFiltered: number of alerts matching the filters

-3 - NOT_GRANTED (Enterprise M; writes: administrators only)

GET /lua/pro/rest/v2/get/wazuh/alert.lua

Get a Wazuh alert

  • Description: All the fields of one Wazuh alert (NOT_FOUND outside the user allowed networks). Enterprise L, ClickHouse, Wazuh integration enabled, alerts capability (and historical flows capability for non-admin users).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

wazuh_alert_id

query

alert_id of the alert

string

Responses

0 - OK

-1 - NOT_FOUND

-3 - NOT_GRANTED (Enterprise M; writes: administrators only)

GET /lua/pro/rest/v2/get/wazuh/alert_rules.lua

Get the Wazuh alert rules

  • Description: The rules choosing which Wazuh alerts are notified, by priority. Enterprise L, ClickHouse, Wazuh integration enabled, alerts capability (and historical flows capability for non-admin users).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED (Enterprise M; writes: administrators only)

POST /lua/pro/rest/v2/add/wazuh/alert_rule.lua

Add a Wazuh alert rule

  • Description: Adds a rule. Enterprise M, administrators only.

  • Consumes: [‘application/x-www-form-urlencoded’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

wazuh_rule_id

formData

Rule id (letters, digits and dashes)

string

wazuh_rule_priority

formData

Priority, lower first (default 100)

integer

wazuh_rule_min_level

formData

Minimum Wazuh rule level (0-15) of the alerts matched

integer

wazuh_rule_groups

formData

Comma separated Wazuh rule groups matched (empty: any)

string

wazuh_rule_pattern

formData

Lua pattern matched against the alert

string

wazuh_rule_immediate

formData

1: notify immediately, 0: in the digest

integer

wazuh_rule_subject

formData

Subject of the notification

string

wazuh_rule_enabled

formData

1: enabled (default), 0: disabled

integer

wazuh_rule_comment

formData

Free comment

string

Responses

0 - OK. The outcome is in the ‘result’ field of the response: ‘ok’ on success, otherwise the error message

-3 - NOT_GRANTED (Enterprise M; writes: administrators only)

POST /lua/pro/rest/v2/edit/wazuh/alert_rule.lua

Edit a Wazuh alert rule

  • Description: Changes a rule, and renames it when wazuh_rule_new_id is set. Enterprise M, administrators only.

  • Consumes: [‘application/x-www-form-urlencoded’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

wazuh_rule_id

formData

Id of the rule to change

string

wazuh_rule_new_id

formData

New id of the rule

string

wazuh_rule_priority

formData

Priority, lower first (default 100)

integer

wazuh_rule_min_level

formData

Minimum Wazuh rule level (0-15) of the alerts matched

integer

wazuh_rule_groups

formData

Comma separated Wazuh rule groups matched (empty: any)

string

wazuh_rule_pattern

formData

Lua pattern matched against the alert

string

wazuh_rule_immediate

formData

1: notify immediately, 0: in the digest

integer

wazuh_rule_subject

formData

Subject of the notification

string

wazuh_rule_enabled

formData

1: enabled (default), 0: disabled

integer

wazuh_rule_comment

formData

Free comment

string

Responses

0 - OK. The outcome is in the ‘result’ field of the response: ‘ok’ on success, otherwise the error message

-3 - NOT_GRANTED (Enterprise M; writes: administrators only)

POST /lua/pro/rest/v2/delete/wazuh/alert_rule.lua

Delete a Wazuh alert rule

  • Description: Enterprise M, administrators only.

  • Consumes: [‘application/x-www-form-urlencoded’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

wazuh_rule_id

formData

Id of the rule

string

Responses

0 - OK. The outcome is in the ‘result’ field of the response: ‘ok’ on success, otherwise the error message

-3 - NOT_GRANTED (Enterprise M; writes: administrators only)

GET /lua/pro/rest/v2/get/wazuh/alert_exceptions.lua

Get the Wazuh alert exceptions

  • Description: The Wazuh alerts matching an exception are not notified. Enterprise L, ClickHouse, Wazuh integration enabled, alerts capability (and historical flows capability for non-admin users).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED (Enterprise M; writes: administrators only)

POST /lua/pro/rest/v2/add/wazuh/alert_exception.lua

Add a Wazuh alert exception

  • Description: Adds an exception. Fails if the id is already used. Enterprise M, administrators only.

  • Consumes: [‘application/x-www-form-urlencoded’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

wazuh_exception_id

formData

Exception id (e.g. a UUID generated by the client)

string

wazuh_exception_rule_id

formData

Wazuh rule id (0: any)

integer

wazuh_exception_agent_name

formData

Agent name (empty: any)

string

wazuh_exception_src_ip

formData

Source IP (empty: any)

string

wazuh_exception_dst_ip

formData

Destination IP (empty: any)

string

wazuh_exception_username

formData

User name (empty: any)

string

wazuh_exception_process

formData

Process (empty: any)

string

wazuh_exception_rule_group

formData

Rule group (empty: any)

string

wazuh_exception_pattern

formData

Lua pattern matched against the alert

string

wazuh_exception_enabled

formData

1: enabled (default), 0: disabled

integer

wazuh_exception_comment

formData

Free comment

string

Responses

0 - OK. The outcome is in the ‘result’ field of the response: ‘ok’ on success, otherwise the error message

-3 - NOT_GRANTED (Enterprise M; writes: administrators only)

POST /lua/pro/rest/v2/edit/wazuh/alert_exception.lua

Edit a Wazuh alert exception

  • Description: Changes an exception, and renames it when old_wazuh_exception_id differs from wazuh_exception_id. Enterprise M, administrators only.

  • Consumes: [‘application/x-www-form-urlencoded’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

old_wazuh_exception_id

formData

Current id of the exception (default: wazuh_exception_id)

string

wazuh_exception_id

formData

(New) id of the exception

string

wazuh_exception_rule_id

formData

Wazuh rule id (0: any)

integer

wazuh_exception_agent_name

formData

Agent name (empty: any)

string

wazuh_exception_src_ip

formData

Source IP (empty: any)

string

wazuh_exception_dst_ip

formData

Destination IP (empty: any)

string

wazuh_exception_username

formData

User name (empty: any)

string

wazuh_exception_process

formData

Process (empty: any)

string

wazuh_exception_rule_group

formData

Rule group (empty: any)

string

wazuh_exception_pattern

formData

Lua pattern matched against the alert

string

wazuh_exception_enabled

formData

1: enabled (default), 0: disabled

integer

wazuh_exception_comment

formData

Free comment

string

Responses

0 - OK. The outcome is in the ‘result’ field of the response: ‘ok’ on success, otherwise the error message

-3 - NOT_GRANTED (Enterprise M; writes: administrators only)

POST /lua/pro/rest/v2/delete/wazuh/alert_exception.lua

Delete a Wazuh alert exception

  • Description: Enterprise M, administrators only.

  • Consumes: [‘application/x-www-form-urlencoded’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

wazuh_exception_id

formData

Id of the exception

string

Responses

0 - OK. The outcome is in the ‘result’ field of the response: ‘ok’ on success, otherwise the error message

-3 - NOT_GRANTED (Enterprise M; writes: administrators only)

1.4.16. nAnalyst

1.4.17. Traffic Model

1.4.18. Syslog

GET /lua/pro/rest/v2/get/syslog/stats.lua

Get the syslog message counters

  • Description: Counters since ntopng started, summed over the syslog interfaces: messages received by the collector and messages stored in ClickHouse. The history is the iface:syslog_messages timeseries. Enterprise XL, administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK. rsp: { received, stored, ifids: [interfaces with the counters] }

-3 - NOT_GRANTED (Enterprise XL, administrators only)

1.4.19. Notification Recipients

POST /lua/rest/v2/add/notification/recipient.lua

Add a notification recipient

  • Description: Add a notification recipient on an existing connection (endpoint_id) or on a new connection created in the same call (endpoint_conf_type and its params). Plus the params of the channel type (e.g. email: smtp_server, email_sender, email_recipient; slack: slack_sender_username, slack_webhook), as listed by the notification page context. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

recipient_name

formData

Recipient name (unique)

string

endpoint_id

formData

Existing connection id (omit to create a new connection)

integer

endpoint_conf_type

formData

Channel type of the new connection (email, slack, telegram, webhook…)

string

endpoint_conf_name

formData

Name of the new connection (default: the recipient name)

string

recipient_minimum_severity

formData

Minimum alert severity id (default: notice)

integer

recipient_check_categories

formData

Comma-separated alert category ids (empty: all)

string

recipient_check_entities

formData

Comma-separated alert entity ids (empty: all)

string

recipient_host_pools

formData

Comma-separated host pool ids (empty: all)

string

recipient_am_hosts

formData

Comma-separated Active Monitoring host ids (empty: no filter)

string

recipient_labels

formData

Comma-separated tag ids: only alerts with at least one of them (empty: no filter)

string

recipient_checks

formData

Comma-separated <alert_id>_<entity_id>: only these alerts (empty: no filter)

string

recipient_notifications_type

formData

alerts (default), reports, active_scans, wazuh_alerts

string

recipient_delivery_mode

formData

Alerts recipients: alerts (default, each alert) or issues (a notification when an issue is opened, escalated, reopened or resolved; Enterprise XXL+ with the Issues preference on). Edit: the stored mode is kept when not set

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (rsp.type: error type, e.g. endpoint_recipient_already_existing, missing_mandatory_param, invalid_param)

POST /lua/rest/v2/delete/notification/endpoint.lua

Delete a notification connection

  • Description: Delete a notification connection and all the recipients using it. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

endpoint_id

formData

Connection id

integer

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (rsp.type: error type, e.g. endpoint_recipient_already_existing, missing_mandatory_param, invalid_param)

POST /lua/rest/v2/delete/notification/recipient.lua

Delete a notification recipient

  • Description: Delete a notification recipient (not the builtin one). Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

recipient_id

formData

Recipient id

integer

delete_endpoint

formData

true: also delete its connection when no other recipient uses it

boolean

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (rsp.type: error type, e.g. endpoint_recipient_already_existing, missing_mandatory_param, invalid_param)

POST /lua/rest/v2/edit/notification/endpoint.lua

Edit a notification connection

  • Description: Edit name and params of a notification connection: all the params are replaced, missing optional ones are cleared. Plus the params of the channel type (e.g. email: smtp_server, email_sender, email_recipient; slack: slack_sender_username, slack_webhook), as listed by the notification page context. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

endpoint_id

formData

Connection id

integer

endpoint_conf_name

formData

Connection name

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (rsp.type: error type, e.g. endpoint_recipient_already_existing, missing_mandatory_param, invalid_param)

POST /lua/rest/v2/edit/notification/recipient.lua

Edit a notification recipient

  • Description: Edit name, filters and recipient params of a notification recipient. The builtin alert database recipient keeps its name. Plus the params of the channel type (e.g. email: smtp_server, email_sender, email_recipient; slack: slack_sender_username, slack_webhook), as listed by the notification page context. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

recipient_id

formData

Recipient id

integer

recipient_name

formData

Recipient name

string

recipient_minimum_severity

formData

Minimum alert severity id (default: notice)

integer

recipient_check_categories

formData

Comma-separated alert category ids (empty: all)

string

recipient_check_entities

formData

Comma-separated alert entity ids (empty: all)

string

recipient_host_pools

formData

Comma-separated host pool ids (empty: all)

string

recipient_am_hosts

formData

Comma-separated Active Monitoring host ids (empty: no filter)

string

recipient_labels

formData

Comma-separated tag ids: only alerts with at least one of them (empty: no filter)

string

recipient_checks

formData

Comma-separated <alert_id>_<entity_id>: only these alerts (empty: no filter)

string

recipient_notifications_type

formData

alerts (default), reports, active_scans, wazuh_alerts

string

recipient_delivery_mode

formData

Alerts recipients: alerts (default, each alert) or issues (a notification when an issue is opened, escalated, reopened or resolved; Enterprise XXL+ with the Issues preference on). Edit: the stored mode is kept when not set

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (rsp.type: error type, e.g. endpoint_recipient_already_existing, missing_mandatory_param, invalid_param)

POST /lua/rest/v2/exec/notification/test_recipient.lua

Test a notification recipient

  • Description: Send a test message with an existing connection (endpoint_id) or a not yet saved one (endpoint_conf_type and its params), plus the recipient params. Nothing is saved. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

endpoint_id

formData

Existing connection id

integer

endpoint_conf_type

formData

Channel type of a not yet saved connection

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (rsp.type: error type, e.g. endpoint_recipient_already_existing, missing_mandatory_param, invalid_param)

GET /lua/rest/v2/get/notification/endpoints.lua

List notification connections

  • Description: Notification connections (endpoints: SMTP server, bot token, webhook URL…) with their params, credentials included, and the number of recipients using them. Builtin connections are excluded. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (rsp.type: error type, e.g. endpoint_recipient_already_existing, missing_mandatory_param, invalid_param)

GET /lua/rest/v2/get/notification/recipients.lua

List notification recipients

  • Description: Notification recipients (builtin alert database recipient included) with channel type, connection, filters, delivery_mode (alerts or issues), recipient params and delivery stats. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (rsp.type: error type, e.g. endpoint_recipient_already_existing, missing_mandatory_param, invalid_param)

POST /lua/rest/v2/delete/recipients.lua

Delete all defined recipients and reset them to factory-defaults

  • Description: Delete all defined recipients and reset them to factory-defaults

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

1.4.20. Active Monitoring

POST /lua/rest/v2/set/active_monitoring/measurement.lua

Add or edit an Active Monitoring measurement

  • Description: Adds (action=add) or changes (action=edit, identified by old_host and old_measurement) a measurement. POST (form data, CSRF checked). Requires the Active Monitoring capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

action

formData

add or edit

string

am_host

formData

Host or URL to measure

string

measurement

formData

Measurement type (e.g. icmp, cicmp, http, https, throughput, speedtest)

string

ifname

formData

Interface used for the measurement

string

threshold

formData

Alert threshold (unit of the measurement)

string

granularity

formData

How often to measure (e.g. min, 5mins, hour)

string

old_host

formData

With action=edit: the current host

string

old_measurement

formData

With action=edit: the current measurement

string

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/rest/v2/export/active_monitoring/config.lua

Export the active monitoring configuration as a JSON file

  • Description: Export the active monitoring configuration

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

download

query

Download as file (no REST envelope)

boolean

Responses

0 - OK

-3 - NOT_GRANTED

1.4.21. SNMP

POST /lua/pro/rest/v2/set/snmp/auto_assign_role.lua

Set the role of the SNMP interfaces by name

  • Description: Gives a role to every interface whose name contains the filter, on all the SNMP devices; returns how many were changed. POST with a JSON body (CSRF checked), never from the query string. Requires the SNMP capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

payload

body

JSON body: { “interface_name_filter”: “eth”, “role”: “uplink”, “csrf”: “…” }

Responses

0 - OK

-3 - NOT_GRANTED

-59 - MISSING_PARAMETERS

GET /lua/pro/rest/v2/get/snmp/device/similarity.lua

Get the SNMP devices similar to a device

  • Description: Devices with a similar traffic behaviour. Enterprise.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

IP address of the SNMP device

string

Responses

0 - OK

-3 - NOT_GRANTED

-1 - NOT_FOUND (not available)

GET /lua/pro/rest/v2/get/snmp/topology_map.lua

Get the SNMP topology map

  • Description: Nodes and links of the network topology learned from the SNMP devices; with host only the part around that device. Enterprise.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

IP address of an SNMP device (optional)

string

Responses

0 - OK

-3 - NOT_GRANTED

-1 - NOT_FOUND (not available)

GET /lua/pro/rest/v2/get/snmp/device/topology.lua

Get the neighbours of an SNMP device

  • Description: The devices connected to an SNMP device (LLDP/CDP and bridge tables). Enterprise.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

IP address of the SNMP device

string

Responses

0 - OK

-3 - NOT_GRANTED

-1 - NOT_FOUND (not available)

POST /lua/pro/rest/v2/add/snmp/import_devices.lua

Import SNMP devices

  • Description: Adds the devices of a configuration export (devices, JSON as produced by export/snmp/config.lua) or of a CSV (devices_csv, one device per line: ip, read_community, write_community, version, level, username, auth_protocol, auth_passphrase, privacy_protocol, privacy_passphrase, context). POST (form data, CSRF checked). Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

devices

formData

JSON configuration to import

string

devices_csv

formData

CSV of the devices to import

string

Responses

0 - OK

-3 - NOT_GRANTED

-8 - BAD_CONTENT

POST /lua/pro/rest/v2/check/snmp/ping_all_devices.lua

Poll all the SNMP devices now

  • Description: Starts a poll of every SNMP device without waiting for the next periodic one. Administrators only, Enterprise M.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

POST /lua/pro/rest/v2/delete/snmp/unresponsive_devices.lua

Delete the unresponsive SNMP devices

  • Description: Deletes the devices that do not answer to SNMP. POST only (CSRF checked). Administrators only, Enterprise M.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (not a POST)

POST /lua/pro/rest/v2/delete/snmp/all_devices.lua

Delete all the SNMP devices

  • Description: Deletes every configured SNMP device. POST only (CSRF checked). Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (not a POST)

POST /lua/pro/rest/v2/edit/snmp/device/config.lua

Edit the polling options of an SNMP device

  • Description: Sets the options of a device. POST (form data, CSRF checked). Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

formData

IP address of the SNMP device

string

toggle_snmp_qos_mib_polling

formData

1 to poll the Cisco QoS MIB, 0 not to

string

Responses

0 - OK

-3 - NOT_GRANTED

-1 - NOT_FOUND (not an administrator)

GET /lua/pro/rest/v2/get/snmp/device/config.lua

Get the polling options of an SNMP device

  • Description: Options of a device: { toggle_snmp_qos_mib_polling }. Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

IP address of the SNMP device

string

Responses

0 - OK

-3 - NOT_GRANTED

-1 - NOT_FOUND (not an administrator)

GET /lua/pro/rest/v2/get/snmp/device/available_interfaces.lua

List the interfaces of an SNMP device

  • Description: The interfaces of a device ([{ id, name }]), from the SNMP cache. Requires the SNMP capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

IP address of the SNMP device

string

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/snmp/list.lua

List the SNMP devices

  • Description: The configured SNMP devices with their polling status (name, description, version, last poll, interfaces with errors, unreachable). Requires the SNMP capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

device_responsiveness

query

Only the ‘responsive’ or the ‘unresponsive’ devices

string

verbose

query

More details per device

boolean

rsp_format

query

Response in the table format

boolean

Responses

0 - OK

-3 - NOT_GRANTED

POST /lua/pro/rest/v2/add/snmp/device.lua

Add SNMP devices

  • Description: Add devices to the monitored SNMP devices. POST (form data, CSRF checked). Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

snmp_host

formData

IP address or symbolic name of and an SNMP device

string

snmp_read_community

formData

The SNMP read community to use (SNMP v1/v2c only)

string

snmp_write_community

formData

The SNMP write community to use (SNMP v1/v2c only)

string

snmp_version

formData

The SNMP version to use: 2 (SNMP v3), 1 (v2c) or 0 (v1)

string

snmp_level

formData

Used only with SNMP v3: noAuthNoPriv, authNoPriv, or authPriv)

string

snmp_auth_protocol

formData

Used only with SNMP v3 and level not set to noAuthNoPriv: MD5 or SHA

string

snmp_auth_passphrase

formData

Used only with SNMP v3 and level not set to noAuthNoPriv: 8 chars+ passphrase

string

snmp_privacy_protocol

formData

Used only with SNMP v3 and level set to autPriv: DES or AES

string

snmp_privacy_passphrase

formData

Used only with SNMP v3 and level set to autPriv: 8 chars+ passphrase

string

cidr

formData

Either 24 or 32. If 32, snmp_host is treated as single host. If 24 snmp_host is treated as as CIDR address

string

snmp_username

formData

SNMP v3 username

string

snmp_context

formData

SNMP v3 context name

string

Responses

-3 - NOT_GRANTED

-4 - INVALID_HOST

-5 - INVALID_ARGUMENTS

-9 - NAME_RESOLUTION_FAILED

-10 - SNMP_DEVICE_ALREADY_ADDED

-11 - SNMP_DEVICE_UNREACHABLE

-12 - NO_SNMP_DEVICE_DISCOVERED

GET /lua/pro/rest/v2/change/snmp/device/interface/status.lua

Change SNMP device interface status

  • Description: Change the status of an SNMP device in terface to up or down

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

IP address of an SNMP device

string

snmp_admin_status

query

The new admin status, either ‘up’ or ‘down’

string

snmp_port_idx

query

The index of the SNMP device interface

string

Responses

0 - OK

-3 - NOT_GRANTED

-4 - INVALID_HOST

-5 - INVALID_ARGUMENTS

-26 - SNMP_DEVICE_INTERFACE_STATUS_CHANGE_FAILED

POST /lua/pro/rest/v2/delete/snmp/device.lua

Delete an SNMP device

  • Description: Delete an SNMP device from the monitored SNMP devices. POST (form data, CSRF checked). Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

formData

IP address of an SNMP device

string

Responses

0 - SNMP_DEVICE_DELETED_SUCCESSFULLY

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

POST /lua/pro/rest/v2/edit/snmp/device/device.lua

Edit a SNMP device

  • Description: Edit an existing monitored SNMP device. POST (form data, CSRF checked).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

snmp_host

formData

IP address or symbolic name of and an SNMP device

string

snmp_read_community

formData

The SNMP read community to use (SNMP v1/v2c only). Empty keeps the saved one

string

snmp_write_community

formData

The SNMP write community to use (SNMP v1/v2c only). Empty keeps the saved one

string

snmp_remove_write_community

formData

true removes the saved write community (an empty snmp_write_community keeps it)

boolean

snmp_version

formData

The SNMP version to use: 2 (SNMP v3), 1 (v2c) or 0 (v1)

string

snmp_level

formData

Used only with SNMP v3: noAuthNoPriv, authNoPriv, or authPriv)

string

snmp_auth_protocol

formData

Used only with SNMP v3 and level not set to noAuthNoPriv: MD5 or SHA

string

snmp_auth_passphrase

formData

Used only with SNMP v3 and level not set to noAuthNoPriv: 8 chars+ passphrase. Empty keeps the saved one

string

snmp_privacy_protocol

formData

Used only with SNMP v3 and level set to autPriv: DES or AES

string

snmp_privacy_passphrase

formData

Used only with SNMP v3 and level set to authPriv: 8 chars+ passphrase. Empty keeps the saved one

string

snmp_username

formData

SNMP v3 username

string

snmp_context

formData

SNMP v3 context name

string

Responses

-3 - NOT_GRANTED

-4 - INVALID_HOST

-5 - INVALID_ARGUMENTS

-9 - NAME_RESOLUTION_FAILED

-10 - SNMP_DEVICE_ALREADY_ADDED

-11 - SNMP_DEVICE_UNREACHABLE

-12 - NO_SNMP_DEVICE_DISCOVERED

-22 - SNMP_UNKNOWN_DEVICE

GET /lua/pro/rest/v2/get/snmp/device/bridge.lua

Get bridge MIB information

  • Description: Get bridge MIB information for a single or all SNMP devices

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

The IP address of the SNMP device (optional, all devices are returned if empty)

string

Responses

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/snmp/device/interfaces.lua

Get interfaces information

  • Description: Get interfaces information for a single or all SNMP devices

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

The IP address of the SNMP device (optional, all devices are returned if empty)

string

Responses

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/snmp/device/lldp.lua

Get LLDP adjacency information

  • Description: Get LLDP adjacencies for a single or all SNMP devices

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

The IP address of the SNMP device (optional, all devices are returned if empty)

string

Responses

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/snmp/device/list.lua

Get all SNMP devices

  • Description: Retrieve all configured SNMP devices.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/snmp/device/system.lua

Get system information

  • Description: Get system information (SNMPv2-MIB system group) for a single or all SNMP devices; oid_label is the object id with the hardware model when known. Requires the SNMP capability and access to the system interface.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

The IP address of the SNMP device (optional, all devices are returned if empty)

string

Responses

-3 - NOT_GRANTED

0 - OK

1.4.22. Host

GET /lua/pro/rest/v2/add/interface/host_rules/add_host_rule.lua

Add Host Rule

  • Description: Add an host rule to an interface, used to run periodic check on traffic and similar, on the timeseries

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

Host to apply the check, IP address of the host or * to check for all the hosts

string

frequency

query

Frequency of the check to run, every minute, every 5 minutes, every hour or daily (‘min’, ‘5min’, ‘hour’, ‘day’)

string

metric

query

Timeseries schema of the metric to analyze

string

threshold

query

Threshold that if exceeded, it’s going to trigger an alert

string

metric_type

query

metric used to analyze the data, Throughput or Volume? (currently available: ‘throughput’, ‘volume’)

string

Responses

0 - OK

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

-7 - BAD_FORMAT

GET /lua/pro/rest/v2/delete/interface/host_rules/add_host_rule.lua

Remove an Host Rule

  • Description: Remove an host rule from an interface, used to run periodic check on traffic and similar, on the timeseries

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

rule_id

query

Identifier of the rule to delete

string

Responses

0 - OK

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/pro/rest/v2/get/host/flows/data.lua

Get host flows data

  • Description: Given an host return the information used to create the sankey chart with all the flows information regarding that hosts (protocols, traffic, ecc.)

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

formData

Host address

string

hosts_type

query

Currently available: local_only -> return only flows between local hosts, remote_only -> return only flows between remote hosts, local_origin_remote_target -> return only flows between local clients and remote servers, remote_origin_local_target -> return only flows between local servers and remote clients, all_hosts -> return all flows

string

Responses

0 - OK

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/interface/host_rules/host_rules_data.lua

Get Host Rule

  • Description: Get an host rule to an interface, used to run periodic check on traffic and similar, on the timeseries

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

-7 - BAD_FORMAT

GET /lua/pro/rest/v2/get/interface/host_rules/host_rules_metric.lua

Get Host Rule available metrics

  • Description: Get an host rule available metrics, used to run periodic check on traffic and similar, on the timeseries

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

-7 - BAD_FORMAT

1.4.23. Observation Point

GET /lua/pro/rest/v2/delete/observation_point/stats.lua

Remove an Observation Point stats

  • Description: Remove Observation Point stats stored until now. If the Observation Point is no more seen on the network, even the entry is going to be deleted

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

observation_point

query

Identifier of the rule to delete

integer

Responses

0 - OK

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/pro/rest/v2/delete/observation_points/stats.lua

Delete an Observation Point

  • Description: Given an Observation Point ID, it is going to delete it and all the information related to it

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

observation_point_id

query

Observation Point ID

integer

ifid

query

Interface identifier

integer

Responses

0 - OK

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/observation_points/alias.lua

Get the alias of an Observation Point

  • Description: The alias of an Observation Point (empty string when not set)

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

observation_point

query

Observation Point ID

integer

Responses

0 - OK

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/interface/observation_points/stats.lua

Get the observation points stats

  • Description: Observation points seen on the interface: { observation_point, observation_point_alias, exporters, total_flows, hosts, throughput (bps), traffic (bytes) }. Pro only

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/interface/observation_points/flowexporter_list.lua

Get the flow exporters of an observation point

  • Description: Flow exporters seen on an observation point: [{ exporter_ip, exporter_name (SNMP name with the SNMP capability, else the host name; null when it is the IP) }]. Empty list for an unknown observation point. Pro only

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

obs_point

query

Observation point identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

POST /lua/pro/rest/v2/set/observation_points/alias.lua

Set the alias of an Observation Point

  • Description: Set the alias of an Observation Point. Administrators only

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

alias

formData

New Observation Point Alias (empty: remove it)

string

observation_point

formData

Observation Point ID

integer

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

1.4.24. Pools

GET /lua/pro/rest/v2/get/pool/policy.lua

Get the traffic policy of a host pool

  • Description: Default policy and rules (nDPI markers) of a host pool, with the values usable in the rules (options: [{ value, label }] per kind) and the markers. Rules by kind: l7_proto (nDPI protocol id), l7_category (nDPI category id), host (host name or IP), country (ISO code), continent (code), risk (flow risk id), each [{ value, marker }]; marker = pass | 3 (slow) | 2 (slower) | drop (risks always drop). Pro (not nEdge), pools capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

pool

query

Host pool identifier

integer

Responses

0 - OK

-3 - NOT_GRANTED

-16 - POOL_NOT_FOUND

GET /lua/pro/rest/v2/export/pool/policy.lua

Export pool policies

  • Description: Export pool policies

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

POST /lua/pro/rest/v2/set/pool/policy.lua

Set the traffic policy of a host pool

  • Description: Replaces the traffic policy (nDPI markers) of a host pool. Pro (not nEdge), pools capability, pool allowed to the user.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (no JSON)

-6 - INTERNAL_ERROR

-7 - BAD_FORMAT (not an object, or no pool_id)

POST /lua/pro/rest/v2/set/pool/policy_autoconf.lua

Configure the traffic policy of a host pool from its traffic

  • Description: Replaces the traffic policy of a host pool with one built from the traffic seen by its hosts (default drop, the protocols and the top visited sites allowed). Pro (not nEdge), pools capability.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

POST /lua/rest/v2/add/host/pool.lua

Add an host pool

  • Description: Add an host pool with its members. Needs the Pools capability; users restricted to some pools cannot add pools. rsp: {pool_id} of the new pool.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

pool_name

formData

Host pool name

string

pool_members

formData

Members separated by commas, each <ip or network>/<prefix>@<vlan> or a MAC address (e.g. 192.168.1.10/32@0,10.0.0.0/24@0). Can be empty

string

Responses

0 - POOL_ADDED_SUCCESSFULLY

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-13 - ADD_POOL_FAILED

-53 - ADD_POOL_FAILED_TOO_MANY_POOLS

-54 - ADD_POOL_FAILED_TOO_MANY_POOLS_ENTERPRISE

POST /lua/rest/v2/add/host/pool_member.lua

Add a member to an host pool

  • Description: Administrators only. A member of the Default pool (0) is moved there from any other pool.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - POOL_MEMBER_BOUND_SUCCESSFULLY

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS

-17 - BIND_POOL_MEMBER_FAILED

-18 - BIND_POOL_MEMBER_ALREADY_BOUND: rsp = the pool that already has the member (remove it from there first)

GET /lua/rest/v2/bind/host/pool/member.lua

Bind a member to an host pool

  • Description: Bind a member to an host pool

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

pool

query

Host Pool ID

integer

member

query

IP/MAC/Network CIDR to add to the Host Pool ID

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-17 - BIND_POOL_MEMBER_FAILED

POST /lua/rest/v2/delete/host/pool.lua

Delete an host pool

  • Description: Delete an host pool. Needs the Pools capability and access to the pool.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

pool

formData

Host pool id

integer

Responses

0 - POOL_DELETED_SUCCESSFULLY

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-16 - POOL_NOT_FOUND

POST /lua/rest/v2/delete/host/pool_member.lua

Remove a member from its host pool

  • Description: Administrators only. The member goes back to the Default pool.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - POOL_MEMBER_BOUND_SUCCESSFULLY

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS

-17 - BIND_POOL_MEMBER_FAILED

POST /lua/rest/v2/delete/pools.lua

Delete all pools for any available pool type

  • Description: Delete all pools for any available pool type

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

POST /lua/rest/v2/edit/host/pool.lua

Edit an host pool

  • Description: Rename an host pool and replace its members. Needs the Pools capability and access to the pool.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

pool

formData

Host pool id

integer

pool_name

formData

Host pool name

string

pool_members

formData

Members separated by commas, each <ip or network>/<prefix>@<vlan> or a MAC address. They replace the current members

string

Responses

0 - POOL_EDITED_SUCCESSFULLY

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-14 - EDIT_POOL_FAILED

POST /lua/rest/v2/edit/host/pool/member.lua

Replace a member of an host pool

  • Description: Administrators only. old_member goes back to the Default pool, member joins the pool; refused (old_member unchanged) when member already belongs to another pool.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - POOL_MEMBER_BOUND_SUCCESSFULLY

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS

-17 - BIND_POOL_MEMBER_FAILED

-18 - BIND_POOL_MEMBER_ALREADY_BOUND: rsp = the pool that already has the member (remove it from there first)

POST /lua/rest/v2/edit/host_pool/pool.lua

Edit an host pool pool

  • Description: Edit an host pool pool (only recipients edit is allowed)

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-14 - EDIT_POOL_FAILED

GET /lua/rest/v2/export/pool/config.lua

Export the pools configuration as a JSON file

  • Description: Export the configuration of all pools and dependencies (notifications, SNMP, active monitoring, checks

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

download

query

Download as file (no REST envelope)

boolean

Responses

0 - OK

-3 - NOT_GRANTED

1.4.25. Traffic

GET /lua/pro/rest/v2/get/db/historical_db_search.lua

Get historical flows info

  • Description: Get historical flows info

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (required unless any_interface=true)

integer

any_interface

query

Search the flows of all the interfaces (ifid is ignored)

boolean

query_preset

query

Query preset id (preset/consts.lua), empty for the raw flows

string

aggregated

query

Search the hourly aggregated flows (Enterprise XL)

boolean

visible_columns

query

Comma separated list of the columns to return

string

sort

query

Column to sort by

string

order

query

Sort order

string

start

query

Starting record (e.g. start=100, it will start returning records from the 101st)

integer

length

query

Maximum number of records to get

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

l7proto

query

Application protocol identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

l7proto_master

query

Application protocol identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

l7cat

query

Application category identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

flow_risk

query

Flow risk identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

l4proto

query

Transport protocol identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

ip_version

query

IP version (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_ip

query

Client IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_ip

query

Server IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

traffic_direction

query

Traffic direction identifier, currently available: 0 -> remote only, 1 -> local only, 2 -> remote to local, 3 -> local to remote (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

name

query

Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

cli_name

query

Client Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

srv_name

query

Server Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

network_name

query

Network Name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

src2dst_dscp

query

Client to Server DSCP identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_port

query

Client port (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_port

query

Server port (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

country

query

Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_country

query

Client Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_country

query

Server Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_asn

query

Client ASN identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_asn

query

Server ASN identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_nw_latency

query

Client network latency (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

srv_nw_latency

query

Server network latency (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

observation_point_id

query

Observation point identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

probe_ip

query

Probe IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

vlan_id

query

VLAN ID (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

snmp_interface

query

SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

input_snmp

query

Input SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

output_snmp

query

Output SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

src2dst_tcp_flags

query

Client to Server TCP Flags (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

dst2src_tcp_flags

query

Server to Client TCP Flags (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

mac

query

MAC Address (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_mac

query

Client MAC Address (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_mac

query

Server MAC Address (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

network

query

Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_network

query

Client Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_network

query

Server Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

info

query

Info field (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

bytes

query

Total Bytes (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

packets

query

Total Packets (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

host_pool_id

query

Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

cli_host_pool_id

query

Client Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

srv_host_pool_id

query

Server Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

l7_error_id

query

Application layer error identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_proc_name

query

Client process name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_proc_name

query

Server process name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_user_name

query

Client user name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_user_name

query

Server user name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/rest/v2/connect/test.lua

Test ntopng

  • Description: Test ntopng reachability and authentication

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

1.4.26. Timeseries

GET /lua/pro/rest/v2/get/db/ts.lua

Return the number of flows in a period of time

  • Description: Return the timeseries of number of flows in a period of time

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

l7proto

query

Application protocol identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

l7proto_master

query

Application protocol identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

l7cat

query

Application category identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

flow_risk

query

Flow risk identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

l4proto

query

Transport protocol identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

ip_version

query

IP version (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_ip

query

Client IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_ip

query

Server IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

traffic_direction

query

Traffic direction identifier, currently available: 0 -> remote only, 1 -> local only, 2 -> remote to local, 3 -> local to remote (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

name

query

Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

cli_name

query

Client Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

srv_name

query

Server Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

network_name

query

Network Name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

src2dst_dscp

query

Client to Server DSCP identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_port

query

Client port (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_port

query

Server port (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

country

query

Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_country

query

Client Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_country

query

Server Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_asn

query

Client ASN identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_asn

query

Server ASN identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_nw_latency

query

Client network latency (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

srv_nw_latency

query

Server network latency (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

observation_point_id

query

Observation point identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

probe_ip

query

Probe IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

vlan_id

query

VLAN ID (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

snmp_interface

query

SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

input_snmp

query

Input SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

output_snmp

query

Output SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

src2dst_tcp_flags

query

Client to Server TCP Flags (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

dst2src_tcp_flags

query

Server to Client TCP Flags (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

mac

query

MAC Address (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_mac

query

Client MAC Address (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_mac

query

Server MAC Address (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

network

query

Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_network

query

Client Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_network

query

Server Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

info

query

Info field (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

bytes

query

Total Bytes (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

packets

query

Total Packets (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

host_pool_id

query

Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

cli_host_pool_id

query

Client Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

srv_host_pool_id

query

Server Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

l7_error_id

query

Application layer error identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_proc_name

query

Client process name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_proc_name

query

Server process name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_user_name

query

Client user name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_user_name

query

Server user name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

FILE - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

-7 - BAD_FORMAT

POST /lua/pro/rest/v2/get/timeseries/ts_multi.lua

Return timeseries

  • Description: Return the requested timeseries in the requested timeframe

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

limit

query

Maximum number of timeseries points

number

ts_compare

query

Choices available: ‘30m’, ‘1h’, ‘1d’. A string reporting the timeframe of the timeseries to be compared to (e.g. ‘30m’, means to return other then the timeserie requested, the 30 minutes before)

string

ts_requests

query

An array of timeseries to be returned, containing ts_query, ts_schema and tskey (e.g. [{ts_query: ‘ifid:1,asn:199524’, ts_schema: ‘asn:traffic’, tskey: ‘199524’}]; the explaination of these three parameters can be found into ‘/lua/rest/v2/get/timeseries/ts.lua’ REST)

array

Responses

0 - OK

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

1.4.27. Flow Exporters

GET /lua/pro/rest/v2/get/exporters/get_exporters_interfaces_stats.lua

Get the flow exporters interfaces

  • Description: Interfaces of the flow exporters (routers, switches) sending flows to the interface, with their traffic since startup. Pro only

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

interface_role

query

Only the interfaces with this SNMP role (other, transit, ix, peering, customer_interface, internet_connectivity, internal_interface)

string

deviceIP

query

Only the interfaces of this flow exporter IP

string

Responses

0 - OK: list of { exporter_ip, exporter_name, interface_id, interface_name, role: { value, label }, probe_source_id, exporter_source_id, ifid, bytes_sent, bytes_rcvd, total_bytes }

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/flowdevices/get_top_exporters_interfaces.lua

Get the top flow exporters interfaces

  • Description: The 7 flow exporters interfaces with the most traffic, same filters and fields as get_exporters_interfaces_stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

interface_role

query

Only the interfaces with this SNMP role (other, transit, ix, peering, customer_interface, internet_connectivity, internal_interface)

string

deviceIP

query

Only the interfaces of this flow exporter IP

string

Responses

0 - OK: list of at most 7 interfaces, by total_bytes desc

-2 - INVALID_INTERFACE

GET /lua/pro/rest/v2/get/sflowdevice/interfaces.lua

Get the interfaces of an sFlow device

  • Description: Ports of an sFlow device from its sFlow counters, raw values: [{ ifindex, name (SNMP, null without it), has_snmp, has_timeseries, iftype, speed (bps), full_duplex, is_up, promisc, in_bytes, out_bytes, in_errors, out_errors, ratio (Counters/SNMP, null when not available, -1 not computable), ratio_status }], is_ratio_available. Pro only, needs the flow devices capability (SNMP fields: SNMP capability)

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

ip

query

sFlow device IP

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/sflowdevices/list.lua

Get the sFlow devices

  • Description: sFlow devices (agents exporting sFlow counters) seen on the interface: { ip, has_snmp, snmp_name, snmp_descr, snmp_location }. The SNMP fields need the SNMP capability. Pro only, needs the flow devices capability

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

1.4.28. Peers

GET /lua/pro/rest/v2/get/host/no_tx_peers.lua

Get RX-only host peers

  • Description: Get list of host with RX-only traffic (i.e. no TX traffic sent)

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

1.4.29. Top

GET /lua/pro/rest/v2/get/host/top/local/sites.lua

Get host top local sites

  • Description: Get host top local sites

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

The IP address of the host

string

vlan

query

VLAN of the host (default 0)

integer

hour

query

Time range: current, last_5_min, day (yesterday) or the hour of today (0-23)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED (not ntopng Pro)

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/pro/rest/v2/get/interface/top/l7_stats.lua

Get interface top Layer-7 stats

  • Description: Get interface top Layer-7 stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/pro/rest/v2/get/interface/top/realtime_traffic.lua

Get interface top traffic stats

  • Description: Get interface top traffic stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/pro/rest/v2/get/interface/top/score.lua

Get interface top score stats

  • Description: Get interface top score stats

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

1.4.30. System

GET /lua/pro/rest/v2/get/infrastructure/data.lua

Get infrastructure data

  • Description: Get infrastructure data

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/system/data.lua

Get system data

  • Description: Get system data

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

POST /lua/rest/v2/delete/system/all_data.lua

Purge all ntopng data

  • Description: Request a full purge of the ClickHouse database and/or of the whole data directory (RRDs, etc.). Actual deletion is performed at the next restart as data is currently in use

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

clickhouse

formData

Request the purge of the ClickHouse database

boolean

datadir

formData

Request the purge of the whole data directory (RRDs, etc.)

boolean

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

1.4.31. Sites

GET /lua/pro/rest/v2/get/interface/top/sites.lua

Get interface top sites

  • Description: Get the top sites for an interface

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/pro/rest/v2/get/sites/list.lua

Get the sites

  • Description: List of the configured sites (id, name, description, latitude, longitude, networks, reserved). Needs an Enterprise M license (or higher).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

1.4.32. Maps

GET /lua/pro/rest/v2/get/interface/map/data.lua

Get the graph of a service or periodicity map

  • Description: Nodes (hosts, MACs: id, label, type local|remote|multicast|broadcast|mac, is_active, device group) and edges (from, to, value = number of services, bidirectional, protocols = up to 3 application names, num_protocols, status = worst service status) of the map, at most 2500 services (max_entry_reached).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

map

query

Map

string

host

query

Only the services of this host: IP or MAC, with @vlan for the VLAN hosts

string

vlan_id

query

VLAN identifier

integer

host_pool_id

query

Host pool identifier

integer

l7proto

query

Application protocol name (e.g. DNS)

string

network

query

Local network identifier

integer

service_status

query

Service map only: 0 authorized, 1 unauthorized, 2 undecided

integer

traffic_direction

query

Periodicity map only: 0 local only, 1 remote only, 2 local client and remote server, 3 remote client and local server

integer

unicast_only

query

Only unicast hosts

boolean

first_seen

query

Only the services seen after this epoch

integer

Responses

0 - OK

-2 - INVALID_INTERFACE (missing ifid, or an interface the user cannot see) or NOT_ENABLED (behaviour analysis disabled on the interface)

-5 - INVALID_ARGUMENTS (unknown map)

GET /lua/pro/rest/v2/get/interface/map/table.lua

Get the services of a service or periodicity map

  • Description: One page of the services (view=standard: client, server, port, protocols, uses/observations, frequency, first/last seen, status) or of the hosts ranked by centrality (view=centrality: host, rank, edges). Peers are objects { host, ip, vlan, is_mac, name, active }. recordsTotal is the number of entries.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

map

query

Map

string

view

query

Services or hosts ranking

string

host

query

Only the services of this host: IP or MAC, with @vlan for the VLAN hosts

string

vlan_id

query

VLAN identifier

integer

host_pool_id

query

Host pool identifier

integer

l7proto

query

Application protocol name (e.g. DNS)

string

network

query

Local network identifier

integer

service_status

query

Service map only: 0 authorized, 1 unauthorized, 2 undecided

integer

traffic_direction

query

Periodicity map only: 0 local only, 1 remote only, 2 local client and remote server, 3 remote client and local server

integer

unicast_only

query

Only unicast hosts

boolean

first_seen

query

Only the services seen after this epoch

integer

start

query

Row offset

integer

length

query

Rows per page

integer

sort

query

Sort column

string

order

query

Sort order

string

map_search

query

Text to search in the hosts

string

Responses

0 - OK

-2 - INVALID_INTERFACE (missing ifid, or an interface the user cannot see) or NOT_ENABLED (behaviour analysis disabled on the interface)

-5 - INVALID_ARGUMENTS (unknown map)

GET /lua/pro/rest/v2/get/interface/map/filters.lua

Get the filter values of a service or periodicity map

  • Description: VLANs, application protocols, host pools ({ id, name }) and local networks ({ id, name }) seen by the map, optionally only for one host.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

map

query

Map

string

host

query

Only the services of this host: IP or MAC, with @vlan for the VLAN hosts

string

vlan_id

query

VLAN identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE (missing ifid, or an interface the user cannot see) or NOT_ENABLED (behaviour analysis disabled on the interface)

-5 - INVALID_ARGUMENTS (unknown map)

POST /lua/pro/rest/v2/edit/interface/map/service_status.lua

Set the status of a service of the service map

  • Description: Marks a service of the service map as authorized (0), unauthorized (1) or undecided (2). Administrators only.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

Responses

0 - OK

-2 - INVALID_INTERFACE (missing ifid, or an interface the user cannot see) or NOT_ENABLED (behaviour analysis disabled on the interface)

-5 - INVALID_ARGUMENTS (unknown map)

-3 - NOT_GRANTED (administrators only)

POST /lua/pro/rest/v2/delete/interface/map/data.lua

Delete the services of a service or periodicity map

  • Description: Deletes all the services learnt by the map of the interface: the map learns them again from the new traffic. Administrators only.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

Responses

0 - OK

-2 - INVALID_INTERFACE (missing ifid, or an interface the user cannot see) or NOT_ENABLED (behaviour analysis disabled on the interface)

-5 - INVALID_ARGUMENTS (unknown map)

-3 - NOT_GRANTED (administrators only)

1.4.33. User

POST /lua/rest/v2/create/ntopng/api_token.lua

Create an API token

  • Description: Create an API token

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

username

formData

An existing ntopng username

string

Responses

0 - OK

-5 - INVALID_ARGUMENTS

1.4.34. Checks

GET /lua/rest/v2/delete/application/application.lua

Remove a custom protocol

  • Description: If run ntopng using -p option, delete a custom protocol if it exists

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

protocol_alias

form

Application Name

string

Responses

0 - OK

-3 - NOT_GRANTED

POST /lua/rest/v2/disable/check.lua

Disables a check

  • Description: Disables a check

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

check_subdir

form

The check subdir

string

script_key

form

The key of the script

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/edit/application/application.lua

Edit a custom protocol

  • Description: If run ntopng using -p option, edit a custom protocol if it exists

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

protocol_alias

form

Application Name

string

category

form

Category ID

integer

l7_proto_id

form

Application ID

integer

custom_rules

form

List of custom rules separated by commas

string

Responses

0 - OK

-3 - NOT_GRANTED

POST /lua/rest/v2/enable/check.lua

Enables a check

  • Description: Enables a check

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

check_subdir

form

The check subdir

string

script_key

form

The key of the script

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/export/checks/config.lua

Export Checks configuration

  • Description: Export Checks configuration

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

1.4.35. Notification Endpoints

POST /lua/rest/v2/delete/endpoints.lua

Delete all defined notification endpoints and reset them to factory-defaults

  • Description: Delete all defined notification endpoints and reset them to factory-defaults

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

1.4.36. Assets

POST /lua/pro/rest/v2/add/assets/assets.lua

Import assets

  • Description: Import the assets of a CSV file (as exported by export/assets/assets.lua). Enterprise M, administrators only

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

assets

formData

CSV content

string

Responses

0 - OK

-3 - NOT_GRANTED

-7 - BAD_FORMAT

GET /lua/pro/rest/v2/export/assets/assets.lua

Export assets

  • Description: The assets of every interface as CSV (is_snmp=true: the SNMP assets). Enterprise M, administrators only

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

is_snmp

query

true for the SNMP assets

string

Responses

0 - OK

-3 - NOT_GRANTED

POST /lua/pro/rest/v2/set/assets/wazuh_info.lua

Merge the Wazuh agents info into the assets

  • Description: Read the agents from the Wazuh API and update the matching assets of the interface. Enterprise M, administrators only, needs the Wazuh API configured

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

formData

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

POST /lua/pro/rest/v2/delete/host/asset.lua

Delete assets

  • Description: Delete one asset (serial_key = its key), all the assets (serial_key = all), or the ones not seen since an epoch (serial_key = epoch). The journal of the assets records the deletions: one entry for one asset, a single entry with their number (no asset key) for several assets deleted at once. Administrators only

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

formData

Interface identifier

integer

serial_key

formData

Asset key, all, or an epoch

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

POST /lua/pro/rest/v2/delete/host/asset_tag.lua

Remove a tag from an asset

  • Description: Remove a user-defined tag (32-63) from an asset and from all its hosts (the hosts of its IP on every VLAN of the asset, also the inactive ones). The journal of the assets records the removal. The built-in tags (0-31) are set by the hosts and cannot be removed. Enterprise M, administrators only

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

Responses

0 - OK

-1 - NOT_FOUND (no such asset, or the asset has not the tag)

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

1.4.37. L7 Application Categories

GET /lua/rest/v2/edit/category/category.lua

Change the custom hosts for a specific category

  • Description: Given a category, an alias for the category and a list of hosts, networks or domain names, separated by comma, it is going to change the alias of the category and aggregate the traffic done by those hosts into the category

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

category

query

Category, formatted as cat_{id}, where ID is the ID of the category

string

custom_hosts

query

List of Hosts, Networks, Domain Names, separated by comma

string

alias

query

Alias of the Category

string

Responses

0 - OK

1.4.38. Configuration

POST /lua/rest/v2/edit/ntopng/incr_flows.lua

Double the maximum number of flows managed by ntopng

  • Description: Double the maximum number of flows managed by ntopng

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

-7 - BAD_FORMAT

POST /lua/rest/v2/edit/ntopng/incr_hosts.lua

Double the maximum number of hosts managed by ntopng

  • Description: Double the maximum number of hosts managed by ntopng

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

-7 - BAD_FORMAT

1.4.39. All

GET /lua/rest/v2/export/all/config.lua

Export all configurations as a JSON file

  • Description: Export all configurations including Pools, Active Monitoring, Notifications (Endpoints and Recipients), Checks, SNMP devices

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

download

query

Download as file (no REST envelope)

boolean

Responses

0 - OK

-3 - NOT_GRANTED

1.4.40. Notifications

GET /lua/rest/v2/export/notifications/config.lua

Export the notifications configuration as a JSON file

  • Description: Export the configuration for endpoints and recipients

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

download

query

Download as file (no REST envelope)

boolean

Responses

0 - OK

-3 - NOT_GRANTED

1.4.41.

GET /lua/rest/v2/export/scripts/config.lua

Export the Checks configuration as a JSON file

  • Description: Export the configuration for all checks

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

download

query

Download as file (no REST envelope)

boolean

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/rest/v2/export/snmp/config.lua

Export the SNMP configuration as a JSON file

  • Description: Export the configuration for the SNMP devices

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

download

query

Download as file (no REST envelope)

boolean

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/rest/v2/get/alert/filter/consts.lua

Get available alert filters

  • Description: Given a specific alert type (flow, host, …) return the available filters

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

page

query

Alert Page (all, interface, flow, host, network, as, snmp_device, mac, user, am_host, system), default all

string

Responses

0 - OK

-3 - NOT_GRANTED: the user has no alerts capability

GET /lua/rest/v2/get/alert/list/alerts.lua

List stored interface alerts

  • Description: List alerts stored in the ntopng alert database

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

alert_family

query

Alert family. Possible values: active_monitoring, flow, host, interface, mac , network , snmp , system , user

string

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

select_clause

query

Select clause (default: *)

string

where_clause

query

Where clause (default: none). IP values should be double-quoted and between parenthesis (e.g. IPV4_SRC_ADDR = (“192.168.1.1”)).

string

maxhits_clause

query

Max hits (default: 10)

integer

order_by

query

Order by clause (default: no order)

string

group_by

query

Group by clause (default: no group)

string

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/alert/severity/consts.lua

Get alert severity constants

  • Description: Alert severity string and integer severity id for each defined severity

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

GET /lua/rest/v2/get/alert/severity/counters.lua

Get alert counters by severity

  • Description: Alert severity counters in descending order

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

status

query

Status filter (historical, historical-flows)

string

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

Start time (epoch)

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/alert/type/consts.lua

Get alert type constants

  • Description: Alert type string and integer alert key for each defined alert

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

GET /lua/rest/v2/get/alert/type/counters.lua

Get alert counters by type

  • Description: Alert type counters indescending order

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

status

query

Status filter (historical, historical-flows)

string

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/all/alert/list.lua

Get all alerts list

  • Description: Get all alerts list

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

start

query

Starting record (e.g. start=100, it will start returning records from the 101st)

integer

length

query

Maximum number of records to get

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

format

query

Format of the return data (json or txt)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/all/alert/ts.lua

Get all alerts timeseries

  • Description: Get all alerts timeseries

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

Start time (epoch)

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/am_host/alert/list.lua

Get Active Monitoring alerts list

  • Description: Get Active Monitoring alerts list

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

start

query

Starting record (e.g. start=100, it will start returning records from the 101st)

integer

length

query

Maximum number of records to get

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

format

query

Format of the return data (json or txt)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/am_host/alert/ts.lua

Get Active Monitoring alerts timeseries

  • Description: Get Active Monitoring alerts timeseries

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

POST /lua/rest/v2/get/asn/asn_info.lua

Get Autonomous systems data

  • Description: Return the ASN data ntopng collected from analyzing the network. If an ASN is given, then return the data regarding the requested ASN

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

asn

formData

Autonomous System ID

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

POST /lua/rest/v2/get/asn/asn_name.lua

Get Autonomous systems name

  • Description: Return the ASN name given an IP

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ip

query

IP Address

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/asn/get_as_data.lua

Get the autonomous systems of an interface with their traffic

  • Description: Live: the active ASes of the interface (since startup). Historical (is_live=false, needs ClickHouse): the ASes of the flows in [epoch_begin, epoch_end]. rsp is an array of records: asn, asname (none for ASN 0, the private hosts), num_hosts, avg_host_score, score, alerted_flows, seen_since (epoch), bytes_sent, bytes_rcvd, traffic, throughput (bps), breakdown {bytes_sent, bytes_rcvd}, breakdown_role {bytes_other, bytes_transit, bytes_peering, bytes_ix}, is_customer_asn / is_sub_customer_asn / is_remote_asn (ASN configuration), is_in_memory (historical only: the AS has active hosts now).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

is_live

query

true (default) live data, false historical data (ClickHouse)

boolean

epoch_begin

query

Historical only: start of the time range (epoch)

integer

epoch_end

query

Historical only: end of the time range (epoch)

integer

show_as

query

all (default), my_as, my_customer_as, remote_as or other_as (ASN configuration)

string

interface_role

query

Enterprise M: all (default), ix, peering or transit (SNMP interface role)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-61 - CLICKHOUSE_MISSING (historical data without ClickHouse)

GET /lua/rest/v2/get/asn/get_top_asn.lua

Get the top autonomous systems of an interface

  • Description: The top ASes by traffic, live or in [epoch_begin, epoch_end] (is_live=false, needs ClickHouse): used for the top ASN chart. rsp is an array of AS records (asn, asname, traffic and the per-role bytes).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

is_live

query

true (default) live data, false historical data (ClickHouse)

boolean

epoch_begin

query

Historical only: start of the time range (epoch)

integer

epoch_end

query

Historical only: end of the time range (epoch)

integer

show_as

query

all (default), my_as, my_customer_as, remote_as or other_as

string

interface_role

query

Enterprise M: all (default), ix, peering or transit

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-61 - CLICKHOUSE_MISSING

GET /lua/rest/v2/get/category/list.lua

Get category information

  • Description: Get all the category information available

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/rest/v2/get/checks/check_config.lua

Get the configuration of a check

  • Description: Return the configuration of a check: per-hook configuration, available severities, GUI metadata and the tags added to its alerts (and to the issues they open or update), with the tags that can be assigned

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

check_subdir

query

Family of the check (e.g. host, flow, interface)

string

script_key

query

Key of the check

string

factory

query

true to return the factory defaults (no tags)

boolean

Responses

0 - OK. rsp: hooks, severities, gui, default_value, field_metadata, tags (array of tag ids), available_tags (array of {id, name, color})

-1 - NOT_FOUND

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/checks/config.lua

Get Checks configuration

  • Description: Get checks configuration

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

download

query

Download the data or not

boolean

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/rest/v2/get/checks/list.lua

List the checks

  • Description: Return the checks of a family with their status, severity and the tags added to their alerts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

check_subdir

query

Family of the checks (e.g. host, flow), all for every family

string

ifid

query

Interface ID

integer

status

query

all (default), enabled or disabled

string

Responses

0 - OK. rsp: array of {key, subdir, title, description, category_key, category_icon, severity_key, severity_icon, is_enabled, enabled_hooks, tags (array of {id, name, color}), is_editable}

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

POST /lua/rest/v2/get/country/country_name.lua

Get Country Name

  • Description: Return the Country name given a country code

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

country_id

query

Country Code

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/country/list.lua

Get the countries of the active hosts

  • Description: The countries (from the geolocation database) of the hosts active on the interface. rsp is an array of records: name (ISO 3166 country code), hosts (active hosts), seen_since (epoch of the first packet), score, bytes_sent, bytes_rcvd, traffic (bytes), throughput (bps). recordsTotal/recordsFiltered: number of countries. Any user can call it (interface restrictions apply).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/rest/v2/get/dns/resolve.lua

Resolve an host name into an IP address

  • Description: Resolve an host name into an IP address

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

hostname

query

The host name to be resolved

string

Responses

0 - OK

-9 - NAME_RESOLUTION_FAILED

GET /lua/rest/v2/get/flow/live/overview.lua

Get the details of a live flow

  • Description: One active flow: rsp.flow is the flow as exported by the engine (raw keys, e.g. cli2srv.bytes, protos.tls.client_requested_server_name, tcp.nw_latency.3wh_client_rtt), rsp.ext what the server resolves: host names (cli_name, srv_name), VLAN alias, tags, AS/site/exporter/observation point names, the issues (alert id, nDPI risk id, source, score, i18n key of the title, info, MITRE id and tactic), SIP/RTP values, the additional exported fields with their description, the protocol views of the flow (views: modbus, bgp, s7comm, profinet) and the user capabilities (is_admin, can_disable_check). Flows of hosts outside the allowed networks of the user are not found.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

flow_key

query

Flow key (key of the live flows list)

integer

flow_hash_id

query

Flow hash id (hash_id of the live flows list)

integer

counters

query

true: only rsp.flow and rsp.now (for polling the live values)

boolean

bgp

query

true: also rsp.ext.bgp_info (BGP/BMP information of the peers)

boolean

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/category/host_rule_context.lua

Get the context of a custom host rule

  • Description: For a server name or URL: the host name suggested for a custom host rule, the custom category that already matches it, and the nDPI categories and applications (applications only with a protos file) it can be added to. Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

Server name or URL (e.g. www.example.com)

string

Responses

0 - OK

-3 - NOT_GRANTED

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

POST /lua/rest/v2/add/category/host_rule.lua

Add a custom host rule

  • Description: Adds a host to a custom category (applied at once) or to an application (written in the protos file, applied after a restart). Exactly one of category_id and application_id. rsp.restart_needed: true for an application. BAD_CONTENT: the host is already in the category. Administrators only.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-8 - BAD_CONTENT

GET /lua/rest/v2/get/flow/active.lua

Get active flows

  • Description: List of active flows

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

currentPage

query

Pagination: page (optional)

integer

perPage

query

Pagination: items per page (optional)

integer

sortColumn

query

Pagination: column for sorting (e.g. ‘score’) (optional)

string

sortOrder

query

Pagination: sorting order: ‘asc’ or ‘desc’ (optional)

string

host

query

Host address filter (optional)

string

vlan

query

VLAN ID filter (optional)

integer

l4proto

query

L4 protocol filter (optional)

string

application

query

Application protocol filter (optional)

string

verbose

query

Add more details including TCP stats (optional)

boolean

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/flow/alert/list.lua

Get flow alerts list

  • Description: Get flow alerts list

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

start

query

Starting record (e.g. start=100, it will start returning records from the 101st)

integer

length

query

Maximum number of records to get

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

ip_version

query

IP version (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_ip

query

Client IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_ip

query

Server IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_name

query

Client Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

srv_name

query

Server Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

cli_port

query

Client port (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_port

query

Server port (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

vlan_id

query

VLAN ID (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

l7proto

query

Application protocol identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_country

query

Client Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_country

query

Server Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

probe_ip

query

Probe IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

input_snmp

query

Input SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

output_snmp

query

Output SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

snmp_interface

query

SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_host_pool_id

query

Client Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

srv_host_pool_id

query

Server Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

cli_network

query

Client Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_network

query

Server Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

l7_error_id

query

Application layer error identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

custom_script

query

Title of a custom flow script that triggered the alert, with operator: <title>;eq, <title>;neq, <text>;in (title contains it), <text>;nin. Matches any of the scripts of the custom alert, also when it is not the main alert of the flow

string

traffic_direction

query

Traffic direction identifier, currently available: 0 -> remote only, 1 -> local only, 2 -> remote to local, 3 -> local to remote (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

format

query

Format of the return data (json or txt)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/flow/alert/ts.lua

Get flow alerts timeseries

  • Description: Get flow alerts timeseries

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

ip_version

query

IP version (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_ip

query

Client IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_ip

query

Server IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_name

query

Client Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

srv_name

query

Server Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

cli_port

query

Client port (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_port

query

Server port (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

vlan_id

query

VLAN ID (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

l7proto

query

Application protocol identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_country

query

Client Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_country

query

Server Country ID, e.g. IT (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

probe_ip

query

Probe IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

input_snmp

query

Input SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

output_snmp

query

Output SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

snmp_interface

query

SNMP interface identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

cli_host_pool_id

query

Client Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

srv_host_pool_id

query

Server Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

cli_network

query

Client Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

srv_network

query

Server Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

l7_error_id

query

Application layer error identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

traffic_direction

query

Traffic direction identifier, currently available: 0 -> remote only, 1 -> local only, 2 -> remote to local, 3 -> local to remote (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/flow/alert/geomap.lua

Get flow alerts by country

  • Description: Flow alerts aggregated per host (client and server) and per country (GeoIP), with the same filters as the flow alerts list. Requires GeoIP and ClickHouse.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

status

query

Alerts status: ‘historical’ (require attention, default), ‘engaged’ or ‘any’

string

alert_id

query

Alert type (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

severity

query

Severity (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

score

query

Score (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

cli_ip

query

Client IP (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

srv_ip

query

Server IP (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED: no alerts capability or GeoIP not available

-6 - INTERNAL_ERROR: ClickHouse not enabled

GET /lua/rest/v2/get/flow/l4/counters.lua

Get flow counters for L4 protocols

  • Description: Number of active flows per L4 protocol

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/flow/l7/counters.lua

Get flow counters for L7 protocols

  • Description: Number of active flows per L7 application protocol

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/flow/traffic_stats.lua

Get traffic stats for active flows

  • Description: Get traffic stats for active flows

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/rest/v2/get/geo_map/hosts.lua

Get the geolocated hosts of an interface

  • Description: The active hosts with a known location (latitude/longitude from the geolocation database), at most 512. rsp is an array of records: ip, name, vlan {id, name}, lat, lng, country (ISO 3166 alpha-3), country_code (alpha-2), country_id, city (when known), scoreClient, scoreServer, numAlerts (alerted active flows), isAlert (score > 0), isRoot. Any user can call it (interface and network restrictions apply).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

hosts_category

query

0 active hosts by traffic (default), 1 alerted hosts by score, 2 local hosts, 3 remote hosts

integer

host

query

When set, the hosts the given host is talking with (active flows) instead of the category

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/host/active.lua

Get active hosts

  • Description: List of active hosts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

currentPage

query

Pagination: page (optional)

integer

perPage

query

Pagination: items per page (optional)

integer

sortColumn

query

Pagination: column for sorting (e.g. ip, name, since, last, alerts, country, vlan, num_flows, traffic, thpt) (optional)

string

sortOrder

query

Pagination: sorting order: ‘asc’ or ‘desc’ (optional)

string

all

query

Get all hosts (optional)

boolean

mode

query

Mode filter: all, local, remote, broadcast_domain, filtered, blacklisted, dhcp (optional)

string

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/host/active_list.lua

Get the active hosts list

  • Description: Active hosts of the interface, one page at a time, with the filters of the Hosts page. Each row: host (ip, vlan, mac, os, country and flags), hostname, first_seen, last_seen, throughput, bytes, alerts, num_flows, score, isBlocked (nEdge), location (nEdge). recordsTotal is the number of hosts matching the filters. Only the hosts of the networks the user is allowed to see are listed.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (optional, default: the selected one). An interface the user cannot access answers INVALID_INTERFACE

integer

start

query

Pagination: index of the first host (optional)

integer

length

query

Pagination: number of hosts (optional)

integer

sort

query

Sort column: ip_address, hostname, vlan, num_flows, alerts, score, first_seen, throughput, bytes (optional)

string

order

query

Sort order: asc or desc (optional)

string

map_search

query

Text search on the hosts (optional)

string

mode

query

Hosts filter: local, local_no_tx, local_no_tcp_tx, remote, remote_no_tx, remote_no_tcp_tx, broadcast_domain, broadcast_multicast, filtered, blacklisted, dhcp (optional)

string

version

query

IP version: 4 or 6 (optional)

integer

traffic_type

query

Direction: one_way or bidirectional (optional)

string

vlan

query

VLAN id (optional)

integer

network

query

Local network id (optional)

integer

network_cidr

query

Network in CIDR format (optional)

string

pool

query

Host pool id (optional)

integer

asn

query

Autonomous System number (optional)

integer

country

query

Country code, e.g. IT (optional)

string

os

query

Operating system id (optional)

integer

mac

query

MAC address (optional)

string

protocol

query

nDPI application protocol id (optional)

integer

deviceIP

query

Flow exporter IP (optional)

string

location

query

nEdge only: lan, wan or unknown (optional)

string

label

query

Host tag id (optional)

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/rest/v2/get/host/alert/list.lua

Get host alerts list

  • Description: Get host alerts list

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

start

query

Starting record (e.g. start=100, it will start returning records from the 101st)

integer

length

query

Maximum number of records to get

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

vlan_id

query

VLAN ID (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

ip_version

query

IP version (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

name

query

Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

host_pool_id

query

Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

network

query

Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

format

query

Format of the return data (json or txt)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/host/alert/ts.lua

Get host alerts timeseries

  • Description: Get host alerts timeseries

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

vlan_id

query

VLAN ID (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

ip_version

query

IP version (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

ip

query

IP (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

name

query

Hostname (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘in’ -> contains, ‘nin’ -> not contains)

string

host_pool_id

query

Host Pool identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

string

network

query

Network identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/host/alert/geomap.lua

Get host alerts by country

  • Description: Host alerts aggregated per host and per country (GeoIP), with the same filters as the host alerts list. Requires GeoIP and ClickHouse.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

status

query

Alerts status: ‘historical’ (require attention, default), ‘engaged’ or ‘any’

string

alert_id

query

Alert type (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

severity

query

Severity (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

score

query

Score (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

ip

query

Host IP (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED: no alerts capability or GeoIP not available

-6 - INTERNAL_ERROR: ClickHouse not enabled

GET /lua/rest/v2/get/host/custom_data.lua

Get host custom data

  • Description: Custom data is returned for one or all hosts

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

Host address

string

field_alias

query

Field alias

string

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-4 - INVALID_HOST

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

-7 - BAD_FORMAT

-8 - BAD_CONTENT

GET /lua/rest/v2/get/host/data.lua

Get host data

  • Description: Host data is returned

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

Host address (IP or IP@VLAN if traffic is tagged)

string

host_stats

query

false: without the host statistics (default: included)

boolean

host_stats_flows

query

true: also the active flows of the host (default: not included)

boolean

limit

query

Maximum number of flows returned with host_stats_flows=true

integer

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-4 - INVALID_HOST

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

-7 - BAD_FORMAT

-8 - BAD_CONTENT

GET /lua/rest/v2/get/host/used_ports.lua

Get the ports of a host

  • Description: The server ports an active host answered on (local_server_ports) and the server ports it contacted (remote_contacted_ports), each as “<l4 proto>:<port>” -> application.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

Host address (IP or IP@VLAN if traffic is tagged)

string

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/host/icmp.lua

Get the ICMP messages of a host

  • Description: The ICMP messages of an active host per version (ICMPv4, ICMPv6): “<type>,<code>” -> packets sent and rcvd, last_host_sent_peer and last_host_rcvd_peer.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

Host address (IP or IP@VLAN if traffic is tagged)

string

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/host/dns.lua

Get the DNS counters of a host

  • Description: The DNS counters of an active host (dns.sent / dns.rcvd: num_queries, num_replies_ok, num_replies_error and the queries per type) and the DoH/DoT servers it used (doh_dot: ip, vlan_id, num_uses).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

Host address (IP or IP@VLAN if traffic is tagged)

string

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/host/http.lua

Get the HTTP counters of a host

  • Description: The HTTP counters of an active host: requests sent per method (http.sender.query), responses received per code (http.receiver.response) and the virtual hosts it served (http.virtual_hosts: bytes sent/rcvd, requests).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

Host address (IP or IP@VLAN if traffic is tagged)

string

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/host/overview.lua

Get the overview of a host

  • Description: An active host as raw values (host): identity and flags (MAC, router, VLAN, OS, ASN, network, country, local/private/multicast/broadcast/blacklisted…), first/last seen, bytes and packets sent/rcvd, local/non-local bytes, score as client/server with its network/security breakdown, active/total/alerted/unreachable flows, blacklisted and unidirectional TCP flows, peers, unresponsive peers, contacted servers, TCP retransmissions/out of order/lost/keep-alive, alerts, names, OS learning, flow exporter. ext: pool, symbolic MAC and device type, local network alias and site, host tags (name, or name_i18n for the built-in ones), asset key, ICMP active monitoring state, notes, page flags. counters=true: only host.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

Host address (IP or IP@VLAN if traffic is tagged)

string

counters

query

true: only the host values (no ext), for the live updates

boolean

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/host/dscp/stats.lua

Get IP DSCP statistics for a host

  • Description: DSCP statistics

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

Host address

string

vlan

query

VLAN ID

integer

direction

query

Select direction: ‘sent’ or ‘recvd’ (default)

boolean

Responses

0 - OK

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/host/fingerprint/data.lua

Get the client fingerprints of a host

  • Description: Given an host, return its JA4 (TLS) or HASSH (SSH) client fingerprints with the application name, the number of uses and the malicious flag

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

Host address

string

vlan

query

VLAN ID

integer

fingerprint_type

query

The fingerprint type

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/host/interfaces.lua

Get host interfaces

  • Description: All interface ids of a given host are returned

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

formData

Interface identifier

integer

host

formData

Host address

string

vlan

formData

VLAN ID

integer

Responses

0 - OK

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/host/l4/data.lua

Get the host information about transport protocols

  • Description: Given an host, return the transport protocols information (bytes sent, received, …) of an host

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

Host address

string

vlan

query

VLAN ID

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/rest/v2/get/host/l7/data.lua

Get the nDPI applications or categories of a host

  • Description: Given an host, return its nDPI applications (bytes sent, received, duration, share) or its nDPI categories (with their applications)

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

Host address

string

vlan

query

VLAN ID

integer

view

query

applications, or categories (any other value)

string

Responses

0 - OK

-4 - INVALID_HOST

GET /lua/rest/v2/get/host/l7/stats.lua

Get L7 statistics for a host

  • Description: nDPI statistics

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

Host address

string

vlan

query

VLAN ID

integer

breed

query

Show breed

boolean

ndpi_category

query

Show nDPI category

boolean

collapse_stats

query

Collapse the returned stats into ‘Other’ stats if bytes/flows are too low (< 3%)

boolean

Responses

0 - OK

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/pro/rest/v2/get/host/assets.lua

Get the assets inventory

  • Description: Assets of the interface (page=snmp: the SNMP assets of the system interface), paginated. The VLAN is not part of the identity of a host asset: host.vlans [{ id, name, online }] lists the VLANs where its IP has been seen, with the state of the host of each one (the asset is online when any of them is); host.vlan is the VLAN seen last. Enterprise M only. Needs the historical flows capability (non-admin users).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

page

query

snmp: the SNMP assets

string

start

query

First record

integer

length

query

Number of records

integer

sort

query

Column (ip_address, name, mac_address, vlan, network, device_type, manufacturer, first_seen, last_seen, os (the OS tag), model, status, switch_ip, switch_port)

string

order

query

asc or desc

string

manufacturer

query

Filter

string

vlan

query

Filter: one of the VLANs of the asset

integer

device_type

query

Filter

integer

network

query

Filter

integer

status

query

0 online, 1 offline

string

os_type

query

Filter on the OS learnt by the host (not the OS tag: see label)

string

server_type

query

Filter

integer

switch_ip

query

Filter

string

switch_port

query

Filter

integer

label

query

Tag id

integer

map_search

query

Text searched in IP, name, MAC

string

wazuh_available

query

0 with Wazuh info, 1 without

integer

site_id

query

Site

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/host/assets_total_traffic.lua

Get the traffic of the assets

  • Description: Local and remote traffic (bytes) of each asset with traffic in a time interval: host, name, online, local_traffic, remote_traffic. Enterprise: the assets of the inventory (needs the historical flows capability for non-admin users); Pro: the local hosts. epoch_begin equal to epoch_end reads the live counters.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

ts_schema

query

Timeseries schema of the totals (default: host:local_traffic)

string

epoch_begin

query

Start of the interval, epoch (default: epoch_end - 3600)

integer

epoch_end

query

End of the interval, epoch (default: now)

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/host/assets_filters.lua

Get the assets inventory filters

  • Description: Filters of the assets table with their options (as the other *_filters REST). Enterprise M only. Needs the historical flows capability (non-admin users).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

site_id

query

Adds the Site filter

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/host/assets_journal.lua

Get the assets journal entries

  • Description: Entries of the assets journal in a time interval, newest first: event_time and created_time (epochs), asset (key, type, ip, vlan, name; empty key for an event of several assets at once: a deletion, the conversion of the assets recorded per VLAN by an older version), who, action, subaction, message. Enterprise L, assets inventory and journal preference enabled. Needs the historical flows capability (non-admin users).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

serial_key

query

Key of an asset: only its entries (default: all the assets of the interface)

string

epoch_begin

query

Begin of the interval, on the time of the events (epoch, default: epoch_end - 1 day)

integer

epoch_end

query

End of the interval, on the time of the events (epoch, default: now)

integer

action

query

Only the entries with this action (Baseline, New, Update, Delete, Manual)

string

who

query

Only the entries caused by this user (ntopng for the automatic events)

string

subaction

query

Only the entries about this subaction (e.g. os, tag, mac)

string

start

query

Offset of the first entry of the page (default: 0)

integer

length

query

Number of entries of the page (default: all the entries)

integer

sort

query

Column to sort by: event_time (default), created_time, asset, action, subaction, who

string

order

query

Sort order: asc or desc (default)

string

map_search

query

Free text (case insensitive): key (IP of the asset), who, action, subaction and message of the entries

string

Responses

0 - OK: the entries of the page in rsp, the number of the entries matching (all the pages) in recordsTotal and recordsFiltered

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/host/assets_journal_filters.lua

Get the assets journal filters

  • Description: Filters of the assets journal table (action, who, subaction) with their options, as the other *_filters REST: the values of the entries in the interval. Enterprise L, assets inventory and journal preference enabled. Needs the historical flows capability (non-admin users).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

serial_key

query

Key of an asset: only its entries (default: all the assets of the interface)

string

epoch_begin

query

Begin of the interval, on the time of the events (epoch, default: epoch_end - 1 day)

integer

epoch_end

query

End of the interval, on the time of the events (epoch, default: now)

integer

action

query

Only the entries with this action (Baseline, New, Update, Delete, Manual)

string

who

query

Only the entries caused by this user (ntopng for the automatic events)

string

subaction

query

Only the entries about this subaction (e.g. os, tag, mac)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/host/inactive_asset.lua

Return the data collected by ntopng relative to an inactive asset (local host)

  • Description: Given a serial key (concatenation of ifid, host ip and host vlan), returns all the data relative to the host requested if present

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

serial_key

query

Host identifier

integer

Responses

0 - OK

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/host/pool/members.lua

Get all host pool members

  • Description: Get all the members of a given host pool

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

pool

query

Host Pool ID

integer

member

query

IP/MAC/Network CIDR to add to the Host Pool ID

string

Responses

0 - OK

-16 - POOL_NOT_FOUND

GET /lua/rest/v2/get/host/pool/list.lua

Get the host pools of an interface with their traffic

  • Description: The host pools with live statistics on the interface, only the pools the user can access. rsp is an array of records: pool_id, pool_name, hosts (active hosts), seen_since (seconds since the first packet), bytes_sent, bytes_rcvd, traffic (bytes), throughput (bps), members (as stored: <address>/<prefix>@<vlan> or MAC), members_labels (members without the @<vlan> suffix). recordsTotal/recordsFiltered: number of pools.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/rest/v2/get/host/pool/pools.lua

Get one or all host pools

  • Description: Get one or all host pools

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

pool

query

Host Pool ID

integer

Responses

0 - OK

-16 - POOL_NOT_FOUND

GET /lua/rest/v2/get/host/pool_by_member.lua

Get an host pool given a member

  • Description: Get an host pool given a member

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

member

query

IP/MAC/Network CIDR

string

pool_name_only

query

Return only the pool name (do not return pool details including members)

boolean

Responses

0 - OK

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/host/processes/listening_ports.lua

Get the host information about listening ports

  • Description: Given an host, return the information about listening ports (transport level protocol, package and process that’s currently running on that port)

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

Host address

string

vlan

query

VLAN ID

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/rest/v2/get/host/to_scan_list.lua

List the hosts to scan

  • Description: Hosts and networks of the Active Scan list, with the status and result (open ports) of their last scan. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

port

query

Only the hosts with this port open

integer

epoch_end

query

Report time: the hosts as they were in that report

integer

was_down

query

Only the hosts that were down and are now up

boolean

netscan_report

query

Hosts discovered by the network scans

boolean

Responses

0 - OK

-3 - NOT_GRANTED (administrators only)

GET /lua/rest/v2/get/host/active_scan_type_list.lua

List the scan types

  • Description: Scan types available on this system (they need nmap). rsp.rsp: [{ id }]: the page builds the labels. Admin only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED (administrators only)

GET /lua/rest/v2/get/interface/address.lua

Get interface IP addresses

  • Description: List of interface IP addresses is returned

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/interface/alert/list.lua

Get interface alerts list

  • Description: Get interface alerts list

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

start

query

Starting record (e.g. start=100, it will start returning records from the 101st)

integer

length

query

Maximum number of records to get

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

subtype

query

Alert subtype

string

format

query

Format of the return data (json or txt)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/interface/alert/ts.lua

Get interface alerts timeseries

  • Description: Get interface alerts timeseries

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

subtype

query

Alert subtype

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/interface/arp.lua

Get interface ARP info

  • Description: Get interface ARP info

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

Host address

string

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/rest/v2/get/interface/bcast_domains.lua

Get interface broadcast domains

  • Description: Interface broadcast domains as detected from ARP traffic and broadcast traffic are returned

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/interface/lightview/data.lua

Get interface data aggregated from all interfaces (Overview)

  • Description: Interface data aggregated (summed) across all the interfaces, as shown by the Overview (lightview) mode in the Interface Details page. The response is a subset of /lua/rest/v2/get/interface/data.lua, plus the list of aggregated interfaces. Export stats (db, es, kafka, syslog) are reported only when the corresponding export is enabled, alert counters only when the user has the alerts capability, ZMQ counters only when at least one interface is a collector.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

Name

Description

Type

packets

Total packets

integer

bytes

Total bytes

integer

drops

Dropped flows (collector interfaces) or packets

integer

num_deduplicated_flows

integer

tot_nprobe_pkts

Packets seen by the nProbe instances

integer

tot_pkt_drops

Packets dropped by the nProbe instances

integer

num_probes

nProbe instances sending flows

integer

probe_ifid

First interface receiving flows from an nProbe instance (its nProbe page)

integer

db_stats

Records processed and discarded (flows, dropped_flows), only when some interface has records

object

has_traffic_directions

At least one interface tells sent from received traffic

boolean

discarded_probing_packets

integer

discarded_probing_bytes

integer

db

es

kafka

syslog

engaged_alerts

integer

dropped_alerts

integer

remote_pps

number

remote_bps

number

bytes_upload

integer

bytes_download

integer

packets_upload

integer

packets_download

integer

bytes_upload_since_reset

integer

bytes_download_since_reset

integer

packets_upload_since_reset

integer

packets_download_since_reset

integer

num_local_hosts_anomalies

integer

num_remote_hosts_anomalies

integer

zmqRecvStats

object

zmq.num_flow_exports

integer

zmq.drops.export_queue_full

integer

zmq.drops.flow_collection_drops

integer

zmq.drops.flow_collection_udp_socket_drops

integer

tcpPacketStats

object

ifaces

Aggregated interfaces

array

-2 - INVALID_INTERFACE

GET /lua/rest/v2/get/interface/config.lua

Get the settings of an interface

  • Description: Administrators only. The settings that apply to the interface and their values: custom_name, speed (Mbit/s), scaling_factor, lbd_by_mac (hosts of the local broadcast domain identified by MAC; lbd_locked when forced to IP), top_talkers, flow_dump, automatic_reports, mirrored and gw_macs, network_discovery, companion and companions, recording_provider and recording_providers, disaggregation and disaggregation_modes, show_dyn_traffic, push_host_filters. A setting missing from the answer does not apply to the interface. Not for pcap files.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE (missing, not allowed or a pcap file)

-3 - NOT_GRANTED (administrators only)

GET /lua/rest/v2/get/interface/data.lua

Get interface data

  • Description: Interface data is returned

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/interface/dscp/stats.lua

Get IP DSCP statistics for an interface

  • Description: DSCP statistics

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/interface/l7/stats.lua

Get L7 statistics for an interface

  • Description: nDPI statistics

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

ndpistats_mode

query

Stats mode: ‘sinceStartup’ or ‘count’

string

breed

query

Show breed

boolean

ndpi_category

query

Show nDPI category

boolean

all_values

query

Return all the values available

boolean

max_values

query

Get at most max_values, by default 5

int16

collapse_stats

query

Collapse the returned stats into ‘Other’ stats if bytes/flows are too low (< 3%)

boolean

Responses

0 - OK

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/interface/nprobes/data.lua

Get interface nProbe data

  • Description: nProbe instances connected to the interface: probe_ip, probe_name, probe_source_id, probe_uuid, probe_public_ip, probe_instance_name, probe_version, probe_edition, probe_license (”” when none), probe_maintenance (”” when expired), probe_last_update (epoch), probe_interface (”” in collector mode), is_collector, flow_exporters, exporters_interfaces, exported_flows, dropped_flows, captured_packets, dropped_packets, is_in_memory, ntopng_interface, ifid, timeseries_enabled

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/rest/v2/get/interface/overview.lua

Get the interface overview

  • Description: Identity and configuration of an interface, as shown by its Overview page: name, type, MTU and speed, paused state, connected nProbe instances, flow export backends. Administrators also get the traffic recording windows, the disk usage and the ZMQ encryption public key. The live counters are returned by get/interface/data.lua. With view=lightview (all the interfaces together) only is_light_view, can_reset, show_alerts, timeseries_enabled, exports, export_enabled, dedup_enabled and nprobe_page are returned (the aggregated counters are in get/interface/lightview/data.lua).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the interface of the session)

integer

view

query

lightview: all the interfaces together

string

Responses

0 - OK: { ifid, name, label, description, mac, type, inline, has_traffic_directions, mtu, speed_mbps, is_view, is_sub_interface, is_packet_interface, is_pcap_dump, is_syslog, is_netfilter, is_paused, can_pause, can_reset, can_live_capture, num_probes, nprobe_page, show_alerts, timeseries_enabled, has_role_traffic, has_flow_collection, db_stats, dedup_enabled, exports: [{ id, label }], export_enabled, export_direct, zmq_encryption_key, recording, storage, external_stats, maps_available, is_asn_mode }

-2 - INVALID_INTERFACE

GET /lua/rest/v2/get/interface/icmp_stats.lua

Get the ICMP messages of an interface

  • Description: ICMP messages seen on the interface (or by a host): type, code and packets.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the interface of the session)

integer

version

query

4 (default) or 6

string

host

query

Host IP (optional): the counters of this host instead of the interface

string

vlan

query

VLAN of the host

integer

Responses

0 - OK: [{ icmp_type, icmp_code, packets, icmp_message: { label, url } }]

-2 - INVALID_INTERFACE (missing ifid or interface not allowed)

GET /lua/rest/v2/get/interface/pkt_distribution.lua

Get the packet size or IP version distribution

  • Description: Packets of the interface by size (sizes below 5% grouped as Other) or by IP version.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

distr

query

size (default) or ipver

string

Responses

0 - OK: [{ label, value }] (value: packets)

-2 - INVALID_INTERFACE (missing ifid or interface not allowed)

GET /lua/rest/v2/get/interface/tcp_flags_distribution.lua

Get the TCP flags distribution

  • Description: TCP packets of the interface (or of a host) by flags: SYN, SYN/ACK, FIN/ACK, RST. Without TCP packets: [{ label: Other, value: 100 }].

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the interface of the session)

integer

host

query

Host IP (optional): the counters of this host instead of the interface

string

vlan

query

VLAN of the host

integer

Responses

0 - OK: [{ label, value }] (value: packets)

-2 - INVALID_INTERFACE (missing ifid or interface not allowed)

GET /lua/rest/v2/get/internals/periodic_activities.lua

Get the periodic activities

  • Description: State and timings of the periodic activities (the Lua scripts run every second, minute, 5 minutes…) of an interface. Without ifid: the ones of the system interface and of every allowed interface, each row with iface_id and iface_name.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (-1: the system one; none: all)

integer

periodic_script

query

Only this activity (e.g. minute)

string

periodic_script_issue

query

Only the activities with this issue (any_issue: any)

string

Responses

0 - OK: [{ iface_id, iface_name, script, state, periodicity, max_duration_secs, last_start_time, last_duration_ms, busy_pct, tot_not_executed, tot_running_slow, issues, … }]

-2 - INVALID_INTERFACE (ifid not allowed)

GET /lua/rest/v2/get/syslog/producer/list.lua

Get the syslog producers

  • Description: Administrators only. The hosts that send their logs to a syslog interface and the type of their logs.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK: [{ host, producer, producer_title }]

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED (administrators only)

POST /lua/rest/v2/add/syslog/producer.lua

Add or change a syslog producer

  • Description: Administrators only, syslog interfaces. Adds a producer, or changes the one of old_syslog_producer_host.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS: rsp = { field } the refused one (exists: true when the name/host is already used)

POST /lua/rest/v2/delete/syslog/producer.lua

Delete a syslog producer

  • Description: Administrators only, syslog interfaces.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS: rsp = { field } the refused one (exists: true when the name/host is already used)

GET /lua/pro/rest/v2/get/interface/sub_interfaces.lua

Get the sub-interfaces of an interface

  • Description: Administrators only, Enterprise M. The custom disaggregation: the sub-interfaces receiving the traffic matching a filter.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK: [{ name, filter }]

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED (administrators only)

POST /lua/pro/rest/v2/add/interface/sub_interface.lua

Add or change a sub-interface

  • Description: Administrators only, Enterprise M. Adds a sub-interface, or changes the one of old_name. The filter is nBPF (packet interfaces) or xnBPF (flow interfaces).

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS: rsp = { field } the refused one (exists: true when the name/host is already used)

POST /lua/pro/rest/v2/delete/interface/sub_interface.lua

Delete a sub-interface

  • Description: Administrators only, Enterprise M.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS: rsp = { field } the refused one (exists: true when the name/host is already used)

GET /lua/rest/v2/get/l4/protocol/consts.lua

Get L4 protocol constants

  • Description: L4 protocol names and integer identifiers

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

GET /lua/rest/v2/get/l7/application/consts.lua

Get L7 application protocol constants

  • Description: L7 application protocol names and integer identifiers

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

GET /lua/rest/v2/get/l7/category/consts.lua

Get L7 application category constants

  • Description: L7 application category names and integer identifiers

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

GET /lua/rest/v2/get/mac/data.lua

Get Macs traffic information

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

mac

query

Mac Address to get information

string

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

GET /lua/rest/v2/get/mac/overview.lua

Get the overview of a MAC address

  • Description: An active MAC address: name, device type, model, DHCP fingerprint, host pool, first host and number of hosts, first observed, last counters reset, events, and the traffic counters (seen.first/last, bytes/packets/dhcp sent and rcvd, ARP requests/replies, flows.dropped). counters=true: only the counters.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

MAC address (e.g. AA:BB:CC:DD:EE:FF)

string

counters

query

true: only the live counters

boolean

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/mac/snmp_location.lua

Get where a MAC address was seen on the SNMP devices

  • Description: The access ports and the trunk ports of the monitored SNMP devices (Bridge MIB) where the MAC address was seen: device IP and name, port index and name, trunk. Enterprise M.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

MAC address (e.g. AA:BB:CC:DD:EE:FF)

string

Responses

0 - OK

-3 - NOT_GRANTED

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/mac/config.lua

Get the settings of a MAC address

  • Description: Alias, device type and host pool of the MAC address, with the pools that can be chosen (none on view interfaces). Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

host

query

MAC address (e.g. AA:BB:CC:DD:EE:FF)

string

Responses

0 - OK

-3 - NOT_GRANTED

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

POST /lua/rest/v2/set/mac/config.lua

Set the settings of a MAC address

  • Description: Saves alias (empty: removed), device type (0-12, see discover_utils) and host pool (not on view interfaces) of a MAC address. Administrators only.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

Responses

0 - OK

-3 - NOT_GRANTED

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR (the pool member could not be bound)

POST /lua/rest/v2/set/mac/reset_stats.lua

Reset the counters of a MAC address

  • Description: Resets the traffic counters of an active MAC address. Administrators only.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

Responses

0 - OK

-1 - NOT_FOUND

-3 - NOT_GRANTED

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/mac/macs_list.lua

Get the active MAC addresses of an interface

  • Description: One page of the active MACs. rsp is an array of records: mac, manufacturer (with the [model] when known), device_type {id, device_type_label, <type name>: true}, name {has_name, name | num_hosts, host_label}, hosts, arp (ARP packets sent + received), seen_since (epoch of the first packet), bytes_sent, bytes_rcvd, traffic (bytes), throughput + throughput_type (bps or pps, per the throughput preference), location (nEdge only). recordsTotal/recordsFiltered: MACs matching the filters.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

start

query

Offset of the first MAC returned (default 0)

integer

length

query

Number of MACs returned (default: all)

integer

sort

query

Sort column: mac, manufacturer, hosts, arp, seen_since, throughput, traffic (default mac)

string

order

query

Sort order: asc or desc (default asc)

string

map_search

query

Free-text search on the MAC address and manufacturer

string

devices_mode

query

source_macs_only: only the MACs that sent traffic (inactive_macs_only is handled as source_macs_only)

string

manufacturer

query

Manufacturer name (exact match)

string

device_type

query

Device type id

integer

location

query

nEdge only: lan, wan or unknown

string

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/rest/v2/get/mac/alert/list.lua

Get MAC alerts list

  • Description: Get MAC alerts list

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

start

query

Starting record (e.g. start=100, it will start returning records from the 101st)

integer

length

query

Maximum number of records to get

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

format

query

Format of the return data (json or txt)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/mac/alert/ts.lua

Get MAC alerts timeseries

  • Description: Get MAC alerts timeseries

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/network/alert/list.lua

Get network alerts list

  • Description: Get network alerts list

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

start

query

Starting record (e.g. start=100, it will start returning records from the 101st)

integer

length

query

Maximum number of records to get

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

network_name

query

Network Name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

format

query

Format of the return data (json or txt)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/network/alert/ts.lua

Get network alerts timeseries

  • Description: Get network alerts timeseries

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

network_name

query

Network Name (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/as/alert/list.lua

Get AS alerts list

  • Description: Get the alerts of the Autonomous Systems

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

start

query

Starting record

integer

length

query

Maximum number of records to get

integer

status

query

Alerts status: ‘historical’ (require attention, default), ‘engaged’ or ‘any’

string

alert_id

query

Alert type (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

severity

query

Severity (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

score

query

Score (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

asn

query

Autonomous System number (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

format

query

Format of the return data: ‘json’ (default) or ‘txt’ (CSV)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED: the user has no alerts capability

GET /lua/rest/v2/get/as/alert/ts.lua

Get AS alerts timeseries

  • Description: Get the number of AS alerts over time, by severity

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

status

query

Alerts status: ‘historical’ (require attention, default), ‘engaged’ or ‘any’

string

alert_id

query

Alert type (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

severity

query

Severity (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

score

query

Score (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

asn

query

Autonomous System number (format: ‘value;op’, op: ‘eq’, ‘neq’, ‘lt’, ‘lte’, ‘gt’, ‘gte’)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED: the user has no alerts capability

GET /lua/rest/v2/get/network/discovery/discover.lua

Get interface network discovery data

  • Description: Get data regarding the network discovery done by an ntopng interface

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

operating_system

query

Operating System identifier

integer

device_type

query

Device type identifier

integer

manufacturer

query

Manufacturer of the device

string

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/rest/v2/get/network/networks.lua

Return list of networks

  • Description: Return the list of all networks

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

GET /lua/rest/v2/get/ntopng/interfaces.lua

Get ntopng actively monitored interfaces names and ids

  • Description: Interface name and integer interface id for each actively monitored ntopng interface

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

GET /lua/rest/v2/get/ntopng/users.lua

Read all configured ntopng users

  • Description: Read all configured ntopng users

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/rest/v2/get/ntopng/license.lua

Get license information for the current ntopng instance

  • Description: Get license information for the current ntopng instance, including SystemId and license validity/expiry

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

POST /lua/rest/v2/set/ntopng/license.lua

Set the ntopng license key

  • Description: Set the ntopng license key

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ntopng_license

The license key

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/pcap/live_extraction.lua

Extract (live download) PCAP data from the traffic recorded with the continuous recording (n2disk)

  • Description: Raw PCAP data is returned

  • Produces: [‘application/vnd.tcpdump.pcap’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

bpf_filter

query

BPF filter

string

Responses

FILE - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

-7 - BAD_FORMAT

GET /lua/rest/v2/create/pcap/extraction/task.lua

Schedule PCAP data extraction from traffic recorded with the continuous recording (n2disk). A job ID is returned to check the extraction status (see /lua/rest/v2/get/pcap/extraction/tasks.lua)

  • Description: Job info is returned

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

bpf_filter

query

BPF filter

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/interface/recording/config.lua

Read the traffic recording (n2disk) settings of an interface

  • Description: Administrators only, with n2disk installed. managed: ntopng runs n2disk (else provider names the external one and there are no settings). enabled, jobs_available (Enterprise M), smart_available (Enterprise XL), reminder (external n2disk instances detected), max_pcap_mb (size extracted PCAPs are split at). settings: disk_space / smart_disk_space / max_space (GB), bpf_filter, snaplen (bytes), max_file_size (MB, null: auto) and max_file_size_auto, pcap_path, smart_pcap_path, smart_enabled; ZMQ collectors also ext_interfaces [{name, label}], ext_ifname, flow_export. storage (bytes): total, avail, system_used, if_used, extraction_used. A view returns viewed_interfaces [{ifid, name}] (the ones with recording) instead.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

POST /lua/rest/v2/set/interface/recording/config.lua

Save the traffic recording (n2disk) settings of an interface and start or stop n2disk

  • Description: Administrators only, with n2disk installed and managed by ntopng (not on views). All the fields are applied: a missing toggle is off, a missing number takes its default. An invalid value answers INVALID_ARGUMENTS with rsp.field. Answers enabled and started (n2disk configured and restarted).

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/interface/recording/status.lua

Read the traffic recording (n2disk) status of an interface

  • Description: Administrators only, with n2disk installed (not on views). enabled, running, external (n2disk run by another provider). When enabled: first_epoch / last_epoch (dump window), start_epoch, bytes, packets, dropped, smart {first_epoch, last_epoch}, log (last 32 lines of the n2disk log, most recent first); external and running: extraction {ok, status: OK | ERR_MISSING_TIMELINE | ERR_TIMELINE_PATH_NOT_EXISTING | ERR_UNABLE_TO_ACCESS_TIMELINE}.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

POST /lua/rest/v2/set/interface/recording/restart.lua

Restart the traffic recording (n2disk) of an interface

  • Description: Administrators only, with n2disk installed, the recording enabled and managed by ntopng (else INVALID_ARGUMENTS). Nothing is done when n2disk is already running.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/pcap/extraction/jobs.lua

Read the PCAP extraction jobs of an interface (raw values)

  • Description: Administrators only, with n2disk installed. Newest first: id, time, status (waiting, waiting_nospace, processing, completed, stopped, failed), error_code (failed), time_from, time_to, filter, chart_url, files (PCAP files to download with /lua/rest/v2/get/pcap/extraction/data.lua), extracted_pkts and extracted_bytes (completed).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

POST /lua/rest/v2/delete/pcap/extraction/job.lua

Delete a PCAP extraction job and its files

  • Description: Administrators only, with n2disk installed. job_id: a job of the interface; all=true instead: every job of the interface (the running ones are stopped).

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

POST /lua/rest/v2/set/pcap/extraction/stop_job.lua

Stop a running PCAP extraction job

  • Description: Administrators only, with n2disk installed. The PCAP extracted so far is kept (status stopped).

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/pcap/extraction/tasks.lua

Read PCAP extraction jobs (scheduled with /lua/rest/v2/create/pcap/extraction/task.lua) information

  • Description: DataTables format with formatted values (perPage, currentPage, sortColumn, sortOrder): {data, totalRows, …}, no rc. Administrators only, with n2disk installed (else an empty answer). Raw values: /lua/rest/v2/get/pcap/extraction/jobs.lua

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/pcap/extraction/data.lua

Download PCAP data extracted by a scheduled extraction task (scheduled with /lua/rest/v2/create/pcap/extraction/task.lua)

  • Description: Raw PCAP data is returned

  • Produces: [‘application/vnd.tcpdump.pcap’]

Parameters

Name

Position

Description

Type

job_id

query

Job ID

integer

file_id

query

File ID (default 1)

integer

Responses

FILE - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

-7 - BAD_FORMAT

GET /lua/rest/v2/get/pod/list.lua

Get the Kubernetes pods

  • Description: Kubernetes pods seen in the flows of the interface: pod, num_containers, flows_as_client, flows_as_server, rtt_as_client, rtt_as_server, rtt_variance_as_client, rtt_variance_as_server (RTT in ms)

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

Responses

0 - OK

-2 - INVALID_INTERFACE: the user cannot access the interface

GET /lua/rest/v2/get/container/list.lua

Get the containers

  • Description: Containers (Docker or Kubernetes) seen in the flows of the interface: id, name, pod, flows_as_client, flows_as_server, rtt_as_client, rtt_as_server, rtt_variance_as_client, rtt_variance_as_server (RTT in ms)

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

pod

query

Only the containers of this Kubernetes pod

string

Responses

0 - OK

-2 - INVALID_INTERFACE: the user cannot access the interface

GET /lua/rest/v2/get/pcap/live_captures.lua

Get the running live captures

  • Description: Live captures (pcap downloads of live traffic) running on the interface: id, host (missing when the whole interface is captured), num_captured_packets, capture_max_pkts, capture_until (epoch). Needs the pcap download right

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

Responses

0 - OK

-3 - NOT_GRANTED: the user cannot download pcap files

-2 - INVALID_INTERFACE: the user cannot access the interface

POST /lua/rest/v2/delete/pcap/live_capture.lua

Stop a live capture

  • Description: Stops a running live capture of the interface. Administrators only

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

{ ifid, capture_id } (capture_id: id returned by get/pcap/live_captures.lua)

Responses

0 - OK

-3 - NOT_GRANTED: administrators only

-5 - INVALID_ARGUMENTS: ifid or capture_id missing

-2 - INVALID_INTERFACE: the user cannot access the interface

GET /lua/rest/v2/get/pcap/live_traffic.lua

Live traffic capture

  • Description: Raw PCAP data is returned

  • Produces: [‘application/vnd.tcpdump.pcap’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

bpf_filter

query

BPF filter

string

Responses

FILE - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

-7 - BAD_FORMAT

GET /lua/rest/v2/get/pools.lua

Get all pools of any type

  • Description: Get all pools defined for any available pool type

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

GET /lua/rest/v2/get/recipient/pools.lua

Get recipient pools

  • Description: Get all pools bound to a recipient

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

recipient_id

query

Recipient identifier

integer

Responses

0 - OK

GET /lua/rest/v2/get/system/alert/list.lua

Get system alerts list

  • Description: Get system alerts list

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

start

query

Starting record (e.g. start=100, it will start returning records from the 101st)

integer

length

query

Maximum number of records to get

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

format

query

Format of the return data (json or txt)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/system/alert/ts.lua

Get system alerts timeseries

  • Description: Get system alerts timeseries

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/system/configurations/download_backup.lua

Get system configuration automatic backup

  • Description: Get on of the automatic system configurations backups

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

epoch

query

The epoch of the backup

integer

download

query

Download the backup or just retrive info

boolean

Responses

0 - OK

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/system/configurations/list_availabled_backups.lua

Get system configurations automatic backups

  • Description: Get list of automatic system configurations backups

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/system/health/influxdb.lua

Get InfluxDB Stats

  • Description: InfluxDB export status. With InfluxDB as timeseries driver: status UP, version, health (green, yellow while retrying failed exports, red while dropping points), exports, points_exported and, when the InfluxDB internal monitoring database is available, db_bytes, memory, num_series. Otherwise status DISABLED. Needs access to the system interface

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK: { status, version?, health?, exports?, points_exported?, db_bytes?, memory?, num_series? }

-3 - NOT_GRANTED: the user cannot access the system interface

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/system/health/interfaces.lua

Get interfaces stats

  • Description: Get statistics of every active interfaces

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/system/health/interfaces_list.lua

Get the counters of every interface

  • Description: One record per monitored interface: ifid, name (alias if set), engaged_alerts, alerted_flows, local_hosts, remote_hosts, devices, flows and, since the last counters reset, bytes, packets, drops. Needs access to the system interface

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK: [{ ifid, name, engaged_alerts, alerted_flows, local_hosts, remote_hosts, devices, flows, bytes, packets, drops }]

-3 - NOT_GRANTED: the user cannot access the system interface

GET /lua/rest/v2/get/system/health/log.lua

Get the last ntopng log lines

  • Description: The last 33 lines of the ntopng log, newest first, as plain text. Needs access to the system interface; not available on OEM builds

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK: [line]

-3 - NOT_GRANTED: the user cannot access the system interface

GET /lua/rest/v2/get/system/health/redis.lua

Get Redis Stats

  • Description: Redis status: used memory (resident set size, bytes), number of keys (dbsize) and health (green, or red when the last persistence to disk failed). On Windows dbsize is missing and health is always green. Needs access to the system interface

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK: { memory, dbsize, health }

-3 - NOT_GRANTED: the user cannot access the system interface

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/redis/redis_stats.lua

Get Redis calls per command

  • Description: Calls made by ntopng to Redis since startup, one record per command: { command: { key, name }, hits }. Needs access to the system interface

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED: the user cannot access the system interface

GET /lua/rest/v2/get/system/health/stats.lua

Get system stats

  • Description: Get statistics of the system on top of which ntopng is running

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED: the user cannot access the system interface

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/system/status.lua

Get system status info

  • Description: Get license information and resources used data

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

GET /lua/rest/v2/get/system/reload_ndpi.lua

Reload nDPI and Blacklists

  • Description: Reload nDPI (also the changes to the custom protocols) and all the enabled blacklists

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/rest/v2/get/timeseries/ts.lua

Get timeseries data

  • Description: Get timeseries data

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

limit

query

Maximum number of timeseries points

number

initial_point

query

A boolean used to return the first point of the timeseries or not

boolean

ts_compare

query

Choices available: ‘30m’, ‘1h’, ‘1d’. A string reporting the timeframe of the timeseries to be compared to (e.g. ‘30m’, means to return other then the timeserie requested, the 30 minutes before)

string

ts_query

query

Containing the parameters used to find the timeserie in the following format, parameter:value;parameter:value;… (e.g. ‘ifid:1;host:192.168.1.1’)

string

tskey

query

Containing the timeseries key, whom the timeseries is referred to (e.g. if the timeserie is regarding the interface ‘7’ or the host ‘192.168.1.1’, then tskey is going to be ‘7’ or ‘192.168.1.1’)

string

ts_schema

query

Contains the timeserie schema (e.g. ‘iface:traffic’)

string

Responses

0 - OK

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/timeseries/type/consts.lua

Get available timeseries

  • Description: Get all the available timeseries given a tag

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

query

query

Tag used to retrieve the timeseries; currently available: iface, host, mac, subnet, asn, country, os, vlan, host_pool, pod, container, ht, system, profile, redis, influxdb, am, snmp_interface, snmp_device, obs_point, sflowdev_port, flowdev, flowdev_port

string

host

query

Host IP@VLAN, REQUIRED in case of timeseries regarding Host, SNMP or Flow devices

string

asn

query

ASN identifier, REQUIRED in case of timeseries regarding Autonomous Systems

integer

pool

query

Host Pool identifier, REQUIRED in case of timeseries regarding Host Pools

integer

vlan

query

VLAN identifier, REQUIRED in case of timeseries regarding VLANs

integer

mac

query

MAC address, REQUIRED in case of timeseries regarding MACs

string

hash_table

query

Hash table name (e.g. FlowHash), with query=ht: only the timeseries of that hash table

string

Responses

0 - OK

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/rest/v2/get/user/alert/list.lua

Get user alerts list

  • Description: Get user alerts list

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

start

query

Starting record (e.g. start=100, it will start returning records from the 101st)

integer

length

query

Maximum number of records to get

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

format

query

Format of the return data (json or txt)

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

GET /lua/rest/v2/get/user/alert/ts.lua

Get user alerts timeseries

  • Description: Get user alerts timeseries

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier

integer

epoch_begin

query

Start time (epoch)

integer

epoch_end

query

End time (epoch)

integer

alert_id

query

Alert identifier (format: ‘id;eq’, where ‘id’ is the id and ‘eq’ stands for ‘equal’, currently available: ‘eq’, ‘neq’)

integer

severity

query

Severity identifier (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

score

query

Score (format: ‘id;eq’, where ‘id’ is the amount of traffic and ‘eq’ stands for ‘equal’, currently available: ‘eq’ -> equal, ‘neq’ -> not equal, ‘lt’ -> lesser then, ‘lte’ -> lesser or equal then, ‘gt’ -> greater then, ‘gte’ -> greater or equal then

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

POST /lua/rest/v2/set/vlan/alias.lua

Set the alias of a VLAN

  • Description: Set the alias of a VLAN; an empty alias removes it. Administrators only

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

vlan

formData

VLAN id (1-4095)

integer

alias

formData

New alias (empty: remove it)

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/vlan/alias.lua

Get the alias of a VLAN

  • Description: The alias of a VLAN (empty string when not set)

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

vlan

query

VLAN id (1-4095)

integer

Responses

0 - OK

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/vlan/list.lua

Get the VLANs of an interface

  • Description: The VLANs seen on the interface, untagged traffic (vlan_id 0) included. rsp is an array of records: vlan_id, vlan_alias (only when an alias is set), is_untagged, num_hosts (active hosts), score, seen_since (seconds since the first packet), bytes_sent, bytes_rcvd, traffic (bytes), throughput_bps, throughput_pps. recordsTotal/recordsFiltered: number of VLANs. Any user can call it (interface restrictions apply).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current interface)

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

POST /lua/rest/v2/import/active_monitoring/config.lua

Import the active monitoring configuration providing a JSON file

  • Description: Import the active monitoring configuration

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-27 - CONFIGURATION_FILE_MISMATCH

-28 - PARTIAL_IMPORT

POST /lua/rest/v2/import/all/config.lua

Import all configurations providing a JSON file

  • Description: Import all configurations including Pools, Active Monitoring, Notifications (Endpoints and Recipients), Checks, SNMP devices

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-27 - CONFIGURATION_FILE_MISMATCH

-28 - PARTIAL_IMPORT

POST /lua/rest/v2/import/checks/config.lua

Import Checks configuration

  • Description: Import Checks configuration

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

JSON

form

The Checks configuration in JSON

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-27 - CONFIGURATION_FILE_MISMATCH

POST /lua/rest/v2/import/infrastructure/config.lua

Import the Infrastructure configuration providing a JSON file

  • Description: Import the configuration for all infrastructure configurations

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-27 - CONFIGURATION_FILE_MISMATCH

-28 - PARTIAL_IMPORT

POST /lua/rest/v2/import/notifications/config.lua

Import the notifications configuration providing a JSON file

  • Description: Import the configuration for endpoints and recipients

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-27 - CONFIGURATION_FILE_MISMATCH

-28 - PARTIAL_IMPORT

POST /lua/rest/v2/import/pool/config.lua

Import the pools configuration providing a JSON file

  • Description: Import the configuration of all pools and dependencies (notifications, SNMP, active monitoring, checks

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-27 - CONFIGURATION_FILE_MISMATCH

-28 - PARTIAL_IMPORT

GET /lua/rest/v2/import/pool/host_pool/members.lua

Import host pool members

  • Description: Import host pool members

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

pool

form

Pool identifier

integer

host_pool_members

form

A newline-separated list of host pool members

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

POST /lua/rest/v2/import/scripts/config.lua

Import the Checks configuration providing a JSON file

  • Description: Import the configuration for all checks

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-27 - CONFIGURATION_FILE_MISMATCH

-28 - PARTIAL_IMPORT

POST /lua/rest/v2/import/snmp/config.lua

Import the SNMP configuration providing a JSON file

  • Description: Import the configuration for the SNMP devices

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-27 - CONFIGURATION_FILE_MISMATCH

-28 - PARTIAL_IMPORT

GET /lua/rest/v2/reset/active_monitoring/config.lua

Reset Active Monitoring configuration

  • Description: Reset active monitoring configuration

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

POST /lua/rest/v2/reset/all/config.lua

Reset all configurations

  • Description: Reset all configurations

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/rest/v2/reset/checks/config.lua

Reset Checks configuration

  • Description: Reset checks configuration

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

POST /lua/rest/v2/reset/infrastructure/config.lua

Reset all infrastructure configurations

  • Description: Reset all infrastructure configurations

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/rest/v2/reset/notifications/config.lua

Reset Notifications configuration

  • Description: Reset notifications configuration

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/rest/v2/reset/snmp/config.lua

Reset SNMP configuration

  • Description: Reset SNMP configuration including all configured devices

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

POST /lua/rest/v2/set/checks/check_config.lua

Set the configuration of a check

  • Description: Save the configuration of a check and the tags added to its alerts (and to the issues they open or update)

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

check_subdir

formData

Family of the check (e.g. host, flow, interface)

string

script_key

formData

Key of the check

string

JSON

formData

Per-hook configuration in JSON: {“<hook>”: {“enabled”: true, “script_conf”: {…}}}

string

tag_ids

formData

Comma-separated ids (0..63) of the tags added to the alerts of the check, empty for none. When missing, the current tags are kept

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

-7 - BAD_FORMAT

POST /lua/rest/v2/set/checks/config.lua

Set Checks configuration

  • Description: Set Checks configuration

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

JSON

form

Check configuration in JSON

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

POST /lua/rest/v2/set/host/alias.lua

Set host alias

  • Description: Set host custom name

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

formData

Host address

string

custom_name

formData

Custom name

string

Responses

0 - OK

-5 - INVALID_ARGUMENTS

POST /lua/rest/v2/set/device/alias.lua

Set device alias

  • Description: Set device custom name

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

device

formData

Device MAC Address

string

custom_name

formData

Custom name

string

Responses

0 - OK

-5 - INVALID_ARGUMENTS

POST /lua/rest/v2/set/network/alias.lua

Set network alias

  • Description: Set network custom name

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

network_cidr

formData

Network CIDR

string

custom_name

formData

Custom name

string

Responses

0 - OK

-5 - INVALID_ARGUMENTS

POST /lua/rest/v2/set/interface/alias.lua

Set interface alias

  • Description: Set interface custom name

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

formData

Interface ID

string

custom_name

formData

Custom name

string

Responses

0 - OK

-5 - INVALID_ARGUMENTS

POST /lua/rest/v2/set/interface/config.lua

Save settings of an interface

  • Description: Administrators only. Only the fields in the body are changed (the others are kept), and only the ones that apply to the interface. Nothing is saved when a value is refused.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - OK: { restart_required }

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS: rsp = { field } the refused one

POST /lua/rest/v2/set/interface/idle_state.lua

Pause or resume an interface

  • Description: Administrators only. Pauses (active=false) or resumes (active=true) the monitoring of an interface: while paused its traffic is not processed. Not available for pcap files and nEdge netfilter queues.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - OK: { is_paused }

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED (administrators only)

-5 - INVALID_ARGUMENTS

POST /lua/rest/v2/set/host/reset_stats.lua

Reset the counters of a host

  • Description: Resets the counters of an active host: all of them (reset_all) or only the blacklisted flows/contacts counters (reset_blacklisted). Administrators only.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

Responses

0 - OK

-1 - NOT_FOUND

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

POST /lua/rest/v2/set/host/traffic_policy.lua

Drop or allow the traffic of a host

  • Description: Traffic policy of a local host on an inline interface: block (drop all its traffic), allow (stop dropping it), drop_flows (drop its active flows once). Answers the current state (blocked). Administrators only.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

Responses

0 - OK

-1 - NOT_FOUND (not an active local unicast host)

-2 - INVALID_INTERFACE, or NOT_ENABLED (not an inline interface)

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

POST /lua/rest/v2/set/host/notes.lua

Set host custom notes

  • Description: Given an host and a note, it is going to set that Note to the host

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

custom_notes

form

Custom Host Note

string

Responses

0 - OK

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/trigger/host/alert.lua

Trigger an external alert on a host

  • Description: Trigger alert

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

formData

Interface identifier

integer

host

formData

Host address

string

vlan

formData

VLAN ID

integer

score

formData

Set the alert score

boolean

info

formData

Set the alert description

string

Responses

0 - OK

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

-6 - INTERNAL_ERROR

GET /lua/rest/version.lua

Get supported and current REST API versions

  • Description: Return all the supported REST API versions and the current REST API version used

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

GET /lua/rest/v2/get/active_monitoring/list.lua

List the active monitoring measurements

  • Description: Measurements with their last result and thresholds. Requires access to the system interface.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface ID

string

measurement

query

Only this measurement type (e.g. icmp, http)

string

only_alerted_hosts

query

Only the measurements with engaged alerts

boolean

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/rest/v2/get/active_monitoring/filters.lua

Active monitoring table filters

  • Description: Filters (measurement types) of the active monitoring table. Requires access to the system interface.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface ID

string

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/rest/v2/get/active_monitoring/measurements.lua

Active monitoring measurement types

  • Description: Definitions of the available measurements (units, thresholds, granularities). Requires access to the system interface.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/rest/v2/get/active_monitoring/timeseries_list.lua

Active monitoring hosts with timeseries

  • Description: Active monitoring hosts, the sources of the timeseries charts. Requires access to the system interface.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

POST /lua/rest/v2/delete/active_monitoring/measurement.lua

Delete an active monitoring measurement

  • Description: Removes a measurement. Requires the active monitoring capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

am_host

formData

Monitored host

string

measurement

formData

Measurement type (e.g. icmp, http)

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/ntopng/menu.lua

Menu and shared page flags

  • Description: Sidebar menu of the GUI and the flags shared by its pages (e.g. is_am_active, are_system_ts_enabled, are_alerts_enabled).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface ID

string

Responses

0 - OK

GET /lua/pro/rest/v2/get/snmp/page_context.lua

Context of the SNMP devices page

  • Description: Number and limit of the configured devices, LLDP/CDP availability, polling/timeseries/license flags and the default community used by the SNMP devices page. Administrators only. Requires access to the system interface.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/snmp/device/page_context.lua

Context of the SNMP device page

  • Description: Device name and the data it exposes (interfaces, LLDP/CDP, BRIDGE, NET-SNMP, Printer MIBs, QoS polling, flow export); found is false for a device not configured. Requires the SNMP capability and access to the system interface.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

IP address of the SNMP device

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/snmp/device/netsnmp.lua

NET-SNMP resources of an SNMP device

  • Description: CPU states (%), memory and swap (bytes) from the UCD-SNMP-MIB and which of their timeseries exist (charts). Requires the SNMP capability and access to the system interface.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

IP address of the SNMP device

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/snmp/device/printer.lua

Printer data of an SNMP device

  • Description: Printer-MIB data; error_state_bytes are the bytes of hrPrinterDetectedErrorState (flag bits, RFC 1759). Requires the SNMP capability and access to the system interface.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

IP address of the SNMP device

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/snmp/mac/macs_info.lua

MAC addresses learned by an SNMP device

  • Description: MAC addresses of the BRIDGE-MIB forwarding table, of all the ports or of one, with manufacturer, device type id (discover id, e.g. printer) and associated IP. Requires the SNMP capability and access to the system interface.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

IP address of the SNMP device

string

snmp_port_idx

query

Only the MACs of this port (SNMP ifIndex)

integer

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/snmp/interface/page_context.lua

Context of the SNMP interface page

  • Description: Device and interface names, role label, learned MACs, timeseries and the interface exporting the flows of this port (exporter_ifid); found is false for an unknown device or interface. Requires the SNMP capability and access to the system interface.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

IP address of the SNMP device

string

snmp_port_idx

query

SNMP ifIndex of the interface

integer

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/snmp/interface/details.lua

Details of an SNMP interface

  • Description: Raw interface data: name, type, IPs, VLAN, speeds (bit/s), status codes, counters, last change (s), LLDP neighbour, last usage (%, -1 when not available). Requires the SNMP capability and access to the system interface.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

IP address of the SNMP device

string

snmp_port_idx

query

SNMP ifIndex of the interface

integer

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/snmp/interface/config.lua

Configuration of an SNMP interface

  • Description: Alerts toggles, role, usage page exclusion, speeds (bit/s) and admin status of an interface. Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

IP address of the SNMP device

string

snmp_port_idx

query

SNMP ifIndex of the interface

integer

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

POST /lua/pro/rest/v2/edit/snmp/interface/config.lua

Edit the configuration of an SNMP interface

  • Description: Only the parameters sent are changed. toggle_snmp_port_admin_status sets the admin status on the device (SNMP SET, admin_status_set_failed when it fails). Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

formData

IP address of the SNMP device

string

snmp_port_idx

formData

SNMP ifIndex of the interface

integer

toggle_snmp_alerts_port_status_change

formData

Alerts on operational status changes

boolean

toggle_snmp_alerts_port_duplexstatus_change

formData

Alerts on duplex status changes

boolean

toggle_snmp_alerts_port_errors

formData

Alerts on discards/errors

boolean

toggle_exclude_from_usage_page

formData

Exclude the interface from the usage page

boolean

snmp_interface_role_change

formData

Interface role (a value of get/snmp/interface_roles_options.lua)

string

uplink_speed

formData

Uplink speed in Gbit (>= 0)

number

downlink_speed

formData

Downlink speed in Gbit (>= 0)

number

toggle_snmp_port_admin_status

formData

Admin status up (true) or down (false)

boolean

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/snmp/device/rules.lua

List the SNMP interface rules

  • Description: Threshold rules on the metrics of SNMP interfaces. Enterprise, requires the SNMP capability and access to the system interface.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface ID

string

Responses

0 - OK: rsp = [{ id, device { id, label }, interface { id, label }, metric { id, label, type }, frequency, threshold { value, sign, label, unit } }]

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED

POST /lua/pro/rest/v2/add/snmp/device/rule.lua

Add or edit an SNMP interface rule

  • Description: Alert when a metric of an SNMP interface crosses a limit. With rule_id the rule is replaced (edit). Enterprise, administrators only.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - OK: rsp = { id } (the id of the saved rule)

-1 - NOT_FOUND: rsp.error = rule_not_found (rule_id of an edit not found)

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED (not an administrator or no Enterprise license)

-5 - INVALID_ARGUMENTS: rsp.error = invalid_rule (missing or not valid fields) or duplicate_rule (same device, port, metric, frequency and direction)

POST /lua/pro/rest/v2/delete/snmp/device/rule.lua

Delete an SNMP interface rule

  • Description: Enterprise, administrators only.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

JSON object (with the csrf of the web session, not needed with API tokens)

Responses

0 - OK

-1 - NOT_FOUND: rsp.error = rule_not_found

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED (not an administrator or no Enterprise license)

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/snmp/snmp_debug.lua

Download the SNMP cache of a device

  • Description: Raw cached SNMP data of a device, as a text file attachment (debug). Administrators only.

  • Produces: [‘application/octet-stream’]

Parameters

Name

Position

Description

Type

host

query

IP address of the SNMP device

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/snmp/metric/interfaces.lua

List the SNMP interfaces

  • Description: Interfaces of all the devices or of one, with status, speeds, counters and usage, filtered and paged (without start/length the whole list). Requires access to the system interface.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

Only the interfaces of this device

string

start

query

First row

integer

length

query

Number of rows

integer

sort

query

Column to sort by

string

order

query

asc or desc

string

map_search

query

Text to search

string

snmp_status

query

Operational status code

string

snmp_admin_status

query

Admin status code

string

snmp_if_type

query

Interface type

string

err_counters_filter

query

Only the interfaces with errors

boolean

snmp_interface_role

query

Interface role

string

lldp_cdp_mode

query

Only the interfaces with LLDP/CDP neighbours

boolean

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/snmp/metric/interfaces_filters.lua

SNMP interfaces table filters

  • Description: Filters of the SNMP interfaces table (status, type, role, errors). Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

Only the values of this device

string

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/snmp/metric/usage.lua

SNMP interfaces usage

  • Description: Usage of the SNMP interfaces in a time range, paged. Requires the SNMP capability and access to the system interface.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

Only the interfaces of this device

string

epoch_begin

query

Begin of the range (epoch)

integer

epoch_end

query

End of the range (epoch)

integer

start

query

First row

integer

length

query

Number of rows

integer

sort

query

Column to sort by

string

order

query

asc or desc

string

map_search

query

Text to search

string

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/snmp/metric/usage_chart.lua

SNMP interfaces usage chart

  • Description: Usage distribution of the SNMP interfaces in a time range, for the usage chart. Requires the SNMP capability and access to the system interface.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

Only the interfaces of this device

string

epoch_begin

query

Begin of the range (epoch)

integer

epoch_end

query

End of the range (epoch)

integer

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/issue/list.lua

List issues

  • Description: List the issues of a view, with filters, sorting and paging. Each record has issue_id, status (open|resolved), severity {id, label}, alert {id, name}, entity {id, label, value, name, host, role, url (host and flow issues: the host page on the first interface where the issue has been seen)}, ifids, interfaces [{id, name}] (where the issue has been seen), first_seen, last_seen, resolved_at, duration, signal_count, score (highest score of the alerts), total_score (sum of the scores of the alerts), peers_count, peers_sample, reopen_count, resolve_policy (on_release|quiet_period|manual), auto_resolve_at (open quiet_period issues: when resolved unless new alerts arrive), resolution, ack_user, ack_tstamp, assignee, suppressed, suppressed_until, tags [{id, name, color}] (union of the tags of the alerts of the issue, host and flow alerts only), alerts_url. The total is in recordsTotal. Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

view

query

problems (open issues, default), recent (resolved in the last 24 hours) or history (all the issues active in epoch_begin..epoch_end)

string

epoch_begin

query

Start time (epoch, view history only)

integer

epoch_end

query

End time (epoch, view history only)

integer

severity

query

Severity identifiers, comma separated (e.g. ‘5’ or ‘5;eq,6;eq’)

string

alert_id

query

Alert type identifiers, comma separated

string

entity_id

query

Alert entity identifiers, comma separated (e.g. 1 host, 4 flow)

string

assignee

query

Users the issues are assigned to, comma-separated (~: unassigned)

string

tag

query

Tag ids (0-63), comma-separated: the issues with one of the tags (tags of their alerts)

string

suppressed

query

Open issues: 1 the suppressed issues, 0 the not suppressed ones (default), 0,1 both

string

resolve_policy

query

Open issues: comma-separated ways they are resolved: 0 when the alert ends, 1 after 24 hours without alerts, 2 only by a user

string

opened_within

query

Only the issues first seen in the last seconds (e.g. 3600). Heatmap: also its time window (3600, 86400 or 172800, the default)

integer

map_search

query

Text searched in the entity (e.g. part of an IP), or an issue ID (e.g. 1573 or #1573)

string

host

query

Host (IP or IP@VLAN): only the issues of the host and the flow issues about it

string

alert_category

query

Alert categories, comma-separated

string

mitre_tactic

query

MITRE tactic ids of the alert types, comma-separated (0: no tactic)

string

problem

query

Alert types as <alert entity id>:<alert id>, comma-separated (e.g. 4:102,1:3)

string

issue_entity

query

Entity of the issues as <alert entity id>|<entity value> (e.g. 0|12 for interface 12)

string

issue_peer

query

Peer of the issues: an IP (the issues whose only peer is it), * (the issues with several peers) or ~ (the issues without peers)

string

show_suppressed

query

View problems: include the suppressed issues (default false)

boolean

only_suppressed

query

View problems: only the suppressed issues (default false)

boolean

start

query

First record (default 0)

integer

length

query

Number of records (default 10, max 500)

integer

sort

query

Sort column: issue_id, severity, score, first_seen, last_seen (default), resolved_at, signal_count, total_score, peers_count, alert_id, entity_val

string

order

query

asc or desc (default)

string

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (unknown view)

GET /lua/pro/rest/v2/get/issue/counters.lua

Issue counters

  • Description: Number of open (not suppressed) problems (problems) and by severity (problems_by_severity), of the issues of each view (views.problems, views.recent) and of the suppressed problems (suppressed). Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

Host (IP or IP@VLAN): only the issues of the host and the flow issues about it

string

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/issue/stats.lua

Issue manager statistics

  • Description: Internal statistics of the issue manager: loaded, issues in memory (num_open, num_recent, num_in_memory), pending writes (num_unsaved, num_pending_events, num_pending_notifications), num_signals, num_tracked_flows, dropped events and notifications, writer_since, and the queue of the ClickHouse flow alerts (flow_alert_queue_len, flow_alert_queue_bytes, num_flow_alerts_queued, num_flow_alert_drops, num_flow_alerts_processed, last_flow_alert_batch_alerts, last_flow_alert_batch_msec). Enterprise XXL+ only, requires alerts enabled. Administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED (not an administrator)

GET /lua/pro/rest/v2/get/issue/facets.lua

Issue facets

  • Description: For each facet (entity_id, severity, alert_category, mitre_tactic, problem, assignee, tag: all the tags, those without issues last with count 0, suppressed and resolve_policy: problems view only), the number of issues of each value (at most 12 except tag, the largest first; severities the most severe first) among the issues matching the filters of the other facets. Values have a label, or a label_key to translate. Same filters of the issue list. Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

view

query

problems (open issues, default), recent (resolved in the last 24 hours) or history (all the issues active in epoch_begin..epoch_end)

string

epoch_begin

query

Start time (epoch, view history only)

integer

epoch_end

query

End time (epoch, view history only)

integer

severity

query

Severity identifiers, comma separated (e.g. ‘5’ or ‘5;eq,6;eq’)

string

alert_id

query

Alert type identifiers, comma separated

string

entity_id

query

Alert entity identifiers, comma separated (e.g. 1 host, 4 flow)

string

assignee

query

Users the issues are assigned to, comma-separated (~: unassigned)

string

tag

query

Tag ids (0-63), comma-separated: the issues with one of the tags (tags of their alerts)

string

suppressed

query

Open issues: 1 the suppressed issues, 0 the not suppressed ones (default), 0,1 both

string

resolve_policy

query

Open issues: comma-separated ways they are resolved: 0 when the alert ends, 1 after 24 hours without alerts, 2 only by a user

string

opened_within

query

Only the issues first seen in the last seconds (e.g. 3600). Heatmap: also its time window (3600, 86400 or 172800, the default)

integer

map_search

query

Text searched in the entity (e.g. part of an IP), or an issue ID (e.g. 1573 or #1573)

string

host

query

Host (IP or IP@VLAN): only the issues of the host and the flow issues about it

string

alert_category

query

Alert categories, comma-separated

string

mitre_tactic

query

MITRE tactic ids of the alert types, comma-separated (0: no tactic)

string

problem

query

Alert types as <alert entity id>:<alert id>, comma-separated (e.g. 4:102,1:3)

string

show_suppressed

query

View problems: include the suppressed issues (default false)

boolean

only_suppressed

query

View problems: only the suppressed issues (default false)

boolean

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (unknown view)

GET /lua/pro/rest/v2/get/issue/groups.lua

Issue groups

  • Description: Issues grouped by one dimension (group_by), the most severe groups first, then the largest. Each group has key, label, entity (entity type label, problem and host groups only), count, max_severity, last_seen, signal_count, total_score (sum of the scores of the alerts) and params: the parameters to add to list.lua to get the issues of the group, or to this endpoint for a further level. has_more tells if there are more groups. Same filters of the issue list. Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

group_by

query

Dimension of the groups: problem (alert type), host, peer (the only peer, * several peers, ~ none), severity, alert_category, entity_id (alert family), mitre_tactic or assignee (each user: an issue assigned to several users is in the group of each of them)

string

view

query

problems (open issues, default), recent (resolved in the last 24 hours) or history (all the issues active in epoch_begin..epoch_end)

string

epoch_begin

query

Start time (epoch, view history only)

integer

epoch_end

query

End time (epoch, view history only)

integer

severity

query

Severity identifiers, comma separated (e.g. ‘5’ or ‘5;eq,6;eq’)

string

alert_id

query

Alert type identifiers, comma separated

string

entity_id

query

Alert entity identifiers, comma separated (e.g. 1 host, 4 flow)

string

assignee

query

Users the issues are assigned to, comma-separated (~: unassigned)

string

tag

query

Tag ids (0-63), comma-separated: the issues with one of the tags (tags of their alerts)

string

suppressed

query

Open issues: 1 the suppressed issues, 0 the not suppressed ones (default), 0,1 both

string

resolve_policy

query

Open issues: comma-separated ways they are resolved: 0 when the alert ends, 1 after 24 hours without alerts, 2 only by a user

string

opened_within

query

Only the issues first seen in the last seconds (e.g. 3600). Heatmap: also its time window (3600, 86400 or 172800, the default)

integer

map_search

query

Text searched in the entity (e.g. part of an IP), or an issue ID (e.g. 1573 or #1573)

string

host

query

Host (IP or IP@VLAN): only the issues of the host and the flow issues about it

string

alert_category

query

Alert categories, comma-separated

string

mitre_tactic

query

MITRE tactic ids of the alert types, comma-separated (0: no tactic)

string

problem

query

Alert types as <alert entity id>:<alert id>, comma-separated (e.g. 4:102,1:3)

string

issue_entity

query

Entity of the issues as <alert entity id>|<entity value> (e.g. 0|12 for interface 12)

string

issue_peer

query

Peer of the issues: an IP (the issues whose only peer is it), * (the issues with several peers) or ~ (the issues without peers)

string

show_suppressed

query

View problems: include the suppressed issues (default false)

boolean

only_suppressed

query

View problems: only the suppressed issues (default false)

boolean

start

query

First record (default 0)

integer

length

query

Number of records (default 10, max 500)

integer

sort

query

Sort column: severity (most severe issue of the group, default), count (number of issues), signal_count (number of alerts), total_score (sum of the scores of the alerts)

string

order

query

asc or desc (default)

string

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (unknown view)

GET /lua/pro/rest/v2/get/issue/heatmap.lua

Issue heatmap

  • Description: Issue activity in a time window (opened_within: 1 hour, 24 hours, or 48 hours by default), in slots of 1, 15 or 30 minutes: slot (seconds), begin and end (epochs) and cells, a list of { tstamp, severity, value, issues } where value is the number of issues opened, reopened or escalated to that severity in the slot (events) and issues the number of distinct issues, only for the severities from min_severity (the minimum severity of the alerts opening issues, Preferences > Alerts). Same filters of the issue list, except the view and its time range. Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

severity

query

Severity identifiers, comma separated (e.g. ‘5’ or ‘5;eq,6;eq’)

string

alert_id

query

Alert type identifiers, comma separated

string

entity_id

query

Alert entity identifiers, comma separated (e.g. 1 host, 4 flow)

string

assignee

query

Users the issues are assigned to, comma-separated (~: unassigned)

string

tag

query

Tag ids (0-63), comma-separated: the issues with one of the tags (tags of their alerts)

string

suppressed

query

Open issues: 1 the suppressed issues, 0 the not suppressed ones (default), 0,1 both

string

resolve_policy

query

Open issues: comma-separated ways they are resolved: 0 when the alert ends, 1 after 24 hours without alerts, 2 only by a user

string

opened_within

query

Only the issues first seen in the last seconds (e.g. 3600). Heatmap: also its time window (3600, 86400 or 172800, the default)

integer

map_search

query

Text searched in the entity (e.g. part of an IP), or an issue ID (e.g. 1573 or #1573)

string

host

query

Host (IP or IP@VLAN): only the issues of the host and the flow issues about it

string

alert_category

query

Alert categories, comma-separated

string

mitre_tactic

query

MITRE tactic ids of the alert types, comma-separated (0: no tactic)

string

problem

query

Alert types as <alert entity id>:<alert id>, comma-separated (e.g. 4:102,1:3)

string

issue_entity

query

Entity of the issues as <alert entity id>|<entity value> (e.g. 0|12 for interface 12)

string

issue_peer

query

Peer of the issues: an IP (the issues whose only peer is it), * (the issues with several peers) or ~ (the issues without peers)

string

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (unknown view)

GET /lua/pro/rest/v2/get/alert/groups.lua

Alert groups

  • Description: Alerts grouped by one dimension (Alerts Overview and issue preview), on the Alert Explorer stores (ClickHouse or SQLite) merged with the live alerts in memory (engaged host alerts, active flows with an alert). Any Alert Explorer filter (e.g. alert_id=79;eq, ip=192.168.1.1;eq, cli_ip, srv_ip) narrows the alerts; each group returns key, label, count, max_severity, max_score, first_seen, last_seen, families, the distinct hosts and the filters that select it in the Alert Explorer. Enterprise L+ only, with the Experimental Features preference or the issues enabled, and the alerts capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface identifier (default: the current one)

integer

epoch_begin

query

Start of the time range (epoch seconds)

integer

epoch_end

query

End of the time range (epoch seconds)

integer

group_by

query

Dimension of the groups (default alert_id)

string

page

query

Alert family: only its alerts (default: flow and host alerts)

string

status

query

Alert status: historical (require attention, default), acknowledged or any

string

sort

query

Order of the groups (default priority)

string

order

query

Direction of the sort (default desc)

string

limit

query

Maximum number of groups (default 50, max 500)

integer

episodes

query

0 to skip the episodes count (ClickHouse only, default 1)

integer

episode_gap

query

Maximum pause (seconds) between alerts of the same episode (default 900)

integer

totals

query

1 to also return the totals of the grouping

integer

strict

query

0 to match also the flows where the alert_id filter type is only a secondary alert, as the Alert Explorer (default 1: predominant alert only, so that child groups add up to their parent). Live flows match their predominant alert only

integer

Responses

0 - OK

-3 - NOT_GRANTED (not Enterprise L+, feature not enabled or no alerts capability)

-5 - INVALID_ARGUMENTS (time range, page or group_by)

-6 - INTERNAL_ERROR

GET /lua/pro/rest/v2/get/issue/details.lua

Issue details

  • Description: Details of an issue (same fields as get/issue/list.lua, plus alert.description: what the alert type means, from the check that triggers it, when it has one). Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

issue_id

query

Issue identifier

integer

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

-1 - NOT_FOUND

GET /lua/pro/rest/v2/get/issue/events.lua

Issue timeline

  • Description: Events of an issue, oldest first: tstamp, event (open, escalate, resolve, reopen, acknowledge, assign, comment, suppress), user, info (e.g. severities, resolution, assignee, comment text). Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

issue_id

query

Issue identifier

integer

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/issue/signals.lua

Issue alerts

  • Description: Latest alerts (signals) of an issue, newest first. Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

issue_id

query

Issue identifier

integer

length

query

Number of alerts (default 20, max 100)

integer

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

-1 - NOT_FOUND

GET /lua/pro/rest/v2/get/issue/assignees.lua

Issue assignees

  • Description: Users an issue can be assigned to. Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

POST /lua/pro/rest/v2/edit/issue/acknowledge.lua

Acknowledge an issue

  • Description: Records that the current user is handling the issue. The acknowledgement is cleared when the severity rises or the issue is reopened. POST (JSON or form data, CSRF checked). Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

issue_id

formData

Issue identifier

integer

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

-1 - NOT_FOUND

-5 - INVALID_ARGUMENTS: rsp.error tells why (not_open, not_resolved, newer_issue_open, expired)

POST /lua/pro/rest/v2/edit/issue/assign.lua

Assign an issue

  • Description: Assigns the issue to a user (empty: unassigned). POST (JSON or form data, CSRF checked). Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

issue_id

formData

Issue identifier

integer

assignee

formData

Usernames, comma-separated (the issue is assigned to all of them), empty to unassign

string

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

-1 - NOT_FOUND

-5 - INVALID_ARGUMENTS: rsp.error tells why (not_open, not_resolved, newer_issue_open, expired)

-24 - USER_DOES_NOT_EXIST

POST /lua/pro/rest/v2/edit/issue/comment.lua

Comment an issue

  • Description: Adds a comment to the issue timeline. POST (JSON or form data, CSRF checked). Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

issue_id

formData

Issue identifier

integer

comment

formData

Comment text (max 4096 characters)

string

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

-1 - NOT_FOUND

-5 - INVALID_ARGUMENTS

POST /lua/pro/rest/v2/edit/issue/group.lua

Apply an action to a group of issues

  • Description: Applies the same user action to all the issues matching the filters of get/issue/list.lua (e.g. the params of a group of get/issue/groups.lua), written once. The issues the action does not apply to (e.g. resolve on a resolved issue) are skipped and counted in skipped by error id (not_found, not_open, not_resolved, newer_issue_open). An optional comment is added to each changed issue; with action comment only the comment is added, to all the matching issues. The changes are written in batches of 500. A group larger than the maximum number of open issues (preference issues_max_open, 50000 by default, as resolve_all.lua) is refused (error too_many, rsp.max), never changed in part. POST (JSON or form data, CSRF checked). Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

action

formData

The action: acknowledge, assign, suppress, severity, resolve, reopen or comment

string

issue_assignee

formData

assign: comma-separated users, empty to unassign (assignee is the filter of the issues)

string

duration

formData

suppress: seconds, 0 to remove the suppression

integer

issue_severity

formData

severity: 3=notice, 4=warning, 5=error, 6=critical, 8=emergency (severity is the filter of the issues)

integer

comment

formData

Comment added to each changed issue (max 4096 characters), required with action comment

string

view

formData

problems (default), recent or history (with epoch_begin, epoch_end)

string

host

formData

Filter: IP or IP@VLAN. The other filters of get/issue/list.lua (problem, severity, entity_id, alert_category, mitre_tactic, assignee, tag, suppressed, resolve_policy, issue_peer, issue_entity, opened_within) are accepted too

string

Responses

0 - OK: { matched (issues of the group), done (issues changed), skipped (error id -> number of issues) }

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (rsp.error too_many: more than rsp.max issues)

-6 - INTERNAL_ERROR (the comment could not be written)

POST /lua/pro/rest/v2/edit/issue/severity.lua

Change the severity of an issue

  • Description: Set the severity of an open issue (3=notice, 4=warning, 5=error, 6=critical, 8=emergency), e.g. to escalate it. A higher severity is an escalation: the acknowledgement is cleared and the recipients of the issues are notified. Later alerts more severe than the chosen severity still raise it. Recorded in the issue events (severity) with the user. Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

issue_id

formData

Issue identifier

integer

severity

formData

The severity: 3=notice, 4=warning, 5=error, 6=critical, 8=emergency

integer

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

-1 - NOT_FOUND

-5 - INVALID_ARGUMENTS: rsp.error tells why (not_open, not_resolved, newer_issue_open, expired)

POST /lua/pro/rest/v2/edit/issue/suppress.lua

Suppress an issue

  • Description: Suppresses the issue notifications for a time: the issue is hidden from the problems unless show_suppressed is set. POST (JSON or form data, CSRF checked). Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

issue_id

formData

Issue identifier

integer

duration

formData

Seconds, 0 removes the suppression

integer

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

-1 - NOT_FOUND

-5 - INVALID_ARGUMENTS: rsp.error tells why (not_open, not_resolved, newer_issue_open, expired)

POST /lua/pro/rest/v2/edit/issue/resolve.lua

Resolve an issue

  • Description: Resolves an open issue (resolution manual), with an optional comment added to its timeline. POST (JSON or form data, CSRF checked). Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

issue_id

formData

Issue identifier

integer

comment

formData

Comment added to the timeline of the issue when resolved (at most 4096 characters)

string

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

-1 - NOT_FOUND

-5 - INVALID_ARGUMENTS: rsp.error tells why (not_open, not_resolved, newer_issue_open, expired)

-6 - INTERNAL_ERROR (the issue was resolved, the comment could not be written)

POST /lua/pro/rest/v2/edit/issue/resolve_all.lua

Resolve all the issues matching the filters

  • Description: Resolves all the open issues matching the filters of the issue list (view problems; same filters as get/issue/list.lua: entity_id, severity, alert_category, mitre_tactic, problem, assignee, tag, suppressed, resolve_policy, opened_within, map_search, host, issue_entity, issue_peer), as the Resolve All button of the issues page. Each one is resolved as by edit/issue/resolve.lua (resolution manual, recipients notified), with the optional comment added to its timeline. Answer: resolved (issues resolved) and matching (issues matching the filters; the others were resolved meantime). POST (JSON or form data, CSRF checked). Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

view

formData

problems (default, the only one accepted)

string

severity

formData

Comma-separated severity ids (e.g. 4,5); the other filters as in get/issue/list.lua

string

comment

formData

Comment added to the timeline of each issue resolved (at most 4096 characters)

string

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (view other than problems, invalid filters)

-6 - INTERNAL_ERROR (the issues were resolved, the comment could not be written)

POST /lua/pro/rest/v2/edit/issue/reopen.lua

Reopen an issue

  • Description: Reopens a resolved issue: from then on it is resolved only by a user. POST (JSON or form data, CSRF checked). Enterprise XXL+ only, requires alerts enabled and the alerts capability.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

issue_id

formData

Issue identifier

integer

Responses

0 - OK

-2 - NOT_ENABLED (not Enterprise XXL+, alerts disabled or Issues preference off)

-3 - NOT_GRANTED

-1 - NOT_FOUND

-5 - INVALID_ARGUMENTS: rsp.error tells why (not_open, not_resolved, newer_issue_open, expired)

GET /lua/pro/rest/v2/get/flow/geomap.lua

Get the active flows on the map

  • Description: The hosts of the active flows placed by GeoIP (nodes: ip, label, lat, lng, country, protocols, connectionCount, status) and the flows between them (edges), at most 512 flows. Same filters of get/flow/active_list.lua (e.g. application, l4proto, flowhosts_type, status, vlan, host). Enterprise L with the GeoIP database.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface id

integer

flowhosts_type

query

Host filter, also ip_version_4 / ip_version_6 or a host (IP[@vlan])

string

application

query

Application (nDPI id)

string

l4proto

query

Layer 4 protocol number

integer

status

query

Flow status / alert type

string

vlan

query

VLAN id

integer

Responses

0 - OK

-3 - NOT_GRANTED (no Enterprise L or no GeoIP)

GET /lua/rest/v2/get/flow/aggregated_live_flows.lua

Get the active flows grouped by a criteria

  • Description: The active flows of the interface grouped by application, client, server, client/server/port, host, AS… Each row has flows, tot_score, bytes_sent, bytes_rcvd, tot_traffic, num_clients, num_servers and the grouping keys (application { id, label }, client/server/host { ip, label, vlan_id, in_memory, is_alerted, flags }, srv_port, src_as/dst_as/transit_as, info). The criteria besides application_protocol, client, server, client_server_srv_port, client_server_srv_port_app_proto and host need Enterprise M.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface id

integer

aggregation_criteria

query

application_protocol (default), client, server, client_server, app_client_server_criteria, info, client_server_srv_port, client_server_srv_port_app_proto, src_as_dst_as, src_as_transit_as_dst_as, host

string

start

query

Index of the first row (paging)

integer

length

query

Number of rows (paging)

integer

sort

query

Column to sort by (e.g. flows, tot_traffic, tot_score)

string

order

query

asc or desc

string

map_search

query

Text to search

string

host

query

Only the flows of this host

string

vlan_id

query

VLAN id

integer

status

query

Flow status / alert filter

integer

deviceIP

query

Flow exporter IP

string

ifIdx

query

Exporter interface index

integer

srv_port

query

Only the flows with this server port

integer

l4proto

query

Only the flows with this L4 protocol ID (e.g. 6 = TCP)

integer

application

query

Only the flows with this nDPI protocol: ‘master.app’ IDs (e.g. 7.26) or a single ID

string

inIfIdx

query

Exporter input interface index

integer

outIfIdx

query

Exporter output interface index

integer

host_locality

query

With aggregation_criteria=host: local or remote

string

site_id

query

With aggregation_criteria=host: site id

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/rest/v2/get/flow/active_list.lua

Get the active flows

  • Description: The flows currently active on the interface, with paging, sorting and the same filters of the Live Flows page. Each flow carries client and server (ip, name, port, vlan, asn, country…), application, l4_proto, bytes, throughput, score, alerts, first_seen/last_seen, flow_swapped (true when the ntopng direction heuristics swapped client and server) and, on flow-based interfaces, the exporter (the router/switch that exported the flow) and its input/output interfaces; on view interfaces seen_on_interface { id, name } is the interface of the view where ntopng saw the flow. recordsTotal is the number of flows matching the filters.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface id

integer

start

query

Index of the first flow (paging)

integer

length

query

Number of flows to return (paging)

integer

sort

query

Column to sort by (e.g. bytes, throughput, score, first_seen, last_seen, duration)

string

order

query

asc or desc

string

map_search

query

Text to search in the flows

string

application

query

Application (nDPI id, or <master>.<app>)

string

l4proto

query

Layer 4 protocol number (e.g. 6 TCP, 17 UDP)

integer

flowhosts_type

query

local_only, remote_only, local_origin_remote_target, remote_origin_local_target, ip_version_4, ip_version_6

string

status

query

normal, alerted, connecting, closed, error, or an alert type id

string

traffic_type

query

unicast, broadcast_multicast, one_way_unicast, one_way_broadcast_multicast

string

host

query

Flows of this host (IP[@vlan])

string

client

query

Flows with this client

string

server

query

Flows with this server

string

port

query

Flows with this port

integer

vlan

query

VLAN id

integer

network

query

Local network id

integer

host_pool_id

query

Host pool id

integer

site_id

query

Site id

integer

dst_asn

query

Destination AS number

integer

qoe

query

Quality of Experience class, 0 (worst) to 5 (best)

string

deviceIP

query

Flow exporter IP

string

inIfIdx

query

Exporter input interface index

integer

outIfIdx

query

Exporter output interface index

integer

interface_filter

query

Sub-interface (view interfaces)

integer

flow_risk

query

nDPI flow risk id

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/pro/rest/v2/get/host/server_ports.lua

Get the server ports of the live flows

  • Description: The server ports seen in the live flows of the interface for a layer 4 protocol: srv_port, l4_proto, proto_id (nDPI <master>.<app> or <master>), l7_proto_name and n_hosts (servers using it). Enterprise L. Only the flows of the user allowed networks and host pools.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface id

integer

protocol

query

Layer 4 protocol: 6 (TCP) or 17 (UDP)

integer

vlan_id

query

VLAN id (default: all the VLANs)

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

-3 - NOT_GRANTED (no Enterprise L)

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/host/hosts_details_by_port.lua

Get the hosts serving a port

  • Description: The hosts serving a server port in the live flows (ip, name, vlan_id, mac, mac_manufacturer, flows, score, tot_traffic), paged (recordsTotal). A missing or stale application/port falls back to the first available one: the answer has the values used (protocol, application, port) and the options of the page filters, counted on all the hosts of the port: applications [{id, name}], ports [{port, n_hosts}] of the application, vlans [{id, name, count}], manufacturers [{name, count}]. Enterprise L.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface id

integer

protocol

query

Layer 4 protocol: 6 (TCP, default) or 17 (UDP)

integer

application

query

nDPI application, <master>.<app> or <master> (e.g. 7.26, 91); default: the first one by name

string

port

query

Server port; default: the first port of the application

integer

vlan_id

query

Only the hosts of this VLAN

integer

manufacturer

query

Only the hosts with this MAC manufacturer

string

sort

query

Sort column: ip, name, vlan_id, mac, mac_manufacturer, score, flows, tot_traffic

string

order

query

asc or desc

string

start

query

First row (paging)

integer

length

query

Number of rows (paging, default 10)

integer

Responses

0 - OK

-3 - NOT_GRANTED (no Enterprise L)

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/vlan/live_ports.lua

Get the server ports by VLAN (live)

  • Description: Sankey of the live flows: nodes (node_id vlan_<id> / port_<port>, label, link) and links (VLAN -> server port, label = application, value = bytes, l4_proto, l7_proto, optional_info.link to the live flows), the links with the most traffic first; vlans [{id, name}]: all the VLANs with flows; max_entries_reached when cut at limit. Only the flows of the user allowed networks and host pools.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface id

integer

vlan

query

Only this VLAN

integer

l4proto

query

Layer 4 protocol number (default TCP and UDP)

integer

limit

query

Max number of links (default 35)

integer

Responses

0 - OK

-2 - INVALID_INTERFACE

GET /lua/pro/rest/v2/get/vlan/historical_ports.lua

Get the server ports by VLAN (historical)

  • Description: Same answer of get/vlan/live_ports.lua from the historical flows (ClickHouse) of the last timeframe seconds, at most 35 links; links open the historical flows. vlans [{id, name}]: the VLANs of the links. Only the flows of the user allowed networks and host pools. Needs the historical flows capability (non-admin users).

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface id

integer

timeframe

query

Seconds before now (e.g. 3600)

integer

vlan

query

Only this VLAN

integer

l4proto

query

Layer 4 protocol number; empty or -1: TCP and UDP

integer

Responses

0 - OK

-3 - NOT_GRANTED

-2 - INVALID_INTERFACE

-5 - INVALID_ARGUMENTS

GET /lua/rest/v2/get/flow/bgp/looking_glass.lua

Get the BGP routes of an IP address

  • Description: The routes of the BGP RIB entry of an IP address (BGP feed), one row per prefix and peer: prefix, asn (of the IP), peer, peer_name and peer_site (when known), is_best_path, peer_asn { asn, name }, origin, as_path [{ asn, name }], next_hop, med, local_pref and communities. An empty list when the IP is missing, invalid or has no route.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

host

query

IPv4 or IPv6 address

string

Responses

0 - OK

GET /lua/pro/rest/v2/get/llm/audit_log.lua

Get the AI audit log

  • Description: Actions done by the nAnalyst agent and by the users from the AI features, newest first (at most 500 rows). Enterprise, ClickHouse, nAnalyst license, administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

epoch_begin

query

Only actions from this time (epoch)

integer

epoch_end

query

Only actions up to this time (epoch)

integer

username

query

Only the actions of this user

string

tool_name

query

Only this tool (e.g. create_ai_policy)

string

triggered_by

query

llm (agent) or user (direct action)

string

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/llm/token_usage.lua

Get the LLM token usage

  • Description: Calls, tokens and response times of the LLM calls in a time range: summary, by model, by call type, by user and timeline. Non administrators get only their own usage. Enterprise, ClickHouse, nAnalyst license.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

epoch_begin

query

Range begin (epoch)

integer

epoch_end

query

Range end (epoch)

integer

provider

query

Only this provider (e.g. llm_openai)

string

model

query

Only this model

string

username

query

Only this user (administrators only)

string

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/llm/model_prices.lua

Get the LLM model prices

  • Description: Price per million tokens (input and output, USD) of each model, used to compute the costs. Enterprise, ClickHouse, nAnalyst license, administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

POST /lua/pro/rest/v2/post/llm/upsert_model_price.lua

Add or edit an LLM model price

  • Description: Sets the price per million tokens of a model. Enterprise, ClickHouse, nAnalyst license, administrators only.

  • Consumes: [‘application/json’, ‘application/x-www-form-urlencoded’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

provider

formData

Provider id (e.g. llm_openai)

string

model

formData

Model name

string

input_price_usd

formData

USD per million input tokens

number

output_price_usd

formData

USD per million output tokens

number

edit

formData

true to edit an existing price

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

POST /lua/pro/rest/v2/post/llm/delete_model_price.lua

Delete an LLM model price

  • Description: Removes the price of a model. Enterprise, ClickHouse, nAnalyst license, administrators only.

  • Consumes: [‘application/json’, ‘application/x-www-form-urlencoded’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

provider

formData

Provider id

string

model

formData

Model name

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/ai_policy/list.lua

Get the AI policies

  • Description: Policies: SQL queries on the historical data run at a fixed frequency, a non empty result raises an alert. With trigger and run counts. Enterprise XL, ClickHouse, nAnalyst license, administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

periodicity

query

Only this frequency: min, 5min, hourly, daily

string

Responses

0 - OK

-3 - NOT_GRANTED

POST /lua/pro/rest/v2/post/ai_policy/upsert.lua

Add an AI policy

  • Description: Saves a new policy. Enterprise XL, ClickHouse, nAnalyst license, administrators only.

  • Consumes: [‘application/json’, ‘application/x-www-form-urlencoded’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ai_policy_name

formData

Policy name

string

sql_query

formData

ClickHouse query: a non empty result is a violation

string

periodicity

formData

min, 5min, hourly or daily

string

policy_description

formData

Description

string

alert_description

formData

Message shown in the alert

string

custom_score

formData

Alert score (1, 10, 50, 100, 150, 200, 250)

integer

explanation

formData

How the query works

string

message_template

formData

Alert message template

string

message_variables

formData

JSON array of the template variables

string

Responses

0 - OK

-3 - NOT_GRANTED

-6 - MISSING_PARAMETERS

-4 - BAD_FORMAT

POST /lua/pro/rest/v2/post/ai_policy/update.lua

Edit an AI policy

  • Description: Changes an existing policy (same fields of the add, plus its id). Enterprise XL, ClickHouse, nAnalyst license, administrators only.

  • Consumes: [‘application/json’, ‘application/x-www-form-urlencoded’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

policy_id

formData

Policy id

integer

ai_policy_name

formData

Policy name

string

sql_query

formData

ClickHouse query

string

periodicity

formData

min, 5min, hourly or daily

string

policy_description

formData

Description

string

alert_description

formData

Message shown in the alert

string

custom_score

formData

Alert score

integer

explanation

formData

How the query works

string

message_template

formData

Alert message template

string

message_variables

formData

JSON array of the template variables (omitted: kept)

string

Responses

0 - OK

-3 - NOT_GRANTED

-6 - MISSING_PARAMETERS

-1 - NOT_FOUND

POST /lua/pro/rest/v2/delete/ai_policy/delete.lua

Delete an AI policy

  • Description: Removes a policy. Enterprise XL, ClickHouse, nAnalyst license, administrators only.

  • Consumes: [‘application/json’, ‘application/x-www-form-urlencoded’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

policy_id

formData

Policy id

integer

Responses

0 - OK

-3 - NOT_GRANTED

-6 - MISSING_PARAMETERS

GET /lua/pro/rest/v2/get/analyst_pipeline/list.lua

Get the analyst playbooks

  • Description: Saved playbooks (multi step investigations, SQL queries on the historical data) with name, description, provider and date. Enterprise XL, ClickHouse, nAnalyst license, administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface id

integer

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/analyst_pipeline/get.lua

Get an analyst playbook

  • Description: One playbook with its definition (params, stages and their SQL templates). Enterprise XL, ClickHouse, nAnalyst license, administrators only.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

pipeline_id

query

Playbook id (UUID)

string

Responses

0 - OK

-3 - NOT_GRANTED

-6 - MISSING_PARAMETERS

-1 - NOT_FOUND

POST /lua/pro/rest/v2/delete/analyst_pipeline/delete.lua

Delete an analyst playbook

  • Description: Removes a playbook. Enterprise XL, ClickHouse, nAnalyst license, administrators only.

  • Consumes: [‘application/json’, ‘application/x-www-form-urlencoded’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

pipeline_id

formData

Playbook id (UUID)

string

Responses

0 - OK

-3 - NOT_GRANTED

-6 - MISSING_PARAMETERS

GET /lua/pro/rest/v2/get/traffic_model/server_types.lua

Get the server types

  • Description: Server types of the traffic model (DNS, NTP, …): id, label, application protocols. Enterprise XL, ClickHouse.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

Responses

0 - OK

-3 - NOT_GRANTED

GET /lua/pro/rest/v2/get/traffic_model/servers.lua

Get the servers of a day range

  • Description: Servers of a type seen in a day range, from the daily model built on the historical flows, one page per request. Enterprise XL, ClickHouse, checks capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

server_type

query

Server type id (see server_types)

integer

day

query

First day (YYYY-MM-DD)

string

day_to

query

Last day (YYYY-MM-DD), default: day

string

start

query

Row offset

integer

length

query

Page size (default 10, max 500)

integer

sort

query

Column to sort by

string

order

query

asc or desc

string

map_search

query

Text searched in the server address

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (also when the query fails)

GET /lua/pro/rest/v2/get/traffic_model/expected.lua

Get the servers against the expected ones

  • Description: Servers seen in a day range against the expected ones of the Network Configuration: EXPECTED, UNEXPECTED, MISSING, with a summary. Enterprise XL, ClickHouse, checks capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

server_type

query

Server type id

integer

day

query

First day (YYYY-MM-DD)

string

day_to

query

Last day (YYYY-MM-DD)

string

section

query

seen (servers seen) or configured (expected ones)

string

status

query

Only this status

string

start

query

Row offset

integer

length

query

Page size (default 10, max 500)

integer

sort

query

Column to sort by

string

order

query

asc or desc

string

map_search

query

Text searched in the server address

string

l7_proto

query

Only the servers that received traffic of this nDPI protocol id

integer

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (also when the query fails)

GET /lua/pro/rest/v2/get/traffic_model/compare.lua

Compare the servers of two days

  • Description: Servers of a day against an earlier one: NEW, GONE, UP, DOWN, SAME, with a summary and the days without data. Enterprise XL, ClickHouse, checks capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

server_type

query

Server type id

integer

day_old

query

Reference day (YYYY-MM-DD)

string

day_new

query

Day to check (YYYY-MM-DD)

string

status

query

CHANGES (default, all but SAME), ALL, NEW, GONE, UP, DOWN, SAME

string

start

query

Row offset

integer

length

query

Page size (default 10, max 500)

integer

sort

query

Column to sort by

string

order

query

asc or desc

string

map_search

query

Text searched in the server address

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (also when the query fails)

GET /lua/pro/rest/v2/get/traffic_model/graph.lua

Get the traffic model graph of a day or of a host

  • Description: Busiest client to server communications of the interface in a day (IPv4 and IPv6), with the hosts as nodes. Servers carry server_type and role server. Enterprise XL, ClickHouse, checks capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface id

integer

day

query

Day (YYYY-MM-DD)

string

max_edges

query

Max communications returned (default and max 2000)

integer

host

query

Return only the communications of this host (IPv4 or IPv6)

string

host_role

query

With host: client (the host is the source, default is server) or server (the host is the destination)

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/traffic_model/clients.lua

Get the clients of the servers of a type

  • Description: Clients that used the servers of a type in a day range, from the daily model built on the historical flows: servers contacted (count and the busiest ones with their protocols), flows and bytes, one page per request. Enterprise XL, ClickHouse, checks capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

server_type

query

Server type id (see server_types)

integer

day

query

First day (YYYY-MM-DD)

string

day_to

query

Last day (YYYY-MM-DD), default is day

string

start

query

First row of the page

integer

length

query

Rows of the page (max 500)

integer

sort

query

ip, name, servers, days_seen, flows or bytes (default servers)

string

order

query

asc or desc (default)

string

map_search

query

Address or host name to search

string

server

query

Only the clients of this server address

string

l7_proto

query

Only the traffic of this nDPI protocol id

integer

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/traffic_model/client_servers.lua

Get the servers of a type contacted by a client

  • Description: Servers of a type contacted by one client in a day range, from the daily model built on the historical flows: protocols, flows and bytes, one page per request. Enterprise XL, ClickHouse, checks capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

ifid

query

Interface id

integer

server_type

query

Server type id (see server_types)

integer

client

query

Client address (IPv4 or IPv6)

string

day

query

First day (YYYY-MM-DD)

string

day_to

query

Last day (YYYY-MM-DD), default is day

string

start

query

First row of the page

integer

length

query

Rows of the page (max 500)

integer

sort

query

ip, name, days_seen, flows or bytes (default flows)

string

order

query

asc or desc (default)

string

map_search

query

Server address or host name to search

string

l7_proto

query

Only the traffic of this nDPI protocol id

integer

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

-2 - INVALID_INTERFACE

GET /lua/pro/rest/v2/get/traffic_model/protocols.lua

Get the protocols of the traffic towards the servers of a type

  • Description: Protocols (nDPI id and name) of the traffic towards the servers of a type in a day range, the busiest first: the values of the protocol filter. Enterprise XL, ClickHouse, checks capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

server_type

query

Server type id (see server_types)

integer

day

query

First day (YYYY-MM-DD)

string

day_to

query

Last day (YYYY-MM-DD), default is day

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

GET /lua/pro/rest/v2/get/traffic_model/calendar.lua

Get the days with server changes

  • Description: For each day of a range: nodata, baseline, same or changed (servers appeared and disappeared). Enterprise XL, ClickHouse, checks capability.

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

server_type

query

Server type id

integer

day_from

query

First day (YYYY-MM-DD)

string

day_to

query

Last day (YYYY-MM-DD)

string

Responses

0 - OK

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS

POST /lua/pro/rest/v2/delete/traffic_model/servers.lua

Remove servers from the server model

  • Description: Removes misclassified servers of a type from the server model of a day range: the given hosts, or all the servers of the type with all (the traffic model is kept). Enterprise XL, ClickHouse, checks capability, administrator.

  • Consumes: [‘application/json’]

  • Produces: [‘application/json’]

Parameters

Name

Position

Description

Type

body

body

Responses

0 - OK: { removed: number of valid addresses }

-3 - NOT_GRANTED

-5 - INVALID_ARGUMENTS (also when the delete fails)