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