Base: http://localhost:19014/api/v1 · OpenAPI/Swagger: /api/docs
Everything the GUI does is available here: the SPA only calls these endpoints.
Auth. If API_KEY (env STEGSUITE_API_KEY) is set, every /api request
(except /api/v1/health) needs the key, as any of:
| Where | For |
|---|---|
header X-API-Key: <key> |
scripts, other containers, agents |
cookie stegsuite_key=<key> |
browser loads (<img>, downloads); the GUI sets it |
query ?key=<key> |
WebSockets, quick links |
The GUI asks for the key on the first 401. ./ctf scan / ./ctf test read it
from .env. Everything listens on 127.0.0.1 by default (BIND_ADDR).
Upload a file, get the tool output + downloadable artifacts. Great for wiring StegSuite's tools into other pipelines.
# list available tools
curl -s localhost:19014/api/v1/tools | jq '.[].name'
# run one tool
curl -s -F file=@challenge.png localhost:19014/api/v1/tools/binwalk-extract | jq .
# → { tool, status, summary, output, artifacts:[{name,path,size}], job_id }
# crack a ZIP/PDF/steghide file with a wordlist (optional password)
curl -s -F file=@secret.zip -F password=secret123 localhost:19014/api/v1/tools/7z | jq .Download an artifact produced by a stateless run:
curl -OJ "localhost:19014/api/v1/tooljobs/<job_id>/files/<artifact-name>"A CTF groups its challenges (each challenge is a project). Its flag_format
is used by the flag hunt of every challenge, and a flag in that format marks
the challenge solved automatically.
# create a CTF: flag_format is a prefix ("DUCTF" / "DUCTF{...}") or a regex
CID=$(curl -s -H 'Content-Type: application/json' \
-d '{"name":"DownUnderCTF 2026","flag_format":"DUCTF{...}","url":"https://play.duc.tf"}' \
localhost:19014/api/v1/ctfs | jq -r .id)
# add challenges (one upload = one challenge; start=true analyzes it now)
curl -s -F name="bad policies" -F category=forensics -F files=@badpolicies.zip \
localhost:19014/api/v1/ctfs/$CID/challenges
# autosolver: analyze every unsolved challenge, 2 at a time
curl -s -X POST -H 'Content-Type: application/json' -d '{"parallel":2}' \
localhost:19014/api/v1/ctfs/$CID/autosolve
curl -s localhost:19014/api/v1/ctfs/$CID/autosolve # progress
curl -s -X DELETE localhost:19014/api/v1/ctfs/$CID/autosolve # stop queueing
# the scoreboard: challenges with status / solved / flag / flags found
curl -s localhost:19014/api/v1/ctfs/$CID | jq '.challenge_list[] | {name,status,solved,flag}'
curl -s localhost:19014/api/v1/ctfs | jq . # all CTFs + counters
# edit a challenge (confirm/correct the flag, move it to another CTF…)
curl -s -X PATCH -H 'Content-Type: application/json' \
-d '{"solved":true,"flag":"DUCTF{...}","category":"misc"}' \
localhost:19014/api/v1/projects/<pid>PATCH /ctfs/{cid} edits name/flag_format/url/notes; DELETE /ctfs/{cid}
removes the CTF and keeps its challenges (detached).
# create (Auto = runs everything + auto-cracks; Check = waits for you)
# optional: -F ctf_id=<cid> -F category=forensics
PID=$(curl -s -F mode=auto -F files=@a.png -F files=@b.jpg \
localhost:19014/api/v1/projects | jq -r .id)
# start / pause / resume / cancel (pause/resume show up as status paused/running)
curl -X POST localhost:19014/api/v1/projects/$PID/start
curl -X POST localhost:19014/api/v1/projects/$PID/pause
curl -X POST localhost:19014/api/v1/projects/$PID/resume
curl -X POST localhost:19014/api/v1/projects/$PID/cancel
# results
curl -s localhost:19014/api/v1/projects/$PID | jq . # project + tree
curl -s localhost:19014/api/v1/projects/$PID/findings | jq . # flags/passwords/notes
curl -s localhost:19014/api/v1/projects/$PID/runs | jq . # per-tool runs + artifacts
curl -s localhost:19014/api/v1/projects/$PID/events | jq . # log
# reports (built server-side: the same text the GUI shows)
curl -s localhost:19014/api/v1/projects/$PID/flags | jq . # each flag: chain of files + evidence
curl -s localhost:19014/api/v1/projects/$PID/summary | jq . # what the GUI highlights: route ids/steps/tree, solver runs, tools
curl -s "localhost:19014/api/v1/projects/$PID/report?lang=it" # Markdown report (lang=en|it)
curl -s "localhost:19014/api/v1/projects/$PID/report?format=json" | jq .
curl -s localhost:19014/api/v1/projects/$PID/logs # event log + every run output
curl -s localhost:19014/api/v1/projects/$PID/transcript # context for an AI agent
# re-run tools on one file (optionally with a password you found); 202, runs in background
curl -X POST -H 'Content-Type: application/json' \
-d '{"tools":["steghide","outguess"],"password":"s3cret"}' \
localhost:19014/api/v1/projects/$PID/files/<fid>/run
# file / artifact / tool output
curl -OJ localhost:19014/api/v1/projects/$PID/files/<fid>/content
curl -OJ localhost:19014/api/v1/projects/$PID/artifacts/<aid>/content
curl -s localhost:19014/api/v1/projects/$PID/files/<fid>/runs/<rid> # one run's output
curl -s localhost:19014/api/v1/projects/$PID/runs/<rid>/artifacts # files a run produced
# crack a locked file (Check mode), choosing wordlists
curl -s localhost:19014/api/v1/projects/$PID/locked
curl -X POST -H 'Content-Type: application/json' \
-d '{"file_id":<fid>,"wordlists":["passwords.txt","rockyou-75.txt"]}' \
localhost:19014/api/v1/projects/$PID/crack
curl -s localhost:19014/api/v1/projects/$PID/crack/status # this project's crack jobs
# the crack queue: one job per file, CRACK_WORKERS at a time (several files of
# the same project can be queued; the same file can't be queued twice)
curl -s localhost:19014/api/v1/cracks | jq '.[] | {id,name,status,password}'
curl -X DELETE localhost:19014/api/v1/cracks/<job id> # cancel a queued job
# delete one project, or the whole history (all projects + files)
curl -X DELETE localhost:19014/api/v1/projects/$PID
curl -X DELETE localhost:19014/api/v1/projectsPOST /projects(multipartfiles,mode=auto) →idPOST /projects/{id}/start, then pollGET /projects/{id}untilstatusisdone/error/cancelled(or follow the WebSocket)GET /projects/{id}/flagsfor the answer and how it was found; if there is none,GET /projects/{id}/transcriptgives the full context to continue from- still locked files:
GET /projects/{id}/locked→POST /projects/{id}/crack
A stdlib client is in ../tools/stegsuite_client.py.
StegSuite is also an MCP server
(Streamable HTTP, stateless) at /api/v1/mcp, with the same API key. With
Claude Code:
claude mcp add --transport http ctf http://127.0.0.1:19014/api/v1/mcp
# with a key: add --header "X-API-Key: <key>"Tools: list_ctfs, create_ctf, ctf_scoreboard, add_challenge (files by
URL or base64), autosolve, analyze, project_status, get_flags,
get_report, get_transcript, read_file, list_tools, run_tools,
locked_files, crack, crack_jobs, list_wordlists, set_challenge, toolbox_services, list_projects, list_inbox.
Sized for small local models (16k context): answers are capped at
STEGSUITE_MCP_MAX_CHARS (default 12000), get_transcript/get_report are
paged (offset), project_status/get_flags are summaries (tree_limit,
verbose). Files on the same machine go in ./data/inbox and are passed as
paths; wait_s waits for the end: analyze(paths=["x.png"], wait_s=300).
Browser requests from foreign origins are refused (STEGSUITE_MCP_ORIGINS).
OpenCode (V2):
GET /api/v1/stats?window=20 returns the dashboard numbers (status/mode
counts, flags, passwords, locked files, top tools) in one call.
GET /api/v1/services lists the other web tools of the toolbox (CyberChef,
ZAP, Wireshark, rev sandbox…) with their URL and whether they are up.
ws://localhost:19014/ws/projects/{pid}→ JSON events (status,file,tool,progress,crack,event).ws://localhost:19014/ws/projects/{pid}/terminal→ PTY bash (cwd = project); send{"t":"i","d":"ls\n"}for input and{"t":"r","c":120,"r":30}to resize.
| Model | Notes |
|---|---|
| Ctf | id, name, flag_format, url, notes |
| Project (challenge) | id, name, status, mode(auto/check), ctf_id, category, solved, flag, timestamps |
| FileNode | id, parent_id, name, rel_path, size, mime, hashes, depth, order_index, origin |
| ToolRun | file_id, tool, status, needs_password, summary, output_path |
| Artifact | run_id, file_id, name, path, size |
| Finding | file_id, kind(flag/password/note), value, source |
| Event | ts, level, message |
Bundled in the repo (wordlists/*.txt) plus full rockyou.txt baked into the
image. They are tried smallest → largest, first match wins.
GET /api/v1/wordlists lists them (name, size, lines).
If your service runs on the same Compose network (ctfnet), reach StegSuite by
service name — no host port, no conflicts:
http://stegsuite:19014/api/v1
Example (from the repo):
docker compose -f compose.yaml -f osint/compose.yaml up -dInside your container:
import urllib.request
urllib.request.urlopen("http://stegsuite:19014/api/v1/health")A ready-made stdlib client is in ../osint/example_client.py;
the osint/ area (override compose + contract) is where a separate developer
adds their own services without touching the core.