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 @@
+# Forensic evidence handling
+
+## What is evidence and what is derived
+
+| Data | Status |
+|---|---|
+| `captures/<session>/seg-NNNNNN.pcapng` (live) | **Original**. dumpcap's pcapng output, written byte for byte. Each segment starts with the section and interface headers copied verbatim, so it opens on its own. |
+| `captures/<session>/original.pcap[ng]` (import) | **Original as received**. The uploaded file, unchanged. |
+| SHA-256 per segment | Computed while writing, and over the whole file for imports. Stored in SQLite. |
+| Packet summary rows (SQLite) | Derived: tshark output, regenerable |
+| Protocol trees, filters, exports with a filter | Derived. A filtered export copies the original packet records verbatim, but as a selection it is a new file. |
+
+PiLens never labels reconstructed or synthetic data as an original capture.
+
+## Recorded metadata (per session)
+
+Session `meta` and the manifest record:
+
+- UTC start/stop (milliseconds), capture interfaces and capture filter
+- PiLens and TShark versions, hostname
+- `clock_synchronised` from `timedatectl` at start. If this is not `yes`,
+  absolute timestamps may be wrong. A Pi has no battery-backed clock, so make
+  sure NTP is working before you capture evidence.
+- Segment size, ring-buffer setting, pause/resume log, packets discarded while
+  paused
+- dumpcap's own "received/dropped" report, verbatim (kernel and pcap drops)
+
+## Verifying
+
+- UI: Capture Library → *Integrity* → *Verify hashes now*. This recomputes
+  SHA-256 for every complete segment.
+- Manifest: *Download manifest* gives JSON with every file, its hash, packet
+  count and the metadata above.
+- Offline: `sha256sum seg-*.pcapng` and compare with the manifest.
+
+## Caveats
+
+- **Capture loss** happens under load. Check the drop report. A capture with
+  drops is incomplete.
+- **Segment boundaries**: summaries and dissections are computed per segment,
+  so TCP stream indices and reassembly restart at each boundary. The packet
+  bytes are unaffected.
+- **Interrupted captures** (power loss): on restart, the last segment is
+  scanned, counted and hashed as found, and the session is marked
+  `interrupted`. A truncated final packet record may be present.
+- **Pause capture** discards packets while paused. The pause log in the
+  session metadata records when.
+- **Randomised MAC addresses** do not identify hardware. PiLens never merges
+  device identities automatically.
+- DNS answers do not prove which host a later connection went to.