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.
|
|
|
|
|
|
|
|
|
|
```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.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|

|