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
- get_active_hosts(ifid_num)
Return all active hosts on the selected interface
- Returns:
Active hosts on the selected interface
- Return type:
- 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:
- 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:
- 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:
- get_alert_types_enum()
Return the enum for all the alert types
- Returns:
Alert types enum
- Return type:
- 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:
- 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:
- 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:
- get_broadcast_domains()
Return information about broadcast domains on an interface
- Returns:
Information about broadcast domains
- Return type:
- get_data()
Return information about a Network interface
- Returns:
Information about the interface
- Return type:
- 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
- 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:
- get_l4_protocols_enum()
Return the enum for L4 protocols
- Returns:
Enum for L4 protocols
- Return type:
- get_l7_application_category_enum()
Return the enum for L7 application category enum
- Returns:
Enum for L7 application category enum
- Return type:
- get_l7_application_proto_enum()
Return the enum for L7 application enum
- Returns:
Enum for L7 application enum
- Return type:
- get_l7_stats(max_num_results)
Return statistics about Layer 7 protocols seen on an interface
- 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
- 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:
- get_host_data()
Return all available information about a single host
- Returns:
Information about the host
- Return type:
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:
- get_alert_severity_counters(epoch_begin, epoch_end)
Return statistics about the number of alerts per alert severity
- get_alert_type_counters(epoch_begin, epoch_end)
Return statistics about the number of alerts per alert type
- 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:
- get_alerts_stats(epoch_begin, epoch_end, host=None)
Return flow alerts stats
- 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:
- get_flow_alerts_stats(epoch_begin, epoch_end)
Return flow alerts stats
- 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:
- 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:
- get_host_timeseries(host_ip, ts_schema, epoch_begin, epoch_end)
Return timeseries data in a pandas DataFrame for a specified interface and host
- get_host_timeseries_stats(host_ip, ts_schema, epoch_begin, epoch_end)
Return timeseries statistics
- get_host_top_protocols(host, epoch_begin, epoch_end)
Return Top protocols for an host
- 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:
- get_interface_timeseries(ts_schema, epoch_begin, epoch_end)
Return timeseries data in a pandas DataFrame for a specified interface
- get_interface_timeseries_stats(ts_schema, epoch_begin, epoch_end)
Return timeseries statistics
- 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:
- 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:
- 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:
- 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:
- 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:
- Returns:
Timeseries data
- Return type:
object (pandas DataFrame)
- get_timeseries_metadata()
Return timeseries metadata (list all available timeseries)
- Returns:
Timeseries metadata
- Return type:
- get_timeseries_stats(ts_schema, ts_query, epoch_begin, epoch_end)
Return stats from timeseries
- Parameters:
- Returns:
Timeseries data
- Return type:
object (pandas DataFrame)
- get_top_conversations(epoch_begin, epoch_end, host=None)
Return Top Conversations
- get_topk_flows(epoch_begin, epoch_end, max_hits, where_clause)
Retrieve Top-K from the historical flows database
- 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: