Others
This commit is contained in:
25
.gitignore
vendored
Normal file
25
.gitignore
vendored
Normal 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
|
||||||
94
README.md
94
README.md
@@ -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.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|

|
||||||
|
|||||||
52
config/prototype-vyos.yaml
Normal file
52
config/prototype-vyos.yaml
Normal 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
|
||||||
15
vyos/router-leaf.snippet.txt
Normal file
15
vyos/router-leaf.snippet.txt
Normal 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.
|
||||||
Reference in New Issue
Block a user