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

25
.gitignore vendored Normal file
View File

@@ -0,0 +1,25 @@
evidence/
.local_keys
*.pyc
__pycache__/
tests/.dbg*
tests/.e2e/
# Local credentials and runtime data
.env
.env.*
*.key
*.pem
*.sqlite
*.sqlite-*
*.sock
*.sock.lock
*.pcap
.venv/
.pytest_cache/
# Editor backup files
*.bkp
fig

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)

View File

@@ -0,0 +1,52 @@
# LEAF-PROTO prototype config — run on the LEAF VM (eth1 P2P link to VIPERA).
# Secrets stay in env: export LEAF_VYOS_KEY=... before starting the controller.
vyos:
url: "https://10.0.249.0:8443"
key_env: LEAF_VYOS_KEY
# Router serves a self-signed CN=localhost cert with no IP SAN, so plain
# CA/hostname verification cannot work; trust is anchored on the pinned
# fingerprint below (regenerate with:
# echo | openssl s_client -connect 10.0.249.0:8443 2>/dev/null | openssl x509 -noout -fingerprint -sha256)
tls_cert_pin: "21:3A:73:9A:B5:EE:8A:83:F8:50:E8:F9:4E:0C:DD:28:81:29:75:1F:33:18:F9:C9:0A:9C:AB:F0:91:EF:3C:C4"
timeout: 60
retries: 2
block_group: IDS-BLOCK
ensure_primitives: true
adopt_foreign_members: false # this dedicated group is owned by durable controller state
save_config: false # transient membership; SQLite is the durable desired state
eve:
path: /var/log/suricata-leaf/eve.json
checkpoint: true # resume at the sqlite-persisted offset after restarts
alert_socket:
path: /run/suricata/alerts.sock # AF_UNIX listener owned by this controller;
# suricata unix_stream connects as the client
queue_size: 1000
audit:
max_bytes: 16777216 # rotate decisions.jsonl at 16 MiB...
keep: 3 # ...keeping three rotated files
policy:
mode: threshold
min_hits: 2
window_seconds: 300
ttl_seconds: 3600
max_blocks: 50
sids_only: [1000001, 1000030] # lab-only automatic actions; expand after validating rules
block_src: true # permit source actions for the explicitly allowed lab SIDs
allow_cidrs: # never block these (management/fabric floor)
- 10.0.249.0/31 # VIPERA<->sensor P2P link
- 192.168.88.0/27 # uplink transit
- 192.168.1.0/24 # management LAN (my workstation path)
- 192.168.100.0/24 # LEAF management LAN (sensor itself)
state_db: /var/lib/leaf-controller/state.sqlite
audit_log: /var/log/leaf-controller/decisions.jsonl
poll_interval: 0.2
router_interval: 2
batch_delay: 0.2
metrics: # stats records: counting only, never policy input
reconcile_interval: 30 # = suricata stats period; one health line per window
capture_interval: 3600 # capture.log metrics line cadence (s)
capture_log: /var/log/leaf-controller/capture.log
capture_max_bytes: 10485760 # rotate at 10 MiB...
capture_log_keep: 6 # ...keeping six rotated files
log_level: INFO

View File

@@ -0,0 +1,15 @@
#### Illustrative new-install template only. NOT the live VIPERA configuration.
#### Do not apply this file to VIPERA. Existing OSPF, uplink, mirror and routes
#### are outside LEAF maintenance scope. Verify live hooks through the client.
#### Router OS variants differ: inspect the target schema before configuring.
# One dedicated group, and source/destination drop hooks ahead of accept rules.
set firewall group address-group IDS-BLOCK
set firewall ipv4 forward filter rule 10 action drop
set firewall ipv4 forward filter rule 10 destination group address-group IDS-BLOCK
set firewall ipv4 forward filter rule 11 action drop
set firewall ipv4 forward filter rule 11 source group address-group IDS-BLOCK
# API service, TLS trust and mirroring are provisioned by the administrator.
# No embedded key, interface changes, broad accept rules or commit/save here.
# Controller save_config=false keeps transient membership out of boot config.