88f5571bf9
Fix STEGASOO_* env vars → FIELDWITNESS_* and VERISOO_* → FIELDWITNESS_* across stego module, attest module, and frontends. Wire format identifiers (VERISOO\x00 magic bytes, STEGASOO-Z: QR prefixes) intentionally preserved for backwards compatibility. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
32 KiB
FieldWitness -- FieldWitness
Offline-first provenance attestation with gossip federation for journalists, NGOs, and at-risk organizations.
What is FieldWitness?
FieldWitness is a field-deployable evidence integrity system. It lets journalists, human rights documenters, and NGOs establish cryptographic chain-of-custody over photos, documents, and sensor data -- in airgapped environments, across organizational boundaries, and in adversarial conditions where data may need to be destroyed on demand.
The core claim: a file attested with FieldWitness can be handed to a court or partner organization with proof that it has not been altered, proof of when it was captured (anchored externally via RFC 3161), and proof of who held it -- without requiring the verifying party to install FieldWitness or trust any central authority.
Three-tier deployment model:
Tier 1: Field Device Tier 2: Org Server Tier 3: Federation Relay
(Bootable USB + laptop) (Docker on mini PC / VPS) (Docker on VPS)
Reporter in the field Newsroom / NGO office Friendly jurisdiction
Amnesic, LUKS-encrypted Persistent storage Attestation sync only
Pull USB = zero trace Web UI + federation API Zero knowledge of keys
\ | /
\_____ sneakernet ____+____ gossip API ____/
Stego (steganography, v4.3.0) and Attest (attestation, v0.1.0) are included as
subpackages (import fieldwitness.stego, import fieldwitness.attest). Everything ships as one
install: pip install fieldwitness.
Quick Start
pip install "fieldwitness[web,cli]"
fieldwitness init
fieldwitness serve
This creates the ~/.fwmetadata/ directory structure, generates an Ed25519 identity and
channel key, writes a default config, and starts an HTTPS web UI on
https://127.0.0.1:5000.
Features
Attestation and Provenance (Attest)
- Ed25519 digital signatures for images and arbitrary files (CSV, documents, sensor data)
- Perceptual hashing (pHash, dHash) for tamper-evident photo attestation -- identifies re-uploaded or re-compressed copies. SHA-256-only mode for non-image files
- Append-only hash chain (CBOR-encoded) with Merkle tree verification -- every attestation is chained to all prior attestations, making retroactive tampering detectable
- LMDB-backed attestation storage
- Batch attestation for directories
- Investigation namespaces -- tag and filter attestations by case or project
- Derived work lineage -- parent-child attestation tracking for editorial workflows
- Chain position proof -- verification receipts include the record's position in the hash chain
Extract-Then-Strip EXIF Pipeline
Resolves the tension between protecting sources (strip everything) and proving provenance (preserve everything):
- Extract all EXIF metadata from the original image bytes
- Classify fields as evidentiary (GPS coordinates, timestamp -- valuable for provenance) or dangerous (device serial number, firmware version -- could identify the source)
- Preserve evidentiary fields in the attestation record
- Strip all metadata from the stored/display copy
Gossip Federation
- Gossip protocol -- nodes periodically exchange Merkle roots with peers. Divergence triggers a consistency proof request and incremental record fetch. No central coordinator, no consensus, no leader election -- just append-only logs that converge
- Attestation exchange -- export signed bundles of attestation records and chain data for offline transfer (sneakernet) to partner organizations
- Delivery acknowledgments -- when an organization imports a bundle, a
fieldwitness/delivery-ack-v1chain record is signed and can be shared back, creating a two-way federation handshake - Trust store -- import collaborator Ed25519 public keys; only records signed by trusted keys are imported during federation
- Investigation filtering -- export/import only records tagged with a specific investigation
Evidence Packages
Self-contained ZIP bundles for handing evidence to lawyers, courts, or archives:
- Original images
- Attestation records with full Ed25519 signatures
- Chain segment with hash linkage
- Signer's public key
verify.py-- standalone verification script that requires only Python 3.11+ and thecryptographypip package (no FieldWitness installation needed)- Human-readable README
Cold Archive
Full-state export for long-term evidence preservation (10+ year horizon), aligned with OAIS (ISO 14721):
- Raw chain binary and state checkpoint
- Attestation log and LMDB index
- External timestamp anchors
- Public key and trusted collaborator keys
- Encrypted key bundle (optional, password-protected)
ALGORITHMS.txtdocumenting every cryptographic algorithm, parameter, and format usedverify.pystandalone verifiermanifest.jsonwith SHA-256 integrity hashes of key files
External Timestamp Anchoring
Two mechanisms to prove the chain head existed before a given time:
- RFC 3161 TSA -- automated submission to any RFC 3161 Timestamping Authority (e.g., FreeTSA). The signed timestamp token is saved alongside the chain
- Manual anchors -- export the chain head hash as a compact string for manual submission to any external witness (blockchain transaction, newspaper classified, email to a TSA)
A single anchor for the chain head implicitly timestamps every record that preceded it, because the chain is append-only with hash linkage.
Selective Disclosure
Produce verifiable proofs for specific chain records while keeping others redacted. Selected records are included in full; non-selected records appear only as hashes. A third party can verify that the disclosed records are part of an unbroken chain without seeing the contents of other records. Designed for legal discovery, court orders, and FOIA responses.
Field Security (Fieldkit)
- Killswitch -- emergency destruction of all data under
~/.fwmetadata/, ordered by sensitivity (keys first, then data, then logs). Includes:- Deep forensic scrub -- removes
__pycache__,.pyc, pipdist-info, pip download cache, and scrubs shell history entries containing "fieldwitness" - Self-uninstall -- runs
pip uninstall -y fieldwitnessas the final step - System log clearing -- best-effort journald vacuum on Linux
- Deep forensic scrub -- removes
- Dead man's switch -- automated purge if check-in is missed, with a configurable grace period. During the grace period, a webhook warning is sent (POST to a configured URL) and a local warning file is written before the killswitch fires
- Tamper detection -- file integrity monitoring with baseline snapshots
- USB whitelist -- block or alert on unauthorized USB devices (Linux/pyudev)
- Geofence -- GPS boundary enforcement with configurable radius. Supports live GPS via
gpsd (
get_current_location()connects to127.0.0.1:2947) - Hardware killswitch -- GPIO pin monitoring for Raspberry Pi physical button (configurable pin and hold duration)
Source Drop Box
SecureDrop-style anonymous intake built into the FieldWitness web UI:
- Admin creates a time-limited upload token with a configurable file limit
- Source opens the token URL (no account or FieldWitness branding -- source safety)
- Client-side SHA-256 via SubtleCrypto runs in the browser before upload, so the source can independently verify what they submitted
- Files are run through the extract-then-strip EXIF pipeline and auto-attested on receipt
- Source receives HMAC-derived receipt codes that prove delivery
- Tokens and receipts are stored in SQLite; tokens auto-expire
Key Rotation and Recovery
- Key rotation -- both identity (Ed25519) and channel (AES) keys can be rotated. The
chain records the rotation as a
fieldwitness/key-rotation-v1record signed by the OLD key, creating a cryptographic trust chain - Identity recovery -- after device loss, a new key can be introduced via a
fieldwitness/key-recovery-v1chain record. The record carries the old fingerprint and optional cosigner fingerprints for audit - Channel key only export -- share just the channel key (not identity keys) with
collaborators via encrypted file or QR code (
fieldwitness-channel:URI scheme) - Backup tracking -- records when the last backup was taken and warns when overdue
Cover / Duress Mode
- Configurable certificate CN -- set
cover_namein config to replace "FieldWitness Local" in the self-signed TLS certificate - Portable data directory -- set
FIELDWITNESS_DATA_DIRto relocate all state to an arbitrary path (e.g., an innocuously named directory on a USB stick). All paths resolve lazily fromBASE_DIR, so runtime overrides propagate correctly
Additional Tools: Steganography (Stego)
For situations requiring covert channels -- hiding communications or small payloads inside ordinary media files:
- LSB encoding -- bit-level message hiding in PNG images
- DCT encoding -- frequency-domain hiding in JPEG images (requires
stego-dctextra) - Audio steganography -- hide data in WAV/FLAC audio (requires
stego-audioextra) - Video steganography -- frame-level encoding
- Transport-aware encoding --
--transport whatsapp|signal|telegram|discord|email|directauto-selects the right encoding mode and carrier resolution for lossy messaging platforms. WhatsApp/Signal/Telegram force DCT/JPEG mode and pre-resize the carrier to survive recompression - Carrier reuse tracking -- warns when a carrier image has been used before, since comparing two versions of the same carrier trivially reveals steganographic modification
- AES-256-GCM encryption with Argon2id key derivation
- EXIF stripping on encode to prevent metadata leakage
- Compression support (zstandard, optional LZ4)
Installation
Basic install (core library only)
pip install fieldwitness
With extras
pip install "fieldwitness[web,cli]" # Web UI + CLI (most common)
pip install "fieldwitness[all]" # Everything except dev tools
pip install "fieldwitness[dev]" # All + pytest, black, ruff, mypy
Available extras
| Extra | What it adds |
|---|---|
stego-dct |
DCT steganography (numpy, scipy, jpeglib, reedsolo) |
stego-audio |
Audio steganography (pydub, soundfile, reedsolo) |
stego-compression |
LZ4 compression support |
attest |
Attestation features (imagehash, lmdb, exifread) |
cli |
Click CLI with rich output, QR code support, piexif |
web |
Flask web UI with Waitress/Gunicorn, pyzbar QR scanning, includes attest + stego-dct |
api |
FastAPI REST API with uvicorn, includes stego-dct |
fieldkit |
Tamper monitoring (watchdog) and USB whitelist (pyudev) |
federation |
Peer-to-peer attestation federation (aiohttp) |
rpi |
Raspberry Pi deployment (web + cli + fieldkit + gpiozero) |
all |
All of the above |
dev |
All + pytest, pytest-cov, black, ruff, mypy |
Airgapped install
Bundle wheels on a networked machine, then install offline:
# On networked machine
pip download "fieldwitness[web,cli]" -d ./wheels
# Transfer ./wheels to target via USB
# On airgapped machine
pip install --no-index --find-links=./wheels "fieldwitness[web,cli]"
fieldwitness init
fieldwitness serve --host 0.0.0.0
Deployment
FieldWitness uses a three-tier deployment model designed for field journalism, organizational evidence management, and cross-organization federation.
Tier 1 -- Field Device. A bootable Debian Live USB stick. Boots into a minimal desktop with Firefox pointed at the local FieldWitness web UI. LUKS-encrypted persistent partition. Pull the USB and the host machine retains nothing.
Tier 2 -- Org Server. A Docker deployment on a mini PC or trusted VPS. Runs the full web UI (port 5000) and federation API (port 8000). Manages keys, attestations, and federation sync.
Tier 3 -- Federation Relay. A lightweight Docker container in a jurisdiction with strong press protections. Relays attestation records between organizations. Stores only hashes and signatures -- never keys, plaintext, or original media.
Quick deploy
# Tier 1: Build USB image
cd deploy/live-usb && sudo ./build.sh
# Tier 2: Docker org server
cd deploy/docker && docker compose up server -d
# Tier 3: Docker federation relay
cd deploy/docker && docker compose up relay -d
Threat level configuration presets
FieldWitness ships four configuration presets at deploy/config-presets/:
| Preset | Session | Killswitch | Dead Man | Cover Name |
|---|---|---|---|---|
low-threat.json |
30 min | Off | Off | None |
medium-threat.json |
15 min | On | 48h / 4h grace | "Office Document Manager" |
high-threat.json |
5 min | On | 12h / 1h grace | "Local Inventory Tracker" |
critical-threat.json |
3 min | On | 6h / 1h grace | "System Statistics" |
cp deploy/config-presets/high-threat.json ~/.fwmetadata/config.json
See docs/deployment.md for the full deployment guide including security hardening, Kubernetes manifests, systemd services, and operational security notes.
CLI Reference
All commands accept --data-dir PATH to override the default ~/.fwmetadata directory,
and --json for machine-readable output.
fieldwitness [--data-dir PATH] [--json] COMMAND
Core commands
| Command | Description |
|---|---|
fieldwitness init |
Create directory structure, generate identity + channel key, write default config |
fieldwitness serve |
Start the web UI (default: https://127.0.0.1:5000) |
fieldwitness status |
Show instance status: identity, keys, chain, fieldkit, config |
fieldwitness serve options
| Option | Default | Description |
|---|---|---|
--host |
127.0.0.1 |
Bind address |
--port |
5000 |
Bind port |
--no-https |
off | Disable HTTPS (use HTTP) |
--debug |
off | Use Flask dev server instead of Waitress |
--workers |
4 |
Number of Waitress/Gunicorn worker threads |
Attestation commands (fieldwitness attest)
# Attest an image (sign with Ed25519 identity)
fieldwitness attest IMAGE photo.jpg
fieldwitness attest IMAGE photo.jpg --caption "Field report" --location "Istanbul"
# Batch attest a directory
fieldwitness attest batch ./photos/ --caption "Field report"
# Verify an image against the attestation log
fieldwitness attest verify photo.jpg
# View attestation log
fieldwitness attest log --limit 20
Chain commands (fieldwitness chain)
fieldwitness chain status # Show chain head, length, integrity
fieldwitness chain verify # Verify entire chain integrity (hashes + signatures)
fieldwitness chain show INDEX # Show a specific chain record
fieldwitness chain log --count 20 # Show recent chain entries
fieldwitness chain backfill # Backfill existing attestations into chain
# Evidence export
fieldwitness chain export --start 0 --end 100 -o chain.zip
# Selective disclosure (for legal discovery / court orders)
fieldwitness chain disclose -i 5,12,47 -o disclosure.json
# External timestamp anchoring
fieldwitness chain anchor # Manual anchor (prints hash for tweet/email/blockchain)
fieldwitness chain anchor --tsa https://freetsa.org/tsr # RFC 3161 automated anchor
Fieldkit commands (fieldwitness fieldkit)
fieldwitness fieldkit status # Show fieldkit state
fieldwitness fieldkit checkin # Reset dead man's switch timer
fieldwitness fieldkit check-deadman # Check if deadman timer has expired
fieldwitness fieldkit purge --confirm # Activate killswitch (destroys all data)
fieldwitness fieldkit geofence set --lat 48.8566 --lon 2.3522 --radius 1000
fieldwitness fieldkit geofence check --lat 48.8600 --lon 2.3500
fieldwitness fieldkit geofence clear
fieldwitness fieldkit usb snapshot # Snapshot current USB devices as whitelist
fieldwitness fieldkit usb check # Check for unauthorized USB devices
Key management commands (fieldwitness keys)
fieldwitness keys show # Display current key info
fieldwitness keys export -o backup.enc # Export encrypted key bundle
fieldwitness keys import -b backup.enc # Import key bundle
fieldwitness keys rotate-identity # Generate new Ed25519 identity (records rotation in chain)
fieldwitness keys rotate-channel # Generate new channel key
Steganography commands (fieldwitness stego)
Stego uses multi-factor authentication: a reference photo (shared image both parties have), a passphrase (4+ words), and a PIN (6-9 digits). All three are required to encode or decode. The passphrase and PIN are prompted interactively (hidden input) if not provided via options.
# Encode a text message into an image
# CARRIER is the image to hide data in, -r is the shared reference photo
fieldwitness stego encode cover.png -r shared_photo.jpg -m "Secret message"
# Passphrase: **** (prompted, hidden)
# PIN: **** (prompted, hidden)
# -> writes encoded PNG to current directory
# Encode with explicit output path
fieldwitness stego encode cover.png -r shared_photo.jpg -m "Secret" -o stego_output.png
# Encode a file instead of text
fieldwitness stego encode cover.png -r shared_photo.jpg -f document.pdf
# Transport-aware encoding (auto-selects DCT/JPEG and resizes for the platform)
fieldwitness stego encode cover.jpg -r shared.jpg -m "Secret" --transport whatsapp
fieldwitness stego encode cover.jpg -r shared.jpg -m "Secret" --transport signal
fieldwitness stego encode cover.jpg -r shared.jpg -m "Secret" --transport telegram
fieldwitness stego encode cover.jpg -r shared.jpg -m "Secret" --transport email
fieldwitness stego encode cover.jpg -r shared.jpg -m "Secret" --transport direct
# Dry run -- check capacity without encoding
fieldwitness stego encode cover.png -r shared_photo.jpg -m "Secret" --dry-run
# Decode a message from a stego image (same reference + passphrase + PIN)
fieldwitness stego decode stego_output.png -r shared_photo.jpg
# Passphrase: ****
# PIN: ****
# -> prints decoded message or saves decoded file
# Decode and save file payload to specific path
fieldwitness stego decode stego_output.png -r shared_photo.jpg -o recovered.pdf
# DCT mode for JPEG (survives social media compression)
fieldwitness stego encode cover.jpg -r shared_photo.jpg -m "Secret" --platform telegram
# Audio steganography
fieldwitness stego audio-encode audio.wav -r shared_photo.jpg -m "Hidden in audio"
fieldwitness stego audio-decode stego.wav -r shared_photo.jpg
# Generate credentials
fieldwitness stego generate # Generate passphrase + PIN
fieldwitness stego generate --pin-length 8 # Longer PIN
# Channel key management
fieldwitness stego channel status # Show current channel key
fieldwitness stego channel generate # Generate new channel key
# Image info and capacity
fieldwitness stego info cover.png # Image details + LSB/DCT capacity
Web UI
Start with fieldwitness serve. The web UI provides authenticated access to all features
through Flask blueprints. Served by Waitress (production WSGI server) by default.
Routes
| Blueprint | Routes | Description |
|---|---|---|
| attest | /attest, /verify |
Attestation signing and verification |
| federation | /federation/* |
Federation peer dashboard, peer add/remove |
| fieldkit | /fieldkit/* |
Killswitch, dead man's switch, status dashboard |
| keys | /keys/* |
Key management, rotation, export/import |
| admin | /admin/* |
User management (multi-user auth via SQLite) |
| dropbox | /dropbox/admin, /dropbox/upload/<token> |
Source drop box: token creation (admin), anonymous upload (source), receipt verification |
| stego | /encode, /decode, /generate |
Steganography operations |
| health | /health |
Capability reporting endpoint (see API section) |
Configuration
FieldWitness loads configuration from ~/.fwmetadata/config.json. All fields have sensible defaults.
fieldwitness init writes the default config file.
Config fields
| Field | Type | Default | Description |
|---|---|---|---|
host |
string | 127.0.0.1 |
Web UI bind address |
port |
int | 5000 |
Web UI bind port |
https_enabled |
bool | true |
Enable HTTPS with self-signed cert |
auth_enabled |
bool | true |
Require login for web UI |
max_upload_mb |
int | 50 |
Maximum upload size in MB |
session_timeout_minutes |
int | 15 |
Session expiry |
login_lockout_attempts |
int | 5 |
Failed logins before lockout |
login_lockout_minutes |
int | 15 |
Lockout duration |
default_embed_mode |
string | auto |
Stego encoding mode |
killswitch_enabled |
bool | false |
Enable killswitch functionality |
deadman_enabled |
bool | false |
Enable dead man's switch |
deadman_interval_hours |
int | 24 |
Check-in interval |
deadman_grace_hours |
int | 2 |
Grace period after missed check-in |
deadman_warning_webhook |
string | "" |
URL to POST warning before auto-purge |
usb_monitoring_enabled |
bool | false |
Enable USB device whitelist enforcement |
tamper_monitoring_enabled |
bool | false |
Enable file integrity monitoring |
chain_enabled |
bool | true |
Enable attestation hash chain |
chain_auto_wrap |
bool | true |
Auto-wrap attestations in chain records |
backup_reminder_days |
int | 7 |
Days before backup reminder |
cover_name |
string | "" |
If set, used for SSL cert CN instead of "FieldWitness Local" (cover/duress mode) |
gpio_killswitch_pin |
int | 17 |
Raspberry Pi GPIO pin for hardware killswitch |
gpio_killswitch_hold_seconds |
float | 5.0 |
Hold duration to trigger hardware killswitch |
Environment variables
| Variable | Description |
|---|---|
FIELDWITNESS_DATA_DIR |
Override the data directory (default: ~/.fwmetadata). Enables portable USB mode and cover/duress directory naming |
Architecture
Source layout
src/fieldwitness/
__init__.py Package init, __version__
cli.py Click CLI (entry point: fieldwitness)
paths.py All path constants (lazy resolution from BASE_DIR)
config.py Unified config loader (dataclass + JSON)
exceptions.py FieldWitnessError base exception
metadata.py Extract-then-strip EXIF pipeline
evidence.py Self-contained evidence package export
archive.py Cold archive for long-term preservation (OAIS-aligned)
attest/ Attestation engine (subpackage)
models.py ImageHashes (images + arbitrary files), AttestationRecord
keystore/
manager.py Key material management (channel + identity + trust store + backup)
models.py KeyBundle, IdentityBundle dataclasses
export.py Full bundle export, channel-key-only export, QR code sharing
federation/
chain.py Append-only hash chain (key rotation, recovery, delivery ack, selective disclosure)
anchors.py RFC 3161 timestamps + manual chain anchors
exchange.py Cross-org attestation bundle export/import
fieldkit/
killswitch.py Emergency data destruction (deep forensic scrub, self-uninstall)
deadman.py Dead man's switch (webhook warnings)
tamper.py File integrity monitoring
usb_monitor.py USB device whitelist (Linux/pyudev)
geofence.py GPS boundary enforcement (gpsd integration)
stego/ Steganography engine (subpackage)
encode.py Transport-aware encoding (--transport flag)
carrier_tracker.py Carrier reuse tracking and warnings
frontends/web/
app.py Flask app factory (create_app())
auth.py SQLite3 multi-user auth
temp_storage.py File-based temp storage with expiry
subprocess_stego.py Crash-safe subprocess isolation
ssl_utils.py Self-signed HTTPS cert generation
blueprints/
attest.py /attest, /verify
federation.py /federation/* (peer dashboard)
fieldkit.py /fieldkit/*
keys.py /keys/*
admin.py /admin/*
dropbox.py /dropbox/* (source drop box)
stego.py /encode, /decode, /generate
deploy/ Deployment artifacts
docker/ Dockerfile (multi-stage: builder, relay, server) + compose
kubernetes/ Namespace, server, and relay deployments
live-usb/ Debian Live USB build scripts (Tier 1)
config-presets/ Threat level presets (low/medium/high/critical)
Data directory (~/.fwmetadata/)
~/.fwmetadata/
config.json Unified configuration
audit.jsonl Append-only audit trail
carrier_history.json Carrier reuse tracking database
identity/ Ed25519 keypair (private.pem, public.pem, identity.meta.json)
stego/ Channel key (channel.key)
attestations/ Attest attestation store (log.bin, index/, peers.json)
chain/ Hash chain (chain.bin, state.cbor, anchors/)
auth/ Web UI auth database (fieldwitness.db, dropbox.db)
certs/ Self-signed TLS certificates
fieldkit/ Fieldkit state (deadman.json, tamper/, usb/, geofence.json)
temp/ Ephemeral file storage (dropbox uploads)
instance/ Flask instance (sessions, secret key)
trusted_keys/ Collaborator Ed25519 public keys (trust store)
Sensitive directories (identity/, auth/, certs/, and the root) are created with
0700 permissions.
Security Model
Two key domains, never merged. Stego uses AES-256-GCM with keys derived via Argon2id from user-supplied factors. Attest uses Ed25519 for signing. These serve different security purposes and are kept strictly separate.
Killswitch priority. The killswitch destroys all data under ~/.fwmetadata/, including
the audit log. This is intentional -- in a field compromise scenario, data destruction
takes precedence over audit trail preservation. The deep forensic scrub extends beyond
the data directory to remove Python bytecache, pip metadata, pip download cache, shell
history entries, and the fieldwitness package itself.
Offline-first. All static assets are vendored (no CDN calls). Pip wheels can be bundled for fully airgapped installation. No network access is required for any core functionality. RFC 3161 timestamping and webhook warnings are optional features that gracefully degrade when offline.
Web UI hardening:
- CSRF protection via Flask-WTF
- Session timeout (default: 15 minutes)
- Login rate limiting with lockout (5 attempts, 15-minute lockout)
- HTTPS by default with auto-generated self-signed certificates
- EXIF stripping on steganographic encode to prevent metadata leakage
- Dead man's switch webhook SSRF protection (blocks private/internal targets)
Subprocess isolation. Steganographic operations run in a subprocess boundary
(subprocess_stego.py) to contain crashes and prevent memory corruption from affecting
the main web server process.
Chain integrity. The append-only hash chain uses Ed25519 signatures and SHA-256 linkage. Key rotation records create a verifiable trust chain; identity recovery records are auditable. Selective disclosure uses Merkle-style proofs so third parties can verify specific records without accessing the full chain.
Cross-Domain Applications
While FieldWitness was designed for journalist and NGO field security, the attestation chain, federation, and evidence packaging capabilities apply to a range of domains:
- Human rights documentation -- field workers attest photos and videos of incidents with GPS and timestamps, federate evidence to international partners, and produce court-ready evidence packages
- Research integrity -- researchers attest datasets (CSV, sensor readings) at
collection time, creating a tamper-evident chain of custody.
ImageHashes.from_file()supports arbitrary file types via SHA-256 - Election monitoring -- observers attest ballot images and tally sheets with location metadata, anchor the chain to an RFC 3161 TSA for independent time proof, and use selective disclosure for audit requests
- Supply chain verification -- attest inspection photos, sensor data, and certificates of origin at each stage. Federation enables multi-party chains across organizations
- Art authentication -- attest high-resolution photographs of artworks with device and location metadata, creating provenance records that survive format conversion via perceptual hashing
- Corporate whistleblowing -- the source drop box accepts anonymous uploads with
client-side hashing. Cover mode (
cover_name,FIELDWITNESS_DATA_DIR) disguises the installation. The killswitch provides emergency destruction if the instance is compromised - Environmental monitoring -- attest sensor data, satellite imagery, and field
photographs. Cold archives with
ALGORITHMS.txtensure evidence remains verifiable decades later
API
/health endpoint
The web UI exposes a /health endpoint that reports installed capabilities:
{
"status": "ok",
"version": "0.2.0",
"capabilities": ["stego-lsb", "stego-dct", "attest", "fieldkit", "chain"]
}
Useful for monitoring and for clients to discover which extras are installed.
FastAPI (optional)
Install the api extra for a standalone FastAPI REST interface:
pip install "fieldwitness[api]"
This provides fieldwitness.api with a FastAPI application served by uvicorn, suitable for
programmatic integration.
Development
Setup
git clone https://github.com/alee/fieldwitness.git
cd fieldwitness
pip install -e ".[dev]"
Commands
pytest # Run tests with coverage
black src/ tests/ frontends/ # Format (100-char line length)
ruff check src/ tests/ frontends/ --fix # Lint
mypy src/ # Type check
Code style
- Black with 100-character line length
- Ruff with E, F, I, N, W, UP rule sets
- mypy strict mode with missing imports ignored
- Imperative commit messages (e.g., "Add killswitch purge confirmation")
Python support
Python 3.11, 3.12, 3.13, and 3.14.
Documentation
| Document | Audience | Description |
|---|---|---|
| docs/deployment.md | Field deployers, IT staff | Three-tier deployment guide, security hardening, troubleshooting |
| docs/federation.md | System administrators | Gossip protocol, peer setup, offline bundles, federation API |
| docs/evidence-guide.md | Investigators, legal teams | Evidence packages, cold archives, selective disclosure, anchoring |
| docs/source-dropbox.md | Administrators | Source drop box setup, EXIF pipeline, receipt codes |
| docs/security/threat-model.md | Security reviewers, contributors | Threat model, adversary model, trust boundaries, cryptographic primitives |
| docs/training/reporter-quickstart.md | Field reporters | One-page quick-start card for Tier 1 USB users |
| docs/training/emergency-card.md | All users | Laminated wallet card: emergency destruction, dead man's switch |
| docs/training/admin-reference.md | Administrators | CLI cheat sheet, hardening checklist, troubleshooting |
Architecture documents (design-level, for contributors):
| Document | Description |
|---|---|
| docs/architecture/federation.md | System architecture overview, threat model, layer design |
| docs/architecture/chain-format.md | Chain record spec (CBOR, entropy witnesses) |
| docs/architecture/export-bundle.md | Export bundle spec (binary format, envelope encryption) |
| docs/architecture/federation-protocol.md | Federation server protocol (CT-inspired, gossip) |
License
GPL-3.0 License. See LICENSE for details.