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>
220 lines
7.5 KiB
Markdown
220 lines
7.5 KiB
Markdown
# Administrator Quick Reference
|
|
|
|
**Audience**: IT staff and technical leads responsible for deploying and maintaining
|
|
FieldWitness instances.
|
|
|
|
---
|
|
|
|
## Deployment Tiers
|
|
|
|
| Tier | Form Factor | Use Case | Key Feature |
|
|
|---|---|---|---|
|
|
| 1 -- Field Device | Bootable Debian Live USB | Reporter in the field | Amnesic, LUKS encrypted, pull USB = zero trace |
|
|
| 2 -- Org Server | Docker on mini PC or VPS | Newsroom / NGO office | Persistent, web UI + federation API |
|
|
| 3 -- Federation Relay | Docker on VPS | Friendly jurisdiction | Attestation sync only, zero knowledge of keys |
|
|
|
|
---
|
|
|
|
## Quick Deploy
|
|
|
|
### Tier 1: Build USB image
|
|
|
|
```bash
|
|
$ sudo apt install live-build
|
|
$ cd deploy/live-usb
|
|
$ sudo ./build.sh
|
|
$ sudo dd if=live-image-amd64.hybrid.iso of=/dev/sdX bs=4M status=progress
|
|
```
|
|
|
|
### Tier 2: Docker org server
|
|
|
|
```bash
|
|
$ cd deploy/docker
|
|
$ docker compose up server -d
|
|
```
|
|
|
|
Exposes port 5000 (web UI) and port 8000 (federation API).
|
|
|
|
### Tier 3: Docker federation relay
|
|
|
|
```bash
|
|
$ cd deploy/docker
|
|
$ docker compose up relay -d
|
|
```
|
|
|
|
Exposes port 8001 (federation API only).
|
|
|
|
### Kubernetes
|
|
|
|
```bash
|
|
$ docker build -t fieldwitness-server --target server -f deploy/docker/Dockerfile .
|
|
$ docker build -t fieldwitness-relay --target relay -f deploy/docker/Dockerfile .
|
|
$ kubectl apply -f deploy/kubernetes/namespace.yaml
|
|
$ kubectl apply -f deploy/kubernetes/server-deployment.yaml
|
|
$ kubectl apply -f deploy/kubernetes/relay-deployment.yaml
|
|
```
|
|
|
|
Single-replica only. FieldWitness uses SQLite -- do not scale horizontally.
|
|
|
|
---
|
|
|
|
## Threat Level Presets
|
|
|
|
Copy the appropriate preset to configure FieldWitness for the operational environment:
|
|
|
|
```bash
|
|
$ cp deploy/config-presets/<level>-threat.json ~/.fwmetadata/config.json
|
|
```
|
|
|
|
| Level | Session | Killswitch | Dead Man | Cover Name |
|
|
|---|---|---|---|---|
|
|
| `low-threat` | 30 min | Off | Off | None |
|
|
| `medium-threat` | 15 min | On | 48h / 4h grace | "Office Document Manager" |
|
|
| `high-threat` | 5 min | On | 12h / 1h grace | "Local Inventory Tracker" |
|
|
| `critical-threat` | 3 min | On | 6h / 1h grace | "System Statistics" |
|
|
|
|
---
|
|
|
|
## Essential CLI Commands
|
|
|
|
### System
|
|
|
|
| Command | Description |
|
|
|---|---|
|
|
| `fieldwitness init` | Create directory structure, generate keys, write default config |
|
|
| `fieldwitness serve --host 0.0.0.0` | Start web UI (LAN-accessible) |
|
|
| `fieldwitness status` | Pre-flight check: keys, chain, deadman, backup, geofence |
|
|
| `fieldwitness status --json` | Machine-readable status output |
|
|
|
|
### Keys
|
|
|
|
| Command | Description |
|
|
|---|---|
|
|
| `fieldwitness keys show` | Display current key info and fingerprints |
|
|
| `fieldwitness keys export -o backup.enc` | Export encrypted key bundle |
|
|
| `fieldwitness keys import -b backup.enc` | Import key bundle from backup |
|
|
| `fieldwitness keys rotate-identity` | Rotate Ed25519 identity (records in chain) |
|
|
| `fieldwitness keys rotate-channel` | Rotate AES-256-GCM channel key |
|
|
| `fieldwitness keys trust --import pubkey.pem` | Trust a collaborator's public key |
|
|
|
|
### Fieldkit
|
|
|
|
| Command | Description |
|
|
|---|---|
|
|
| `fieldwitness fieldkit status` | Show fieldkit state (deadman, geofence, USB, tamper) |
|
|
| `fieldwitness fieldkit checkin` | Reset dead man's switch timer |
|
|
| `fieldwitness fieldkit check-deadman` | Check if deadman timer expired (for cron) |
|
|
| `fieldwitness fieldkit purge --confirm CONFIRM-PURGE` | Activate killswitch |
|
|
| `fieldwitness fieldkit geofence set --lat X --lon Y --radius M` | Set GPS boundary |
|
|
| `fieldwitness fieldkit usb snapshot` | Record USB whitelist baseline |
|
|
| `fieldwitness fieldkit tamper baseline` | Record file integrity baseline |
|
|
|
|
### Chain and Evidence
|
|
|
|
| Command | Description |
|
|
|---|---|
|
|
| `fieldwitness chain status` | Show chain head, length, integrity |
|
|
| `fieldwitness chain verify` | Verify full chain (hashes + signatures) |
|
|
| `fieldwitness chain log --count 20` | Show recent chain entries |
|
|
| `fieldwitness chain export -o bundle.zip` | Export attestation bundle |
|
|
| `fieldwitness chain disclose -i 5,12,47 -o disclosure.json` | Selective disclosure |
|
|
| `fieldwitness chain anchor` | Manual anchor (prints hash for external witness) |
|
|
| `fieldwitness chain anchor --tsa https://freetsa.org/tsr` | RFC 3161 automated anchor |
|
|
|
|
---
|
|
|
|
## User Management
|
|
|
|
The web UI admin panel at `/admin` provides:
|
|
|
|
- Create user accounts
|
|
- Delete user accounts
|
|
- Reset passwords (temporary password issued)
|
|
- View active sessions
|
|
|
|
User credentials are stored in SQLite at `~/.fwmetadata/auth/fieldwitness.db`.
|
|
|
|
---
|
|
|
|
## Backup Checklist
|
|
|
|
| What | How often | Command |
|
|
|---|---|---|
|
|
| Key bundle | After every rotation, weekly minimum | `fieldwitness keys export -o backup.enc` |
|
|
| Cold archive | Weekly or before travel | `fieldwitness archive export --include-keys -o archive.zip` |
|
|
| Docker volume | Before updates | `docker compose stop server && docker run --rm -v server-data:/data -v /backup:/backup busybox tar czf /backup/fieldwitness-$(date +%Y%m%d).tar.gz -C /data .` |
|
|
|
|
Store backups on separate physical media. Keep one copy offsite.
|
|
|
|
---
|
|
|
|
## Federation Setup
|
|
|
|
1. Exchange public keys between organizations (verify fingerprints out-of-band)
|
|
2. Import collaborator keys: `fieldwitness keys trust --import /path/to/pubkey.pem`
|
|
3. Register peers via web UI at `/federation` or via CLI
|
|
4. Gossip starts automatically; monitor at `/federation`
|
|
|
|
For airgapped federation: `fieldwitness chain export` to USB, carry to partner, import there.
|
|
|
|
---
|
|
|
|
## Source Drop Box
|
|
|
|
1. Navigate to `/dropbox/admin` (admin login required)
|
|
2. Create a token with label, expiry, and file limit
|
|
3. Share the generated URL with the source over a secure channel
|
|
4. Monitor submissions at `/dropbox/admin`
|
|
5. Revoke tokens when no longer needed
|
|
|
|
---
|
|
|
|
## Hardening Checklist
|
|
|
|
- [ ] Disable or encrypt swap (`swapoff -a` or dm-crypt random-key swap)
|
|
- [ ] Disable core dumps (`echo "* hard core 0" >> /etc/security/limits.conf`)
|
|
- [ ] Configure firewall (UFW: allow 5000, 8000; deny all other incoming)
|
|
- [ ] Disable unnecessary services (bluetooth, avahi-daemon)
|
|
- [ ] Apply a threat level preset appropriate for the environment
|
|
- [ ] Set `cover_name` in config if operating under cover
|
|
- [ ] Set `FIELDWITNESS_DATA_DIR` to an inconspicuous path if needed
|
|
- [ ] Enable HTTPS (default) or place behind a reverse proxy with TLS
|
|
- [ ] Create systemd service for bare metal (see `docs/deployment.md` Section 7)
|
|
- [ ] Set up regular backups (key bundle + cold archive)
|
|
- [ ] Arm dead man's switch if appropriate for threat level
|
|
- [ ] Take initial USB whitelist snapshot
|
|
- [ ] Record tamper baseline
|
|
|
|
---
|
|
|
|
## Troubleshooting Quick Fixes
|
|
|
|
| Symptom | Check |
|
|
|---|---|
|
|
| Web UI unreachable from LAN | `host` must be `0.0.0.0`, not `127.0.0.1`. Check firewall. |
|
|
| Docker container exits | `docker compose logs server` -- check for port conflict or volume permissions |
|
|
| Dead man fires unexpectedly | Service crashed and exceeded interval+grace. Ensure `Restart=on-failure`. |
|
|
| Permission errors on `~/.fwmetadata/` | Run FieldWitness as the same user who ran `fieldwitness init` |
|
|
| Drop box tokens expire immediately | System clock wrong. Run `date -u` and fix if needed. |
|
|
| Chain anchor TSA fails | Requires network. Use manual anchor on airgapped devices. |
|
|
| Account locked out | Wait for lockout to expire, or restart the server. |
|
|
| SSL cert shows wrong name | Delete `~/.fwmetadata/certs/cert.pem`, set `cover_name`, restart. |
|
|
|
|
---
|
|
|
|
## Health Checks
|
|
|
|
```bash
|
|
# Web UI
|
|
$ curl -k https://127.0.0.1:5000/health
|
|
|
|
# Federation API (Tier 2)
|
|
$ curl http://localhost:8000/health
|
|
|
|
# Relay (Tier 3)
|
|
$ curl http://localhost:8001/health
|
|
|
|
# Full system status
|
|
$ fieldwitness status --json
|
|
```
|