gnat_rule_file

Synopsis

Definition of JSON file format for defining patterns to trigger actions on flow records.

Description

Rule files define patterns that mark 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.

The rule patterns are defined in a JSON file and specified with the --options rule=<path> argument of the gnat_rule command line interface.

JSON File Format

The JSON file is composed of an array of JSON objects, each object representing a rule pattern. Each object contains a set of key-value pairs, where the key is the name of the field and the value is the value to match against.

[
  {
    "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

Trigger on High-Risk Traffic

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

Ignore Internal Traffic

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

Trigger on Anomalous Behavior

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

Trigger on Suspicious SSH Traffic

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

Ignore Known Good Traffic

[
  {
    "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

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

Complex Rule - External Server Access

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

Combined Trigger and Ignore Rules

[
  {
    "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."
  }
]

Usage

The rule configuration file is specified using the rule option when running the rule pipeline. A model file is also required:

--options "model=/path/to/model.duckdb;rule=/path/to/rule-config.json"

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".
• The rule processor requires a pre-trained model file to function.
• Trigger counts are reported after processing, grouped by severity level (low, medium, high, severe).

See Also

• gnat_command
• gnat_rule