490f9d4a1d
Complete project rebrand for better positioning in the press freedom and digital security space. FieldWitness communicates both field deployment and evidence testimony — appropriate for the target audience of journalists, NGOs, and human rights organizations. Rename mapping: - soosef → fieldwitness (package, CLI, all imports) - soosef.stegasoo → fieldwitness.stego - soosef.verisoo → fieldwitness.attest - ~/.soosef/ → ~/.fwmetadata/ (innocuous data dir name) - SOOSEF_DATA_DIR → FIELDWITNESS_DATA_DIR - SoosefConfig → FieldWitnessConfig - SoosefError → FieldWitnessError Also includes: - License switch from MIT to GPL-3.0 - C2PA bridge module (Phase 0-2 MVP): cert.py, export.py, vendor_assertions.py - README repositioned to lead with provenance/federation, stego backgrounded - Threat model skeleton at docs/security/threat-model.md - Planning docs: docs/planning/c2pa-integration.md, docs/planning/gtm-feasibility.md Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
264 lines
8.8 KiB
Markdown
264 lines
8.8 KiB
Markdown
# FieldWitness Reporter Field Guide
|
|
|
|
**Audience**: Reporters, field researchers, and documentarians using FieldWitness to protect
|
|
and verify their work. No technical background required.
|
|
|
|
**Prerequisites**: A working FieldWitness instance (Tier 1 USB or web UI access to a Tier 2
|
|
server). Your IT admin should have set this up for you.
|
|
|
|
---
|
|
|
|
## What FieldWitness Does For You
|
|
|
|
FieldWitness helps you do three things:
|
|
|
|
1. **Prove your photos and files are authentic** -- every photo you attest gets a
|
|
cryptographic signature that proves you took it, when, and that it has not been
|
|
tampered with since.
|
|
2. **Hide messages in images** -- send encrypted messages that look like ordinary photos.
|
|
3. **Destroy everything if compromised** -- if your device is about to be seized, FieldWitness
|
|
can erase all evidence of itself and your data in seconds.
|
|
|
|
---
|
|
|
|
## Daily Workflow
|
|
|
|
### Attesting Photos
|
|
|
|
After taking photos in the field, attest them as soon as possible. Attestation creates a
|
|
permanent, tamper-evident record.
|
|
|
|
**Through the web UI:**
|
|
|
|
1. Open Firefox (on Tier 1 USB, it opens automatically)
|
|
2. Go to the **Attest** page
|
|
3. Upload one or more photos
|
|
4. Add a caption describing what the photo shows (optional but recommended)
|
|
5. Add a location if relevant (optional)
|
|
6. Click **Attest**
|
|
|
|
FieldWitness will:
|
|
- Extract GPS coordinates and timestamp from the photo's EXIF data (for the provenance record)
|
|
- Strip device-identifying information (serial numbers, firmware version) from the stored copy
|
|
- Sign the photo with your Ed25519 identity key
|
|
- Add the attestation to the hash chain
|
|
|
|
**Through the CLI (if available):**
|
|
|
|
```bash
|
|
$ fieldwitness attest IMAGE photo.jpg --caption "Market protest, central square"
|
|
```
|
|
|
|
> **Warning**: Attest the original, unedited photo. If you crop, filter, or resize
|
|
> first, the attestation will not match the original file. Attest first, edit later.
|
|
|
|
### Batch Attestation
|
|
|
|
If you have a folder of photos from a field visit:
|
|
|
|
```bash
|
|
$ fieldwitness attest batch ./field-photos/ --caption "Site visit 2026-04-01"
|
|
```
|
|
|
|
### Checking Your Status
|
|
|
|
Run `fieldwitness status` or visit the web UI home page to see:
|
|
- Whether your identity key is set up
|
|
- How many attestations you have
|
|
- Whether your dead man's switch needs a check-in
|
|
- Whether your backup is overdue
|
|
|
|
---
|
|
|
|
## Sending Hidden Messages (Steganography)
|
|
|
|
Steganography hides an encrypted message inside an ordinary-looking image. To anyone who
|
|
does not have the decryption credentials, the image looks completely normal.
|
|
|
|
### What You Need
|
|
|
|
Both you and the recipient must have:
|
|
1. **A reference photo** -- the same image file, shared beforehand
|
|
2. **A passphrase** -- at least 4 words, agreed in person
|
|
3. **A PIN** -- 6 to 9 digits, agreed in person
|
|
|
|
All three are required to encode or decode. Share them in person, never over email or SMS.
|
|
|
|
### Encoding a Message
|
|
|
|
**Web UI:** Go to **Encode**, upload your carrier image and reference photo, enter your
|
|
message, passphrase, and PIN.
|
|
|
|
**CLI:**
|
|
|
|
```bash
|
|
$ fieldwitness stego encode vacation.jpg -r shared_photo.jpg -m "Meeting moved to Thursday"
|
|
# Passphrase: (enter your passphrase, hidden)
|
|
# PIN: (enter your PIN, hidden)
|
|
```
|
|
|
|
The output is a normal-looking image file that contains your hidden message.
|
|
|
|
### Transport-Aware Encoding
|
|
|
|
If you are sending the image through a messaging app, tell FieldWitness which platform. The
|
|
app will recompress images, so FieldWitness needs to use a survival-resistant encoding:
|
|
|
|
```bash
|
|
$ fieldwitness stego encode photo.jpg -r shared.jpg -m "Safe house confirmed" --transport whatsapp
|
|
$ fieldwitness stego encode photo.jpg -r shared.jpg -m "Safe house confirmed" --transport signal
|
|
$ fieldwitness stego encode photo.jpg -r shared.jpg -m "Safe house confirmed" --transport telegram
|
|
```
|
|
|
|
> **Warning**: Never reuse the same carrier image twice. FieldWitness will warn you if you
|
|
> do. Comparing two versions of the same image trivially reveals steganographic changes.
|
|
|
|
### Decoding a Message
|
|
|
|
```bash
|
|
$ fieldwitness stego decode received_image.jpg -r shared_photo.jpg
|
|
# Passphrase: (same passphrase)
|
|
# PIN: (same PIN)
|
|
```
|
|
|
|
---
|
|
|
|
## Check-In (Dead Man's Switch)
|
|
|
|
If your admin has enabled the dead man's switch, you must check in regularly. If you miss
|
|
your check-in window, FieldWitness assumes something has gone wrong and will eventually destroy
|
|
all data to protect you.
|
|
|
|
**Check in through the web UI:** Visit the **Fieldkit** page and click **Check In**.
|
|
|
|
**Check in through the CLI:**
|
|
|
|
```bash
|
|
$ fieldwitness fieldkit checkin
|
|
```
|
|
|
|
> **Warning**: If you will be unable to check in (traveling without the device, planned
|
|
> downtime), ask your admin to disarm the dead man's switch first. Forgetting to check in
|
|
> will trigger the killswitch and destroy all your data permanently.
|
|
|
|
---
|
|
|
|
## Emergency: Triggering the Killswitch
|
|
|
|
If your device is about to be seized or compromised:
|
|
|
|
**CLI:**
|
|
|
|
```bash
|
|
$ fieldwitness fieldkit purge --confirm CONFIRM-PURGE
|
|
```
|
|
|
|
**Web UI:** Visit the **Fieldkit** page and use the emergency purge button.
|
|
|
|
**Tier 1 USB:** Pull the USB stick from the laptop. The laptop retains nothing (it
|
|
was running from the USB). The USB stick is LUKS-encrypted and requires a passphrase to
|
|
access.
|
|
|
|
**Raspberry Pi with hardware button:** Hold the killswitch button for 5 seconds (default).
|
|
|
|
### What gets destroyed
|
|
|
|
1. Your signing keys (without these, encrypted data is unrecoverable)
|
|
2. Your channel key
|
|
3. User accounts and session data
|
|
4. All attestation records and chain data
|
|
5. Temporary files and audit logs
|
|
6. Configuration
|
|
7. System log entries mentioning FieldWitness
|
|
8. Python bytecache and pip metadata (to hide that FieldWitness was installed)
|
|
9. The FieldWitness package itself
|
|
|
|
> **Warning**: This is irreversible. Make sure you have recent backups stored
|
|
> separately before relying on the killswitch. See "Backups" below.
|
|
|
|
---
|
|
|
|
## Backups
|
|
|
|
Back up your keys regularly. FieldWitness will remind you if your backup is overdue.
|
|
|
|
### Creating a Backup
|
|
|
|
```bash
|
|
$ fieldwitness keys export -o /media/usb/fieldwitness-backup.enc
|
|
```
|
|
|
|
You will be prompted for a passphrase. This creates an encrypted bundle containing your
|
|
identity key and channel key. Store the USB drive **in a different physical location**
|
|
from your FieldWitness device.
|
|
|
|
### Restoring From Backup
|
|
|
|
On a fresh FieldWitness instance:
|
|
|
|
```bash
|
|
$ fieldwitness init
|
|
$ fieldwitness keys import -b /media/usb/fieldwitness-backup.enc
|
|
```
|
|
|
|
---
|
|
|
|
## Evidence Packages
|
|
|
|
When you need to hand evidence to a lawyer, a court, or a partner organization that does
|
|
not use FieldWitness:
|
|
|
|
1. Go to the web UI or use the CLI to create an evidence package
|
|
2. Select the photos to include
|
|
3. FieldWitness creates a ZIP file containing:
|
|
- Your original photos
|
|
- Attestation records with signatures
|
|
- The chain segment proving order and integrity
|
|
- Your public key
|
|
- A standalone verification script
|
|
- A README with instructions
|
|
|
|
The recipient can verify the evidence using only Python -- they do not need FieldWitness.
|
|
|
|
---
|
|
|
|
## What To Do If...
|
|
|
|
**Your device is seized**: If you did not trigger the killswitch in time, assume all
|
|
local data is compromised. Any attestation bundles you previously sent to your
|
|
organization (Tier 2) or federated to relays (Tier 3) are safe and contain your full
|
|
chain. Contact your organization's IT team.
|
|
|
|
**You lose your USB stick**: The USB is LUKS-encrypted, so the finder cannot read it
|
|
without your passphrase. Restore from your backup on a new USB stick. All attestations
|
|
that were already synced to Tier 2/3 are safe.
|
|
|
|
**You forget your stego passphrase or PIN**: There is no recovery. The message is
|
|
encrypted with keys derived from the passphrase, PIN, and reference photo. If you lose
|
|
any of the three, the message cannot be recovered.
|
|
|
|
**You need to share evidence with a court**: Use selective disclosure
|
|
(`fieldwitness chain disclose`) to produce a proof that includes only the specific records
|
|
requested. The court can verify these records are part of an authentic, unbroken chain
|
|
without seeing your other work.
|
|
|
|
**Your check-in is overdue**: Check in immediately. During the grace period, a warning
|
|
webhook fires (if configured) but data is not yet destroyed. After the grace period,
|
|
the killswitch fires automatically.
|
|
|
|
---
|
|
|
|
## Security Reminders
|
|
|
|
- **Attest photos immediately** after taking them. The sooner you attest, the smaller
|
|
the window during which someone could have tampered with the file.
|
|
- **Never send stego credentials over digital channels.** Share the reference photo,
|
|
passphrase, and PIN in person.
|
|
- **Never reuse carrier images** for steganography.
|
|
- **Check in on schedule** if the dead man's switch is armed.
|
|
- **Back up regularly** and store backups in a separate physical location.
|
|
- **Lock the browser** or close it when you walk away. Session timeouts help, but do not
|
|
rely on them.
|
|
- **Do not discuss FieldWitness by name** in environments where your communications may be
|
|
monitored. If `cover_name` is configured, the tool presents itself under that name.
|