# Source Drop Box Setup Guide **Audience**: Administrators setting up FieldWitness's anonymous source intake feature. **Prerequisites**: A running FieldWitness instance with web UI enabled (`fieldwitness[web]` extra), an admin account, and HTTPS configured (self-signed is acceptable). --- ## Overview The source drop box is a SecureDrop-style anonymous file intake built into the FieldWitness web UI. Admins create time-limited upload tokens, sources open the token URL in a browser and submit files without creating an account. Files are processed through the extract-then-strip EXIF pipeline and automatically attested on receipt. Sources receive HMAC-derived receipt codes that prove delivery. > **Warning:** The drop box protects source identity through design -- no accounts, no > branding, no IP logging. However, the security of the system depends on how the upload URL > is shared. Never send drop box URLs over unencrypted email or SMS. --- ## How It Works ``` Admin Source FieldWitness Server | | | |-- Create token ------------->| | | (label, expiry, max_files) | | | | | |-- Share URL (secure channel) | | | | | | |-- Open URL in browser --------->| | | (no login required) | | | | | |-- Select files | | | Browser computes SHA-256 | | | (SubtleCrypto, client-side) | | | | | |-- Upload files ---------------->| | | |-- Extract EXIF | | |-- Strip metadata | | |-- Attest originals | | |-- Save stripped copy | | | | |<-- Receipt codes ---------------| | | (HMAC of file hash + token) | ``` --- ## Setting Up the Drop Box ### Step 1: Ensure HTTPS is enabled The drop box should always be served over HTTPS. Sources must be able to trust that their connection is not being intercepted. ```bash $ fieldwitness serve --host 0.0.0.0 ``` FieldWitness auto-generates a self-signed certificate on first HTTPS start. For production use, place a reverse proxy with a proper TLS certificate in front of FieldWitness. ### Step 2: Create an upload token Navigate to `/dropbox/admin` in the web UI (admin login required), or use the admin panel. Each token has: | Field | Default | Description | |---|---|---| | **Label** | "Unnamed source" | Human-readable name for the source (stored server-side only, never shown to the source) | | **Expiry** | 24 hours | How long the upload link remains valid | | **Max files** | 10 | Maximum number of uploads allowed on this link | After creating the token, the admin receives a URL of the form: ``` https://:/dropbox/upload/ ``` The token is a 32-byte cryptographically random URL-safe string. ### Step 3: Share the URL with the source Share the upload URL over an already-secure channel: - **Best**: in person, on paper - **Good**: encrypted messaging (Signal, Wire) - **Acceptable**: verbal dictation over a secure voice call - **Never**: unencrypted email, SMS, or any channel that could be intercepted ### Step 4: Source uploads files The source opens the URL in their browser. The upload page is minimal -- no FieldWitness branding, no identifying marks, generic styling. The page works over Tor Browser with JavaScript enabled (no external resources, no CDN, no fonts, no analytics). When files are selected: 1. The browser computes SHA-256 fingerprints client-side using SubtleCrypto 2. The source sees the fingerprints and is prompted to save them before uploading 3. On upload, the server processes each file through the extract-then-strip pipeline 4. The source receives receipt codes for each file ### Step 5: Monitor submissions The admin panel at `/dropbox/admin` shows: - Active tokens with their usage counts - Token expiry times - Ability to revoke tokens immediately --- ## The Extract-Then-Strip Pipeline Every file uploaded through the drop box is processed through FieldWitness's EXIF pipeline: 1. **Extract**: all EXIF metadata is read from the original image bytes 2. **Classify**: fields are split into evidentiary (GPS coordinates, capture timestamp -- valuable for provenance) and dangerous (device serial number, firmware version -- could identify the source's device) 3. **Attest**: the original bytes are attested (Ed25519 signed) with evidentiary metadata included in the attestation record. The attestation hash matches what the source actually submitted. 4. **Strip**: all metadata is removed from the stored copy. The stripped copy is saved to disk. No device fingerprint persists on the server's storage. This resolves the tension between protecting the source (strip device-identifying metadata) and preserving evidence (retain GPS and timestamp for provenance). --- ## Receipt Codes Each uploaded file generates an HMAC-derived receipt code: ``` receipt_code = HMAC-SHA256(token, file_sha256)[:16] ``` The receipt code proves: - The server received the specific file (tied to the file's SHA-256) - The file was received under the specific token (tied to the token value) Sources can verify their receipt by posting it to `/dropbox/verify-receipt`. This returns the filename, SHA-256, and reception timestamp if the receipt is valid. > **Note:** Receipt codes are deterministic. The source can compute the expected receipt > themselves if they know the token value and the file's SHA-256 hash, providing > independent verification. --- ## Client-Side SHA-256 The upload page computes SHA-256 fingerprints in the browser before upload using the SubtleCrypto Web API. This gives the source a verifiable record of exactly what they submitted -- the hash is computed on their device, not the server. The source should save these fingerprints before uploading. If the server later claims to have received different content, the source can prove what they actually submitted by comparing their locally computed hash with the server's receipt. --- ## Storage | What | Where | |---|---| | Uploaded files (stripped) | `~/.fwmetadata/temp/dropbox/` (mode 0700) | | Token metadata | `~/.fwmetadata/auth/dropbox.db` (SQLite) | | Receipt codes | `~/.fwmetadata/auth/dropbox.db` (SQLite) | | Attestation records | `~/.fwmetadata/attestations/` (standard attestation log) | Expired tokens are cleaned up automatically on every admin page load. --- ## Operational Security ### Source safety - **No FieldWitness branding** on the upload page. Generic "Secure File Upload" title. - **No authentication required** -- sources never create accounts or reveal identity. - **No IP logging** -- FieldWitness does not log source IP addresses. Ensure your reverse proxy (if any) also does not log access requests to `/dropbox/upload/` paths. - **Self-contained page** -- inline CSS and JavaScript only. No external resources, CDN calls, web fonts, or analytics. Works with Tor Browser. - **CSRF exempt** -- the upload endpoint does not require CSRF tokens because sources do not have sessions. ### Token management - **Short expiry** -- set token expiry as short as practical. 24 hours is the default; for high-risk sources, consider 1-4 hours. - **Low file limits** -- set `max_files` to the expected number of submissions. Once reached, the link stops accepting uploads. - **Revoke immediately** -- if a token is compromised or no longer needed, revoke it from the admin panel. This deletes the token and all associated receipt records from SQLite. - **Audit trail** -- token creation events are logged to `~/.fwmetadata/audit.jsonl` with the action `dropbox.token_created`. ### Running as a Tor hidden service FieldWitness has built-in support for exposing the drop box as a Tor hidden service (a `.onion` address). When a source accesses the drop box over Tor, the server never sees their real IP address -- Tor's onion routing ensures that only the Tor network knows both the source and the destination. #### Step 1: Install and configure Tor ```bash # Debian / Ubuntu sudo apt install tor # macOS (Homebrew) brew install tor # Fedora / RHEL sudo dnf install tor ``` Enable the control port so FieldWitness can manage the hidden service. Add these lines to `/etc/tor/torrc`: ``` ControlPort 9051 CookieAuthentication 1 ``` Then restart Tor: ```bash sudo systemctl restart tor ``` **Authentication note:** `CookieAuthentication 1` lets FieldWitness authenticate using the cookie file that Tor creates automatically. Alternatively, use a password: ``` ControlPort 9051 HashedControlPassword ``` #### Step 2: Install the stem library stem is an optional FieldWitness dependency. Install it alongside the fieldkit extra: ```bash pip install 'fieldwitness[tor]' # or, if already installed: pip install stem>=1.8.0 ``` #### Step 3: Start FieldWitness with --tor ```bash fieldwitness serve --host 127.0.0.1 --port 5000 --tor ``` With a custom control port or password: ```bash fieldwitness serve --tor --tor-control-port 9051 --tor-password yourpassword ``` For a one-off intake session where a fixed address is not needed: ```bash fieldwitness serve --tor --tor-transient ``` On startup, FieldWitness will print the `.onion` address: ``` ============================================================ TOR HIDDEN SERVICE ACTIVE ============================================================ .onion address : abc123def456ghi789jkl012mno345pq.onion Drop box URL : http://abc123def456ghi789jkl012mno345pq.onion/dropbox/upload/ Persistent : yes (key saved to ~/.fwmetadata/fieldkit/tor/) ============================================================ Sources must use Tor Browser to access the .onion URL. Share the drop box upload URL over a secure channel (Signal, in person). ============================================================ ``` #### Step 4: Share the .onion drop box URL Create a drop box token as usual (see Step 2 above), then construct the `.onion` upload URL: ``` http:///dropbox/upload/ ``` Share this URL with the source over Signal or in person. The source opens it in **Tor Browser** -- not in a regular browser. #### Persistent vs. transient hidden services | Mode | Command | Behaviour | |---|---|---| | **Persistent** (default) | `--tor` | Same `.onion` address on every restart. Key stored at `~/.fwmetadata/fieldkit/tor/hidden_service/`. | | **Transient** | `--tor --tor-transient` | New `.onion` address each run. No key written to disk. | Use persistent mode when you want sources to bookmark the address or share it in advance. Use transient mode for single-session intake where address continuity does not matter. #### Source instructions Tell sources: 1. Install **Tor Browser** from [torproject.org](https://www.torproject.org/download/). 2. Open Tor Browser and paste the full `.onion` URL into the address bar. 3. Do not open the `.onion` URL in a regular browser -- your real IP will be visible. 4. JavaScript must be enabled for the SHA-256 fingerprint feature to work. Set the Security Level to "Standard" in Tor Browser (shield icon in the toolbar). 5. Save the SHA-256 fingerprints shown before clicking Upload. 6. Save the receipt codes shown after upload. #### Logging and access logs Even with Tor, access logs on the server can record that *someone* connected -- the connection appears to come from a Tor exit relay (for regular Tor) or from a Tor internal address (for hidden services). For hidden services, the server sees no IP at all; the connection comes from the Tor daemon on localhost. **Recommendation:** Set the web server or reverse proxy to not log access requests to `/dropbox/upload/` paths. If using FieldWitness directly (Waitress), access log output goes to stdout; redirect it to `/dev/null` or omit the log handler. #### Killswitch and the hidden service key The persistent hidden service key is stored under `~/.fwmetadata/fieldkit/tor/hidden_service/` and is treated as key material. The FieldWitness killswitch (`fieldwitness fieldkit purge`) destroys this directory during both `KEYS_ONLY` and `ALL` purge scopes. After a purge, the `.onion` address cannot be linked to the operator even if the server hardware is seized. > **Warning:** Even with Tor, timing analysis and traffic correlation attacks are possible > at the network level. The drop box protects source identity at the application layer; > network-layer protection requires operational discipline beyond what software can provide. > Tor is not a silver bullet -- but it removes the most direct risk (IP address exposure) > that limitation L7 in the threat model describes.