ntopng Lua API Reference (host.* bindings)

This document describes all C→Lua bindings exposed as host.* functions via src/LuaEngineHost.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 host.* works
2. Usage context
3. Identity & Addressing
4. Address Type Flags
5. Traffic Counters
6. Protocol Statistics
7. Peer Contact Counters
8. Score & Alerts
9. Script Control
10. Complete Function Index

1. How host.* works

Context

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

C→Lua registration

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

static int ntop_host_get_xxx(lua_State* vm) {
    NtopngLuaContext* c = getLuaVMContext(vm);
    Host* h = c ? c->host : NULL;

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

    return ntop_lua_return_value(vm, __FUNCTION__, CONST_LUA_OK);
}

// Registered as:
{ "xxx", ntop_host_get_xxx },   // called as host.xxx()

Where host check scripts live

Host check scripts are stored in:

scripts/lua/modules/host_checks/

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

2. Usage context

Standard boilerplate for a host check script

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

local host_consts = require("host_consts")

local my_check = {}

-- Called once per tracked host by the engine
function my_check.check(host_info)
    -- Guard: skip non-local or non-unicast hosts
    if not host.is_local() then return end
    if not host.is_unicast() then return end

    -- Skip on first run (no baseline yet)
    if host.isFirstCheckRun() then return end

    local bytes = host.bytes()
    local score = host.score()

    if bytes > 1e9 then
        host.triggerAlert(100, "Host transferred > 1 GB: " .. tostring(bytes))
    end
end

return my_check

Important notes

• host.* functions return nil if called outside a host check context (i.e. when NtopngLuaContext::host is NULL).
• Most functions take no arguments (exceptions: host.skipVisitedHost and host.triggerAlert).
• host.* is completely separate from interface.* — there is no need to call interface.select() inside host check scripts.
• Unlike flow.*, host check scripts run periodically (not per-packet), so counters reflect accumulated totals since the host was first seen.

3. Identity & Addressing

4. Address Type Flags

These predicates classify the host's IP address type. All return false when called outside a host check context.

Typical guard pattern

-- Most checks only make sense for local unicast hosts
if not host.is_local() then return end
if not host.is_unicast() then return end
if host.is_blacklisted() then return end  -- already flagged elsewhere

5. Traffic Counters

All byte counters accumulate from the moment the host was first seen (or since the last counter reset via interface.resetHostStats()).

6. Protocol Statistics

Example — detect heavy BitTorrent usage

local l7 = host.l7()
if l7 and l7["BitTorrent"] then
    local bt = l7["BitTorrent"]
    if (bt.bytes_sent + bt.bytes_rcvd) > 100e6 then
        host.triggerAlert(60, "Heavy BitTorrent usage detected")
    end
end

7. Peer Contact Counters

These counters track TCP/UDP connections that were one-sided (the host sent traffic but received no reply, or vice versa). They are useful for detecting port scans, SYN floods, and other anomalous contact patterns.

Example — port scan detection

local contacted_ports = host.getNumContactedTCPUDPServerPortsNoTX()
local contacted_peers = host.getNumContactedPeersAsClientTCPUDPNoTX()

if contacted_ports > 50 or contacted_peers > 100 then
    host.triggerAlert(80, string.format(
        "Possible scan: %d ports / %d peers with no reply",
        contacted_ports, contacted_peers))
    host.resetHostContacts()  -- reset to avoid re-alerting next cycle
end

8. Score & Alerts

Alert severity guidelines

9. Script Control

skipVisitedHost usage pattern

-- After triggering an alert, suppress re-alerting for 1 hour
if should_alert then
    host.triggerAlert(70, "Anomaly detected")
    local one_hour_from_now = os.time() + 3600
    host.skipVisitedHost(true, one_hour_from_now)
end

10. Complete Function Index

All 23 host.* functions: