gnat_tag_file

Synopsis

Definition of JSON file format for defining, matching, and tagging patterns of flow records.

Description

Tag files define patterns that label network flows based on matching criteria. When a flow matches the specified conditions, a tag (label) is appended to the flow's tag field. Up to 16 tags can be applied to a single flow.

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

JSON File Format

The JSON file is composed of an array of JSON objects, each object representing a tag rule. 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.

[
  {
    "tag": "tag_name",
    "observe": "observation_domain",
    "proto": "protocol",
    "saddr": "source_address",
    "sport": 443,
    "daddr": "destination_address",
    "dport": 80,
    "ndpi_appid": "application_id",
    "orient": "flow_orientation"
  }
]

Field Descriptions

Field	Type	Required	Default	Match Type	Description
tag	string	Yes	-	n/a	The tag/label name to apply when the rule matches
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)
ndpi_appid	string	No	""	prefix	nDPI application ID prefix to match
orient	string	No	""	prefix	Flow orientation prefix (e.g., "00", "01", "10", "11")

Matching Behavior

• Required field: Only tag is required. All other fields are optional.
• Empty/zero fields: Fields with empty strings ("") or zero values (0 for ports) are ignored in matching.
• Prefix matching: The fields observe, saddr, daddr, ndpi_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.
• Multiple conditions: When multiple fields are specified, ALL conditions must match (AND logic).
• Tag uniqueness: A tag is only added if it doesn't already exist on the flow.

Examples

Tag HTTPS Traffic

[
  {
    "tag": "https",
    "dport": 443
  }
]

Tag Internal Network Traffic

[
  {
    "tag": "internal",
    "saddr": "10."
  }
]

Tag DNS Traffic

[
  {
    "tag": "dns",
    "proto": "UDP",
    "dport": 53
  }
]

Multiple Tags

[
  {
    "tag": "web",
    "dport": 80
  },
  {
    "tag": "web",
    "dport": 443
  },
  {
    "tag": "corporate",
    "saddr": "192.168.1."
  },
  {
    "tag": "external-dns",
    "proto": "UDP",
    "dport": 53,
    "daddr": "8.8."
  }
]

Tag by Application

[
  {
    "tag": "ssh-traffic",
    "ndpi_appid": "SSH"
  }
]

Complex Rule

[
  {
    "tag": "prod-webserver",
    "observe": "datacenter-1",
    "proto": "TCP",
    "daddr": "192.168.100.10",
    "dport": 443
  }
]

Comprehensive Example

[
  { "tag": "cloudflare", "observe": "lan0", "proto": "tcp", "ndpi_appid": "tls.cloudflare" },
  { "tag": "dns", "observe": "lan1", "ndpi_appid": "dns" },
  { "tag": "intrusion", "orient": "oi" },
  { "tag": "tls", "proto": "tcp", "ndpi_appid": "tls" },
  { "tag": "app8181", "observe": "lan", "proto": "tcp", "daddr": "10.1.10.81", "dport": 8181 },
  { "tag": "snmp", "proto": "udp", "daddr": "192.168.73.13", "dport": 161, "ndpi_appid": "snmp" },
  { "tag": "china", "daddr": "218.199.73" },
  { "tag": "internal_web", "proto": "tcp", "saddr": "10.0.4.240", "daddr": "10.1.1.61", "dport": 9000, "ndpi_appid": "http", "orient": "ii" }
]

Usage

The tag configuration file is specified using the tag option when running the tag pipeline:

--options "tag=/path/to/tag-config.json"

Limits

• Maximum of 16 tags per flow (TAG_LIMIT)
• Tags are stored as a list in the flow's tag field

Notes

• Rules are processed in order; multiple rules can match and add different tags to 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".

See Also

• gnat_command
• gnat_tag