StegoForge

Hide encrypted data in images, audio, video, documents and executables.
Find it again, or find what someone else hid.

_{A real recording of the local web UI (stegoforge web): hide a file, extract it, run the detectors.}

Why StegoForge

• Both sides of the problem. Embed a payload and analyse a suspicious file with the same tool: 20 embedding methods, 7 core detectors, one-command CTF mode.
• Encrypted before it is hidden. Every payload is sealed with AES-256-GCM under an Argon2id key. A payload that is found still cannot be read without the passphrase.
• Honest about limits. Steganography is statistical, not magic. Detectors say inconclusive when they cannot tell, docs list what each method does not survive, and measured numbers are published with their error bars (docs/DETECTOR-EVAL.md).
• Local by default. The web UI listens on loopback only and makes no request to any third party; --offline switches the network off entirely; StegoForge never downloads an executable or a model.
• Scriptable. Every command has --json; errors go to stderr with stable codes, so stdout stays clean for pipes.

Install

Then check the installation:

$ stegoforge doctor

doctor lists what this machine can and cannot do (video support, FFmpeg for MP3/FLAC/OGG, the bundled ML model) and never touches the network.

Python 3.10: it works, but Pillow's image-decoder fixes (24 advisories in 12.3.0, patched in 13.0.0) need Python 3.11 or newer. Use Python 3.11+ when you analyse files you do not trust.

A one-minute tour

# Keep the passphrase out of your shell history and `ps` (a plain -k works, with a warning)
export STEGOFORGE_KEY="a long passphrase, not a short one"

stegoforge encode -c photo.png -p secret.txt        # method picked from the carrier type
stegoforge decode -f photo_stego.png                # -> photo_decoded.txt

stegoforge capacity -c photo.png --depth 2          # how much fits, and how stealthy each method is
stegoforge diff -c photo.png -s photo_stego.png     # heatmap of exactly which pixels changed
stegoforge detect -f photo_stego.png                # run the detectors on a file
stegoforge ctf -f challenge.png                     # every detector + extraction, one ranked report

# Will it survive an upload? Simulates the platform's recompression locally and tries to extract.
stegoforge encode -c photo.png -p secret.txt --target twitter --test-survival

# The same secret into every carrier in a folder
stegoforge batch -d ./carriers -p secret.txt --jobs 4

stegoforge web                                      # the local web UI on http://localhost:5000

An unencrypted payload (--allow-plaintext) is refused unless you ask for it. That is on purpose: without a key the embedded bytes are readable by anyone who extracts them, and the CTF scene in the recording above shows how easily that happens.

Interactive menu

Run stegoforge with no arguments for a guided menu (it opens with the boot screen above). STEGOFORGE_FAST_UI=1 skips the animation for instant starts, and STEGOFORGE_UI_STAGE_DELAY=0.4 tunes its pacing.

What it can hide where

Every method, its capacity formula and what it survives is in docs/METHODS.md.

Security model

• Crypto. AES-256-GCM; key from Argon2id (3 passes, 64 MiB, 2 lanes) with a fresh salt and nonce per embed. The envelope is bound to the embedding method and authenticates its own padding flag, so a payload cannot be replayed into another method or have its padding rewritten.
• One generic failure. A wrong passphrase, a damaged file and a file with nothing hidden in it all give the same error, with a stable machine code (decryption-failed).
• No fixed bytes on request. --no-magic embeds with no identifying header at all. --pad-to hides the payload length.
• Deniability. --decoy stores two payloads under two keys; both slots are the same size and header-less. It protects against someone who has only the file, not against someone who can compel both keys.
• Compatible with the past. Payloads, decoy containers and key-exchange files written by StegoForge ≤ 1.1.5 still open (a distinct KDF profile is kept for them; checked by creating files with the real 1.1.5 release), and --require-v2 refuses them if you want that. The reverse is not true: 1.1.5 cannot open files made by 1.5.
• What it does not do. It cannot make an image statistically perfect, survive lossy re-encoding, or protect a compromised machine. The passphrase also sets the order samples are visited in, which is obfuscation rather than a second layer of encryption.

The full list of what is and is not protected: docs/THREAT-MODEL.md.

Detect and CTF mode

Results are indicators, not proof. On the small bundled test corpus chi-square and RS miss most small payloads, and the blind extractor cannot see keyed embeds at all (measurements and caveats). A clean or inconclusive result never proves a file is clean.

The web UI

stegoforge web serves the same engine locally: encode, decode, detect, CTF, capacity, diff and survival checks. It is built to be safe to leave running and to analyse hostile files:

• Listens on 127.0.0.1 only. Any other --host refuses to start without STEGOFORGE_WEB_TOKEN (=auto generates one).
• Host and Origin checks (DNS rebinding, cross-site form posts), constant-time token comparison, rate limiting, downloads served as attachments, and no server paths or exception text in responses.
• Everything that comes from the file being analysed (metadata, file names, detector notes) is escaped before it reaches the page.
• Fonts are served from the package: no Google Fonts, no analytics, no third-party requests.
• Keyboard-navigable tabs, visible focus, a skip link, and a layout that works on a phone.

Command line reference

Conventions scripts can rely on:

• --json prints exactly one JSON document on stdout. Errors are {"status": "error", "message": …, "code": …}.
• Human-readable errors and warnings go to stderr (error …, then a hint … line); exit status is 1 on error.
• STEGOFORGE_KEY supplies the passphrase; --offline / STEGOFORGE_OFFLINE=1 disables all network access.
• stegoforge COMMAND --help for flags, man stegoforge after a .deb install, stegoforge schema --json for the JSON Schema of every --json output.

eval "$(stegoforge completion bash)"                    # bash
stegoforge completion zsh > "${fpath[1]}/_stegoforge"   # zsh
stegoforge completion fish | source                     # fish

stegoforge deadrop post  -c cover.png -p msg.txt -k "shared key" --upload-url https://…
stegoforge deadrop check --url https://example.com/cover.png -k "shared key"   # payload lands in the current directory
stegoforge deadrop monitor --url https://example.com/cover.png -k "shared key" --interval 30

stegoforge deadrop keyx initiate -c a.png -o a_out.png     # prompts for the private-key-file passphrase
stegoforge deadrop keyx complete -f b_out.png --output-key-file session.key

from core.crypto import aes
from core.image.lsb import LSBEncoder

sealed  = aes.encrypt_envelope(b"secret", "a long passphrase", method="lsb")   # AES-256-GCM, bound to the method
stego   = LSBEncoder().encode(open("photo.png", "rb").read(), sealed, depth=1)
sealed2 = LSBEncoder().decode(stego, depth=1)
assert aes.decrypt_envelope(sealed2, "a long passphrase", method="lsb") == b"secret"

Troubleshooting

Development

pip install -e ".[web]" pytest
python -m pytest tests/ -q                      # 400+ tests: crypto, every encoder, detectors, CLI, web, packaging

uvx ruff check core detect protocol web stegoforge.py stegoforge_ops scripts
uvx --with-requirements requirements.txt mypy core detect protocol stegoforge_ops --ignore-missing-imports

# in a real browser (needs Chrome and Playwright): encode, download, decode, detect, keyboard, phone layout
uvx --with playwright --with pillow --with numpy python scripts/ui_smoke.py

python -m build && python scripts/check_dist.py dist/*     # wheel + sdist, verified to contain the program
python scripts/build_deb.py --out dist-deb                 # Debian package
python scripts/make_readme_media.py                        # regenerate the screenshots and GIFs above from the real program

CI runs the suite on Python 3.10 and 3.12, lint, types, a blocking dependency audit (on 3.12, see the note under Install), the distribution checks, and installs the built .deb with apt. Dependencies are locked for the whole supported range in requirements.hash.lock (scripts/compile_lock.sh regenerates it).

stegoforge.py        CLI entry point (Typer): commands and rendering
stegoforge_ops/      the operation layer shared by CLI and web: encode, decode, detect, capacity, batch, UI helpers, completion
core/
  crypto/            AES-256-GCM envelopes, Argon2id profiles, decoy containers, keyed traversal
  image/ audio/ video/ document/ binary/ network/   one module per method, all subclassing core.base.BaseEncoder
  bits.py errors.py config.py guess.py http.py       shared helpers: bit packing, typed errors, limits, payload sniffing, SSRF-safe client
detect/              the detectors
protocol/            dead drops, X25519 key exchange
web/                 Flask app, template, script, stylesheet and self-hosted fonts
models/              the bundled ONNX model and its checksum
docs/                methods, threat model, detector evaluation, API and error references, man page
scripts/             lock, SBOM, .deb, dist check, UI smoke test, media generator
tests/

Documentation

METHODS · THREAT-MODEL · DETECTOR-EVAL · MODEL-CARD · PROTOCOL · OFFLINE · API · ERRORS · OPENAPI · CHANGELOG

Responsible use

StegoForge is built for digital-forensics research, CTF competitions, privacy work and authorised security testing. Hiding unlawful content, exfiltrating data you are not entitled to take, or evading lawful oversight is illegal in most places, and the covert-channel and dead-drop features must only be used on systems you own or are explicitly authorised to test. The software is provided as is, without warranty (see LICENSE).

Contributing

Issues and pull requests are welcome. A new method subclasses BaseEncoder, honours its error contract, documents its capacity and what it does not survive in docs/METHODS.md, and comes with tests that round-trip a real carrier. Run the checks above before opening a PR.