Documentation: network policy, security model, forensics, operations, API, testing, limitations

2026-10-09 17:58:58 +01:00
parent 01b568aaf7
commit 1c31e3b3d5
9 changed files with 487 additions and 1 deletions
@@ -0,0 +1,50 @@
+# Testing
+
+## Automated
+
+| Command | What it covers | Needs |
+|---|---|---|
+| `make test` | Config validation, nft/dnsmasq/NM rendering, Argon2id, TOTP (RFC 6238 vector), throttling, helper parsers, pcap/pcapng reader incl. malformed input, API auth flow (setup token, authorised-use, CSRF, source allow-list, lock-out detection, logout, throttling), TypeScript typecheck | Go, Node |
+| `make test-docker` | Everything above that needs tshark/dumpcap (import → index → filter → PDML with verified byte ranges → filtered export re-read by tshark → hash verify; live capture with segment rotation, counts agreement, per-segment validity), **plus** the netns suite below | Docker |
+
+The netns suite (`tests/integration/run.sh`) builds an upstream/Pi/client topology from
+veth pairs and runs the real `pilens` binary plus the configuration rendered by `pilens-helper`:
+DHCP lease and options, DNS override, NAT to a public address, blocking of RFC 1918 /
+management / IPv6 / inbound / Pi-SSH, management reachable only from the allowed subnet (not
+from AP clients, not even via the uplink address), first-admin creation, capture on the AP
+interface through the API, display filter, packet detail, export opened by tshark, integrity
+check, CSRF rejection, deny mode, and survival of an unrelated nft table.
+
+Not covered by automation: NetworkManager AP activation and its rollback (needs a real radio;
+`mac80211_hwsim` is not available in containers), systemd unit behaviour, installer.
+
+## Hardware acceptance checklist (Raspberry Pi)
+
+Record date, Pi model, OS, PiLens version and the result for each item.
+
+| # | Test | Expected |
+|---|---|---|
+| H1 | Fresh install on Pi OS Lite via SSH over Ethernet | Installer completes. Prints URL, fingerprint, token. Existing connections unchanged. |
+| H2 | Wizard: create admin, apply AP | Steps all ✓. SSID visible. Ethernet SSH session not interrupted. |
+| H3 | Phone joins the AP | Lease in the pool, Pi as DNS, internet works |
+| H4 | Phone → LAN host (e.g. router admin page) | Blocked |
+| H5 | Phone → `https://<pi-ap-ip>:8443` and SSH to the Pi | Blocked |
+| H6 | Capture on wlan0 while browsing | Packets live in the UI. Export opens in desktop Wireshark. Verify = ok. |
+| H7 | Cold boot | AP returns. Firewall table loaded before the AP (`journalctl -b -u pilens-firewall -u NetworkManager`). Forwarding works. |
+| H8 | Power loss during capture | Session marked interrupted. Segment hashed. Earlier segments verify. |
+| H9 | Unplug Ethernet for 1 min, replug | Dashboard shows no default route, then recovers. Clients keep their leases. |
+| H10 | Client disconnects and reconnects | Device list updates. Same lease. |
+| H11 | `kill -9` of pilens during a capture | systemd restarts it. Session interrupted. Forwarding unaffected. |
+| H12 | Storage exhaustion (small quota) | Oldest unpreserved session deleted, or capture stops with an error. Preserved session intact. |
+| H13 | Apply an invalid AP config (e.g. WPA3 on a radio without SAE) | Rolled back, previous AP restored, error shown |
+| H14 | `uninstall.sh` then `install.sh` | Captures kept. Old Wi-Fi client profile works again after uninstall. |
+| H15 | `repair.sh` after `setcap -r /usr/bin/dumpcap` | Capabilities restored |
+| H16 | Throughput: iperf3 through the AP while capturing | Record Mbit/s, dumpcap drops, ingest lag |
+| H17 | Import a 500 MB pcapng | Indexing time recorded. UI responsive. |
+
+TLS-interception hardware tests belong to phase 4.
+
+## Results log
+
+Hardware results are recorded here only after they have actually been run. See the
+release notes or commit log for the latest run.