ntopng/doc/README.lua_network_api.md

ntopng Lua API Reference (network.* bindings)

This document describes all C→Lua bindings exposed as network.* functions via src/LuaEngineNetwork.cpp. It is intended both for human developers writing Lua scripts and as a machine-readable reference for AI-assisted code generation (e.g. Claude Code in this repository).

---

Table of Contents

1. How network.* works
2. Usage context
3. Network Selection
4. Network Statistics
5. Alerts
6. Alert Context Cache
7. Complete Function Index

---

1. How network.* works

Context

network.* functions operate on a local network (a configured CIDR subnet) stored in the Lua VM context (NtopngLuaContext::network → NetworkStats*). Before calling most network.* functions you must either:

• Call network.select(network_id) with the numeric network ID, or
• Call network.checkContext(cidr_string) with the CIDR string (e.g. "192.168.1.0/24")

Both set the active NetworkStats object for the current Lua VM.

C→Lua registration

Every function in _ntop_network_reg[] (bottom of src/LuaEngineNetwork.cpp) follows the standard pattern:

static int ntop_network_xxx(lua_State* vm) {
    NtopngLuaContext* c = getLuaVMContext(vm);
    NetworkStats* ns = c ? c->network : NULL;
    // ...
}

// Registered as:
{ "xxx", ntop_network_xxx },   // called as network.xxx()

Where network check scripts live

Network check scripts are stored in:

scripts/lua/modules/network_checks/

Each script is a Lua module with a check() function called per-network by the engine.

---

2. Usage context

Standard boilerplate for a network check script

-- scripts/lua/modules/network_checks/my_network_check.lua
local dirs = ntop.getDirs()
package.path = dirs.installdir .. "/scripts/lua/modules/?.lua;" .. package.path

local alert_consts = require("alert_consts")
local alerts_api   = require("alerts_api")

local my_check = {}

function my_check.check(network_info)
    -- network_info.network_cidr contains the CIDR string, e.g. "10.0.0.0/8"

    -- Ensure the network context is set
    if not network.checkContext(network_info.network_cidr) then return end

    local stats = network.getNetworkStats()
    if not stats then return end

    -- Example: alert on high score
    if stats.score and stats.score > 100 then
        -- store/release alerts via network.storeTriggeredAlert / network.releaseTriggeredAlert
    end
end

return my_check

Using network.select() directly (e.g. from a REST endpoint)

local ifid       = _GET["ifid"] or interface.getFirstInterfaceId()
local network_id = tonumber(_GET["network_id"])

interface.select(tostring(ifid))
network.select(network_id)

local stats = network.getNetworkStats()
rest_utils.answer(rest_utils.consts.success.ok, stats)

---

3. Network Selection

Lua call	Returns	Description
network.select(network_id)	nil	Selects the active local network by its numeric ID (as returned by interface.getNetworksStats() key or ntop.getLocalNetworkId()). Pass nil to deselect. Must be called before network.getNetworkStats().
network.checkContext(cidr_string)	boolean	Looks up the local network by its CIDR string (e.g. "192.168.1.0/24") and sets it as the active network context. Returns true on success, false if the CIDR is not a known local network. Preferred in network check scripts where the CIDR is known.

Difference between select and checkContext

	network.select(id)	network.checkContext(cidr)
Input	Numeric network ID	CIDR string
Use case	REST endpoints, scripts with a known ID	Network check scripts (engine passes CIDR)
Returns	nil	boolean (success/failure)

---

4. Network Statistics

Lua call	Returns	Description
network.getNetworkStats()	table	Returns a table of traffic and alert statistics for the currently selected local network. Returns nil if no network is selected.
network.resetTrafficBetweenNets()	nil	Resets the inter-network traffic matrix counters for the current network. Pro edition only — no-op in Community.

network.getNetworkStats() return table fields

The returned table is populated by NetworkStats::lua() and typically includes:

Field	Type	Description
network_id	integer	Numeric ID of this network
network_key	string	CIDR string identifying the network (e.g. "192.168.1.0/24")
score	integer	Current alert score for this network
bytes_sent	integer	Total bytes sent by hosts in this network
bytes_rcvd	integer	Total bytes received by hosts in this network
num_hosts	integer	Number of active hosts in this network
num_local_hosts	integer	Number of active local hosts in this network
engaged_alerts	integer	Count of currently engaged (active) alerts
ingress	table	Per-protocol ingress traffic statistics
egress	table	Per-protocol egress traffic statistics
inner	table	Per-protocol traffic between hosts within this network

---

5. Alerts

Alert lifecycle

Lua call	Returns	Description
network.getAlerts(params_table)	table	Returns alerts matching given filter criteria for the currently selected local network. Supports the same params_table fields as interface.getAlerts(): status, alert_type, alert_severity, page, perPage, order_by.
network.storeTriggeredAlert(alert_table)	nil	Stores a triggered alert record in the alert database for the currently selected local network. Called by alerts_api internals.
network.releaseTriggeredAlert(alert_table)	nil	Marks a previously triggered alert for the current network as resolved/released. Called by alerts_api internals.

Typical alert pattern in a network check script

local alerts_api   = require("alerts_api")
local alert_consts = require("alert_consts")

-- In check():
local score = (network.getNetworkStats() or {}).score or 0
local alert_info = {
    alert_type     = alert_consts.alert_types.alert_network_anomaly,
    alert_severity = alert_consts.alert_severities.error,
    alert_entity   = alerts_api.networkEntity(network_info.network_cidr),
    alert_score    = score,
}

if score > 200 then
    alerts_api.store(alert_info)
else
    alerts_api.release(alert_info)
end

---

6. Alert Context Cache

The alert context cache lets network check scripts persist small state values (strings) between consecutive check runs without hitting Redis. Values are keyed by (key, periodicity) pairs — different periodicities (minute, 5-minute, hourly, etc.) maintain independent cache namespaces.

Lua call	Returns	Description
network.getCachedAlertValue(key, periodicity)	string	Retrieves a cached string value for the current network. key is an arbitrary string; periodicity is a ScriptPeriodicity integer constant. Returns an empty string "" if not set.
network.setCachedAlertValue(key, value, periodicity)	nil	Stores a string value in the alert context cache for the current network. Both key and value are strings; periodicity is a ScriptPeriodicity integer.

ScriptPeriodicity constants

These are defined in Lua as checks.periodicities.*:

Constant	Typical value	Period
checks.periodicities.min	0	Every minute
checks.periodicities.5mins	1	Every 5 minutes
checks.periodicities.hour	2	Every hour
checks.periodicities.day	3	Every day

Cache usage example — track previous byte count for delta alerting

local checks = require("checks")
local periodicity = checks.periodicities.min

local stats    = network.getNetworkStats() or {}
local cur_bytes = (stats.bytes_sent or 0) + (stats.bytes_rcvd or 0)

local prev_str  = network.getCachedAlertValue("prev_bytes", periodicity)
local prev_bytes = tonumber(prev_str) or 0

local delta = cur_bytes - prev_bytes
network.setCachedAlertValue("prev_bytes", tostring(cur_bytes), periodicity)

if delta > 1e9 then
    -- alert: more than 1 GB transferred in one minute
end

---

7. Complete Function Index

All 9 network.* functions:

Lua function	C implementation	Category
network.checkContext(cidr_string)	ntop_network_check_context	Selection
network.getCachedAlertValue(key, periodicity)	ntop_network_get_cached_alert_value	Alert cache
network.getAlerts(params_table)	ntop_network_get_alerts	Alerts
network.getNetworkStats()	ntop_network_get_network_stats	Statistics
network.releaseTriggeredAlert(alert_table)	ntop_network_release_triggered_alert	Alerts
network.resetTrafficBetweenNets()	ntop_network_reset_traffic_between_nets	Statistics
network.select(network_id)	ntop_select_local_network	Selection
network.setCachedAlertValue(key, value, periodicity)	ntop_network_set_cached_alert_value	Alert cache
network.storeTriggeredAlert(alert_table)	ntop_network_store_triggered_alert	Alerts