6325e86873
README.md (700 lines): - Three-tier deployment model with ASCII diagram - Federation blueprint in web UI routes - deploy/ directory in architecture tree - Documentation index linking all guides CLAUDE.md (256 lines): - Updated architecture tree with all new docs and deploy files New guides: - docs/federation.md (317 lines) — gossip protocol mechanics, peer setup, trust filtering, offline bundles, relay deployment, jurisdiction - docs/evidence-guide.md (283 lines) — evidence packages, cold archives, selective disclosure, chain anchoring, legal discovery workflow - docs/source-dropbox.md (220 lines) — token management, client-side hashing, extract-then-strip pipeline, receipt mechanics, opsec - docs/index.md — documentation hub linking all guides Training materials: - docs/training/reporter-quickstart.md (105 lines) — printable one-page card: boot USB, attest photo, encode message, check-in, emergency - docs/training/emergency-card.md (79 lines) — wallet-sized laminated card: three destruction methods, 10-step order, key contacts - docs/training/admin-reference.md (219 lines) — deployment tiers, CLI tables, backup checklist, hardening checklist, troubleshooting Also includes existing architecture docs from the original repos. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
264 lines
8.6 KiB
Markdown
264 lines
8.6 KiB
Markdown
# SooSeF Reporter Field Guide
|
|
|
|
**Audience**: Reporters, field researchers, and documentarians using SooSeF to protect
|
|
and verify their work. No technical background required.
|
|
|
|
**Prerequisites**: A working SooSeF instance (Tier 1 USB or web UI access to a Tier 2
|
|
server). Your IT admin should have set this up for you.
|
|
|
|
---
|
|
|
|
## What SooSeF Does For You
|
|
|
|
SooSeF 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, SooSeF
|
|
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**
|
|
|
|
SooSeF 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
|
|
$ soosef 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
|
|
$ soosef attest batch ./field-photos/ --caption "Site visit 2026-04-01"
|
|
```
|
|
|
|
### Checking Your Status
|
|
|
|
Run `soosef 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
|
|
$ soosef 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 SooSeF which platform. The
|
|
app will recompress images, so SooSeF needs to use a survival-resistant encoding:
|
|
|
|
```bash
|
|
$ soosef stego encode photo.jpg -r shared.jpg -m "Safe house confirmed" --transport whatsapp
|
|
$ soosef stego encode photo.jpg -r shared.jpg -m "Safe house confirmed" --transport signal
|
|
$ soosef stego encode photo.jpg -r shared.jpg -m "Safe house confirmed" --transport telegram
|
|
```
|
|
|
|
> **Warning**: Never reuse the same carrier image twice. SooSeF will warn you if you
|
|
> do. Comparing two versions of the same image trivially reveals steganographic changes.
|
|
|
|
### Decoding a Message
|
|
|
|
```bash
|
|
$ soosef 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, SooSeF 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
|
|
$ soosef 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
|
|
$ soosef 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 SooSeF
|
|
8. Python bytecache and pip metadata (to hide that SooSeF was installed)
|
|
9. The SooSeF 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. SooSeF will remind you if your backup is overdue.
|
|
|
|
### Creating a Backup
|
|
|
|
```bash
|
|
$ soosef keys export -o /media/usb/soosef-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 SooSeF device.
|
|
|
|
### Restoring From Backup
|
|
|
|
On a fresh SooSeF instance:
|
|
|
|
```bash
|
|
$ soosef init
|
|
$ soosef keys import -b /media/usb/soosef-backup.enc
|
|
```
|
|
|
|
---
|
|
|
|
## Evidence Packages
|
|
|
|
When you need to hand evidence to a lawyer, a court, or a partner organization that does
|
|
not use SooSeF:
|
|
|
|
1. Go to the web UI or use the CLI to create an evidence package
|
|
2. Select the photos to include
|
|
3. SooSeF 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 SooSeF.
|
|
|
|
---
|
|
|
|
## 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
|
|
(`soosef 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 SooSeF by name** in environments where your communications may be
|
|
monitored. If `cover_name` is configured, the tool presents itself under that name.
|