gnat_rule

Synopsis

Generates triggers (alerts) based on rule patterns that match flow records.

Description

The gnat_rule tool marks network flows for triggering or ignoring based on matching criteria. When a flow matches the specified conditions, the flow's trigger field is set to either 1 (trigger) or -1 (ignore). This is useful for alerting, filtering, or prioritizing flows based on network security policies.

Rules are specified in a JSON configuration file containing an array of rule objects. Each rule specifies an action (trigger or ignore) and optional matching criteria.

This tool implements the gnat command line interface and shares the same required and optional arguments as other GNAT tools.

Required Options

rule=<JSON file>

Path to a JSON file containing an array of rule definitions. Specified via the --options argument.

model=<DuckDB file>

Path to a pre-trained model file (DuckDB database). The rule processor requires this model file to function.

Rule Configuration Format

The configuration file is a JSON array containing one or more rule objects:

[
  {
    "action": "trigger",
    "observe": "observation_domain",
    "proto": "protocol",
    "saddr": "source_address",
    "sport": 443,
    "daddr": "destination_address",
    "dport": 80,
    "appid": "application_id",
    "orient": "flow_orientation",
    "tag": "tag_name",
    "risk_severity": 3,
    "hbos_severity": 2
  }
]

Field Descriptions

Field	Type	Required	Default	Match Type	Description
action	string	Yes	-	n/a	Action to take: "trigger" (set trigger=1) or "ignore" (set trigger=-1)
observe	string	No	""	prefix	Observation domain prefix to match
proto	string	No	""	exact	Protocol to match (exact match)
saddr	string	No	""	prefix	Source IP address prefix to match
sport	integer	No	0	exact	Source port to match (0 means any)
daddr	string	No	""	prefix	Destination IP address prefix to match
dport	integer	No	0	exact	Destination port to match (0 means any)
appid	string	No	""	prefix	nDPI application ID prefix to match
orient	string	No	""	prefix	Flow orientation prefix (e.g., "00", "01", "10", "11")
tag	string	No	""	exact	Tag/label to match (checks if flow has this tag)
risk_severity	integer	No	0	threshold	Minimum nDPI risk severity to match (0-255, 0 means any)
hbos_severity	integer	No	0	threshold	Minimum HBOS severity to match (0-255, 0 means any)

Matching Behavior

• Required field: Only action is required. All other fields are optional.
• Empty/zero fields: Fields with empty strings ("") or zero values are ignored in matching.
• Prefix matching: The fields observe, saddr, daddr, appid, and orient use prefix matching (the flow value must start with the specified string).
• Exact matching: The fields proto, sport, and dport use exact matching.
• Threshold matching: The fields risk_severity and hbos_severity use greater-than-or-equal matching.
• Tag matching: The tag field checks if the specified tag exists in the flow's tag list.
• Multiple conditions: When multiple fields are specified, ALL conditions must match (AND logic).

Actions

Action	Trigger Value	Description
trigger	1	Mark flow for alerting/investigation
ignore	-1	Mark flow to be ignored/suppressed

Severity Levels Reference

HBOS Severity Levels

Level	Value	Description
Low	1	Minor deviation from normal
Medium	2	Moderate anomaly
High	3	Significant anomaly
Severe	4	Major anomaly requiring attention
Critical	5	Critical anomaly

nDPI Risk Severity Levels

Level	Value	Description
Low	1	Low risk
Medium	2	Medium risk
High	3	High risk

Examples

Basic Usage

$ gnat_rule --input /var/spool/input --output /var/spool/output \
    --options "model=/path/to/model.duckdb;rule=/etc/rule_patterns.json"

Trigger on High-Risk Traffic

Trigger on flows with high nDPI risk severity:

[
  {
    "action": "trigger",
    "risk_severity": 3
  }
]

Ignore Internal Traffic

Ignore traffic from internal networks:

[
  {
    "action": "ignore",
    "saddr": "10."
  },
  {
    "action": "ignore",
    "saddr": "192.168."
  },
  {
    "action": "ignore",
    "saddr": "172.16."
  }
]

Trigger on Anomalous Behavior

Trigger on flows with HBOS anomaly scores indicating severe anomalies:

[
  {
    "action": "trigger",
    "hbos_severity": 4
  }
]

Trigger on Suspicious SSH Traffic

Trigger on SSH traffic from external sources:

[
  {
    "action": "trigger",
    "proto": "TCP",
    "dport": 22,
    "appid": "SSH"
  }
]

Ignore Known Good Traffic

Ignore DNS traffic to trusted resolvers:

[
  {
    "action": "ignore",
    "proto": "UDP",
    "dport": 53,
    "daddr": "8.8.8.8"
  },
  {
    "action": "ignore",
    "proto": "UDP",
    "dport": 53,
    "daddr": "8.8.4.4"
  }
]

Trigger on Tagged Flows

Trigger on flows that have been tagged as suspicious:

[
  {
    "action": "trigger",
    "tag": "suspicious"
  }
]

Complex Rule - External Server Access

Trigger on external access to production servers with anomalies:

[
  {
    "action": "trigger",
    "observe": "datacenter-prod",
    "proto": "TCP",
    "daddr": "192.168.100.",
    "dport": 443,
    "hbos_severity": 2
  }
]

Combined Trigger and Ignore Rules

Use multiple rules to create a policy that triggers on anomalies but ignores known patterns:

[
  {
    "action": "trigger",
    "hbos_severity": 3
  },
  {
    "action": "trigger",
    "risk_severity": 3
  },
  {
    "action": "ignore",
    "tag": "known-scanner"
  },
  {
    "action": "ignore",
    "saddr": "10.0.0.",
    "daddr": "10.0.0."
  }
]

Limits

• Maximum of 1000 rules recommended per configuration file (warning issued if exceeded)
• Rules with no matching conditions (all fields empty/zero) are skipped

Notes

• Rules are processed in order; later rules can override earlier ones for the same flow.
• Prefix matching on IP addresses allows for subnet-style matching (e.g., "192.168." matches any IP starting with 192.168.).
• The orient field represents flow orientation with values like "00", "01", "10", "11".
• Trigger counts are reported after processing, grouped by severity level (low, medium, high, severe).

See Also

• gnat_command
• gnat_rule_file
• gnat_tag
• gnat_hbos