incendiary/htb-canvas

# htb-canvas **htb-canvas** 是一款专为 HTB Enterprise 管理员设计的命令行工具。它将每位用户映射至其分配的许可证，同时将每项许可证映射至其分配的用户，从而为您呈现组织内访问权限覆盖情况和席位使用率的清晰全貌。 ## 为什么需要此工具 HTB Enterprise 的 Web UI 将用户与许可证分开独立显示。htb-canvas 将它们关联起来——以便您可以回答以下问题： - 哪些用户尚未分配许可证？ - 哪些许可证使用过度或不足？ - 谁拥有 `admin` 角色，以及该角色覆盖了哪些许可证？ ## 功能特性 - 通过 HTB Enterprise API 枚举所有用户和许可证 - 双向交叉引用用户与许可证 - 按角色对用户进行分组，并显示每个许可证的席位使用率百分比 - 透明处理分页的 API 响应 - 输出适用于终端显示或通过管道重定向至文件的清晰表格视图 ## 架构 ``` main.py └── setup_client() loads config from .env / .secret └── enrich_license_and_user_data(client) ├── LicenseEnumerator fetches all licenses (paginated) ├── UserEnumerator fetches all users (paginated) └── per-license GET fetches assigned users, cross-links both objects Output functions ├── print_users_by_role() grouped user table ├── print_license_summary() seat utilisation per license ├── print_license_assignments() users listed under each license └── print_user_access() licenses listed under each user ``` ``` models/ pagination.py generic paginated_fetch helper (no API coupling) relationships.py enrich_license_and_user_data() users.py UserEnumerator licenses.py LicenseEnumerator assignments.py AssignmentEnumerator (filtered, optional) labs.py LabEnumerator (lab-specific licenses) client.py HTBApiClient — session, Bearer auth, SSL via certifi, error handling ``` ## 设置 ### 1. 安装依赖 ``` pipenv install ``` ### 2. 配置凭证 在项目根目录下创建两个文件： **.env** — 非敏感配置（可安全提交）： ``` BASE_URL=https://enterprise.hackthebox.com/api/ext/v1 API_PATH_LICENSES=/licenses API_PATH_USERS=/users API_PATH_CHANNELS=/channels API_PATH_ACADEMY_MODULES=/academy/modules ``` **.secret** — 您的 API token（已添加至 gitignore，绝不可提交）： ``` HTB_TOKEN=your-api-token-here ``` 您的 token 可以在 HTB Enterprise 面板的 **Settings → API** 中获取。 ## 运行 ``` pipenv run python main.py ``` 输出内容包括： - 按角色分组的用户列表 - 许可证使用情况概览（已分配 / 总席位数，使用率 %） - 每个许可证的用户分配列表 - 每个用户的许可证访问列表 ## 开发 ### 运行测试 ``` pipenv install --dev pipenv run pytest -v ``` ### Lint 和格式化 ``` pipenv run ruff check . pipenv run black . ``` ### 预提交钩子 这些钩子会在每次提交时自动运行 gitleaks、black 和 ruff。 ``` pre-commit install pre-commit run --all-files ``` ## 项目结构 ``` . ├── client.py # HTTP client — auth, SSL, error handling ├── main.py # Entry point and output formatting ├── models/ │ ├── pagination.py # Shared paginated_fetch helper │ ├── relationships.py # User ↔ license cross-reference │ ├── users.py # UserEnumerator │ ├── licenses.py # LicenseEnumerator │ ├── assignments.py # AssignmentEnumerator (filtered) │ └── labs.py # LabEnumerator ├── tests/ │ ├── test_client.py │ ├── test_pagination.py │ └── test_relationships.py ├── .env # Non-sensitive config (committed) ├── .secret # API token (gitignored) ├── .pre-commit-config.yaml # gitleaks + black + ruff hooks ├── pyproject.toml # Black, Ruff, and pytest configuration └── Pipfile # Dependency definitions ``` ## 路线图 | 议题 | 状态 | 描述 | |-------|--------|-------------| | [#1](https://github.com/incendiary/htb-canvas/issues/1) | ✅ 已关闭 | 密钥扫描与 Git 历史审计 | | [#2](https://github.com/incendiary/htb-canvas/issues/2) | ✅ 已关闭 | PEP 8 合规性与 Bug 修复 | | [#3](https://github.com/incendiary/htb-canvas/issues/3) | ✅ 已关闭 | Ruff、Black 及 pre-commit 流水线 | | [#4](https://github.com/incendiary/htb-canvas/issues/4) | ✅ 已关闭 | 专业的 README 与架构概览 | | [#6](https://github.com/incendiary/htb-canvas/issues/6) | ✅ 已关闭 | 针对分页、数据富化及 HTTP 客户端的单元测试套件 | ### 安全强化 - [x] 密钥与代码分离 — API token 从 `.secret`（已添加至 gitignore）加载，非敏感配置存放于 `.env` - [x] Git 历史已审计 — 提交历史中无凭证 ([#1](https://github.com/incendiary/htb-canvas/issues/1)) - [x] `.gitignore` 已覆盖 `__pycache__`、`.venv`、`Pipfile.lock` 及工具缓存 - [x] 已对 `main` 分支开启保护 — 提交 PR 为必填项，禁止强制推送，禁止删除 ### Lint、格式化与流水线 ([#3](https://github.com/incendiary/htb-canvas/issues/3)) - [x] 已在 `pyproject.toml` 中配置 [Ruff](https://docs.astral.sh/ruff/) 和 [Black](https://black.readthedocs.io/) - [x] 包含 GitLeaks、Black 及 Ruff 的 `.pre-commit-config.yaml` 配置 ### 测试 ([#6](https://github.com/incendiary/htb-canvas/issues/6)) - [x] 跨 `pagination`、`relationships` 和 `client` 模块的 10 个单元测试 - [x] 开发依赖中包含 `pytest` 和 `pytest-mock`

标签：API集成, HTB API, HTB Canvas, HTB Enterprise, Python, 企业安全管理, 分页请求处理, 可观测性, 安全培训平台管理, 安全管理, 安全规则引擎, 席位利用率分析, 无后门, 权限审计, 用户与许可证映射, 系统管理员, 终端表格输出, 许可证管理, 账户权限梳理, 资产盘点, 逆向工具