alee/fieldwitness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
e4f68fc83a
fieldwitness/docs/training/admin-reference.md
Aaron D. Lee 490f9d4a1d Rebrand SooSeF to FieldWitness 
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>
2026-04-02 15:05:13 -04:00

220 lines
7.5 KiB
Markdown
Raw Blame History

# 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
```
Reference in New Issue View Git Blame Copy Permalink