Python API

ntopng provides a Python 3 API for querying the engine and retrieve traffic information by using the Python language.

The API is based on the ntopng REST API and it allows users to perform operations such as:

  • Read host statistics
  • Get the active flows list
  • Query network interface stats
  • Search historical flows

For each ntopng component there is a corresponding Python class (Host, Interface, Historical), and for each REST API call there is a corresponding method. The ntopng class is used to keep information about the ntopng configuration including IP address and credentials required to connect.

Prerequisites

The API is using Pandas and NumPy for working with time series data, plotly and fpdf for generating reports in PDF format, and a few additional libraries.

pip3 install -r requirements.txt

Installation

For you convenience, ntop periodically builds pip packages. You can install the latest available package as:

pip3 install ntopng

Examples

A few sample applications are distributed with the ntopng source code and are available at https://github.com/ntop/ntopng/tree/dev/python/examples

All the examples require:

Some of the examples also require an ntopng interface ID (-i option) and additional parameters (e.g. host).

Example:

python3 alerts.py -n http://localhost:3000 -i admin -p password -i 0

This sample application is printing alert statistics, please see below a code snippet for achieving the same:

# Connect to ntopng using the Ntopng class
my_ntopng = Ntopng(username, password, auth_token, ntopng_url)

# Get an Historical instance for a specific interface by ID
my_historical = my_ntopng.get_historical_interface(iface_id)

# Read alert statistics
data = my_historical.get_alerts_stats(epoch_begin, epoch_end)

# Print the raw statistics
print(data)

API

Ntopng

The Ntopng class stores information for accessing the ntopng instance (IP and credentials) and provides global traffic information and constants (interfaces, alert types, etc).

class ntopng.Ntopng(username=None, password=None, auth_token=None, url='http://localhost:3000')

Ntopng provides information about global data (e.g. list of interfaces) and consts (e.g. alert types)

Parameters:ntopng_obj – The ntopng handle
get_alert_severities()

Return all severities

Returns:The list of severities
Return type:array
get_alert_types()

Return all alert types

Returns:The list of alert types
Return type:array
get_historical_interface(ifid)

Return an Historical handle for an interface

Parameters:ifid (int) – The interface ID
Returns:The historical handle
Return type:ntopng.Historical
get_host_interfaces_list(host)

Return all ntopng interfaces for a given host

Parameters:host (string) – The host
Returns:List of interfaces
Return type:array
get_interface(ifid)

Return an Interface instance

Parameters:ifid (int) – The interface ID
Returns:The interface instance
Return type:ntopng.Interface
get_interfaces_list()

Return all available interfaces

Returns:The list of interfaces
Return type:array

Interface

The Interface class can be used to access information about interface statistics through the REST API (https://www.ntop.org/guides/ntopng/api/rest/api_v2.html).

class interface.Interface(ntopng_obj, ifid)

Interface provides information about a Network interface

Parameters:
  • ntopng_obj – The ntopng handle
  • ifid – The interface ID
get_active_flows_paginated(currentPage, perPage)

Retrieve the (paginated) list of active flows for the specified interface

Parameters:
  • currentPage (int) – The current page
  • perPage (int) – The number of results per page
Returns:

All active flows
Return type:

array
get_active_hosts()

Retrieve the list of active hosts for the specified interface

Returns:All active hosts
Return type:array
get_active_l4_proto_flow_counters()

Return statistics about active flows per Layer 4 protocol on an interface

Returns:Layer 4 protocol flows statistics
Return type:object
get_active_l7_proto_flow_counters()

Return statistics about active flows per Layer 7 protocol on an interface

Returns:Layer 7 protocol flows statistics
Return type:object
get_address()

Return the interface IP address(es)

Returns:The interface address(es)
Return type:array
get_all_alerts(ifid, epoch_begin, epoch_end, ip=None)

Return alerts for specified interface and epoch_begin and epoch_end. By default it returns all alerts

Returns:Flow alerts for the specified IP (if present)
Return type:object
get_broadcast_domains()

Return information about broadcast domains on an interface

Returns:Information about broadcast domains
Return type:object
get_data()

Return information about a Network interface

Returns:Information about the interface
Return type:object
get_dscp_stats()

Return statistics about DSCP

Returns:DSCP statistics
Return type:object
get_historical()

Return an Historical handle for the interface

Returns:The historical handle
Return type:ntopng.Historical
get_host(ip, vlan=None)

Return an Host instance

Parameters:
  • ifid (int) – The interface ID
  • ip (string) – The host IP address
  • vlan (int) – The host VLAN ID (if any)
Returns:

The host instance
Return type:

ntopng.Host
get_l7_stats(max_num_results)

Return statistics about Layer 7 protocols seen on an interface

Parameters:max_num_results (int) – The maximum number of results to limit the output
Returns:Layer 7 protocol statistics
Return type:object
get_top_local_talkers()

Return Top Local hosts generating more traffic

Returns:The top local hosts
Return type:array
get_top_remote_talkers()

Return Top Remote hosts generating more traffic

Returns:The top remote hosts
Return type:array

Host

The Host class can be used to access information about an host through the REST API (https://www.ntop.org/guides/ntopng/api/rest/api_v2.html).

class host.Host(ntopng_obj, ifid, ip, vlan=None)

Host provides information about hosts

Parameters:ntopng_obj – The ntopng handle
get_active_flows_paginated(currentPage, perPage)

Retrieve the (paginated) list of active flows for the specified interface and host

Parameters:
  • currentPage (int) – The current page
  • perPage (int) – The number of results per page
Returns:

All active flows
Return type:

array
get_dscp_stats(direction_rcvd)

Return statistics about DSCP per traffic direction for an host

Parameters:direction_rcvd (boolean) – The traffic direction (True for received traffic, False for sent)
Returns:DSCP statistics
Return type:object
get_host_data()

Return all available information about a single host

Returns:Information about the host
Return type:object
get_l7_stats()

Return statistics about Layer 7 protocols for the host

Returns:Layer 7 protocol statistics
Return type:object

Historical

The Historical class can be used to retrieve historical traffic data through the REST API (https://www.ntop.org/guides/ntopng/api/rest/api_v2.html).

class historical.Historical(ntopng_obj, ifid=None)

Historiacl provides access to historical information including flows and alerts

Parameters:ntopng_obj – The ntopng handle
get_active_monitoring_alerts(epoch_begin, epoch_end, select_clause, where_clause, maxhits, group_by, order_by)

Return alerts matching the specified criteria

Parameters:
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
  • select_clause (string) – Select clause (SQL syntax)
  • where_clause (string) – Where clause (SQL syntax)
  • maxhits (int) – Max number of results (limit)
  • group_by (string) – Group by condition (SQL syntax)
  • order_by (string) – Order by condition (SQL syntax)
Returns:

Query result
Return type:

object
get_alert_severity_counters(epoch_begin, epoch_end)

Return statistics about the number of alerts per alert severity

Parameters:
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
Returns:

Statistics
Return type:

object
get_alert_type_counters(epoch_begin, epoch_end)

Return statistics about the number of alerts per alert type

Parameters:
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
Returns:

Statistics
Return type:

object
get_alerts(alert_family, epoch_begin, epoch_end, select_clause, where_clause, maxhits, group_by, order_by)

Run queries on the alert database

Parameters:
  • alert_family (string) – The alert family (flow, host, interface, etc)
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
  • select_clause (string) – Select clause (SQL syntax)
  • where_clause (string) – Where clause (SQL syntax)
  • maxhits (int) – Max number of results (limit)
  • group_by (string) – Group by condition (SQL syntax)
  • order_by (string) – Order by condition (SQL syntax)
Returns:

Query result
Return type:

object
get_alerts_stats(epoch_begin, epoch_end, host=None)

Return flow alerts stats

Parameters:
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
  • host (string) – Host IP address (optional)
Returns:

Flow alert stats
Return type:

object
get_flow_alerts(epoch_begin, epoch_end, select_clause, where_clause, maxhits, group_by, order_by)

Return flow alerts matching the specified criteria

Parameters:
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
  • select_clause (string) – Select clause (SQL syntax)
  • where_clause (string) – Where clause (SQL syntax)
  • maxhits (int) – Max number of results (limit)
  • group_by (string) – Group by condition (SQL syntax)
  • order_by (string) – Order by condition (SQL syntax)
Returns:

Query result
Return type:

object
get_flow_alerts_stats(epoch_begin, epoch_end)

Return flow alerts stats

Parameters:
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
Returns:

Flow alert stats
Return type:

object
get_flows(epoch_begin, epoch_end, select_clause, where_clause, maxhits, group_by, order_by)

Run queries on the historical flows database (ClickHouse)

Parameters:
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
  • select_clause (string) – Select clause (SQL syntax)
  • where_clause (string) – Where clause (SQL syntax)
  • maxhits (int) – Max number of results (limit)
  • group_by (string) – Group by condition (SQL syntax)
  • order_by (string) – Order by condition (SQL syntax)
Returns:

Query result
Return type:

object
get_host_alerts(epoch_begin, epoch_end, select_clause, where_clause, maxhits, group_by, order_by)

Return host alerts matching the specified criteria

Parameters:
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
  • select_clause (string) – Select clause (SQL syntax)
  • where_clause (string) – Where clause (SQL syntax)
  • maxhits (int) – Max number of results (limit)
  • group_by (string) – Group by condition (SQL syntax)
  • order_by (string) – Order by condition (SQL syntax)
Returns:

Query result
Return type:

object
get_host_timeseries(host_ip, ts_schema, epoch_begin, epoch_end)

Return timeseries data in a pandas DataFrame for a specified interface and host

Parameters:
  • host_ip – The host IP
  • ts_schema (string) – The timeseries schema
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
Returns:

Timeseries data
Return type:

object (pandas DataFrame)
get_host_timeseries_stats(host_ip, ts_schema, epoch_begin, epoch_end)

Return timeseries statistics

Parameters:
  • host_ip – The host IP
  • ts_schema (string) – The timeseries schema
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
Returns:

Timeseries data
Return type:

object (pandas DataFrame)
get_host_top_protocols(host, epoch_begin, epoch_end)

Return Top protocols for an host

Parameters:
  • host (string) – Host IP address
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
Returns:

Top protocols
Return type:

object
get_interface_alerts(epoch_begin, epoch_end, select_clause, where_clause, maxhits, group_by, order_by)

Return interface alerts matching the specified criteria

Parameters:
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
  • select_clause (string) – Select clause (SQL syntax)
  • where_clause (string) – Where clause (SQL syntax)
  • maxhits (int) – Max number of results (limit)
  • group_by (string) – Group by condition (SQL syntax)
  • order_by (string) – Order by condition (SQL syntax)
Returns:

Query result
Return type:

object
get_interface_timeseries(ts_schema, epoch_begin, epoch_end)

Return timeseries data in a pandas DataFrame for a specified interface

Parameters:
  • ts_schema (string) – The timeseries schema
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
Returns:

Timeseries data
Return type:

object (pandas DataFrame)
get_interface_timeseries_stats(ts_schema, epoch_begin, epoch_end)

Return timeseries statistics

Parameters:
  • ts_schema (string) – The timeseries schema
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
Returns:

Timeseries data
Return type:

object (pandas DataFrame)
get_mac_alerts(epoch_begin, epoch_end, select_clause, where_clause, maxhits, group_by, order_by)

Return MAC alerts matching the specified criteria

Parameters:
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
  • select_clause (string) – Select clause (SQL syntax)
  • where_clause (string) – Where clause (SQL syntax)
  • maxhits (int) – Max number of results (limit)
  • group_by (string) – Group by condition (SQL syntax)
  • order_by (string) – Order by condition (SQL syntax)
Returns:

Query result
Return type:

object
get_network_alerts(epoch_begin, epoch_end, select_clause, where_clause, maxhits, group_by, order_by)

Return Network alerts matching the specified criteria

Parameters:
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
  • select_clause (string) – Select clause (SQL syntax)
  • where_clause (string) – Where clause (SQL syntax)
  • maxhits (int) – Max number of results (limit)
  • group_by (string) – Group by condition (SQL syntax)
  • order_by (string) – Order by condition (SQL syntax)
Returns:

Query result
Return type:

object
get_snmp_alerts(epoch_begin, epoch_end, select_clause, where_clause, maxhits, group_by, order_by)

Return SNMP alerts matching the specified criteria

Parameters:
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
  • select_clause (string) – Select clause (SQL syntax)
  • where_clause (string) – Where clause (SQL syntax)
  • maxhits (int) – Max number of results (limit)
  • group_by (string) – Group by condition (SQL syntax)
  • order_by (string) – Order by condition (SQL syntax)
Returns:

Query result
Return type:

object
get_system_alerts(epoch_begin, epoch_end, select_clause, where_clause, maxhits, group_by, order_by)

Return System alerts matching the specified criteria

Parameters:
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
  • select_clause (string) – Select clause (SQL syntax)
  • where_clause (string) – Where clause (SQL syntax)
  • maxhits (int) – Max number of results (limit)
  • group_by (string) – Group by condition (SQL syntax)
  • order_by (string) – Order by condition (SQL syntax)
Returns:

Query result
Return type:

object
get_timeseries(ts_schema, ts_query, epoch_begin, epoch_end)

Return timeseries in a pandas DataFrame for a specified schema and query See https://pandas.pydata.org/docs/user_guide/10min.html

Parameters:
  • ts_schema (string) – The timeseries schema (e.g. ‘host:traffic’)
  • ts_query (string) – The timeseries query (e.g. ‘ifid:0,host:10.0.0.1’)
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
Returns:

Timeseries data
Return type:

object (pandas DataFrame)
get_timeseries_metadata()

Return timeseries metadata (list all available timeseries)

Returns:Timeseries metadata
Return type:object
get_timeseries_stats(ts_schema, ts_query, epoch_begin, epoch_end)

Return stats from timeseries

Parameters:
  • ts_schema (string) – The timeseries schema (e.g. ‘host:traffic’)
  • ts_query (string) – The timeseries query (e.g. ‘ifid:0,host:10.0.0.1’)
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
Returns:

Timeseries data
Return type:

object (pandas DataFrame)
get_top_conversations(epoch_begin, epoch_end, host=None)

Return Top Conversations

Parameters:
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
  • host (string) – Host IP address (optional)
Returns:

Top conversations
Return type:

object
get_topk_flows(epoch_begin, epoch_end, max_hits, where_clause)

Retrieve Top-K from the historical flows database

Parameters:
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
  • maxhits (int) – Max number of results (limit)
  • where_clause (string) – Where clause (SQL syntax)
Returns:

Query result
Return type:

object
get_user_alerts(epoch_begin, epoch_end, select_clause, where_clause, maxhits, group_by, order_by)

Return User alerts matching the specified criteria

Parameters:
  • epoch_begin (int) – Start of the time interval (epoch)
  • epoch_end (int) – End of the time interval (epoch)
  • select_clause (string) – Select clause (SQL syntax)
  • where_clause (string) – Where clause (SQL syntax)
  • maxhits (int) – Max number of results (limit)
  • group_by (string) – Group by condition (SQL syntax)
  • order_by (string) – Order by condition (SQL syntax)
Returns:

Query result
Return type:

object