69 lines
3.5 KiB
Markdown
69 lines
3.5 KiB
Markdown
# Controller architecture
|
|
|
|
## Alert ingestion
|
|
|
|
Suricata is the client of an AF_UNIX stream socket bound by `AlertSocket` in
|
|
`alertsock.py`. The reader frames newline-delimited JSON, accepts alert records,
|
|
and places them on a bounded queue. Oversized or malformed records and queue
|
|
overflow are counted. A socket-path lock prevents competing controllers from
|
|
replacing the listener, even when they use different state databases.
|
|
|
|
The queue wakes the main loop independently of file polling. The reader does
|
|
not run policy or wait for router commits. During graceful shutdown, intake is
|
|
stopped and accepted queued alerts are processed before SQLite closes.
|
|
|
|
The normal EVE file contains stats. `EveTailer` in `eve.py` follows complete
|
|
records, preserves partial writes and drains the old inode during rotation.
|
|
When socket mode is enabled, file alerts are ignored to avoid counting the same
|
|
alert through two outputs.
|
|
|
|
For file-alert mode, set `alert_socket.path: ""` and configure Suricata to write
|
|
alerts into the EVE file. Checkpoints advance per delivered record. File-hit
|
|
identities include record content, inode, offset, SID and candidate address to
|
|
prevent replay from inflating threshold counts. Processing is at-least-once;
|
|
a restart cannot automatically recover unread records in an older rotated file.
|
|
|
|
## Policy and state
|
|
|
|
`policy.py` reads `leaf_action` metadata, applies SID restrictions, rejects
|
|
protected addresses, and evaluates threshold or immediate mode. `state.py`
|
|
stores hit windows, desired blocks, expiry times, applied flags, file checkpoints
|
|
and pending router-save status in SQLite WAL mode.
|
|
|
|
The desired block row is persisted before API submission. Qualifying alerts
|
|
refresh expiry. The active-address cap bounds the number of desired blocks.
|
|
Source and destination actions share a router group; `kind` records the initial
|
|
reason rather than choosing a separate group.
|
|
|
|
## Router reconciliation
|
|
|
|
A separate worker in `main.py` serializes router I/O using its own SQLite
|
|
connection. Each pass reads actual membership, computes changes, commits a batch,
|
|
and reads membership back before marking decisions applied or removals complete.
|
|
|
|
A timeout may still mean a commit succeeded. The following pass reads state
|
|
before retrying. Expiry deletion uses a timestamp condition so that a fresh
|
|
alert received during a slow request does not lose its refreshed decision.
|
|
Failures retain desired state for retry.
|
|
|
|
`vyos_client.py` handles multipart API requests and response validation. TLS can
|
|
use normal CA verification or a certificate fingerprint checked before sending
|
|
credentials. Pinned pool classes are private to each client. Environment proxies
|
|
are disabled for the API session.
|
|
|
|
## Metrics and persistence
|
|
|
|
Stats records update `metrics.py` counters without entering policy or changing
|
|
router state. Reports include capture/decoder deltas and ingress counters.
|
|
`decisions.jsonl` records decisions and verified enforcement changes; `capture.log`
|
|
contains periodic metric windows. Both logs retain the newest size-bounded archives.
|
|
|
|
A zero controller queue-drop count covers that queue only. Suricata can lose
|
|
alerts before delivery under send-buffer pressure or disconnection. The socket
|
|
queue is volatile on crash. Durable decisions can be reconciled after restart,
|
|
but alerts that never reached SQLite cannot be reconstructed from the stats file.
|
|
|
|
Dry-run creates temporary state and logs, disables socket ownership, avoids the
|
|
API, and reads the configured file from its beginning. Use an alert fixture for
|
|
policy replay; the normal stats-only file contains no alert history.
|