Skip to main content

gnat_tag

Synopsis​

Annotates flow records with tags (labels) based on matching patterns.

Description​

The gnat_tag tool labels network flows based on matching criteria. When a flow matches the specified conditions, a tag (label) is appended to the flow's tag field. Tags are useful for categorizing, filtering, and grouping flows for analysis.

Key features:

  • Pattern matching - Match flows by protocol, IP addresses, ports, application IDs, and more
  • Multiple tags - Up to 16 tags can be applied to a single flow
  • Tag uniqueness - A tag is only added if it doesn't already exist on the flow
  • Prefix matching - IP addresses and other fields support prefix matching for subnet-style rules

Patterns are specified in a JSON file which contains a list of patterns and tags that are used to match and annotate the flow records.

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

Required Options​

tag=<JSON file>​

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

Tag Configuration Format​

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

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

FieldTypeRequiredDefaultMatch TypeDescription
tagstringYes-n/aThe tag/label name to apply when the rule matches
observestringNo""prefixObservation domain prefix to match
protostringNo""exactProtocol to match (exact match)
saddrstringNo""prefixSource IP address prefix to match
sportintegerNo0exactSource port to match (0 means any)
daddrstringNo""prefixDestination IP address prefix to match
dportintegerNo0exactDestination port to match (0 means any)
ndpi_appidstringNo""prefixnDPI application ID prefix to match
orientstringNo""prefixFlow 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​

Basic Usage​

$ gnat_tag --input /var/spool/input --output /var/spool/output \
    --options "tag=/etc/tag_patterns.json"

Tag HTTPS Traffic​

Tag all flows with destination port 443 as "https":

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

Tag Internal Network Traffic​

Tag traffic from the 10.0.0.0/8 network:

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

Tag DNS Traffic​

Tag UDP traffic on port 53:

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

Multiple Tags​

Apply multiple tags with different rules:

[
  {
    "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 flows identified as SSH by nDPI:

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

Complex Rule​

Tag specific server traffic with multiple conditions:

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

Comprehensive Tagging Example​

File tag_patterns.json containing an array of JSON objects:

[
  { "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": "app9000", "proto": "tcp", "saddr": "10.0.4.240", "daddr": "10.1.1.61", "dport": 9000, "ndpi_appid": "http", "orient": "ii" }
]

Limits​

  • Maximum of 16 tags per flow
  • 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​