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):

1. Extract all EXIF metadata from the original image bytes
2. Classify fields as evidentiary (GPS coordinates, timestamp -- valuable for provenance) or dangerous (device serial number, firmware version -- could identify the source)
3. Preserve evidentiary fields in the attestation record
4. 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-v1 chain 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 the cryptography pip 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.txt documenting every cryptographic algorithm, parameter, and format used
• verify.py standalone verifier
• manifest.json with 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, pip dist-info, pip download cache, and scrubs shell history entries containing "fieldwitness"
  • Self-uninstall -- runs pip uninstall -y fieldwitness as the final step
  • System log clearing -- best-effort journald vacuum on Linux
• 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 to 127.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-v1 record 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-v1 chain 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_name in config to replace "FieldWitness Local" in the self-signed TLS certificate
• Portable data directory -- set FIELDWITNESS_DATA_DIR to relocate all state to an arbitrary path (e.g., an innocuously named directory on a USB stick). All paths resolve lazily from BASE_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-dct extra)
• Audio steganography -- hide data in WAV/FLAC audio (requires stego-audio extra)
• Video steganography -- frame-level encoding
• Transport-aware encoding -- --transport whatsapp|signal|telegram|discord|email|direct auto-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.txt ensure evidence remains verifiable decades later

---

API

/health endpoint

The web UI exposes a /health endpoint that reports installed capabilities:

{
  "status": "ok",
  "version": "0.3.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.