# LEAF LEAF connects a passive Suricata sensor to VyOS firewall enforcement. It reads alerts, applies a threshold policy, stores block decisions in SQLite, and updates a dedicated router address group through the VyOS API. Suricata receives mirrored traffic. Enforcement happens asynchronously on the router, so packets can pass before a block is committed. ```text Mirrored traffic -> Suricata -> Unix socket -> policy -> SQLite | reconciliation worker | VyOS API + readback | firewall drop rules Suricata stats -> EVE file on tmpfs -> metrics Controller decisions -> persistent audit log ``` ## Policy Rules must carry a `leaf_action` metadata value before they can produce a block: | Metadata | Target | Requirement | |---|---|---| | `leaf_action block` | Destination IPv4 address | Policy permits the SID and address | | `leaf_action block_src` | Source IPv4 address | Also requires `policy.block_src: true` | The lab configuration allows SIDs **1000001** and **1000030**, requires two alerts for the same SID and address within 300 seconds, and assigns a 3600-second TTL. Qualifying alerts refresh the TTL. The default cap is 50 active addresses. Private, loopback, link-local, multicast and configured trusted networks are protected. The included rules are examples for controlled TEST-NET traffic. One worker serializes router changes and verifies group membership after each commit. SQLite retains desired blocks during API failures. Expiry and drift reconciliation run independently of new alerts. Source and destination hooks share the same address group; the stored `kind` records the initial reason. ## Repository | Path | Contents | |---|---| | `controller/leaf_controller/` | Ingestion, policy, state, metrics and API client | | `controller/leaf-controller.service` | Controller service | | `config/prototype-vyos.yaml` | Lab controller configuration | | `controller/config.yaml` | Generic configuration example | | `suricata/` | Sensor configuration, rules and retention units | | `scripts/` | Installation, maintenance and read-only diagnostics | | `tests/` | Unit tests, mock integration and bounded live tests | | `vyos/router-leaf.snippet.txt` | Illustrative enforcement hooks | | `fig/` | Architecture figures | ## Getting started The sensor requires Python 3, the packages in `controller/requirements.txt`, Suricata 7, systemd and a capture interface receiving the intended mirror. Review the interface names, API endpoint, TLS trust, protected networks and firewall hooks before installing. ```bash sudo apt install python3 python3-requests python3-yaml PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -p 'test_*.py' -v bash tests/run_e2e.sh ``` See [Installation and operations](docs/INSTALLATION.md) for deployment, [Architecture](docs/ARCHITECTURE.md) for the controller design, and [Testing](docs/TESTING.md) for offline and live checks. ## Limits LEAF is an IPv4 lab prototype. The sample rules do not establish production detection quality, and no high-throughput capacity is claimed. Router commits can take tens of seconds. Socket alerts are not a durable journal. A process crash, disconnection or Suricata send-buffer pressure can lose alerts before they reach SQLite. A zero controller queue-drop count does not establish that Suricata delivered every alert. Graceful shutdown persists accepted queued alerts; previously stored block decisions survive restarts. Live counter tests establish detection and firewall-rule hits. Ingress capture alone does not prove destination receipt or application connectivity. Sustained throughput and full sensor/router reboot recovery require separate testing. ![Mary Sue my goat](https://data.shupogaki.org/assets/1/HUHV0zHbEAEdCyM.jpeg)