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:

ntopng URL (-n option, localhost:3000 by default)
ntopng credentials
- ntopng user (-u option, admin by default) and ntopng password (-p option, admin by default)
- or ntopng Token (https://www.ntop.org/guides/ntopng/user_interface/shared/settings/preferences.html#token-based-authentication)

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(ifid_num)

Return all active hosts on the selected interface

Returns:: Active hosts on the selected interface
Return type:: object

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_alert_severities_enum()

Return the enum for all the alert severities

Returns:: Alert severity enum
Return type:: object

get_alert_types_enum()

Return the enum for all the alert types

Returns:: Alert types enum
Return type:: object

get_alerts_counter_per_severity(ifid_num)

Return the number of alerts for each severity value

Returns:: Number of alerts for each severity value
Return type:: object

get_alerts_counter_per_type(ifid_num)

Return the number of alerts for each alert type

Returns:: Number of alerts for each alert type
Return type:: object

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_host_data(ifid_num, host_ip)

Return all host data for the selected interface and IP

Returns:: Host data for the specified interface and IP address
Return type:: object

get_l4_protocols_enum()

Return the enum for L4 protocols

Returns:: Enum for L4 protocols
Return type:: object

get_l7_application_category_enum()

Return the enum for L7 application category enum

Returns:: Enum for L7 application category enum
Return type:: object

get_l7_application_proto_enum()

Return the enum for L7 application enum

Returns:: Enum for L7 application enum
Return type:: object

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: