Files
LEAF/docs/ARCHITECTURE.md
2026-11-15 17:43:04 +01:00

3.5 KiB

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.