Docs
This commit is contained in:
87
docs/TESTING.md
Normal file
87
docs/TESTING.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user