gnat_reputation
Synopsis
Enriches flow records with IP reputation data from threat intelligence APIs.
Description
The gnat_reputation tool queries external threat intelligence APIs to enrich flow records with IP reputation information. It processes triggered flows (flows with trigger > 0) that meet a severity threshold and looks up destination IP addresses against the AbuseIPDB API.
The tool maintains a local cache (DuckDB database) to avoid redundant API lookups and respects API rate limits. When rate limits are reached, the tool automatically pauses lookups for one hour before resuming.
Key features:
- AbuseIPDB integration - Queries the AbuseIPDB API for IP reputation data
- Severity filtering - Only processes flows meeting the configured HBOS severity threshold
- Intelligent caching - Caches lookup results in a local DuckDB database
- Rate limit handling - Automatically handles API rate limits (HTTP 429)
- Private IP filtering - Skips lookups for RFC1918 private addresses (10.x.x.x, 172.16-31.x.x, 192.168.x.x)
This tool implements the gnat command line interface and shares the same required and optional arguments as other GNAT tools.
Required Options
The following options must be specified via the --options argument:
key=<API key>
Your AbuseIPDB API key. Required for authentication with the threat intelligence service.
cache=<DuckDB file>
Path to a DuckDB database file used to cache reputation lookup results. The cache is automatically maintained and entries older than 24 hours are expunged.
Optional Options
threshold=<1-5>
Minimum HBOS severity level required for a flow to trigger a reputation lookup. Default is 4 (severe).
| 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 |
abuse_url=<URL>
Override the AbuseIPDB API endpoint. Default is https://api.abuseipdb.com/api/v2/check.
Enrichment Data
The following reputation data is retrieved and cached for each IP address:
| Field | Description |
|---|---|
abuseConfidenceScore | Confidence score (0-100) that the IP is malicious |
countryCode | Two-letter country code |
usageType | ISP usage type classification |
isp | Internet Service Provider name |
domain | Associated domain name |
hostnames | Known hostnames for the IP |
isTor | Whether the IP is a known Tor exit node |
totalReports | Total abuse reports received |
numDistinctUsers | Number of distinct users reporting abuse |
lastReportedAt | Timestamp of last abuse report |
Examples
Basic usage with required options:
$ gnat_reputation --input /var/spool/input --output /var/spool/output \
--options "key=YOUR_ABUSEIPDB_API_KEY;cache=/var/cache/reputation.duckdb"
With custom severity threshold:
$ gnat_reputation --input /var/spool/input --output /var/spool/output \
--options "key=YOUR_API_KEY;cache=/var/cache/reputation.duckdb;threshold=3"
Running continuously with minute polling:
$ gnat_reputation --input /var/spool/input --output /var/spool/output \
--interval minute \
--options "key=YOUR_API_KEY;cache=/var/cache/reputation.duckdb"