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>
220 lines
7.2 KiB
Markdown
220 lines
7.2 KiB
Markdown
# Administrator Quick Reference
|
|
|
|
**Audience**: IT staff and technical leads responsible for deploying and maintaining
|
|
SooSeF 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 soosef-server --target server -f deploy/docker/Dockerfile .
|
|
$ docker build -t soosef-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. SooSeF uses SQLite -- do not scale horizontally.
|
|
|
|
---
|
|
|
|
## Threat Level Presets
|
|
|
|
Copy the appropriate preset to configure SooSeF for the operational environment:
|
|
|
|
```bash
|
|
$ cp deploy/config-presets/<level>-threat.json ~/.soosef/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 |
|
|
|---|---|
|
|
| `soosef init` | Create directory structure, generate keys, write default config |
|
|
| `soosef serve --host 0.0.0.0` | Start web UI (LAN-accessible) |
|
|
| `soosef status` | Pre-flight check: keys, chain, deadman, backup, geofence |
|
|
| `soosef status --json` | Machine-readable status output |
|
|
|
|
### Keys
|
|
|
|
| Command | Description |
|
|
|---|---|
|
|
| `soosef keys show` | Display current key info and fingerprints |
|
|
| `soosef keys export -o backup.enc` | Export encrypted key bundle |
|
|
| `soosef keys import -b backup.enc` | Import key bundle from backup |
|
|
| `soosef keys rotate-identity` | Rotate Ed25519 identity (records in chain) |
|
|
| `soosef keys rotate-channel` | Rotate AES-256-GCM channel key |
|
|
| `soosef keys trust --import pubkey.pem` | Trust a collaborator's public key |
|
|
|
|
### Fieldkit
|
|
|
|
| Command | Description |
|
|
|---|---|
|
|
| `soosef fieldkit status` | Show fieldkit state (deadman, geofence, USB, tamper) |
|
|
| `soosef fieldkit checkin` | Reset dead man's switch timer |
|
|
| `soosef fieldkit check-deadman` | Check if deadman timer expired (for cron) |
|
|
| `soosef fieldkit purge --confirm CONFIRM-PURGE` | Activate killswitch |
|
|
| `soosef fieldkit geofence set --lat X --lon Y --radius M` | Set GPS boundary |
|
|
| `soosef fieldkit usb snapshot` | Record USB whitelist baseline |
|
|
| `soosef fieldkit tamper baseline` | Record file integrity baseline |
|
|
|
|
### Chain and Evidence
|
|
|
|
| Command | Description |
|
|
|---|---|
|
|
| `soosef chain status` | Show chain head, length, integrity |
|
|
| `soosef chain verify` | Verify full chain (hashes + signatures) |
|
|
| `soosef chain log --count 20` | Show recent chain entries |
|
|
| `soosef chain export -o bundle.zip` | Export attestation bundle |
|
|
| `soosef chain disclose -i 5,12,47 -o disclosure.json` | Selective disclosure |
|
|
| `soosef chain anchor` | Manual anchor (prints hash for external witness) |
|
|
| `soosef 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 `~/.soosef/auth/soosef.db`.
|
|
|
|
---
|
|
|
|
## Backup Checklist
|
|
|
|
| What | How often | Command |
|
|
|---|---|---|
|
|
| Key bundle | After every rotation, weekly minimum | `soosef keys export -o backup.enc` |
|
|
| Cold archive | Weekly or before travel | `soosef 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/soosef-$(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: `soosef 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: `soosef 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 `SOOSEF_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 `~/.soosef/` | Run SooSeF as the same user who ran `soosef 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 `~/.soosef/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
|
|
$ soosef status --json
|
|
```
|