Files
LEAF/docs/TESTING.md
2026-11-15 17:43:04 +01:00

88 lines
3.7 KiB
Markdown

# Testing
## Unit and mock integration tests
Run from the repository root:
```bash
PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -p 'test_*.py' -v
bash tests/run_e2e.sh
LEAF_E2E_SOCKET=/tmp/leaf-test.sock bash tests/run_e2e.sh
python3 tests/checkpoint_e2e.py
```
The unit suite covers socket ownership/framing, protected-address policy,
thresholds, persistence, replay identities, reconciliation races, TLS pin
isolation, retention, malformed telemetry and credential-switch failure paths.
It uses local fixtures rather than the lab network.
The shell integration starts a localhost mock VyOS API and a controller. The
first invocation uses file alerts; the second uses the Unix socket. They check
thresholding, protected addresses, source blocking, rotation, adoption and TTL
cleanup. They use port 18443 and disposable `tests/.e2e/` files: run them
sequentially. Keep the socket path short enough for AF_UNIX pathname limits.
The checkpoint check verifies that file mode resumes at the next unread record.
It does not assert socket-alert backlog during controller downtime.
## Offline Suricata replay
On a sensor with Suricata installed and its rules in `/etc/suricata-leaf/`:
```bash
sudo python3 tests/replay_fixture.py
```
The script generates a valid 24-SYN PCAP, replays it with isolated outputs and
requires 24 decoded SYNs, two SID 1000030 alerts and zero fragment/checksum errors.
It leaves the live capture configuration and services in place.
`tests/syn_packets.py` is the maintained TEST-NET SYN generator.
`tests/drill_synsensor.py` can write ICMP/SYN PCAP fixtures or send bounded raw
frames on a selected route. Capture visibility depends on the mirror topology;
use the test hosts for the live enforcement checks.
## Live enforcement tests
Verify the sensor identity, SSH account/key, test hosts, routes and dedicated
block group before running. Defaults describe the supplied lab. Override the
connection arguments for another environment:
```bash
python3 tests/live_e2e.py --help
python3 tests/live_negative.py --help
python3 tests/live_e2e.py --output evidence/live-e2e.json
python3 tests/live_negative.py --output evidence/negative.json
```
These tests use SSH to the sensor and LXCs, deploy temporary helpers, transmit
bounded TEST-NET traffic and temporarily select a 180-second TTL. They require
an empty block group and state for counter attribution. Run them sequentially.
The original configuration is restored on exit; failure cleanup expires only
the test's own targets. An interrupted connection can require checking the
retained configuration backup before another run.
The positive test requires fresh capture, audited decisions, durable applied
rows, verified router membership, source/destination drop-counter growth,
natural TTL removal and clean post-expiry probes. It compares hashes of
protected router configuration before and after.
The negative test sends benign traffic from another source while a block is
active. It checks ingress observation, absence of the benign address from
block membership/state, and selective IDS counter changes. Ingress capture
is not a destination receipt or application-connectivity test.
Live results describe the tested rules, topology and traffic. They do not
establish sustained throughput, production detection quality, lossless alert
delivery, or successful full router/sensor reboot recovery.
## Recovery inspection
```bash
VM=<sensor-user>@<sensor-address> LEAF_SSH_KEY=<key-path> bash scripts/reboot-check.sh
```
Despite its filename, this script performs read-only recovery inspection. It
checks service activity/enabling, tmpfs, socket presence and API/state status,
and prints the current boot identity. It does not initiate or prove a reboot.