Architecture
-supported-success){kind=icon}
-supported-success){kind=icon}
Misc
HTB-Operator is a project developed and maintained by user0x1337. It interacts with the API of HackTheBox, a popular cybersecurity training platform. The main objective is to save time while interacting with the platform of HTB.
Windows imposes certain restrictions or obstacles, which result in not supporting all features. Features/commands which will not work:
- VPN: Starting and stopping
HTB-Operator is written in Python. In general, it can be executed on every OS if python is installed on this OS. But it was only tested on Linux (Kali, Ubuntu) and has some limitations on Windows (I was not in the mood for migrating some features for Windows...maybe later).
It is strongly recommended to create a venv. Use pipx (which will automatically create a virtual python environment) to install htb-operator:
pipx install htb-operatorYou need an API-token from HTB. For that:
-
Visit the URL: https://app.hackthebox.com/profile/settings
-
Click on "Create App Token"
- Create a token
- Store the token
- Call
htb-operator init -api YOUR_API_TOKEN
The API token (and some other settings) will be locally stored on your system in $HOME/.config/htb-operator/config.ini (Linux) / %APPDATA%\htb-operator\config.ini (Windows).
The tool is command based. You can call -h or --help for displaying the help information in each stage. The "top level" commands are displayed if you call the programm without any arguments:
htb-operator
The init command should be the first command you use. As already mentioned above, you need to register your generated API-Key using the init command:
htb-operator init -api YOUR_API_TOKEN
The init command also supports to indicate an alternative URL for accessing HTB API. This should only be used with caution and in an unlikely case when HTB itself changes the API-URL.
The info command retireves the information for a user. If no user is indicated, it will display the information for the authenticated user, i.e. for your user.
htb-operator infoUsing -s USERNAME or --username USERNAME you can search for the user with the username USERNAME and display its profile. E.g.
htb-operator info -s HTBBot
Usually, the activity is limited to the recent 20 entries. Using -a or --activity shows the entire activity history without any limits.
htb-operator info -a-s / --username works with this flag, too.
htb-operator info -a -s HTBBot
You can list or download obtained certification of completion.
List all obtained certification of completion.
htb-operator certificate --list
Using the download subcommand, you are able to download the certificate. With --id you have to indicate the certification id (e.g. obtained by listing all certificates) and with -f or --filename, you can set the target directory and the target filename.
The machine command provides commands for listing all available machines, displaying info about a specific machine, stop, reset and start a machine, and so on.
Lists all active and retired machines. Furthermore, you can add some filter flags for optimizing your view. Check out the provided flags with htb-operator machine list -h.
htb-operator machine list
Active machines which will be retired soon, are flagged as ✘/✔.
As default only the 20 recent machines are displayed. If you want to increase or decrease the number of displyed machine, just use the --limit <NUMBER> flag. For example:
htb-operator machine list --limit 10
If the --retired flag is set, only retired machines are displayed.
htb-operator machine list --retired
If the --active flag is set, only active machines are displayed.
htb-operator machine list --activeYou can change grouping of the result set. Instead of grouping the result by Retired and Active, you can group the result by OS.
htb-operator machine list --group-by-os
Start the instance of a given machine. If another machine already runs, you will asked for terminating the running machine before starting the new one. You must indicate the ID of the machine using --id flag or the name using --name
htb-operator machine start --id 620
If you use this flag, a VPN connection will automatically be established based on the configured VPN-Server. This operation needs root/sudo/admin permission. In Linux, you will be asked for entering your sudo password.
htb-operator machine start --id 620 --start-vpn
If you use this flag, the hosts file in /etc/hosts (Linux) or /drivers/etc/hosts (Windows, not tested) will be updated. The hostname of the machine plus the suffix htb (i.e. HOSTNAME.htb) and the assigned IP address will be inserted. This operation needs root/sudo/admin permission. In Linux, you will be asked for entering your sudo password.
htb-operator machine start --id 620 --update-hosts-file
Only works for scheduled machine. Starting the machine is paused until the release date/time will be reached and will be available for the entire community. It can be useful if you want to get a first blood.
htb-operator machine start --id 620 --wait-for-releaseExecutes a custom bash script when all previous steps are done (i.e. an IP was assigned, possible VPN-Connection has been established, and so on). htb-operator will set the following environment variables:
- $HTB_MACHINE_IP -> Assigned IP
- $HTB_MACHINE_NAME -> Machine name (e.g. "Sea")
- $HTB_MACHINE_OS -> Machine OS ("Linux", "Windows", "FreeBSD", ...)
- $HTB_MACHINE_DIFFICULTY -> Machine's difficulty (e.g. "Easy")
- $HTB_MACHINE_INFO -> Info provided by HTB
- $HTB_MACHINE_HOSTNAME -> Hostname (e.g. "sea.htb")
I would like to run following script:
#!/usr/bin/bash
echo "Starting script, assigned IP $HTB_MACHINE_IP and Hostname $HTB_MACHINE_HOSTNAME"
nmap "$HTB_MACHINE_HOSTNAME" -p 80 --openMy call looks like (as you can see, I can combine the flags for automation):
htb-operator machine start --id 620 --script /tmp/example.sh --start-vpn --update-hosts-file
In my case, I got a warning because I already had a running VPN conneciton. In general, this warning is for your information and you can ignore it.
This command stops an active running machine. This operation needs root/sudo/admin permission. In Linux, you will be asked for entering your sudo password.
htb-operator machine stop
Kills all running HTB-VPN-connection after stopping the machine.
htb-operator machine stop --stop-vpnRemoves the hostname which matches the machine name from your hosts file. This operation needs root/sudo/admin permission. In Linux, you will be asked for entering your sudo password.
htb-operator machine stop --clean-hosts-fileYou can combine the "stop" flags mentioned above:
htb-operator machine stop --stop-vpn --clean-hosts-file
Just reset the active running machine.
htb-operator machine resetUpdates the hosts file, functioning exactly the same way as in machine start.
htb-operator machine reset --update-hosts-fileExtends the expiry time of the machine.
htb-operator machine extendReturns information about the active running machine.
Displays detailed information about a machine given by the flag --id or --name.
htb-operator machine info --id 620
Sumbit the flag for the active machine. Use the flag --user-flag for submitting the user flag, --root-flag for the root flag. You also need to use the flag -d for specifying the level of difficulty (from 1="Piece of Cake" to 10="Brainfuck").
htb-operator machine submit --user-flag <FLAG> -d <DIFFICULTY_RATING>A ssh connection will be established to the victim host. After that, it tries to grab the flag from /home/USERNAME/user.txt (for non-root) or /root/root.txt (for root user) and submit it to HTB for the active running machine. You also need to use the flag -d for specifying the 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 commands for listing all available challenges, displaying info about a specific challenge, downloading files and writeups, starting challenge instances or submitting flags. For example, if you want to download the file, unzip it and start the instance in HTB, you need only one command:
htb-operator challenge download --name "Hunting License" --unzip -sUsing search, you are able to search for challenge which contain the name of the searching word. The argument --name is required.
htb-operator challenge search --name Spook
Displays only challenges which are not solved. If both --solved and --unsolved are speicifed, just unsolved challenges will be returned.
Displays only challenges which are already solved. If both --solved and --unsolved are speicifed, just unsolved challenges will be returned.
Displays only challenges whose TODO-Flag has been set.
Displays only challenges which are part of the specified category. You can specify more than one category, but they must be seperated by commas [,]. For example:
htb-operator challenge search --name Spook --category Web,Crypto,Pwn
Displays only challenges which matches the specified difficulty.
The prolabs command provides commands for listing all ProLabs as well as getting detailed information about a specific ProLab.
List all prolabs.
htb-operator prolabs list
Get more detailed information about a ProLab which is definied by the --id or --name flag.
htb-operator prolabs info --name APTLabs
You can use the submit subcommand for submitting flags. For example:
htb-operator prolabs submit --name "PROLAB" --flag 'HTB{FAKE_FLAG}'
Does not work on Windows.
You can start and stop a HTB-VPN connection. You can also view the status of the HTB-VPN connection. Furthermore, you can download OpenVPN files or execute a benchmark against all or a subset of VPN-Servers.
List all VPN-Servers. You can filter e.g. for locations or for special VPN servers (e.g. labs, prolabs, and so on). You can combine the flags. Use the help command for more information.
htb-operator vpn list --location US
You can download a OpenVPN file for the given VPN-Server ID. You can obtain the VPN-Server ID with the list subcommand mentioned above. Use the help command for more information.
htb-operator vpn download --id <ID> --path /tmp/test.ovpnStart a VPN connection with the given VPN server. If the area or "VPN Access" (as per HTB) is not assigned, htb-operator will attempt to switch to the appropriate "VPN Access" after requesting the user's permission. This action needs root/admin permissions.
htb-operator vpn start --id 35
Stops all running HTB-VPN connections. This action needs root/admin permissions.
htb-operator vpn stop
Switch the accessible VPN-Server(s). The target VPN-Server has to be specified using the --id flag .
htb-operator vpn switch --id 28
Run a benchmark against all VPN-Servers or a subset of the VPN-Servers. Use the help command for more information to refine your test set. This can take a lot time (depending on your internet connection and the size of your test set).
htb-operator vpn benchmark --only-accessible
You can display the results of the current or past seasons using the subcommand list. For more details, you can use the subcommand info.
htb-operator seasons list
The info subcommand provides a flag to display only a subset of the seasons using the flag --ids. Additionally, it allows viewing results from another user using the flag --username. You can combine the flags --ids and --username.
htb-operator seasons info --username HTBBot
You can display all badges in HTB using the command badge with the subcommand list.
htb-operator badge list
You can also filter for "open" badges (i.e. which have not been earned yet) using the flag --open. You can also use the flag --category for filtering for specific categories. Additionally, you can specify another user if you want to display his earning status using the flag --username. You can combine the flags.
htb-operator badge list --username HTBBot --category Rank,Challenge
If you have a running pwnbox instance, you can get the status of the running pwnbox, establish a ssh connection without knowing the credentials, open the pwnbox desktop in your default browser or terminates a running pwnbox instance. Due to implementation restrictions in HTB, it is not possible to start a new pwnbox instance using htb-operator.
Read the status of the running pwnbox instance.
htb-operator pwnbox status
Does not work on Windows.
Establishs a SSH connection with the running pwnbox instance. sshpass must be installed on your system.
htb-operator pwnbox ssh
This command opens the Pwnbox Desktop in your default browser.
htb-operator pwnbox openIt terminates a running Pwnbox instance.
htb-operator pwnbox terminate