Metadata-Version: 2.4
Name: htb-sdk
Version: 0.2.0
Summary: Unofficial Python SDK for the Hack The Box (labs.hackthebox.com) API, reverse-engineered from live traffic.
Project-URL: Homepage, https://github.com/
Project-URL: Source, https://github.com/
Author: Yihang Wang
License: MIT
Keywords: api,ctf,hackthebox,htb,sdk,security
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Provides-Extra: cli
Requires-Dist: rich>=15.0.0; extra == 'cli'
Requires-Dist: typer>=0.26.7; extra == 'cli'
Provides-Extra: mcp
Requires-Dist: fastmcp>=3.4.2; extra == 'mcp'
Description-Content-Type: text/markdown

# htb-sdk

[![CI](https://github.com/WangYihang/htb-sdk/actions/workflows/ci.yml/badge.svg)](https://github.com/WangYihang/htb-sdk/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/htb-sdk.svg)](https://pypi.org/project/htb-sdk/)
[![Python](https://img.shields.io/pypi/pyversions/htb-sdk.svg)](https://pypi.org/project/htb-sdk/)

Unofficial, typed Python SDK for [Hack The Box](https://www.hackthebox.com) —
reverse-engineered from the live `labs.hackthebox.com` API.

```bash
pip install htb-sdk
```

```python
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`](docs/ENDPOINTS.md).

## CLI & MCP

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

```bash
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/`](examples/); full CLI reference in
[`docs/cli.md`](docs/cli.md). Browse the typed API interactively:

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

## Develop

```bash
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/`](capture/) when HTB changes their API.

## License

MIT
