Module Reference

Reference for Snort 3 built-in modules, their purpose, and key configuration parameters.

Modules are the building blocks of Snort 3. Every configurable component — from stream reassembly to alert output — is a module. Modules are configured as Lua tables with the same name as the module.

To inspect any module from the command line:

# Show parameters, type, and defaults for a module
snort --help-module <name>

# Show all configuration parameters
snort --help-config

# Filter to a specific module
snort --help-config stream_tcp

Parameter format in help output:

type module.name = default: help { range }

Using module = { } enables a module with all internal defaults. Run snort --help-module <name> to see those defaults before overriding them.

Core Modules

snort — Main module

The snort module exposes the primary command-line flags as configuration parameters. Settings here have the second-highest precedence (command-line options override them).

snort --help-module snort

Key parameters mirror command-line flags such as -c, -l, -n, and BPF filtering. This module also provides the interactive shell commands when built with --enable-shell.

ips — IPS policy

Controls the intrusion prevention policy: which rules are loaded, built-in rule enablement, and rule variables.

snort --help-module ips

Parameter	Type	Default	Description
enable_builtin_rules	bool	false	Enable built-in decoder and inspector alert rules.
include	string	—	Path to a rules file to load.
rules	string	—	Inline rule text.
states	string	—	Path to a rule states file (parsed after rules).
variables	table	—	Named variable sets for nets, ports, and paths.

ips =
{
    enable_builtin_rules = true,
    include = 'rules/local.rules',
    variables = default_variables
}

# Enable built-in rules from the command line
snort -c snort.lua --lua 'ips = { enable_builtin_rules = true }'

IPS states are similar to rules but parsed after rules, allowing custom policy overrides.

network — Network layer settings

Configures network-layer behaviour such as TTL thresholds and checksum handling.

snort --help-module network

Parameter	Type	Description
min_ttl	int	Drop packets with TTL below this value.
new_ttl	int	Replacement TTL when normalising packets (inline mode).
checksum_drop	multi	Drop packets with bad checksums for listed protocols.

network =
{
    min_ttl = 1,
    new_ttl = 5
}

active — Response settings

Configures how Snort sends active responses (TCP resets, ICMP unreachables) when rules use reject or react.

snort --help-module active

Parameter	Type	Default	Description
attempts	int	0	Number of TCP packets sent per response with varying sequence numbers. Range: 0–20.
device	string	—	Interface for link-layer responses, or 'ip' for network-layer responses.
dst_mac	string	—	Destination MAC for link-layer responses. Format: '01:23:45:67:89:ab'.
max_responses	int	0	Maximum number of response packets. 0 means unlimited.
min_interval	int	255	Minimum seconds between responses. Range: 1+.

active =
{
    attempts = 2,
    device = 'eth0',
    max_responses = 1,
    min_interval = 5
}

active.attempts and active.device cannot be changed during a live reload — a restart is required.

process — Process settings

Controls privilege dropping, daemonisation, and chroot.

snort --help-module process

Parameter	Type	Description
chroot	string	Change root to this directory after startup.
daemon	bool	Run as a background daemon.
set_gid	string	Drop to this group after startup.
set_uid	string	Drop to this user after startup.
dirty_pig	bool	Skip memory cleanup on exit (faster shutdown).

process =
{
    daemon = true,
    set_uid = 'snort',
    set_gid = 'snort'
}

process.chroot, process.daemon, process.set_gid, and process.set_uid require a restart to change; live reload is not supported for these parameters.

Stream Modules

Stream modules provide stateful flow tracking, IP defragmentation, and protocol-level reassembly.

stream — Flow tracking

The top-level stream module enables flow state tracking. It must be configured for any stream reassembly to occur.

snort --help-module stream

stream = { }

stream_ip — IP defragmentation

Reassembles fragmented IP packets before inspection.

snort --help-module stream_ip

stream_ip = { }

stream_tcp — TCP reassembly

Provides full TCP stream reassembly and session tracking.

snort --help-module stream_tcp

Parameter	Type	Default	Description
session_timeout	int	30	Seconds of inactivity before a TCP session expires.
max_window	int	0	Maximum allowed TCP window size (0 = unlimited).
overlap_limit	int	0	Maximum overlapping TCP segments before pruning (0 = unlimited).
small_segments	table	—	Alert on excessive small segments.

stream_tcp = { session_timeout = 60 }

Or equivalently:

stream_tcp = { }
stream_tcp.session_timeout = 60

Adding or removing stream_* inspectors after stream is already configured requires a full restart, not a reload.

stream_udp — UDP session tracking

Tracks UDP sessions for stateful inspection.

snort --help-module stream_udp

Parameter	Type	Default	Description
session_timeout	int	30	Seconds before a UDP session expires.

stream_udp = { }

stream_icmp — ICMP tracking

Tracks ICMP flows for correlation and stateful detection.

snort --help-module stream_icmp

stream_icmp = { }

stream_file — File stream tracking

Tracks file content streams for file identification and policy enforcement.

snort --help-module stream_file

stream_file = { }

Detection Modules

detection — Detection engine

Controls the core rule evaluation engine.

snort --help-module detection

Parameter	Type	Description
service_extension	table	Maps service names to additional services for rule group membership. Default extends http with http2/http3 and netbios-ssn with dcerpc.
global_rule_state	bool	Apply rule state globally across all policies.

-- Default service_extension is built in; override if needed
detection = { }

search_engine — Pattern matching

Selects and tunes the multi-pattern search engine (MPSE) used for fast pattern matching.

snort --help-module search_engine

Parameter	Type	Default	Description
search_method	enum	ac_bnfa	MPSE algorithm. See options below.
max_pattern_len	int	0	Truncate patterns longer than this (0 = no limit).
max_queue_events	int	—	Maximum events queued per packet.

Search methods:

Method	Description
ac_bnfa	Aho-Corasick with BNFA compression. Balances speed and memory (default).
ac_full	Aho-Corasick with full DFA. Faster but uses significantly more memory.
hyperscan	Intel Hyperscan. Best performance and reasonable memory; requires Hyperscan library.

search_engine = { search_method = 'ac_full' }

event_queue — Event handling

Controls how detection events are queued and deduplicated before logging.

snort --help-module event_queue

Parameter	Type	Default	Description
max_events	int	8	Maximum events to queue per packet.
log_events	int	3	Number of events to log from the queue.
order	enum	content_length	Queue ordering: content_length or priority.

event_queue =
{
    max_events = 16,
    log_events = 5,
    order = 'priority'
}

Output / Logging Modules

Output modules are activated via -A <mode> on the command line or by configuring the corresponding Lua table.

Alert loggers

Module	-A alias	Description
alert_cmg	cmg	Compact alert with hex/text payload dump. Equivalent to fast -d -e.
alert_fast	fast	Single-line summary per alert.
alert_full	full	Verbose alert with all header fields.
alert_csv	csv	Comma-separated output. Fields and separator are configurable.
alert_json	json	JSON-formatted alert records.
alert_unified2	unified2 / u2	Binary unified2 format for post-processors.
alert_syslog	—	Send alerts to syslog.

-- Customise CSV output fields and separator
alert_csv =
{
    fields = 'timestamp pkt_num proto src_ap dst_ap gid sid rev msg',
    separator = ','
}

# Output timestamp, pkt_num, proto, pkt_gen, dgm_len, dir, src/dst, rule, action
snort -c snort.lua -A csv

Packet loggers

Module	-L alias	Description
log_pcap	pcap	Write captured packets to a pcap file.
log_hext	hext	Dump TCP stream payload in hex/text format.

# Write 10 packets to log.pcap.*
snort -i eth0 -L pcap -n 10

# Dump stream payload as hext
snort -c snort.lua -L hext

Performance Modules

perf_monitor — Runtime metrics

Captures and periodically outputs a configurable set of peg counts during runtime. Useful for feeding to external monitoring tools without stopping Snort.

snort --help-module perf_monitor

-- Enable with defaults
perf_monitor = { }

profiler — Time and space profiling

Tracks CPU time and memory usage per module and per rule. Output appears in the Summary Statistics section at shutdown.

snort --help-module profiler

Parameter	Type	Description
modules	table	Module-level profiling options (show, count, sort).
rules	table	Rule-level profiling options (show, count, sort).

profiler =
{
    modules = { show = true, count = 10, sort = 'avg_check' },
    rules   = { show = true, count = 10, sort = 'avg_check' }
}

latency — Packet and rule latency

Monitors and optionally enforces time limits on packet processing and rule evaluation.

snort --help-module latency

Parameter	Type	Description
packet	table	Per-packet latency budget and action on timeout.
rule	table	Per-rule evaluation latency budget and action on timeout.

latency =
{
    packet = { max_time = 500, action = 'log' },
    rule   = { max_time = 500, action = 'log' }
}

Filter Modules

suppress — Suppress alerts

Suppresses specific alerts globally or for particular hosts, without removing the rule.

snort --help-module suppress

Field	Type	Description
gid	int	Generator ID of the rule to suppress.
sid	int	Signature ID of the rule to suppress.
track	enum	by_src or by_dst — limit suppression to a specific IP.
ip	string	IP address or CIDR to match when track is set.

suppress =
{
    -- Suppress this SID globally
    { gid = 1, sid = 1 },

    -- Suppress everything for a specific destination host
    { track = 'by_dst', ip = '1.2.3.4' },

    -- Suppress a specific SID for a specific source
    { gid = 1, sid = 2, track = 'by_src', ip = '10.0.0.5' },
}

# Reload with a new suppress entry (no restart needed)
echo 'suppress = { { gid = 1, sid = 2215 } }' >> snort.lua
kill -hup <pid>

event_filter — Alert thresholds

Reduces alert volume by limiting how many times a rule fires for a given source or destination within a time window.

snort --help-module event_filter

Field	Type	Description
gid	int	Generator ID.
sid	int	Signature ID.
type	enum	limit (log first N), threshold (log every Nth), or both.
track	enum	by_src or by_dst.
count	int	Threshold count.
seconds	int	Time window in seconds.

event_filter =
{
    { gid = 1, sid = 1, type = 'limit',  track = 'by_src', count = 2,  seconds = 10 },
    { gid = 1, sid = 2, type = 'both',   track = 'by_dst', count = 5,  seconds = 60 },
}

rate_filter — Rate-based filtering

Changes the action of a rule when a traffic rate threshold is exceeded.

snort --help-module rate_filter

Field	Type	Description
gid	int	Generator ID.
sid	int	Signature ID.
track	enum	by_src or by_dst.
count	int	Number of events in the window.
seconds	int	Time window in seconds.
new_action	enum	Action to apply when rate is exceeded (e.g., alert, drop).
timeout	int	Seconds the new action remains in effect.
apply_to	string	Optional IP address list to restrict the filter.

rate_filter =
{
    { gid = 135, sid = 1, track = 'by_src', count = 5, seconds = 1,
      new_action = 'alert', timeout = 4 },
}

Utility Modules

wizard — Service autodetection

Automatically identifies services by inspecting traffic patterns, eliminating the need to bind inspectors to fixed port numbers.

snort --help-module wizard

-- Use the built-in default wizard configuration
wizard = default_wizard

Configure the wizard and default port bindings will be created automatically based on which inspectors you have enabled. You do not need to explicitly bind ports in most cases.

binder — Traffic-to-policy binding

Maps network traffic characteristics (protocol, port, service, zone) to specific inspection policies.

snort --help-module binder

Each entry has a when clause (match conditions) and a use clause (what to apply):

binder =
{
    { when = { proto = 'tcp', ports = '80 443', role = 'server' },
      use  = { type = 'http_inspect' } },

    { when = { service = 'smtp' },
      use  = { type = 'smtp' } },

    -- Fallback: use wizard for everything else
    { use = { type = 'wizard' } }
}

appid — Application identification

Identifies the application protocol in use on a flow, independent of port number. Required to use AppID names in rules.

snort --help-module appid

Parameter	Type	Description
app_detector_dir	string	Path to the AppID detector library directory.

appid =
{
    app_detector_dir = '/usr/local/lib/snort/appid'
}

file_inspect — File identification

Identifies file types carried in network traffic using magic byte signatures.

snort --help-module file_inspect

Parameter	Type	Description
rules_file	string	Path to the file magic rules file (e.g., file_magic.rules).

-- The file magic rules are in file_magic.rules in the Snort install
file_inspect = { rules_file = 'file_magic.rules' }