Andy Dixon
f3cfa9ccf1
Updated README/architecture/security/limitations/testing/api/CHANGELOG and the LaTeX user guide (now 14pp) with the Certificates and HTTP Explorer screens. 0 called Go vulns, npm audit clean.
80 lines
3.3 KiB
Markdown
80 lines
3.3 KiB
Markdown
# 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 | implemented (HTTP explorer deferred) |
|
|
| 4 | Optional HTTPS inspection (mitmproxy, client-trusted CA) | implemented |
|
|
| 5 | Hardening, Findings, benchmarks, dependency audits | implemented |
|
|
|
|
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)
|
|
- [Encryption: what PiLens can and cannot see](docs/tls-and-encryption.md)
|
|
- [Security and privacy model](docs/security.md)
|
|
- [Forensic evidence handling](docs/forensics.md)
|
|
- [API](docs/api.md)
|
|
- [Development guide](docs/development.md)
|
|
- [Troubleshooting](docs/troubleshooting.md)
|
|
- [Benchmarks](docs/benchmarks.md)
|
|
- [Testing and hardware acceptance checklist](docs/testing.md)
|
|
- [Known limitations](docs/limitations.md)
|
|
- [Illustrated user guide (PDF)](docs/guide/pilens-guide.pdf)
|
|
|
|
## 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.
|