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

Netify Lua Scripting 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
×
curl -fsSL https://download.netify.ai/5/debian/apt-gpg-key-netify.asc | sudo apt-key add -
echo 'deb http://download.netify.ai/5/debian/12/ /' | sudo tee /etc/apt/sources.list.d/netify.list > /dev/null

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
×
curl -fsSL https://download.netify.ai/5/debian/apt-gpg-key-netify.asc | sudo apt-key add -
echo 'deb http://download.netify.ai/5/debian/11/ /' | sudo tee /etc/apt/sources.list.d/netify.list > /dev/null

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
×
curl -fsSL https://download.netify.ai/5/debian/apt-gpg-key-netify.asc | sudo apt-key add -
echo 'deb http://download.netify.ai/5/debian/10/ /' | sudo tee /etc/apt/sources.list.d/netify.list > /dev/null

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
×
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/noble/ /' | sudo tee /etc/apt/sources.list.d/netify.list > /dev/null

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
×
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/jammy/ /' | sudo tee /etc/apt/sources.list.d/netify.list > /dev/null

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
×
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 > /dev/null

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 https://download.netify.ai/5/openwrt/key-build.pub -O /etc/opkg/keys/b18c240cb821dad2
echo 'src/gz netify https://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.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 apt update
sudo apt 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 apt update
sudo apt 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

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


Setup

All plugins are disabled by default, and the Netify Lua Scripting Extension Processor plugin is no different. Use the --enable-plugin and --disable-plugin parameters to enable/disable the plugin:

Terminal - Netify
×
netifyd --enable-plugin proc-lua
netifyd --disable-plugin proc-lua

Alternatively, you can edit /etc/netifyd/plugins.d/10-netify-proc-lua.conf and set enable to yes.

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

Configuration

Once the plugin has been enabled, it can be configured using the JSON configuration file specified in the plugin loader configuration. Let's look at a configuration sample to review the syntax and parts of the file.

script

string

The location of the Lua script.

Example Lua Plugin Configuration

{
  "script": "${path_state_persistent}/netify-proc-lua.lua"
}

Example

Sample Script: lua-proc-lua.lua

-- Netify Lua Processor Example Script
-- Copyright (C) 2024 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')