OS
Architecture
-supported-success){kind=icon}
-supported-success){kind=icon}
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.
Windows has platform-specific limitations, so not all features are supported. Unsupported features/commands:
- VPN start and stop
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-operatorYou need an HTB API token:
-
Click Create App Token.
- Create a token.
- Store the token.
- Run:
htb-operator init -api YOUR_API_TOKENThe API token (and other settings) is stored locally at:
- Linux:
$HOME/.config/htb-operator/config.ini - Windows:
%APPDATA%\htb-operator\config.ini
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 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.
The info command retrieves information for a user. If no user is specified, it shows information for the authenticated user.
htb-operator infoUsing -s USERNAME or --username USERNAME, you can display the profile of USERNAME. Example:
htb-operator info -s HTBBot
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
You can list or download earned certificates of completion.
List all earned certificates of completion:
htb-operator certificate --list
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.
The machine command provides subcommands to list machines, display details, and start, stop, or reset machines.
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 ✘/✔.
By default, the 20 most recent machines are shown. Use --limit <NUMBER> to change that value. Example:
htb-operator machine list --limit 10
If --retired is set, only retired machines are shown.
htb-operator machine list --retired
If --active is set, only active machines are shown.
htb-operator machine list --activeChanges grouping of the result set. Instead of grouping by Retired and Active, output is grouped by OS.
htb-operator machine list --group-by-os
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
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
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
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-releaseExecutes 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 exampleSea)$HTB_MACHINE_OS-> machine OS (Linux,Windows,FreeBSD, ...)$HTB_MACHINE_DIFFICULTY-> machine difficulty (for exampleEasy)$HTB_MACHINE_INFO-> information provided by HTB$HTB_MACHINE_HOSTNAME-> hostname (for examplesea.htb)
Example script:
#!/usr/bin/bash
echo "Starting script, assigned IP $HTB_MACHINE_IP and hostname $HTB_MACHINE_HOSTNAME"
nmap "$HTB_MACHINE_HOSTNAME" -p 80 --openCommand (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.
Stops the currently active machine.
htb-operator machine stop
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-vpnRemoves 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-fileYou can combine the stop flags shown above:
htb-operator machine stop --stop-vpn --clean-hosts-file
Resets the currently active machine.
htb-operator machine resetUpdates the hosts file, working exactly like machine start --update-hosts-file.
htb-operator machine reset --update-hosts-fileExtends the machine expiry time.
htb-operator machine extendReturns information about the currently active machine.
Displays detailed information about a machine specified via --id or --name.
htb-operator machine info --id 620
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>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>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 -sUse search to find challenges that contain the search term. --name is required.
htb-operator challenge search --name Spook
Shows only unsolved challenges. If both --solved and --unsolved are provided, unsolved challenges are returned.
Shows only solved challenges. If both --solved and --unsolved are provided, unsolved challenges are returned.
Shows only challenges with the TODO flag set.
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
Shows only challenges that match the specified difficulty.
The prolabs command provides subcommands to list all ProLabs and retrieve details for a specific ProLab.
Lists all ProLabs.
htb-operator prolabs list
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:
List only ProLab flags.
htb-operator prolabs flags --name APTLabsList only ProLab machines.
htb-operator prolabs machines --name APTLabsShow ownership/certificate progress and milestone status.
htb-operator prolabs progress --name APTLabsShow ProLab changelog entries. By default, the latest 20 entries are displayed.
htb-operator prolabs changelog --name APTLabs --limit 20Show reset status and the timestamp of the last reset (if available).
htb-operator prolabs reset-status --name APTLabsUse submit to submit ProLab flags. Example:
htb-operator prolabs submit --name "PROLAB" --flag 'HTB{FAKE_FLAG}'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.
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
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.ovpnStarts 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
Stops all running HTB VPN connections. This action requires root/admin permissions.
htb-operator vpn stop
Switches accessible VPN server(s). Specify the target server using --id.
htb-operator vpn switch --id 28
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
You can display results for current or past seasons with the list subcommand. For more details, use info.
htb-operator seasons list
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
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
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.
Reads the status of the running Pwnbox instance.
htb-operator pwnbox status
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
Opens the Pwnbox desktop in your default browser.
htb-operator pwnbox openTerminates the running Pwnbox instance.
htb-operator pwnbox terminate