htb-sdk 0.2.0

Unofficial Python SDK for the Hack The Box (labs.hackthebox.com) API, reverse-engineered from live traffic.

htb-sdk

Unofficial, typed Python SDK for Hack The Box — reverse-engineered from the live labs.hackthebox.com API.

pip install htb-sdk

from htb import HTBClient, Difficulty

htb = HTBClient(token="...")          # or set HTB_TOKEN

htb.user.me()
box = htb.machines.list(per_page=1)[0]
htb.machines.spawn(box["id"])
htb.machines.submit_flag(box["id"], "HTB{...}", Difficulty.MEDIUM)
htb.machines.terminate(box["id"])

htb.get("/api/v4/season/list")        # raw access to any endpoint

Get an App Token at Profile → Settings → App Tokens on app.hackthebox.com.

17 typed resource namespaces — machines, challenges, sherlocks, fortresses, prolabs, endgames, tracks, seasons, teams, universities, rankings, user, connection, pwnbox, tokens, walkthroughs, platform. Full map: docs/ENDPOINTS.md.

CLI & MCP

Both are auto-generated from the SDK — every method is a command and a tool.

pip install htb-sdk[cli]                 # Typer CLI
htb machines list --per-page 5           # Rich table
htb machines spawn 351                   # write ops too
htb machines list --json | jq .          # raw JSON for scripting
htb raw GET /api/v4/season/list          # any endpoint

pip install htb-sdk[mcp]                 # FastMCP server (stdio), reads HTB_TOKEN
htb-mcp                                   # tools: machines_spawn, user_me, …

Docs & examples

Runnable scripts in examples/; full CLI reference in docs/cli.md. Browse the typed API interactively:

uv sync --group docs && uv run mkdocs serve   # http://127.0.0.1:8000

Develop

uv sync --all-groups
uv run pytest            # add --e2e for live tests (needs HTB_TOKEN)

The API map is reverse-engineered from real browser traffic + frontend JS; re-run the pipeline in capture/ when HTB changes their API.

License

MIT