SooSeF -- Soo Security Fieldkit

Offline-first security toolkit for journalists, NGOs, and at-risk organizations.

---

What is SooSeF?

SooSeF combines steganography, provenance attestation, and field security tools into a single package designed for airgapped and resource-constrained environments. It lets you:

• Hide messages in images, audio, and video using multiple steganographic techniques, with transport-aware encoding for lossy channels (WhatsApp, Signal, Telegram)
• Prove authenticity of photos, documents, and arbitrary files with Ed25519 signatures, Merkle-style hash chains, and RFC 3161 trusted timestamps
• Protect data in the field with a killswitch (including deep forensic scrub and self-uninstall), dead man's switch with webhook warnings, tamper detection, USB device whitelisting, and GPS geofencing
• Manage cryptographic keys with identity rotation, channel key generation, encrypted key bundle export/import, QR code sharing, trust store management, and identity recovery from chain
• Federate attestations across organizations with signed exchange bundles, delivery acknowledgments, selective disclosure for legal discovery, and investigation namespaces
• Accept anonymous submissions through a SecureDrop-style source drop box with token-gated uploads, client-side SHA-256 hashing, and automatic EXIF extraction/stripping
• Preserve evidence long-term with self-contained evidence packages and OAIS-aligned cold archives that include standalone verification scripts and algorithm documentation

Stegasoo (steganography, v4.3.0) and Verisoo (attestation, v0.1.0) are included as subpackages (import soosef.stegasoo, import soosef.verisoo). Everything ships as one install: pip install soosef.

---

Quick Start

pip install "soosef[web,cli]"
soosef init
soosef serve

This creates the ~/.soosef/ 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

Steganography (Stegasoo)

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

Attestation (Verisoo)

• Ed25519 digital signatures for images and arbitrary files (CSV, documents, sensor data)
• Perceptual hashing (pHash, dHash) for tamper-evident photo attestation; SHA-256-only mode for non-image files
• LMDB-backed attestation storage
• Append-only hash chain (CBOR-encoded) with Merkle tree verification
• 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 steganography (strip everything to protect sources) and attestation (preserve everything to prove provenance):

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

Cross-Organization Federation

• Attestation exchange -- export signed bundles of attestation records and chain data for offline transfer to partner organizations
• Delivery acknowledgments -- when an organization imports a bundle, a soosef/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

External Timestamp Anchoring

Two mechanisms to externally prove that 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, tweet, 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.

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 SooSeF 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

Source Drop Box

SecureDrop-style anonymous intake built into the SooSeF web UI:

• Admin creates a time-limited upload token with a configurable file limit
• Source opens the token URL (no account or SooSeF 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 soosef/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 soosef/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 (soosef-channel: URI scheme)
• Backup tracking -- records when the last backup was taken and warns when overdue

Fieldkit

• Killswitch -- emergency destruction of all data under ~/.soosef/, 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 "soosef"
  • Self-uninstall -- runs pip uninstall -y soosef 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)

Cover / Duress Mode

• Configurable certificate CN -- set cover_name in config to replace "SooSeF Local" in the self-signed TLS certificate
• Portable data directory -- set SOOSEF_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

---

Installation

Basic install (core library only)

pip install soosef

With extras

pip install "soosef[web,cli]"           # Web UI + CLI (most common)
pip install "soosef[all]"               # Everything except dev tools
pip install "soosef[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 / Raspberry Pi install

Bundle wheels on a networked machine, then install offline:

# On networked machine
pip download "soosef[rpi]" -d ./wheels

# Transfer ./wheels to target via USB
# On airgapped machine
pip install --no-index --find-links=./wheels "soosef[rpi]"
soosef init
soosef serve --host 0.0.0.0

---

CLI Reference

All commands accept --data-dir PATH to override the default ~/.soosef directory, and --json for machine-readable output.

soosef [--data-dir PATH] [--json] COMMAND

Core commands

Command	Description
soosef init	Create directory structure, generate identity + channel key, write default config
soosef serve	Start the web UI (default: https://127.0.0.1:5000)
soosef status	Show instance status: identity, keys, chain, fieldkit, config

soosef 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

Steganography commands (soosef stego)

Stegasoo 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
soosef 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
soosef stego encode cover.png -r shared_photo.jpg -m "Secret" -o stego_output.png

# Encode a file instead of text
soosef stego encode cover.png -r shared_photo.jpg -f document.pdf

# Transport-aware encoding (auto-selects DCT/JPEG and resizes for the platform)
soosef stego encode cover.jpg -r shared.jpg -m "Secret" --transport whatsapp
soosef stego encode cover.jpg -r shared.jpg -m "Secret" --transport signal
soosef stego encode cover.jpg -r shared.jpg -m "Secret" --transport telegram
soosef stego encode cover.jpg -r shared.jpg -m "Secret" --transport email
soosef stego encode cover.jpg -r shared.jpg -m "Secret" --transport direct

# Dry run -- check capacity without encoding
soosef stego encode cover.png -r shared_photo.jpg -m "Secret" --dry-run

# Decode a message from a stego image (same reference + passphrase + PIN)
soosef 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
soosef stego decode stego_output.png -r shared_photo.jpg -o recovered.pdf

# DCT mode for JPEG (survives social media compression)
soosef stego encode cover.jpg -r shared_photo.jpg -m "Secret" --platform telegram

# Audio steganography
soosef stego audio-encode audio.wav -r shared_photo.jpg -m "Hidden in audio"
soosef stego audio-decode stego.wav -r shared_photo.jpg

# Generate credentials
soosef stego generate                 # Generate passphrase + PIN
soosef stego generate --pin-length 8  # Longer PIN

# Channel key management
soosef stego channel status           # Show current channel key
soosef stego channel generate         # Generate new channel key

# Image info and capacity
soosef stego info cover.png           # Image details + LSB/DCT capacity

Attestation commands (soosef attest)

# Attest an image (sign with Ed25519 identity)
soosef attest IMAGE photo.jpg
soosef attest IMAGE photo.jpg --caption "Field report" --location "Istanbul"

# Batch attest a directory
soosef attest batch ./photos/ --caption "Field report"

# Verify an image against the attestation log
soosef attest verify photo.jpg

# View attestation log
soosef attest log --limit 20

Fieldkit commands (soosef fieldkit)

soosef fieldkit status                # Show fieldkit state
soosef fieldkit checkin               # Reset dead man's switch timer
soosef fieldkit check-deadman         # Check if deadman timer has expired
soosef fieldkit purge --confirm       # Activate killswitch (destroys all data)
soosef fieldkit geofence set --lat 48.8566 --lon 2.3522 --radius 1000
soosef fieldkit geofence check --lat 48.8600 --lon 2.3500
soosef fieldkit geofence clear
soosef fieldkit usb snapshot          # Snapshot current USB devices as whitelist
soosef fieldkit usb check             # Check for unauthorized USB devices

Key management commands (soosef keys)

soosef keys show                      # Display current key info
soosef keys export -o backup.enc      # Export encrypted key bundle
soosef keys import -b backup.enc      # Import key bundle
soosef keys rotate-identity           # Generate new Ed25519 identity (records rotation in chain)
soosef keys rotate-channel            # Generate new channel key

Chain commands (soosef chain)

soosef chain status                   # Show chain head, length, integrity
soosef chain verify                   # Verify entire chain integrity (hashes + signatures)
soosef chain show INDEX               # Show a specific chain record
soosef chain log --count 20           # Show recent chain entries
soosef chain backfill                 # Backfill existing attestations into chain

# Evidence export
soosef chain export --start 0 --end 100 -o chain.zip

# Selective disclosure (for legal discovery / court orders)
soosef chain disclose -i 5,12,47 -o disclosure.json

# External timestamp anchoring
soosef chain anchor                   # Manual anchor (prints hash for tweet/email/blockchain)
soosef chain anchor --tsa https://freetsa.org/tsr   # RFC 3161 automated anchor

---

Web UI

Start with soosef 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
stego	/encode, /decode, /generate	Steganography operations
attest	/attest, /verify	Attestation signing and verification
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
health	/health	Capability reporting endpoint (see API section)

---

Configuration

SooSeF loads configuration from ~/.soosef/config.json. All fields have sensible defaults. soosef 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	Stegasoo 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 "SooSeF 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
SOOSEF_DATA_DIR	Override the data directory (default: ~/.soosef). Enables portable USB mode and cover/duress directory naming

---

Architecture

Source layout

src/soosef/
  __init__.py              Package init, __version__
  cli.py                   Click CLI (entry point: soosef)
  paths.py                 All path constants (lazy resolution from BASE_DIR)
  config.py                Unified config loader (dataclass + JSON)
  exceptions.py            SoosefError 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)
  stegasoo/                Steganography engine (subpackage)
    encode.py                Transport-aware encoding (--transport flag)
    carrier_tracker.py       Carrier reuse tracking and warnings
  verisoo/                 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)

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/
    stego.py                 /encode, /decode, /generate
    attest.py                /attest, /verify
    fieldkit.py              /fieldkit/*
    keys.py                  /keys/*
    admin.py                 /admin/*
    dropbox.py               /dropbox/* (source drop box)

Data directory (~/.soosef/)

~/.soosef/
  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)
  stegasoo/                Channel key (channel.key)
  attestations/            Verisoo attestation store (log.bin, index/, peers.json)
  chain/                   Hash chain (chain.bin, state.cbor, anchors/)
  auth/                    Web UI auth database (soosef.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. Stegasoo uses AES-256-GCM with keys derived via Argon2id from user-supplied factors. Verisoo uses Ed25519 for signing. These serve different security purposes and are kept strictly separate.

Killswitch priority. The killswitch destroys all data under ~/.soosef/, 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 soosef 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 SooSeF 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, SOOSEF_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.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 "soosef[api]"

This provides soosef.api with a FastAPI application served by uvicorn, suitable for programmatic integration.

---

Development

Setup

git clone https://github.com/alee/soosef.git
cd soosef
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.

---

License

MIT License. See LICENSE for details.