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,74 @@
+# PiLens
+
+PiLens turns a Raspberry Pi into a self-contained Wi-Fi test network with packet
+capture and Wireshark-grade analysis in the browser. You connect an **authorised**
+test device to the Pi's access point and watch its traffic: live packets, a
+protocol tree from TShark, and the original bytes with field highlighting. The
+original captures are kept unmodified, with SHA-256 integrity hashes.
+
+No cloud service, account or internet connection is needed for management,
+capture or analysis.
+
+> **Use it only on devices and networks you own or are explicitly authorised to
+> inspect.** PiLens has no covert, impersonation or credential-harvesting
+> features. Encrypted traffic (HTTPS, QUIC, VPNs, encrypted DNS) stays encrypted:
+> in this version PiLens shows packets and metadata, not decrypted content.
+
+## Status
+
+| Phase | Scope | State |
+|---|---|---|
+| 1 | Installer, services, auth, AP / DHCP / DNS / firewall, health | implemented |
+| 2 | dumpcap capture, pcapng storage, live analyser, filters, export / import | implemented |
+| 3 | Conversations, follow TCP stream, DNS/TLS explorers, statistics | not started |
+| 4 | Optional HTTPS inspection (mitmproxy, client-trusted CA) | not started |
+| 5 | Hardening, advanced UI, benchmarks | partial |
+
+Pages for later phases are not in the UI. PiLens never shows controls that do
+nothing. For what was tested and how, see [docs/testing.md](docs/testing.md).
+
+## Quick start
+
+On a Raspberry Pi 4/5 with Raspberry Pi OS Lite (64-bit, Bookworm or Trixie),
+connected by **Ethernet**:
+
+```sh
+tar xzf pilens-<version>-linux-arm64.tar.gz
+cd pilens-<version>-linux-arm64
+sudo ./install.sh
+```
+
+The installer prints the management URL, the certificate fingerprint and a
+one-time setup token. Open the URL from a machine on the management network and
+complete the setup wizard. The wizard creates the access point and turns the
+Wi-Fi interface into the AP, so **manage the Pi over Ethernet**.
+
+For unattended installation: `sudo ./install.sh --non-interactive --config setup.yaml`
+(see `setup.example.yaml`).
+
+## Building
+
+Requirements: Go ≥ 1.24, Node ≥ 20. Docker is used only for the test suite.
+
+```sh
+make package            # dist/pilens-<ver>-linux-arm64.tar.gz (cross-compiled, static)
+make test               # unit tests + TypeScript typecheck
+make test-docker        # tshark/dumpcap tests + network-namespace integration suite
+```
+
+## Documentation
+
+- [Architecture and design decisions](docs/architecture.md)
+- [Installation, first run, upgrade and recovery](docs/operations.md)
+- [Network topology and firewall policy](docs/network.md)
+- [Security and privacy model](docs/security.md)
+- [Forensic evidence handling](docs/forensics.md)
+- [API](docs/api.md)
+- [Testing and hardware acceptance checklist](docs/testing.md)
+- [Known limitations](docs/limitations.md)
+
+## Licence
+
+AGPL-3.0-or-later. Bundled JavaScript dependencies (React, MIT) are compatible.
+TShark/dumpcap (GPL-2.0+), dnsmasq (GPL-2.0/3.0) and nftables (GPL-2.0) are
+installed from Debian packages and run as separate programs.