2026-11-15 17:43:13 +01:00
2026-11-15 17:43:13 +01:00
2026-11-15 17:41:40 +01:00
2026-11-15 17:43:04 +01:00
2026-11-15 17:42:55 +01:00
2026-11-15 17:42:15 +01:00
2026-11-15 17:42:55 +01:00
2026-11-15 17:43:13 +01:00
2026-11-15 17:43:13 +01:00
2026-11-15 17:43:13 +01:00

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.

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.

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 for deployment, Architecture for the controller design, and Testing 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

Description
An external IPS/IDS for free version of VyOS
Readme 106 KiB
Languages
Python 90.6%
Shell 9.4%