Lua Scripting Plugin

The Netify Lua plugin enables direct integration with the Netify agent engine, allowing Lua scripts to hook into live network telemetry in real time. This plugin is an ideal option for rapid prototyping and custom applications, providing a flexible, lightweight environment for custom logic, data analysis, or experimental features without modifying the core DPI engine.

For AI and machine learning prototyping, the Python plugin provides a direct interface for model development.


License

The Netify Lua Extension plugin is a proprietary plugin requiring a license. Please contact us for details.


Installation

Netify plugins are distributed through the same packaging workflow as the Netify Agent, allowing for a consistent installation experience using standard package manager syntax. While pre-compiled binaries are readily available for x86_64 architectures via our public mirrors, support for ARM, MIPS, and other specialized architectures is available upon request. Please contact us for details.

Step 1 - Select your installation target:

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
sudo apt-get update
sudo apt-get -y install curl gnupg2
sudo curl https://download.netify.ai/5/debian/netify-archive-keyring.gpg -o /usr/share/keyrings/netify-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/netify-archive-keyring.gpg] http://download.netify.ai/5/debian/12/ /' | sudo tee /etc/apt/sources.list.d/netify.list

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
sudo apt update
sudo apt install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
sudo apt-get update
sudo apt-get -y install curl gnupg2
sudo curl https://download.netify.ai/5/debian/netify-archive-keyring.gpg -o /usr/share/keyrings/netify-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/netify-archive-keyring.gpg] http://download.netify.ai/5/debian/11/ /' | sudo tee /etc/apt/sources.list.d/netify.list

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
sudo apt update
sudo apt install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
sudo apt-get update
sudo apt-get -y install curl gnupg2
sudo curl https://download.netify.ai/5/debian/netify-archive-keyring.gpg -o /usr/share/keyrings/netify-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/netify-archive-keyring.gpg] http://download.netify.ai/5/debian/10/ /' | sudo tee /etc/apt/sources.list.d/netify.list

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
sudo apt update
sudo apt install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
sudo apt-get update
sudo apt-get -y install curl gnupg2
sudo curl https://download.netify.ai/5/ubuntu/netify-archive-keyring.gpg -o /usr/share/keyrings/netify-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/netify-archive-keyring.gpg] http://download.netify.ai/5/ubuntu/noble/ /' | sudo tee /etc/apt/sources.list.d/netify.list

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
sudo apt update
sudo apt install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
sudo apt-get update
sudo apt-get -y install curl gnupg2
sudo curl https://download.netify.ai/5/ubuntu/netify-archive-keyring.gpg -o /usr/share/keyrings/netify-archive-keyring.gpg
echo 'deb [signed-by=/usr/share/keyrings/netify-archive-keyring.gpg] http://download.netify.ai/5/ubuntu/jammy/ /' | sudo tee /etc/apt/sources.list.d/netify.list

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
sudo apt update
sudo apt install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
sudo apt-get update
sudo apt-get -y install curl gnupg2
curl -fsSL https://download.netify.ai/5/ubuntu/apt-gpg-key-netify.asc | sudo apt-key add -
echo 'deb http://download.netify.ai/5/ubuntu/focal/ /' | sudo tee /etc/apt/sources.list.d/netify.list

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
sudo apt update
sudo apt install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
wget https://download.netify.ai/5/openwrt/key-build.pub -O /etc/opkg/keys/b18c240cb821dad2
echo 'src/gz netify https://download.netify.ai/5/openwrt/24.10/x86' >> /etc/opkg/customfeeds.conf

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
opkg update
opkg install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
wget https://download.netify.ai/5/openwrt/key-build.pub -O /etc/opkg/keys/b18c240cb821dad2
echo 'src/gz netify https://download.netify.ai/5/openwrt/23.05/x86' >> /etc/opkg/customfeeds.conf

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
opkg update
opkg install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
wget https://download.netify.ai/5/openwrt/key-build.pub -O /etc/opkg/keys/b18c240cb821dad2
echo 'src/gz netify https://download.netify.ai/5/openwrt/22.03/x86' >> /etc/opkg/customfeeds.conf

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
opkg update
opkg install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
wget https://download.netify.ai/5/openwrt/key-build.pub -O /etc/opkg/keys/b18c240cb821dad2
echo 'src/gz netify https://download.netify.ai/5/openwrt/21.02/x86' >> /etc/opkg/customfeeds.conf

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
opkg update
opkg install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
wget http://download.netify.ai/5/openwrt/key-build.pub -O /etc/opkg/keys/b18c240cb821dad2
echo 'src/gz netify http://download.netify.ai/5/openwrt/19.07/x86' >> /etc/opkg/customfeeds.conf

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
opkg update
opkg install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
sudo rpm --import https://download.netify.ai/5/opensuse/15.6/stable/RPM-GPG-KEY-netify
sudo curl https://download.netify.ai/5/opensuse/netify.repo -o /etc/zypp/repos.d/repo-netify.repo

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
sudo zypper update
sudo zypper install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
sudo rpm --import https://download.netify.ai/5/opensuse/15.5/stable/RPM-GPG-KEY-netify
sudo curl https://download.netify.ai/5/opensuse/netify.repo -o /etc/zypp/repos.d/repo-netify.repo

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
sudo zypper update
sudo zypper install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
sudo rpm --import https://download.netify.ai/5/almalinux/9/stable/RPM-GPG-KEY-netify
sudo curl https://download.netify.ai/5/almalinux/9/netify.repo -o /etc/yum.repos.d/netify.repo

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
sudo yum update
sudo yum install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
sudo rpm --import https://download.netify.ai/5/almalinux/8/stable/RPM-GPG-KEY-netify
sudo curl https://download.netify.ai/5/almalinux/8/netify.repo -o /etc/yum.repos.d/netify.repo

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
sudo yum update
sudo yum install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
sudo rpm --import http://download.netify.ai/5/rockylinux/9/stable/RPM-GPG-KEY-netify
sudo curl https://download.netify.ai/5/rockylinux/9/netify.repo -o /etc/yum.repos.d/netify.repo

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
sudo yum update
sudo yum install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
sudo rpm --import http://download.netify.ai/5/rockylinux/8/stable/RPM-GPG-KEY-netify
sudo curl https://download.netify.ai/5/rockylinux/8/netify.repo -o /etc/yum.repos.d/netify.repo

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
sudo yum update
sudo yum install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
mkdir -p /usr/local/etc/pkg/fingerprints/Netify/trusted
curl https://download.netify.ai/5/opnsense/fingerprint -o /usr/local/etc/pkg/fingerprints/Netify/trusted/fingerprint
cat << EOF >  /usr/local/etc/pkg/repos/Netify.conf
Netify: {
  fingerprints: "/usr/local/etc/pkg/fingerprints/Netify",
  url: "https://download.netify.ai/5/opnsense/25.7",
  signature_type: "fingerprints",
  mirror_type: "http",
  priority: 11,
  enabled: yes
}
EOF

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
pkg update
pkg install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
mkdir -p /usr/local/etc/pkg/fingerprints/Netify/trusted
curl https://download.netify.ai/5/opnsense/fingerprint -o /usr/local/etc/pkg/fingerprints/Netify/trusted/fingerprint
cat << EOF >  /usr/local/etc/pkg/repos/Netify.conf
Netify: {
  fingerprints: "/usr/local/etc/pkg/fingerprints/Netify",
  url: "https://download.netify.ai/5/opnsense/24.7",
  signature_type: "fingerprints",
  mirror_type: "http",
  priority: 11,
  enabled: yes
}
EOF

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
pkg update
pkg install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
mkdir -p /usr/local/etc/pkg/fingerprints/Netify/trusted
curl https://download.netify.ai/5/freebsd/fingerprint -o /usr/local/etc/pkg/fingerprints/Netify/trusted/fingerprint
cat << EOF >  /usr/local/etc/pkg/repos/Netify.conf
Netify: {
  fingerprints: "/usr/local/etc/pkg/fingerprints/Netify",
  url: "https://download.netify.ai/5/freebsd/15.0",
  signature_type: "fingerprints",
  mirror_type: "http",
  priority: 11,
  enabled: yes
}
EOF

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
pkg update
pkg install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
mkdir -p /usr/local/etc/pkg/fingerprints/Netify/trusted
curl https://download.netify.ai/5/freebsd/fingerprint -o /usr/local/etc/pkg/fingerprints/Netify/trusted/fingerprint
cat << EOF >  /usr/local/etc/pkg/repos/Netify.conf
Netify: {
  fingerprints: "/usr/local/etc/pkg/fingerprints/Netify",
  url: "https://download.netify.ai/5/freebsd/14.0",
  signature_type: "fingerprints",
  mirror_type: "http",
  priority: 11,
  enabled: yes
}
EOF

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
pkg update
pkg install netify-proc-lua

Step 2 - Add Netify's package signing key and repository:

Terminal - Netify
×
mkdir -p /usr/local/etc/pkg/fingerprints/Netify/trusted
curl https://download.netify.ai/5/freebsd/fingerprint -o /usr/local/etc/pkg/fingerprints/Netify/trusted/fingerprint
cat << EOF >  /usr/local/etc/pkg/repos/Netify.conf
Netify: {
  fingerprints: "/usr/local/etc/pkg/fingerprints/Netify",
  url: "https://download.netify.ai/5/freebsd/14.0",
  signature_type: "fingerprints",
  mirror_type: "http",
  priority: 11,
  enabled: yes
}
EOF

Step 3 - Install Netify Lua Extension:

Terminal - Netify
×
pkg update
pkg install netify-proc-lua

Setup

To use the Netify Lua Extension plugin, ensure your license.json includes the netify-proc-lua entitlement.

All plugins are disabled by default, and the Netify Lua Extension plugin is no different. Use netifyd's --enable-plugin and --disable-plugin flags to enable or disable the plugin.

Terminal - Netify
×
netifyd --enable-plugin proc-lua  # Enables loader
netifyd --disable-plugin proc-lua # Disables loader

For orchestration tools or manual setup, you can also directly update configuration file in the plugins.d subdirectory and set enable to yes.

See the advanced configuration section for details on instantiating multiple instances of the plugin.

Terminal - Netify
×
$ cat 10-netify-proc-lua.conf
[proc-lua]
enable = yes
plugin_library = /usr/lib64/libnetify-proc-lua.so.0.0.0
conf_filename = ${path_state_persistent}/netify-proc-lua.json

The Lua interpreter must also be installed on the host or in the container.


Configuration

Once enabled, the plugin is configured via the JSON file referenced by its loader (typically /etc/netifyd/netify-proc-lua.json ). The configuration file provides a way to define the location of the Lua script.

script

string

The file system path to the Lua script.

Example Lua Plugin Configuration

{
  "script": "/usr/local/bin/monitor.lua"
}

Example

Sample Script: lua-proc-lua.lua

-- Netify Lua Processor Example Script
-- Copyright (C) 2026 eGloo, Incorporated

FLOWS = { }

function TableToCSV(t)
  local escape = function(s)
    if string.find(s, '[,"]') then
      s = '"' .. string.gsub(s, '"', '""') .. '"'
    end
    return s
  end

  local csv = ''
  for _, r in ipairs(t) do
    local row = ''
    for _, c in ipairs(r) do
      row = row .. ',' .. escape(c)
    end
    csv = csv .. string.sub(row, 2) .. "\n"
  end

  return csv
end

function ResetFlows()
  FLOWS = {
    {
      "iface", "digest", "lower_mac", "lower_addr", "lower_port",
      "upper_mac", "upper_addr", "upper_port", "ip_protocol",
      "detected_protocol", "detected_application"
    }
  }
end

-- Process an Agent event.
function ProcessAgentEvent(event)
  local message = 'Agent event: '

  if event == NPP_EVENT_UPDATE_INIT then
    message = message .. 'update'
  elseif event == NPP_EVENT_UPDATE_COMPLETE then
    message = message .. 'update complete'

    if #FLOWS > 1 then
      npp.dispatch(
        'sink-log', { 'lua-csv' },
        TableToCSV(FLOWS),
        NPP_FORMAT_RAW,
        NPP_COMPRESSOR_NONE
      )
      ResetFlows()
    end
  else
    message = message .. string.format('unknown [%d]', event)
  end

  npp.debug(message)
end

-- Process a flow event.
function ProcessFlowEvent(event, flows)
  if event ~= NPP_EVENT_DPI_COMPLETE then
    return
  end

  for _, flow in ipairs(flows) do
    table.insert(FLOWS,
      {
        flow['iface']['name'], flow['digest_mdata'],
        flow['lower_mac'], flow['lower_addr'], flow['lower_port'],
        flow['upper_mac'], flow['upper_addr'], flow['upper_port'],
        flow['ip_protocol'], flow['detected_protocol'], flow['detected_application']
      }
    )
  end
end

function ProcessFlowStats(flows)
    local active_flows = 0
    local total_bytes = 0
    local lower_rate = 0.0
    local upper_rate = 0.0

    for _, flow in ipairs(flows) do
      if flow['stats']['lower_bytes'] > 0 or flow['stats']['upper_bytes'] > 0 then
        active_flows = active_flows + 1
        total_bytes = total_bytes + flow['stats']['total_bytes']
        lower_rate = lower_rate + flow['stats']['lower_rate']
        upper_rate = upper_rate + flow['stats']['upper_rate']
      end
    end

    npp.debug(
      string.format(
        "active flows: %d, total bytes: %d, lower rate: %.1f, upper rate: %.1f",
        active_flows, total_bytes, lower_rate, upper_rate
      )
    )
end

ResetFlows()

npp.print('Netify Lua Processor Example: initialized')