htb-operator - Command-Line tool for accessing HTB

项目说明

HTB-Operator - A CLI for Hack The Box

<img src=" alt="Bild" width="300"/>

!GitHub Tags
!GitHub Releases
!GitHub Repo stars

<div>
<b>Tests</b><br>
<img src="
<br><br>
<b>OS</b><br>
<img alt="current " src="
<img alt="current " src="
<img alt="current " src="
<br><br>
<b>Architecture</b><br>
<img alt="amd64" src=")-supported-success"><br>
<img alt="arm64" src=")-supported-success">
<br><br>
<b>Misc</b><br>
<img alt="current " src="
<br>
<img alt="current " src="
<br><br>
</div>

Unofficial CLI automation tool for Hack The Box workflows

HTB-Operator is de and maintained by user0x1337. It interacts with the Hack The Box API, a popular cybersecurity training platform. Its primary goal is to save time when working with HTB.

<img alt="current " src="

Restrictions on Windows

Windows has platform-specific limitations, so not all features are supported.
Unsupported features/commands:

and stop

Installation

HTB-Operator is written in Python. In general, it can run on any OS with Python installed. It has mainly been tested on Linux (Kali, Ubuntu) and currently has some limitations on Windows.

It is strongly recommended to use a en. Use pipx (which automatically creates an isolated Python en) to install htb-operator:

Configuration

You need an HTB API token:

1. Visit:

2. Click Create App Token.
<img width="1465" height="181" alt="image" src=" />

3. Create a token.
<img width="567" height="409" alt="image" src=" />

4. Store the token.
<img width="562" height="389" alt="image" src=" />

5. Run:

The API token (and other settings) is stored locally at:

Linux: $HOME/.config/htb-operator/config.ini

Windows: %APPDATA%\htb-operator\config.ini

Security Notice

HTB-Operator is an unofficial command-line tool for automating legitimate Hack The Box workflows. It is intended for use with your own Hack The Box account and within authorized HTB lab en only.

The tool stores local configuration , including the HTB API token, in the user's configuration directory. Keep this file private and do not commit API tokens, , logs, flags, configuration files, or challenge-related secrets to public repositories.

Some features may require elevated pri, for example starting or stopping or modifying the local hosts file. Review these actions carefully before execution.

Automation features such as custom scripts are executed locally on your system. Only run scripts you understand and trust.

HTB-Operator is not affiliated with, endorsed by, or officially supported by Hack The Box.

Commands

The tool is command-based. You can use -h or --help at any level to display help information. The top-le are shown when you run the program without arguments:

!image

init

init should be the first command you run. As mentioned above, use it to register your API token:

!image

init also supports an alternative HTB API URL. Use this only with caution and only if HTB changes the API URL.

Info

The info command retrie for a user. If no user is specified, it shows information for the authenticated user.

-s / --username

Using -s USERNAME or --username USERNAME, you can display the profile of USERNAME. Example:

!image

-a / --activity

By default, activity is limited to the most recent 20 entries. Use -a or --activity to show the full activity history.

-s / --username also works with this flag:

!image

certificate

You can list or download earned certificates of completion.

-l / --list

List all earned certificates of completion:

!image

download

Using the download subcommand, you can download a certificate. With --id, specify the certificate ID (for example, from --list), and with -f / --filename, set the target path and filename.

!image

machine

The machine command provides subcommands to list machines, display details, and start, stop, or reset machines.

list

Lists active and retired machines. You can add filter flags to optimize the output. See a flags with htb-operator machine list -h.

!image

Acti that will be retired soon are marked as ✘/✔.

--limit

By default, the 20 most recent machines are shown. Use --limit <NUMBER> to change that value. Example:

!image

--retired

If --retired is set, only retired machines are shown.

!image

--active

If --active is set, only acti are shown.

--group-by-os

Changes grouping of the result set. Instead of grouping by Retired and Active, output is grouped by OS.

!image

start

Starts an instance of a machine. If another machine is already running, you will be asked whether to stop it before starting the new one. Specify either --id or --name.

!image

--start-vpn

If set, a is established automatically based on the configured . This action requires root/sudo/admin permissions. On Linux, you will be prompted for your sudo password.

!image

--update-hosts-file

If set, the hosts file in /etc/hosts (Linux) or /drivers/etc/hosts (Windows, not tested) is updated. The machine hostname plus suffix htb (for example HOSTNAME.htb) and the assigned IP address are added. This action requires root/sudo/admin permissions. On Linux, you will be prompted for your sudo password.

!image

--wait-for-release

Works only for scheduled machines. Starting is paused until the machine reaches its release date/time and is a to the full community. This is useful if you want to aim for first blood.

--script <SCRIPT_FILE>

Executes a custom Bash script after all prior steps are complete (for example, IP assignment and optional ). htb-operator sets these en :

$HTB_MACHINE_IP -> assigned IP

$HTB_MACHINE_NAME -> machine name (for example Sea)

$HTB_MACHINE_OS -> machine OS (Linux, Windows, FreeBSD, ...)

$HTB_MACHINE_DIFFICULTY -> machine difficulty (for example Easy)

$HTB_MACHINE_INFO -> information provided by HTB

$HTB_MACHINE_HOSTNAME -> hostname (for example sea.htb)

#### Example
Example script:

Command (flags can be combined for automation):

!image

In this example, a warning appeared because a was already running. This is informational and can usually be ignored.

stop

Stops the currently acti.

!image

--stop-vpn

Stops all running HTB after stopping the machine. This action requires root/sudo/admin permissions. On Linux, you will be prompted for your sudo password.

--clean-hosts-file

Removes the hostname that matches the machine name from your hosts file. This action requires root/sudo/admin permissions. On Linux, you will be prompted for your sudo password.

Example

You can combine the stop flags shown above:

!image

reset

Resets the currently acti.

--update-hosts-file

Updates the hosts file, working exactly like machine start --update-hosts-file.

extend

Extends the machine expiry time.

status

Returns information about the currently acti.

!image

info

Displays detailed information about a machine specified via --id or --name.

!image

submit

Submits a flag for the acti. Use --user-flag for the user flag and --root-flag for the root flag. You also need -d to rate difficulty (from 1 = Piece of Cake to 10 = Brainfuck).

ssh-grab

Establishes an SSH connection to the target host. It then attempts to read the flag from /home/USERNAME/user.txt (non-root) or /root/root.txt (root), and submits it to HTB for the currently acti. You also need -d to provide a difficulty rating (from 1 = Piece of Cake to 10 = Brainfuck).

challenge

The challenge command provides subcommands to list challenges, display details, download files/writeups, start challenge instances, and submit flags. Example: download files, unzip them, and start the instance with one command:

search

Use search to find challenges that contain the search term. --name is required.

!image

--unsolved

Shows only unsol. If both --solved and --unsolved are provided, unsol are returned.

--solved

Shows only sol. If both --solved and --unsolved are provided, unsol are returned.

--todo

Shows only challenges with the TODO flag set.

--category

Shows only challenges in the specified category. You can provide multiple categories separated by commas. Example:

!image

--difficulty

Shows only challenges that match the specified difficulty.

Prolabs

The prolabs command provides subcommands to list all ProLabs and retrie for a specific ProLab.

list

Lists all ProLabs.

!image

info

Gets detailed information about a ProLab specified via --id or --name.

!image

info already includes ProLab flags and machines. For focused views, use these dedicated subcommands:

flags

List only ProLab flags.

machines

List only ProLab machines.

progress

Show ownership/certificate progress and milestone status.

changelog

Show ProLab changelog entries. By default, the latest 20 entries are displayed.

reset-status

Show reset status and the timestamp of the last reset (if a).

submit

Use submit to submit ProLab flags. Example:

VPN

Does not work on Windows.

You can start and stop HTB , view , download Open, and run benchmarks against all or selected .

list

Lists . You can filter, for example, by location or server type (labs, prolabs, etc.). Flags can be combined. Use the help command for details.

!image

download

Downloads an OpenVPN file for a given ID. You can get the ID from the list subcommand. Use the help command for details.

start

Starts a for the gi. If the area or "" (as defined by HTB) is not assigned, htb-operator will try to switch to the appropriate "" after asking for confirmation. This action requires root/admin permissions.

!image

stop

Stops all running HTB . This action requires root/admin permissions.

!image

switch

Switches accessible (s). Specify the target ser --id.

!image

benchmark

Runs a benchmark against all or a selected subset. Use the help command to refine the test set. This may take significant time, depending on your internet connection and the test size.

!image

Seasons

You can display results for current or past seasons with the list subcommand. For more details, use info.

!image

info

The info subcommand provides --ids to show only selected seasons. It also supports --username to view another user's results. You can combine --ids and --username.

!image

badge

You can display all HTB badges using badge list.

!image

You can also filter for open badges (not yet earned) with --open. Use --category to filter by category. You can additionally use --username to display another user's badge status. Flags can be combined.

!image

Pwnbox

If you have a running Pwnbox instance, you can check status, establish an SSH connection without manually handling credentials, open the Pwnbox desktop in your default browser, or terminate the running instance. Due to HTB implementation restrictions, starting a new Pwnbox instance via htb-operator is currently not possible.

status

Reads the status of the running Pwnbox instance.

!image

ssh

Does not work on Windows.

Establishes an SSH connection to the running Pwnbox instance. sshpass must be installed on your system.

!image

open

Opens the Pwnbox desktop in your default browser.

terminate

Terminates the running Pwnbox instance.

!image

项目信息

开发语言：Python

Star 数：74

技术要点

该项目属于CTF思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Command-Line tool for accessing HTB展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。