This commit is contained in:
2026-11-15 17:43:13 +01:00
parent 6aec4f6082
commit cb117e1008
4 changed files with 185 additions and 1 deletions

View File

@@ -1 +1,93 @@
# Hi
# 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)