Others
This commit is contained in:
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.
|
||||
|
||||
|
||||
|
||||
|
||||

|
||||
|
||||
Reference in New Issue
Block a user