Okymi-X/htb-terminal

# htb-terminal [](https://github.com/Okymi-X/htb-terminal/actions/workflows/ci.yml) [](https://www.python.org/) [](LICENSE) 针对精选 HTB Labs v4 API 工作流的 Python 终端客户端： 靶机、VPN、OVPN 文件以及原始 API 调用。零外部依赖。 请参阅[命令参考](docs/commands.md)以了解每个命令、选项、 默认值以及每个命令调用的 API endpoint。 ## 来源 - 官方 HTB Enterprise Public API 文档：https://enterprise-help.hackthebox.com/en/articles/13375637-introduction-to-enterprise-public-api - 官方关于 Lab/OpenVPN 访问的 HTB 文章：https://help.hackthebox.com/en/articles/5185687-gs-introduction-to-lab-access - v4 Postman 集合：https://documenter.getpostman.com/view/13129365/TVeqbmeq - 易读的 Labs v4 endpoint 社区参考：https://github.com/D3vil0p3r/HackTheBox-API 注意：HTB 官方记录了 Enterprise API。此处使用的 Labs v4 endpoint 来自于 Postman 集合和社区参考；它们可能会在不另行通知的情况下发生更改。 ## 截图 紧凑的活动靶机输出保留了会话详情和仅限 profile 的状态文本，具有高可读性，且不会输出完整的 HTB profile。  表格默认使用紧凑的列、终端颜色和截断显示。当需要完整值时，请使用 `--wide`。  ## 安装说明 需要 Python 3.10+。本项目没有外部依赖。 使用 [pipx](https://pipx.pypa.io)（推荐）作为全局命令安装，这样就可以从任何目录使用 `htb`： ``` pipx install htbx htb --help ``` 或者使用 pip： ``` pip install htbx htb --help ``` 该 package 在 PyPI 上发布为 **`htbx`**；它会安装 `htb` 命令 （同时也会安装一个 `htbx` alias）。如果不想安装，想直接从源码运行最新版本，请使用 clone： ``` chmod +x ./htb ./htb --help ``` ### 认证 从你的 HTB profile 设置中生成一个 App Token，然后使用 `init` 保存一次： ``` htb init # 粘贴你的 HTB App Token (输入已隐藏): ... ``` `init` 会将 token 及其仅限所有者的权限存储在你的用户 config 目录中 （`~/.config/htb-terminal/token`，或 `$XDG_CONFIG_HOME/htb-terminal/token`）， 因此通过 pipx 安装的 `htb` 可以在任何地方找到它。 你也可以通过非交互式方式传递它： ``` htb init --token "$MY_TOKEN" echo "$MY_TOKEN" | htb init ``` token 的解析顺序如下，以第一个匹配项为准： 1. `HTB_API_TOKEN` 环境变量。 2. `--token-file PATH`（如果提供）。 3. 当前目录下的 `./api.token`（作为针对特定项目的覆盖很方便）。 4. 由 `htb init` 写入的用户 config 文件。 `api.token` 已被 gitignored；切勿提交你的 token。 ## 示例 每个命令的完整详情请见[命令参考](docs/commands.md)。 ``` ./htb machine active ./htb machine profile "BoardLight" ./htb machine list ./htb machine list --retired --page 1 ./htb machine list --sp-tier 1 ./htb machine search board ./htb machine search kerberos --all --limit 10 ./htb machine search "breach creds" --all --profiles ./htb machine start "BoardLight" --mode auto ./htb machine start 444 --mode play ./htb machine start 478 --mode spawn ./htb machine stop ./htb machine reset ./htb machine submit 444 HTB{flag} --difficulty 50 ./htb vpn servers ./htb vpn switch us-free-1 ./htb vpn download us-free-1 -o lab-vpn.ovpn ./htb vpn connect us-free-1 -o lab-vpn.ovpn ./htb raw GET /machine/active ./htb raw POST /vm/spawn --data '{"machine_id":478}' ``` ## 输出 默认情况下，命令会打印人类可读的输出，并在 stdout 是交互式终端时自动根据终端宽度进行换行和着色。 在脚本中使用原始 JSON： ``` ./htb --json machine active ``` 可以全局控制颜色： ``` ./htb --color never machine active ./htb --color always machine list ``` 表格默认是紧凑的，并将过长的单元格截断以适应常见的终端宽度。使用 `--wide` 可保留完整的表格值： ``` ./htb --wide machine list ./htb --wide machine search active-directory --all ``` 当有活动的靶机时，`machine active` 会使用匹配的靶机 profile 来丰富活动会话响应，但默认只打印紧凑的摘要。当 HTB 返回结果时，该摘要会包含有用的、仅限 profile 的文本，例如 `info_status` 和 `description`。使用 `--details` 获取简介和 Academy 模块名称，或在命令前使用 `--json` 获取完整的丰富响应： ``` ./htb machine active --details ./htb --json machine active ``` ## 靶机搜索 `machine search` 有意使用已记录/列出的 Labs v4 靶机列表 endpoint，并在本地过滤结果。它不依赖于未公开的搜索 endpoint。 默认情况下，它会扫描可玩的靶机： ``` ./htb machine search linux ``` 有用的选项： - `--retired`：仅搜索已退役的靶机。 - `--all`：搜索可玩和已退役的靶机。 - `--profiles`：同时获取每个扫描到的靶机 profile，并搜索仅限 profile 的字段（例如描述）。 - `--limit N`：在打印最多 `N` 个匹配项后停止。 - `--max-pages N`：限制每个列表扫描的 API 页数。 如果没有 `--profiles`，查询将匹配靶机 ID、名称、OS、难度、标签、创建者名称以及常见的列表字段。对于可能只存在于详细靶机 profile 中的术语（例如提及泄露凭据的描述文本），请使用 `--profiles`。 ## 架构 - `htb_terminal/config.py`：加载 token 和 API URL。 - `htb_terminal/http.py`：经过认证的 HTTP 客户端。 - `htb_terminal/output.py`：人类可读和 JSON 渲染。 - `htb_terminal/services/machines.py`：`MachineService` — 靶机 API 操作。 - `htb_terminal/services/payloads.py`：重塑靶机列表 JSON 的纯辅助函数。 - `htb_terminal/services/search.py`：本地靶机搜索和结果排名。 - `htb_terminal/services/spawn.py`：瞬态生成失败检测。 - `htb_terminal/services/vpn.py`：VPN 和 OVPN 操作。 - `htb_terminal/cli.py`：CLI 解析和编排。 每个模块都保持单一的职责，以便在 HTB 更改 endpoint 时更容易进行未来的更改。`MachineService` 只与 API 交互；payload 重塑、搜索排名和生成错误检测是它所组成的状态无关模块，因此它们可以独立进行测试并保持精简。 ## 开发 安装开发工具并运行测试套件： ``` pip install -e ".[dev]" pytest ruff check . ``` 这些测试也可以仅使用标准库运行： ``` python3 -m unittest discover -s tests -v ``` ## 许可证 MIT — 见 [LICENSE](LICENSE)。

标签：API客户端, Blue Team, Hack The Box, Python, SOC Prime, 开发工具, 文档结构分析, 无后门, 逆向工具, 零依赖