fieldwitness/docs/security/threat-model.md

# FieldWitness Threat Model

**Status:** Living document -- updated as the design evolves and as external review
identifies gaps. Version numbers track significant revisions.

**Document version:** 0.1 (2026-04-01)
**Corresponds to:** FieldWitness v0.3.0

This document follows the style of the Signal Protocol specification and the Tor design
document: it makes precise claims, distinguishes what is guaranteed from what is not, and
does not use marketing language. Unresolved questions and known gaps are stated plainly.

**This document has not been externally audited.** Claims here reflect the designer's
intent and analysis. An independent security review is planned as part of Phase 2 (see
`docs/planning/gtm-feasibility.md`). Until that review is complete, treat this document
as a design statement, not a security certification.

---

## Table of Contents

1. [Intended Users](#1-intended-users)
2. [Adversary Model](#2-adversary-model)
3. [Assets Protected](#3-assets-protected)
4. [Trust Boundaries](#4-trust-boundaries)
5. [Security Guarantees](#5-security-guarantees)
6. [Non-Guarantees](#6-non-guarantees)
7. [Cryptographic Primitives](#7-cryptographic-primitives)
8. [Key Management Model](#8-key-management-model)
9. [Federation Trust Model](#9-federation-trust-model)
10. [Known Limitations](#10-known-limitations)

---

## 1. Intended Users

FieldWitness is designed for three overlapping user populations:

**Field reporters and documenters.** Journalists, human rights monitors, and election
observers working in environments where physical device seizure is a plausible risk.
Operating assumption: the user may be detained, the device may be confiscated, and the
operator at Tier 2 (the org server) may not be reachable in real time. The user needs to
attest evidence locally on a Tier 1 (field device) and sync later -- or never, if the USB
is destroyed.

**Organizational administrators.** IT staff and security-aware operators at newsrooms or
NGOs running Tier 2 deployments. They manage keys, configure threat levels, operate the
source drop box, and maintain federation peering with partner organizations. They are
expected to understand basic operational security concepts but are not expected to be
cryptographers.

**Partner organizations.** Organizations that receive attested evidence bundles from the
primary organization and need to verify chain-of-custody without installing FieldWitness. They
interact with standalone `verify.py` scripts included in evidence packages.

FieldWitness is **not** designed as a general-purpose secure communications tool, a replacement
for SecureDrop's source protection model, or a consumer privacy application.

---

## 2. Adversary Model

### 2.1 Passive Network Observer

**Capability:** Can observe all network traffic between nodes, including Tier 2 to Tier 3
communication and gossip federation traffic. Cannot break TLS or Ed25519.

**Goal:** Determine which organizations are communicating, the timing and volume of
attestation syncs, and potentially correlate sync events with news events.

**FieldWitness's position:** Transport-level metadata (IP addresses, timing, volume) is not
hidden. TLS (self-signed, port 8000) protects payload content. A passive observer can
determine that two Tier 2 servers are federating; they cannot read the attestation records
being exchanged without the relevant Ed25519 public keys.

**Gap:** No traffic padding, no onion routing, no anonymization of federation topology.
Organizations with strong network-level adversaries should route federation traffic through
Tor or a VPN. This is not built in.

### 2.2 Active Network Adversary

**Capability:** Can intercept, modify, replay, and drop traffic. Can present forged
TLS certificates if the operator hasn't pinned the peer's certificate.

**Goal:** Inject forged attestation records into the federation, suppress legitimate
records, or cause evidence to appear tampered.

**FieldWitness's position:** All attestation records are Ed25519-signed. A network adversary
cannot forge a valid signature without the private key. The append-only hash chain makes
retroactive injection detectable: inserting a record at position N requires recomputing all
subsequent hashes. Consistency proofs during gossip sync detect log divergence.

**Gap:** Certificate pinning for federation peers is not implemented as of v0.3.0. The
Tier 3 relay uses a self-signed certificate; operators should verify its fingerprint
out-of-band. Gossip peers authenticate by Ed25519 fingerprint, not certificate, which
provides a secondary check.

### 2.3 Physical Access

**Capability:** Has physical access to the field device (Tier 1 USB) or the org server
(Tier 2). May have forensic tools.

**Goal:** Extract private keys, recover attested evidence, identify the operator, or
determine what evidence was collected.

**FieldWitness's position:**

- Tier 1 is designed for amnesia: Debian Live USB with LUKS-encrypted persistent
  partition. Pulling the USB from the host leaves no trace on the host machine. If the USB
  itself is seized, LUKS protects the persistent partition.
- The killswitch (`fieldwitness fieldkit purge`) destroys all key material and data under
  `~/.fwmetadata/` in sensitivity order. The deep forensic scrub removes Python bytecache, pip
  metadata, download cache, and shell history entries. The final step is `pip uninstall
  -y fieldwitness`.
- The dead man's switch fires the killswitch automatically if check-in is missed.
- Private keys are stored as PEM files with `0600` permissions. Key material is not
  additionally encrypted at rest beyond the filesystem (LUKS on Tier 1; operator-managed
  on Tier 2).

**Gap:** If the device is seized before the killswitch fires and LUKS has been unlocked
(i.e., the device is running), private keys are accessible. Cold boot attacks against
unlocked LUKS volumes are not mitigated. Key material is not stored in a hardware security
module or OS keychain.

### 2.4 Legal Compulsion

**Capability:** Can compel the operator (or their legal jurisdiction) to produce data,
keys, or records. May use court orders, search warrants, or jurisdiction-specific
administrative processes.

**Goal:** Obtain attestation records or private keys under legal authority.

**FieldWitness's position:** FieldWitness provides tools (selective disclosure, evidence packages)
for producing specific records under court order without revealing the full chain.
The Federation Relay (Tier 3) stores only hashes and signatures -- never private keys or
plaintext. Placing Tier 3 in a jurisdiction with strong press protections limits one
compulsion surface.

**Gap:** If private keys are seized, all past and future attestations signed by those keys
are attributable to the key holder. Key rotation limits forward exposure after a
compromise, but prior records signed by the old key remain attributable. FieldWitness does not
implement deniable authentication.

### 2.5 Insider Threat

**Capability:** Has legitimate access to the FieldWitness instance (e.g., a trusted
administrator or a compromised org server). Can read key material, attestation records,
and logs.

**Goal:** Selectively alter or delete records, export keys, or suppress evidence.

**FieldWitness's position:** The append-only hash chain makes deletion or modification of prior
records detectable: the chain head hash changes and any external anchor (RFC 3161 TSA,
blockchain transaction) will no longer match. Key rotation is logged in the chain as a
`fieldwitness/key-rotation-v1` record signed by the old key, creating an auditable trail.

**Gap:** An insider with direct filesystem access can overwrite `chain.bin` entirely,
including the chain head, before an external anchor is taken. The chain provides integrity
guarantees only to the extent that external anchors are taken regularly and independently
(by another party or a public TSA). Frequency of anchoring is an operational decision, not
enforced by the software.

---

## 3. Assets Protected

The following assets are in scope for FieldWitness's security model:

| Asset | Description | Primary Protection |
|---|---|---|
| Attestation records | Ed25519-signed records linking a file hash to a time, identity, and optional metadata | Append-only chain, Ed25519 signatures |
| Identity private key | Ed25519 private key used to sign attestations | `0600` filesystem permissions, LUKS on Tier 1, killswitch |
| Channel key | AES-256-GCM key used for steganographic encoding | `0600` filesystem permissions, separate from identity key |
| Source submissions | Anonymous uploads through the drop box | EXIF stripping, no-branding upload page, HMAC receipt codes |
| Evidentiary metadata | GPS, timestamp, device model extracted from EXIF | Stored in attestation record, dangerous fields stripped |
| Federation topology | Which organizations are peering | Not protected at network level (see 2.1) |

The following are **out of scope** (not protected by FieldWitness):

- Source identity beyond what is stripped from EXIF
- Operator identity (FieldWitness does not provide anonymity)
- Content of files beyond what is hashed and signed (files are not encrypted at rest
  unless encrypted before attestation)
- The Tier 3 relay's knowledge of federation topology

---

## 4. Trust Boundaries

```
[Field reporter / Tier 1] --- LUKS + killswitch --- [Seized device adversary]
         |
    [USB sneakernet or LAN]
         |
[Org Server / Tier 2] ------- TLS (self-signed) ---- [Network adversary]
         |                                            [Active attacker: no forged sigs]
    [Gossip federation]
         |
[Federation Relay / Tier 3] - Stores hashes+sigs only, no keys
         |
[Partner Org / Tier 2] ------ Ed25519 trust store -- [Untrusted peers rejected]
         |
[Verifying party] ----------- standalone verify.py, cryptography package only
```

**Tier 1 trusts:** Its own key material (generated locally), the Tier 2 server it was
configured to sync with.

**Tier 2 trusts:** Its own key material, the Ed25519 public keys in its trust store
(imported explicitly by the administrator), the Tier 3 relay for transport only (not
content validation).

**Tier 3 trusts:** Nothing. It is a content-unaware relay. It cannot validate the
semantic content of what it stores because it has no access to private keys.

**Verifying party trusts:** The signer's Ed25519 public key (received out-of-band, e.g.,
in the evidence package), the `cryptography` Python package, and the chain linkage logic
in `verify.py`.

---

## 5. Security Guarantees

The following are properties FieldWitness is designed to provide. Each is conditional on the
named preconditions.

**G1: Attestation integrity.** Given an attestation record and the signer's Ed25519 public
key, a verifier can determine whether the record has been modified since signing.
_Precondition:_ The verifier has the correct public key and the `cryptography` package.
_Mechanism:_ Ed25519 signature over deterministic JSON serialization of the record.

**G2: Chain append-only property.** If a record is in the chain at position N, it cannot
be removed or modified without invalidating every subsequent record's hash linkage.
_Precondition:_ The verifier has observed the chain head at some prior point or has an
external anchor.
_Mechanism:_ Each record includes `prev_hash = SHA-256(canonical_bytes(record[N-1]))`.

**G3: Timestamp lower bound.** If the chain head has been submitted to an RFC 3161 TSA
and the token is preserved, all records prior to the anchored head provably existed before
the TSA's signing time.
_Precondition:_ The TSA's clock and signing key are trusted.
_Mechanism:_ RFC 3161 timestamp tokens stored in `chain/anchors/`.

**G4: Selective disclosure soundness.** A selective disclosure bundle proves that the
disclosed records are part of an unbroken chain without revealing the contents of
non-disclosed records.
_Precondition:_ The verifier has the chain head hash from an external source.
_Mechanism:_ Non-selected records appear as hashes only; chain linkage is preserved.

**G5: Federation record authenticity.** Records received via federation are accepted only
if signed by a key in the local trust store.
_Precondition:_ The trust store contains only keys the operator has explicitly imported.
_Mechanism:_ Ed25519 verification against trust store before appending federated records.

**G6: Source drop box anonymity (limited).** A source submitting via the drop box does
not need an account, FieldWitness is not mentioned on the upload page, and dangerous EXIF fields
are stripped before the file is stored.
_Precondition:_ The source accesses the drop box URL over HTTPS without revealing their
identity through other means (IP, browser fingerprint, etc.).
_Limitation:_ FieldWitness does not route drop box traffic through Tor or any anonymization
layer. Network-level anonymity is the source's responsibility.

---

## 6. Non-Guarantees

The following properties are explicitly **not** provided by FieldWitness. Including them here
prevents users from assuming protection that does not exist.

**NG1: Operator anonymity.** FieldWitness does not hide the identity of the organization
running the instance. The Tier 2 server has an IP address. The federation relay knows
which Tier 2 servers are peering.

**NG2: Deniable authentication.** Attestation records are non-repudiably signed by
Ed25519 keys. There is no plausible deniability about which key produced a signature.

**NG3: Forward secrecy for attestation keys.** Ed25519 identity keys are long-lived.
If a private key is compromised, all attestations signed by that key are attributable to
the key holder. Key rotation limits future exposure but does not retroactively remove
attributability.

**NG4: Protection against a compromised Tier 2 before anchoring.** An insider with full
Tier 2 access can rewrite the chain before any external anchor is taken. External anchors
are the primary protection against insider tampering; their value is proportional to how
frequently and independently they are taken.

**NG5: Content confidentiality.** FieldWitness does not encrypt attested files at rest. Files
are hashed and signed, not encrypted. Encryption before attestation is the operator's
responsibility.

**NG6: Source protection beyond EXIF stripping.** The drop box strips dangerous EXIF
fields and does not log source IP addresses in attestation records. It does not provide
the same source protection model as SecureDrop. Organizations with strong source
protection requirements should use SecureDrop for intake and FieldWitness for evidence chain
management.

**NG7: Auditability of the Tier 3 relay.** The relay stores only hashes and signatures,
but FieldWitness does not currently provide a mechanism for operators to audit what the relay
has and has not forwarded. The relay is trusted for availability, not integrity.

---

## 7. Cryptographic Primitives

All cryptographic choices are documented here to support independent review and long-term
archival verifiability.

### Signing

| Primitive | Algorithm | Parameters | Use |
|---|---|---|---|
| Identity signing | Ed25519 | RFC 8032 | Sign attestation records, key rotation records, delivery acks |
| Key storage | PEM | PKCS8 (private), SubjectPublicKeyInfo (public) | Disk format for identity keypair |

Ed25519 was chosen for: short key and signature sizes (32-byte public key, 64-byte
signature), deterministic signing (no random oracle required per operation), strong
security margins, and wide library support.

### Encryption (Stego channel key domain)

| Primitive | Algorithm | Parameters | Use |
|---|---|---|---|
| Symmetric encryption | AES-256-GCM | 256-bit key, 96-bit IV, 128-bit tag | Payload encryption in stego encode |
| Key derivation | Argon2id | time=3, memory=65536, parallelism=4, saltlen=16 | Derive AES key from passphrase + PIN + reference photo fingerprint |

**Note:** The AES-256-GCM channel key domain (Stego) and the Ed25519 identity key
domain (Attest) are kept strictly separate. They serve different security purposes and
share no key material.

### Hashing

| Primitive | Algorithm | Use |
|---|---|---|
| Cryptographic hash | SHA-256 | Chain record linkage (`prev_hash`), content fingerprinting |
| Content fingerprinting | SHA-256 | `ImageHashes.sha256` for all file types |
| Perceptual hash | pHash (DCT-based) | Image tamper detection, survives compression |
| Perceptual hash | dHash (difference hash) | Image tamper detection |
| Perceptual hash | aHash (average hash) | Fuzzy matching, high tolerance |
| Chain serialization | CBOR (RFC 7049) | Canonical encoding for chain records |
| HMAC | HMAC-SHA256 | Drop box receipt code derivation |

### External Timestamping

| Mechanism | Standard | Use |
|---|---|---|
| RFC 3161 TSA | RFC 3161 | Automated, signed timestamp tokens |
| Manual anchor | Any external witness | Chain head hash submitted to blockchain, email, etc. |

---

## 8. Key Management Model

### Key types and locations

| Key | Type | Location | Purpose |
|---|---|---|---|
| Identity private key | Ed25519 | `~/.fwmetadata/identity/private.pem` | Sign all attestation records |
| Identity public key | Ed25519 | `~/.fwmetadata/identity/public.pem` | Shared with verifiers; included in evidence packages |
| Channel key | AES-256-GCM | `~/.fwmetadata/stego/channel.key` | Stego encoding/decoding shared secret |
| Trust store keys | Ed25519 (public only) | `~/.fwmetadata/trusted_keys/<fingerprint>/` | Verify federated records from partners |

### Key rotation

Identity rotation creates a `fieldwitness/key-rotation-v1` chain record signed by the **old**
key, containing the new public key. This establishes a cryptographic chain of trust from
the original key through all rotations. Verifiers following the rotation chain can confirm
that new attestations come from the same organizational identity as old ones.

Channel (AES) key rotation creates a new key and archives the old one. Old channel keys
are required to decode stego payloads encoded with them; archived keys are preserved under
`~/.fwmetadata/stego/archived/`.

### Identity recovery

After device loss, a `fieldwitness/key-recovery-v1` chain record is signed by the **new** key,
carrying the old key's fingerprint and optional cosigner fingerprints. This is an
auditable assertion, not a cryptographic proof that the old key authorized the recovery
(the old key is lost). The recovery record's legitimacy depends on out-of-band
confirmation (e.g., cosigner verification, organizational attestation).

### Backup

The keystore manager (`fieldwitness/keystore/manager.py`) tracks backup state. Encrypted key
bundles can be exported to the SOOBNDL format for cold storage. The backup reminder
interval is configurable; the default is 7 days.

---

## 9. Federation Trust Model

### Peer authentication

Federation peers are identified by their Ed25519 public key fingerprint (first 16 bytes of
SHA-256 of the public key, hex-encoded). Peering is established by explicit administrator
action: the peer's public key fingerprint is configured locally. There is no automatic
peer discovery or trust-on-first-use.

### Record acceptance

A record received via federation is accepted only if:
1. It is signed by an Ed25519 key in the local trust store.
2. The signature is valid over the record's canonical serialization.
3. The record does not duplicate a record already in the local log (by record ID).

Records signed by unknown keys are silently dropped. There is no mechanism to accept
records from temporarily trusted but unregistered peers.

### The Tier 3 relay

The Tier 3 relay is a content-unaware intermediary. It forwards attestation bundles between
Tier 2 nodes but has no access to private keys and cannot validate the semantic content of
records. It is trusted for availability (it should forward what it receives) but not for
integrity (it cannot be used as an authority for whether records are authentic).

### Consistency proofs

During gossip sync, nodes exchange their current Merkle log root and size. If roots
differ, the node with fewer records requests a consistency proof from the node with more
records. The consistency proof proves that the smaller log is a prefix of the larger log,
preventing log divergence. Records are fetched incrementally after the proof verifies.

The consistency proof implementation is in `src/fieldwitness/attest/merkle.py`.

---

## 10. Known Limitations

This section is a candid accounting of current gaps. Items here are candidates for future
work, not dismissals.

**L1: No hardware key storage.** Private keys are stored as PEM files protected only by
filesystem permissions and LUKS (on Tier 1). A hardware security module (HSM), TPM, or OS
keychain would provide stronger protection against physical extraction from a running
system. This is a significant gap for high-threat deployments.

**L2: No certificate pinning for federation.** Tier 2 to Tier 3 connections use TLS with
self-signed certificates. The peer's certificate fingerprint is not currently pinned in
configuration. An active network adversary with the ability to present a forged certificate
could intercept federation traffic. The Ed25519 peer fingerprint provides a secondary check
but is not a substitute.

**L3: Killswitch reliability.** The killswitch's effectiveness depends on the operating
system's file deletion semantics. On HDDs without secure erase, file overwriting may not
prevent forensic recovery. On SSDs with wear leveling, even overwriting does not guarantee
physical deletion. The deep forensic scrub does multiple passes, but this is not
equivalent to verified physical destruction. For critical-threat deployments, physical
destruction of storage media is more reliable than software scrub.

**L4: Anchor frequency is an operational decision.** The chain's tamper-evidence
properties against insider threats depend on how frequently external anchors are taken.
FieldWitness does not enforce or automate anchor frequency. An organization that anchors
infrequently has a larger window during which insider tampering is undetectable.

**L5: Gossip topology is not hidden.** The list of peers a node gossips with is visible
to a network observer. For organizations where federation topology is itself sensitive
information, all federation should be routed through Tor or equivalent.

**L6: No audit of Tier 3 relay behavior.** FieldWitness does not currently provide a way for
operators to verify that the Tier 3 relay has faithfully forwarded all bundles it received.
A malicious or compromised relay could suppress specific records. The design mitigation is
to use the relay only for transport, never as an authoritative source -- but no
verification mechanism is implemented.

**L7: Drop box source anonymity is limited.** The drop box does not log source IP addresses
in attestation records or require accounts, but it does not anonymize the source's network
connection. A source's IP is visible to the Tier 2 server operator in web server access
logs. Organizations providing source protection should use Tor for source access and may
wish to configure the web server to not log IP addresses.

**L8: Steganalysis resistance is not guaranteed.** The steganography backend includes a
steganalysis module (`stego/steganalysis.py`) for estimating detection resistance, but
stego channels are not guaranteed to be undetectable by modern ML-based steganalysis tools
under all conditions. Stego should be treated as a covert channel with meaningful
detection risk, not a guaranteed-invisible channel.

**L9: No formal security proof.** The security of FieldWitness's federation protocol, chain
construction, and selective disclosure has not been formally analyzed. The design draws on
established primitives (Ed25519, SHA-256, RFC 3161, Merkle trees) and patterns (gossip,
append-only logs, Certificate Transparency-inspired consistency proofs), but informal
design analysis is not a substitute for a formal proof or an independent security audit.