Files
LEAF/docs/ARCHITECTURE.md

69 lines
3.5 KiB
Markdown
Raw Normal View History

2026-11-15 17:43:04 +01:00
# 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.