htb-operator 1.4.3

HTB-Operator - A CLI for accessing Hackthebox

HTB-Operator - A CLI for Hack The Box

Tests


OS




Architecture



Misc

HTB-Operator is developed 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.

Restrictions on Windows

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

• VPN start 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 virtual environment. Use pipx (which automatically creates an isolated Python environment) to install htb-operator:

pipx install htb-operator

Configuration

You need an HTB API token:

1. Visit: https://app.hackthebox.com/account-settings

2. Click Create App Token.

3. Create a token.

4. Store the token.

5. Run:

htb-operator init -api YOUR_API_TOKEN

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

• Linux: $HOME/.config/htb-operator/config.ini
• Windows: %APPDATA%\htb-operator\config.ini

Commands

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

htb-operator

init

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

htb-operator init -api YOUR_API_TOKEN

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 retrieves information for a user. If no user is specified, it shows information for the authenticated user.

htb-operator info

-s / --username

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

htb-operator info -s HTBBot

-a / --activity

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

htb-operator info -a

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

htb-operator info -a -s HTBBot

certificate

You can list or download earned certificates of completion.

-l / --list

List all earned certificates of completion:

htb-operator certificate --list

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.

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 available flags with htb-operator machine list -h.

htb-operator machine list

Active machines 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:

htb-operator machine list --limit 10

--retired

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

htb-operator machine list --retired

--active

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

htb-operator machine list --active

--group-by-os

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

htb-operator machine list --group-by-os

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.

htb-operator machine start --id 620

--start-vpn

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

htb-operator machine start --id 620 --start-vpn

--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.

htb-operator machine start --id 620 --update-hosts-file

--wait-for-release

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

htb-operator machine start --id 620 --wait-for-release

--script <SCRIPT_FILE>

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

• $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:

#!/usr/bin/bash

echo "Starting script, assigned IP $HTB_MACHINE_IP and hostname $HTB_MACHINE_HOSTNAME"
nmap "$HTB_MACHINE_HOSTNAME" -p 80 --open

Command (flags can be combined for automation):

htb-operator machine start --id 620 --script /tmp/example.sh --start-vpn --update-hosts-file

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

stop

Stops the currently active machine.

htb-operator machine stop

--stop-vpn

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

htb-operator machine stop --stop-vpn

--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.

htb-operator machine stop --clean-hosts-file

Example

You can combine the stop flags shown above:

htb-operator machine stop --stop-vpn --clean-hosts-file

reset

Resets the currently active machine.

htb-operator machine reset

--update-hosts-file

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

htb-operator machine reset --update-hosts-file

extend

Extends the machine expiry time.

htb-operator machine extend

status

Returns information about the currently active machine.

info

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

htb-operator machine info --id 620

submit

Submits a flag for the active machine. 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).

htb-operator machine submit --user-flag <FLAG> -d <DIFFICULTY_RATING>

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 active machine. You also need -d to provide a difficulty rating (from 1 = Piece of Cake to 10 = Brainfuck).

htb-operator machine ssh-grab -u <SSH-USERNAME> -p <SSH-PASSWORD> -i <TARGET_HOST> -d <DIFFICULT_RATING>

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:

htb-operator challenge download --name "Hunting License" --unzip -s

search

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

htb-operator challenge search --name Spook

--unsolved

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

--solved

Shows only solved challenges. If both --solved and --unsolved are provided, unsolved challenges 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:

htb-operator challenge search --name Spook --category Web,Crypto,Pwn

--difficulty

Shows only challenges that match the specified difficulty.

Prolabs

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

list

Lists all ProLabs.

htb-operator prolabs list

info

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

htb-operator prolabs info --name APTLabs

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

flags

List only ProLab flags.

htb-operator prolabs flags --name APTLabs

machines

List only ProLab machines.

htb-operator prolabs machines --name APTLabs

progress

Show ownership/certificate progress and milestone status.

htb-operator prolabs progress --name APTLabs

changelog

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

htb-operator prolabs changelog --name APTLabs --limit 20

reset-status

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

htb-operator prolabs reset-status --name APTLabs

submit

Use submit to submit ProLab flags. Example:

htb-operator prolabs submit --name "PROLAB" --flag 'HTB{FAKE_FLAG}'

VPN

Does not work on Windows.

You can start and stop HTB VPN connections, view VPN status, download OpenVPN files, and run benchmarks against all or selected VPN servers.

list

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

htb-operator vpn list --location US

download

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

htb-operator vpn download --id <ID> --path /tmp/test.ovpn

start

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

htb-operator vpn start --id 35

stop

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

htb-operator vpn stop

switch

Switches accessible VPN server(s). Specify the target server using --id.

htb-operator vpn switch --id 28

benchmark

Runs a benchmark against all VPN servers 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.

htb-operator vpn benchmark --only-accessible

Seasons

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

htb-operator seasons list

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.

htb-operator seasons info --username HTBBot

badge

You can display all HTB badges using badge list.

htb-operator badge list

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.

htb-operator badge list --username HTBBot --category Rank,Challenge

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.

htb-operator pwnbox status

ssh

Does not work on Windows.

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

htb-operator pwnbox ssh

open

Opens the Pwnbox desktop in your default browser.

htb-operator pwnbox open

terminate

Terminates the running Pwnbox instance.

htb-operator pwnbox terminate