Lua in Network Security

-- This is a comment

-- Variables are global by default; use local to scope them
local x = 42
local s = "hello"

-- Tables are the universal data structure (array, map, object)
local t = { "a", "b", "c" }        -- array-style (index 1, 2, 3)
local m = { host = "10.0.0.1", port = 80 }  -- map-style
print(m.host)   -- "10.0.0.1"
print(m["port"]) -- 80

-- Functions are first-class values
local function greet(name)
    return "hello, " .. name       -- .. is string concatenation
end

-- String methods
local line = "GET /index.html HTTP/1.1"
if line:find("^GET") then          -- Lua pattern, not regex
    print("it's a GET")
end

-- String patterns use % as the escape character (not \)
-- %d = digit, %s = whitespace, %a = letter, %p = punctuation
-- . * + ? work as in regex; ^ and $ anchor to start/end

-- ============================================================
-- HEAD: metadata
-- ============================================================
description = [[
Checks whether a web server is running behind a known CDN provider
by examining the Server header and IP geolocation.
]]

categories = {"discovery", "safe"}

author = "Your Name"
license = "Same as Nmap -- See https://nmap.org/book/man-legal.html"

-- NSE library imports
local http = require "http"
local stdnse = require "stdnse"
local shortport = require "shortport"

-- ============================================================
-- RULE: when should this script run?
-- ============================================================
-- portrule: run once per open port
portrule = shortport.http   -- shorthand: run on any open HTTP port

-- hostrule:  run once per host (use instead of portrule for host-level checks)
-- prerule:   run once before scanning begins
-- postrule:  run once after all hosts scanned

-- ============================================================
-- ACTION: the script's logic
-- ============================================================
action = function(host, port)
    local response = http.get(host, port, "/")
    if not response or not response.header then
        return nil
    end
    local server = response.header["server"] or "unknown"
    return stdnse.format_output(true, "Server: " .. server)
end

local nmap = require "nmap"

-- Create a socket
local socket = nmap.new_socket()
socket:set_timeout(5000)  -- milliseconds

-- Exception-safe wrapper: on error, calls the cleanup function and re-raises
local try = nmap.new_try(function() socket:close() end)

try(socket:connect(host.ip, port.number))
try(socket:send("HELLO\r\n"))
local response = try(socket:receive())
socket:close()

-- Check port state
local p = nmap.get_port_state(host, {number=22, protocol="tcp"})
if p and p.state == "open" then ... end

-- Set a port's state/version info
nmap.set_port_version(host, port)

local shortport = require "shortport"

-- True if the port is in a given list (open or open|filtered)
portrule = shortport.port_or_service(80, "http")

-- True for any HTTP-like port
portrule = shortport.http

-- True for SSL/TLS ports
portrule = shortport.ssl

-- True for a port number
portrule = shortport.portnumber(22)

-- True for a named service
portrule = shortport.service("ftp")

local stdnse = require "stdnse"

-- Formatted output (shown indented under host in nmap output)
return stdnse.format_output(true, {"line one", "line two"})

-- Debug printing (shown with -d)
stdnse.debug(1, "Got response: %s", response)

-- Get a script argument (from --script-args)
local path = stdnse.get_script_args("myscript.path") or "/"

-- Sleep (seconds as float)
stdnse.sleep(0.5)

local http = require "http"

local response = http.get(host, port, "/admin/")
-- response.status   (integer, e.g. 200)
-- response.body     (string)
-- response.header   (table, lowercased keys)
-- response.rawheader (table)

local resp2 = http.post(host, port, "/login", nil, nil,
    "username=admin&password=admin")

-- Pipeline multiple requests
local pipeline = http.pipeline_new()
http.pipeline_add("/", nil, pipeline)
http.pipeline_add("/robots.txt", nil, pipeline)
local results = http.pipeline_go(host, port, pipeline)

local vulns   = require "vulns"
local vuln_db = vulns.DB:new()

local vuln = {
    title     = "CVE-2021-12345: Remote Code Execution in Foo Service",
    state     = vulns.STATE.VULN,   -- or NOT_VULN, LIKELY_VULN, UNKNOWN
    IDS       = { CVE = "CVE-2021-12345" },
    risk_factor = "High",
    description = "An unauthenticated attacker can execute arbitrary code.",
    dates     = { disclosure = { year='2021', month='03', day='15' } },
    references = { "https://nvd.nist.gov/vuln/detail/CVE-2021-12345" }
}
return vuln_db:add(vuln)

description = [[
Detects open Telnet services and retrieves the login banner.
Telnet transmits credentials in plaintext — flag for remediation.
]]

categories = {"discovery", "safe"}
author = "Your Name"
license = "Same as Nmap -- See https://nmap.org/book/man-legal.html"

local nmap      = require "nmap"
local shortport = require "shortport"
local stdnse    = require "stdnse"

portrule = shortport.port_or_service(23, "telnet")

action = function(host, port)
    local socket = nmap.new_socket()
    socket:set_timeout(3000)

    local status, err = socket:connect(host.ip, port.number)
    if not status then
        return nil
    end

    -- Read the banner (Telnet sends it immediately)
    local ok, banner = socket:receive()
    socket:close()

    if not ok then
        return "Open Telnet port (no banner received)"
    end

    -- Strip non-printable bytes from the banner
    banner = banner:gsub("[%c]", ".")
    return stdnse.format_output(true, {
        "WARNING: Telnet transmits credentials in plaintext",
        "Banner: " .. banner
    })
end

-- myproto.lua — simple 4-byte header dissector
-- Load with: tshark -X lua_script:myproto.lua -r capture.pcap

-- 1. Create the protocol object
local myproto = Proto("myproto", "My Custom Protocol")

-- 2. Define fields (name, display label, type, optional base/values)
local f_type  = ProtoField.uint8 ("myproto.type",  "Message Type",  base.HEX,
    { [0x01]="HELLO", [0x02]="DATA", [0x03]="BYE" })
local f_flags = ProtoField.uint8 ("myproto.flags", "Flags",         base.HEX)
local f_len   = ProtoField.uint16("myproto.length","Payload Length", base.DEC)
local f_data  = ProtoField.bytes ("myproto.data",  "Payload")

myproto.fields = { f_type, f_flags, f_len, f_data }

-- 3. Implement the dissector function
function myproto.dissector(buf, pkt, tree)
    -- Minimum packet length check
    if buf:len() < 4 then return end

    -- Set the Info column
    pkt.cols.protocol = "MYPROTO"

    -- Add protocol subtree to the packet detail pane
    local subtree = tree:add(myproto, buf(0, 4))

    -- Add each field: buf(offset, length) slices the buffer
    subtree:add(f_type,  buf(0, 1))
    subtree:add(f_flags, buf(1, 1))
    subtree:add(f_len,   buf(2, 2))

    local payload_len = buf(2, 2):uint()
    if buf:len() >= 4 + payload_len and payload_len > 0 then
        subtree:add(f_data, buf(4, payload_len))
    end
end

-- 4. Register the dissector for UDP port 9999
local udp_table = DissectorTable.get("udp.port")
udp_table:add(9999, myproto)

-- dns_tap.lua — print all DNS query names to stdout
-- Usage: tshark -X lua_script:dns_tap.lua -r capture.pcap -q

local tap = Listener.new("dns", "dns.flags.response == 0")

-- Called once per matching packet
function tap.packet(pinfo, tvb, tapdata)
    local qname = tostring(pinfo.private["dns.qry.name"] or "")
    if qname ~= "" then
        print(tostring(pinfo.number) .. "\t" .. qname)
    end
end

-- Called after all packets are processed
function tap.draw()
    print("--- DNS query extraction complete ---")
end

function tap.reset()
    -- Called when the capture is restarted; reset any counters here
end

-- beacon_counter.lua — count packets per destination IP
-- Useful for spotting beaconing malware (regular-interval connections)
-- Usage: tshark -X lua_script:beacon_counter.lua -r capture.pcap -q

local counts = {}

local tap = Listener.new("ip")

function tap.packet(pinfo, tvb)
    local dst = tostring(pinfo.dst)
    counts[dst] = (counts[dst] or 0) + 1
end

function tap.draw()
    print("\nDestination IP packet counts:")
    print(string.format("%-20s %s", "IP Address", "Packets"))
    print(string.rep("-", 35))
    -- Collect and sort
    local sorted = {}
    for ip, count in pairs(counts) do
        table.insert(sorted, {ip=ip, count=count})
    end
    table.sort(sorted, function(a,b) return a.count > b.count end)
    for _, entry in ipairs(sorted) do
        print(string.format("%-20s %d", entry.ip, entry.count))
    end
end

-- detect_php_post.lua
-- Matches HTTP/1.0 POST requests to .php files

-- init: declare which buffer(s) to inspect
function init(args)
    local needs = {}
    needs["http.request_line"] = tostring(true)
    return needs
end

-- match: inspect the buffer and return 1 (match) or 0 (no match)
function match(args)
    local request_line = tostring(args["http.request_line"])

    -- Lua pattern: matches "POST /anything.php HTTP/1.0"
    if request_line:find("^POST%s+.+%.php%s+HTTP/1%.0$") then
        return 1
    end
    return 0
end

-- detect_malicious_ua.lua
-- Alert when User-Agent matches any known-malicious string

local bad_agents = {
    "python%-requests",     -- common in automated attacks
    "zgrab",                -- internet scanner
    "masscan",              -- mass scanner
    "libwww%-perl",         -- old automated client often abused
    "Go%-http%-client/1%.1",-- common in Go-based scanners
}

function init(args)
    local needs = {}
    needs["http.request_user_agent"] = tostring(true)
    return needs
end

function match(args)
    local ua = tostring(args["http.request_user_agent"])
    if #ua == 0 then return 0 end
    ua = ua:lower()
    for _, pattern in ipairs(bad_agents) do
        if ua:find(pattern) then
            return 1
        end
    end
    return 0
end

-- detect_dns_tunnel.lua
-- Flag DNS queries with high-entropy subdomains (likely base32/base64 encoded data)

-- Shannon entropy calculation
local function entropy(s)
    local freq = {}
    for i = 1, #s do
        local c = s:sub(i,i)
        freq[c] = (freq[c] or 0) + 1
    end
    local h = 0
    for _, v in pairs(freq) do
        local p = v / #s
        h = h - p * math.log(p, 2)
    end
    return h
end

function init(args)
    local needs = {}
    needs["dns.query"] = tostring(true)
    return needs
end

function match(args)
    local query = tostring(args["dns.query"])
    if #query == 0 then return 0 end

    -- Extract the leftmost label (before first dot)
    local label = query:match("^([^%.]+)")
    if not label or #label < 12 then return 0 end

    -- Entropy above ~3.8 bits/character is suspicious for a hostname label
    if entropy(label) > 3.8 then
        return 1
    end
    return 0
end