ntopng Lua API Reference (flow.* bindings)

This document describes all C→Lua bindings exposed as flow.* functions via src/LuaEngineFlow.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 flow.* works
2. Usage context
3. Endpoints & Addresses
4. Traffic Counters
5. Protocol Classification
6. Flow Characteristics
7. L7 Protocol Metadata
8. Alert Triggering
9. Complete Function Index

1. How flow.* works

Context

flow.* functions are available only inside flow check scripts — Lua scripts that are invoked by the ntopng flow-processing engine for each active flow. They operate on the current flow implicitly stored in the Lua VM context (NtopngLuaContext::flow); no arguments are needed to identify the flow.

C→Lua registration

Every function in _ntop_flow_reg[] (bottom of src/LuaEngineFlow.cpp) follows this pattern:

static int ntop_flow_get_xxx(lua_State* vm) {
    NtopngLuaContext* c = getLuaVMContext(vm);
    Flow* f = c ? c->flow : NULL;

    if (f)
        lua_push<type>(vm, f->get_xxx());
    else
        lua_pushnil(vm);

    return ntop_lua_return_value(vm, __FUNCTION__, CONST_LUA_OK);
}

// Registered as:
{ "xxx", ntop_flow_get_xxx },   // called as flow.xxx()

Where flow check scripts live

Flow check scripts are stored in:

scripts/lua/modules/flow_checks/

Each script is a Lua module that exports a check() function called per-flow by the engine.

2. Usage context

Standard boilerplate for a flow check script

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

local flow_consts = require("flow_consts")

local my_check = {}

-- Called once per active flow by the engine
function my_check.check(flow_info)
    local cli   = flow.cli()          -- client IP string
    local srv   = flow.srv()          -- server IP string
    local proto = flow.protocol()     -- L4 protocol number
    local bytes = flow.bytes()        -- total bytes

    if bytes > 1000000 then
        flow.triggerAlert(flow_consts.alert_types.flow_score, "Large flow detected")
    end
end

return my_check

Important notes

• flow.* functions return nil if called outside a flow check context (i.e. when NtopngLuaContext::flow is NULL).
• All functions take no arguments (except flow.triggerAlert).
• flow.* is completely separate from interface.* — there is no need to call interface.select() inside flow check scripts.

3. Endpoints & Addresses

4. Traffic Counters

5. Protocol Classification

L4 (transport) protocol

L7 (application) protocol — nDPI IDs

nDPI classifies flows hierarchically as master_protocol.app_protocol (e.g. HTTP.Facebook). The two IDs are separate:

6. Flow Characteristics

7. L7 Protocol Metadata

These functions return dissected protocol-specific metadata tables. The returned table fields are populated only when nDPI has fully dissected the protocol for this flow; fields may be nil if the flow is still being classified or if the protocol does not apply.

flow.http() — HTTP metadata

Returns a table with HTTP flow details. Common fields:

flow.dns() — DNS metadata

Returns a table with DNS flow details. Common fields:

flow.ssh() — SSH metadata

Returns a table with SSH flow details. Common fields:

flow.tls_quic() — TLS/QUIC metadata

Returns a table with TLS or QUIC flow details. Common fields:

8. Alert Triggering

Example

-- Detect large DNS responses (possible DNS tunneling)
local dns = flow.dns()
if dns and dns.last_return_code == 0 then
    local srv2cli = flow.srv2cli_bytes()
    if srv2cli > 512 then
        flow.triggerAlert(50, "Large DNS response: " .. tostring(srv2cli) .. " bytes")
    end
end

9. Complete Function Index

All 20 flow.* functions: