htb-operator 1.1.0

HTB-Operator - A CLI for accessing Hackthebox

HTB-Operator - A CLI for accessing Hackthebox

OS




Architecture



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.

Restrictions on Windows

Windows imposes certain restrictions or obstacles, which result in not supporting all features. Features/commands which will not work:

• VPN: Starting and stopping

Installation

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

Configuration

You need an API-token from HTB. For that:

1. Visit the URL: https://app.hackthebox.com/profile/settings

2. Click on "Create App Token"

3. Create a token

4. Store the token

5. Call htb-operator init -api YOUR_API_TOKEN

Commands

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

init

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.

Info

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 info

-s / --username

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

-a / --activity

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

certificate

You can list or download obtained certification of completion.

-l / --list

List all obtained certification of completion.

htb-operator certificate --list

download

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.

machine

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.

list

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 ✘/✔.

--limit

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

--retired

If the --retired flag is set, only retired machines are displayed.

htb-operator machine list --retired

--active

If the --active flag is set, only active machines are displayed.

htb-operator machine list --active

--group-by-os

You 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

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

--start-vpn

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

--update-hosts-file

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

--wait-for-release

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

--script <SCRIPT_FILE>

Executes 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")

Example

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

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

stop

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

--stop-vpn

Kills all running HTB-VPN-connection after stopping the machine.

htb-operator machine stop --stop-vpn

--clean-hosts-file

Removes 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-file

Example

You can combine the "stop" flags mentioned above:

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

reset

Just reset the active running machine.

htb-operator machine reset

--update-hosts-file

Updates the hosts file, functioning exactly the same way as in machine start.

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

extend

Extends the expiry time of the machine.

htb-operator machine extend

status

Returns information about the active running machine.

info

Displays detailed information about a machine given by the flag --id or --name.

htb-operator machine info --id 620

submit

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 difficulty rating (from 1="Piece of Cake" to 10="Brainfuck").

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

ssh-grab

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>

challenge

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

search

Using 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

--unsolved

Displays only challenges which are not solved. If both --solved and --unsolved are speicifed, just unsolved challenges will be returned.

--solved

Displays only challenges which are already solved. If both --solved and --unsolved are speicifed, just unsolved challenges will be returned.

--todo

Displays only challenges whose TODO-Flag has been set.

--category

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

--difficulty

Displays only challenges which matches the specified difficulty.

Prolabs

The prolabs command provides commands for listing all ProLabs as well as getting detailed information about a specific ProLab.

list

List all prolabs.

htb-operator prolabs list

info

Get more detailed information about a ProLab which is definied by the --id or --name flag.

htb-operator prolabs info --name APTLabs

VPN

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

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

download

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

start

Start 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

stop

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

htb-operator vpn stop

switch

Switch the accessible VPN-Server(s). The target VPN-Server has to be specified using the --id flag .

htb-operator vpn switch --id 28

benchmark

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

Seasons

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

info

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

badge

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

Pwnbox

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.

status

Read the status of the running pwnbox instance.

htb-operator pwnbox status

ssh

Does not work on Windows.

Establishs a SSH connection with the running pwnbox instance. sshpass must be installed on you system.

htb-operator pwnbox ssh

open

This command opens the Pwnbox Desktop in your default browser.

htb-operator pwnbox open

terminate

It terminates a running Pwnbox instance.

htb-operator pwnbox terminate