Docs
This commit is contained in:
68
docs/ARCHITECTURE.md
Normal file
68
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,68 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user