From cb117e1008b848af1e0d45c5bc1697690d55f731 Mon Sep 17 00:00:00 2001 From: YuruC3 Date: Sun, 15 Nov 2026 17:43:13 +0100 Subject: [PATCH] Others --- .gitignore | 25 ++++++++++ README.md | 94 +++++++++++++++++++++++++++++++++++- config/prototype-vyos.yaml | 52 ++++++++++++++++++++ vyos/router-leaf.snippet.txt | 15 ++++++ 4 files changed, 185 insertions(+), 1 deletion(-) create mode 100644 .gitignore create mode 100644 config/prototype-vyos.yaml create mode 100644 vyos/router-leaf.snippet.txt diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a7a6c6b --- /dev/null +++ b/.gitignore @@ -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 \ No newline at end of file diff --git a/README.md b/README.md index b2468c7..49a8ce8 100644 --- a/README.md +++ b/README.md @@ -1 +1,93 @@ -# Hi \ No newline at end of file +# 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) diff --git a/config/prototype-vyos.yaml b/config/prototype-vyos.yaml new file mode 100644 index 0000000..f9264e8 --- /dev/null +++ b/config/prototype-vyos.yaml @@ -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 diff --git a/vyos/router-leaf.snippet.txt b/vyos/router-leaf.snippet.txt new file mode 100644 index 0000000..16c5061 --- /dev/null +++ b/vyos/router-leaf.snippet.txt @@ -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.