rockfish detect

The primary detection service — runs the OCCAM detection engine with integrated Parquet ingest and behavioral threat hunting.

Overview

rockfish detect is the main detection command that replaces the previous rockfish run and rockfish ingest commands. It combines:

OCCAM detection engine — tokenizes EVE events, builds HBOS baselines, scores anomalies
Parquet ingest — writes EVE events to Hive-partitioned Parquet files
Hunt — periodic behavioral threat detection (beaconing, lateral movement, C2, etc.)

Usage

rockfish detect \
    --socket /var/run/rockfish/rockfish.sock \
    --output-dir /var/lib/rockfish/detections \
    --parquet-dir /var/lib/rockfish/parquet \
    --hunt --hunt-interval 60 \
    --license /opt/rockfish/etc/rockfish_license.json

Options

Flag	Default	Description
`--socket <path>`	—	Unix socket for EVE input (Suricata connects to this)
`--eve-file <path>`	—	EVE JSON file input (alternative to socket)
`--follow`	false	Tail mode for file input
`--output-dir <path>`	`/var/lib/rockfish/detections`	Detection JSONL output directory
`--parquet-dir <path>`	—	Parquet output directory (enables EVE-to-Parquet ingest)
`--hunt`	false	Enable periodic behavioral threat detection
`--hunt-interval <min>`	60	Minutes between hunt runs
`--window-minutes <min>`	15	OCCAM window duration
`--baseline-min-days <days>`	7	Days before HBOS baseline activates
`--baseline-min-samples <n>`	256	Minimum samples before baseline activates
`--surprisal-threshold <bits>`	1.5	Default surprisal threshold
`--status-interval <sec>`	60	Status line interval (0 to disable)
`--alert-webhook <url>`	—	POST elevated detections to this URL
`--flush-interval <sec>`	60	Parquet flush interval
`--compression <codec>`	zstd	Parquet compression (none, snappy, zstd)
`--license <path>`	—	License JSON file
`--sensor <name>`	hostname	Sensor name for partitioning

Systemd Service

[Unit]
Description=Rockfish NDR — OCCAM Detection Engine
After=network.target
Before=suricata.service

[Service]
Type=simple
User=rockfish
Group=rockfish
ExecStart=/opt/rockfish/bin/rockfish detect \
    --socket /var/run/rockfish/rockfish.sock \
    --output-dir /var/lib/rockfish/detections \
    --parquet-dir /var/lib/rockfish/parquet \
    --hunt --hunt-interval 60 \
    --license /opt/rockfish/etc/rockfish_license.json
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

Socket Mode

Rockfish creates a Unix socket and listens for Suricata to connect. Suricata must be configured to output EVE JSON to this socket. The order matters:

Start rockfish detect (creates socket, waits for connection)
Start Suricata (connects to the socket)

Detection Output

OCCAM detections are written to both:

JSONL — {output-dir}/{sensor}/sigma/year=YYYY/month=MM/day=DD/detections.jsonl
Parquet — {parquet-dir}/{sensor}/sigma/year=YYYY/month=MM/day=DD/{timestamp}.parquet

The Parquet output is used by rockfish report for the Insight (AI assessment) and OCCAM dashboard pages.

rockfish detect also performs enrichment and passive asset inventory. These are configured in rockfish.yaml, not via CLI flags — so they do not appear in rockfish detect --help. The startup banner reports whether each is active (e.g. OUI Lookup: disabled, Inventory: disabled).

Enrichment — GeoIP, IP reputation (AbuseIPDB), and MAC vendor (OUI) lookup. Configure under enrichment: (geoip_city_path, ip_reputation_enabled, oui_path). See Enrichment.
Asset Inventory — passive device discovery, inferred roles, and OT-protocol usage. Configure under inventory: (enabled, alert_on_new); defaults on for the ot/military profile. See Asset Inventory.

MAC-vendor names in the inventory require enrichment.oui_path — download the IEEE OUI database with scripts/download-oui.sh.

Hunt Thread

When --hunt is enabled, a background thread runs DuckDB queries on the Parquet flow data at the specified interval. Detections include:

Beaconing (periodic C2 check-ins)
Lateral movement (internal-to-internal spread)
C2 fanout (single source → many destinations)
Port scanning
Community detection (clusters of communicating hosts)

45-Day Trial Window

All licenses receive Professional features for 45 days from issued_at (the trial caps at Professional; Enterprise features remain paid-only, and an Enterprise license is never down-ranked). After 45 days, the license settles to its purchased tier. The OCCAM engine re-checks the license once per day.

Rockfish NDR Documentation