k31337/htb-cli

# htb-cli      一个非官方的命令行工具，用于查询 [Hack The Box](https://www.hackthebox.com/) API：浏览靶机和挑战，生成和管理你的活动实例，提交 flag，管理你的 VPN，追踪赛季和排行榜，以及查看你的个人资料，所有这些都可以在终端中完成。 基于 [Typer](https://typer.tiangolo.com/)、[Rich](https://rich.readthedocs.io/) 和 [httpx](https://www.python-httpx.org/) 构建。 ## 目录 - [功能](#features) - [环境要求](#requirements) - [安装](#installation) - [配置](#configuration) - [使用方法](#usage) - [故障排除](#troubleshooting) - [运行测试](#running-tests) - [项目结构](#project-structure) - [免责声明](#disclaimer) ## 功能 - 浏览活动和已退役的靶机，支持分页和带颜色的难度标识 - 查看单个靶机或挑战的完整详情 - 生成、重置和停止你的活动靶机 - 直接从终端提交 user/root flag - 按分类浏览挑战 - 查看你自己的 HTB 资料和统计数据 - 管理你的 VPN 连接：检查状态、列出服务器、切换服务器以及下载 `.ovpn` 文件 - 浏览 HTB 赛季：列出各个赛季、查看当前活动赛季的靶机、检查你的排名和进度 - 浏览排行榜：全球顶尖用户、团队、大学以及按国家/地区排名 - 在每个读取命令上支持原始 JSON 输出 (`--json`)，方便用于脚本编写 ## 环境要求 - Python 3.10 或更高版本 - 一个 HTB API token ### 获取你的 HTB token 1. 登录 [hackthebox.com](https://www.hackthebox.com/) 2. 前往 **Settings > App Tokens** 3. 创建一个新 token 并复制它 请妥善保管此 token。任何持有它的人都可以在 API 上模拟你的身份进行操作。如果发生泄露，请立即在同一设置页面将其撤销，并创建一个新的 token。 ## 安装 ``` git clone https://github.com/k31337/htb-cli.git cd htb-cli ``` ### 选项 1：pipx（推荐） [pipx](https://pipx.pypa.io/) 会将 CLI 安装在其独立的隔离环境中，但能让 `htb` 命令在全局可用，无需激活任何环境。 ``` python -m pip install --user pipx python -m pipx ensurepath ``` 关闭并重新打开你的终端以使 `PATH` 更改生效，然后执行： ``` pipx install -e . ``` `-e`（可编辑）标志意味着 pipx 会直接链接到这个代码库，因此你拉取或做出的任何更改都会立即生效，无需重新安装。 ### 选项 2：虚拟环境 ``` python -m venv .venv pip install -e . ``` 激活虚拟环境（每次打开新终端时都要执行此操作）： ``` source .venv/Scripts/activate # Git Bash .venv\Scripts\Activate.ps1 # PowerShell .venv\Scripts\activate.bat # CMD ``` ## 配置 你有两种身份验证方式： ### 选项 1：`htb login`（跨会话持久化） ``` htb login ``` 系统会提示你输入 token（输入会被隐藏）。它会保存到 `~/.htb-cli/config.json` 中，并且每次运行 CLI 时都会自动加载，即使关闭了终端也是如此。 要移除它： ``` htb logout ``` ### 选项 2：`HTB_TOKEN` 环境变量（仅限当前会话） ``` export HTB_TOKEN=your_token_here # Git Bash $env:HTB_TOKEN = "your_token_here" # PowerShell set HTB_TOKEN=your_token_here # CMD ``` 这仅在当前终端会话中有效，如果同时设置了两者，它的优先级高于已保存的登录信息。 ## 使用方法 ``` htb --help htb --help ``` ### 命令 | 命令 | 描述 | | -------------------------------------- | ------------------------------------------------------ | | `htb login` | 保存你的 API token，这样就无需再次设置 | | `htb logout` | 移除已保存的 API token | | `htb version` | 显示 CLI 版本 | | `htb machines [--retired] [--json]` | 列出活动或已退役的靶机 | | `htb machine [--json]` | 显示单个靶机的详细信息 | | `htb spawn ` | 生成靶机并等待获取其 IP | | `htb stop ` | 停止活动靶机 | | `htb reset ` | 重置活动靶机 | | `htb submit ` | 提交 user/root flag | | `htb challenges [--json]` | 列出挑战 | | `htb challenge [--json]` | 显示单个挑战的详细信息 | | `htb profile [--json]` | 显示你自己的 HTB 资料 | | `htb vpn status [--json]` | 显示你当前分配的 VPN 服务器 | | `htb vpn servers [--json]` | 列出可用的 VPN 服务器 | | `htb vpn switch ` | 切换到不同的 VPN 服务器 | | `htb vpn download [--tcp] [-o file]` | 下载服务器的 `.ovpn` 配置文件 | | `htb season list [--json]` | 列出所有 HTB 赛季 | | `htb season machines [--json]` | 列出当前活动赛季中的靶机 | | `htb season progress [--json]` | 显示你在当前活动赛季中的进度 | | `htb leaderboard users [--json]` | 全球顶尖黑客 | | `htb leaderboard teams [--json]` | 全球顶尖团队 | | `htb leaderboard universities [--json]` | 全球顶尖大学 | | `htb leaderboard country [--json]` | 特定国家/地区的顶尖黑客（例如 ES, US, DE） | 较长的列表每次会分页显示 15 条结果：按 `n` 键查看下一页，`p` 查看上一页，`q` 退出。向任何读取命令传递 `--json` 参数以获取原始 JSON 数据，从而方便通过管道传递给 `jq` 等工具。 ### 典型操作流程 ``` htb login htb vpn servers htb vpn switch 698 htb vpn download 698 -o lab.ovpn htb machines htb spawn 912 htb submit 912 32f7a3b1... htb stop 912 ``` ## 故障排除 - **`'htb' is not recognized as an internal or external command`**：如果你使用 pipx 安装，请确保你执行了 `pipx ensurepath` 并重新打开了终端，并且是从代码库文件夹中运行的 `pipx install -e .`。如果你使用的是 venv 方式，请按照上述说明激活虚拟环境。 - **`HTB token not found`**：运行 `htb login`，或者在当前终端会话中设置 `HTB_TOKEN` 环境变量。 - **`Invalid or expired token`**：从 Settings > App Tokens 生成一个新的 token，然后再次运行 `htb login`（或更新 `HTB_TOKEN`）。 - **`Not found. Check the ID or name and try again.`**：ID/名称不存在或输入错误——请在 HTB 网站上仔细核对。 - **生成/重置失败并提示关于 VIP 的信息**：启动大多数活动靶机需要订阅 HTB VIP。 ## 运行测试 测试使用 [respx](https://lundberg.github.io/respx/) 模拟 HTB API，因此不需要真实的 token 或网络访问权限。 ``` pip install -e ".[test]" pytest -v ``` ## 项目结构 ``` src/htb_cli/ ├── __init__.py ├── api.py # HTTP client for the HTB API ├── cli.py # Entry point: registers commands from each module below └── commands/ ├── _shared.py # Shared console, error handling, pagination, formatters ├── auth.py # version, login, logout ├── machines.py # machines, machine, spawn, stop, reset, submit ├── challenges.py # challenges, challenge ├── profile.py # profile ├── vpn.py # vpn status, vpn servers, vpn switch, vpn download ├── season.py # season list, season machines, season progress └── leaderboard.py # leaderboard users, teams, universities, country tests/ ├── conftest.py # Shared fixtures (fake token, isolated config file) ├── test_token_storage.py ├── test_api_client.py └── test_vpn_season_leaderboard.py ``` ## 免责声明 这是一个非官方的、由社区构建的工具，不附属于 Hack The Box，也未获得其认可。请仅使用你自己的账号和 API token 进行操作，并遵守 [Hack The Box 的服务条款](https://www.hackthebox.com/terms-and-conditions)。