hackthebox.htb — The HTB API Client

Session Caching

If the cache option is sent when initializing an API client, the library will follow this algorithm:

• Check if the given path exists

  • If it does, load the refresh_token and access_token from the file.

  • Check if the refresh_token is expired

    • If it is, attempt to use the refresh_token to gain a new token

    • If this fails, fall back to a login prompt

  • If it doesn’t, fall back to a login prompt

• If it doesn’t, fall back to a login prompt

• After any login prompts, and at program exit, the current token pair will be dumped out to the cache file.

If the option is not set, no cache is used at all.

API Client

class hackthebox.htb.HTBClient(email: Optional[str] = None, password: Optional[str] = None, otp: Optional[str | int] = None, cache: Optional[str] = None, api_base: str = 'https://www.hackthebox.com/api/v4/', remember: Optional[bool] = False, app_token: Optional[str] = None)

The client via which API requests are made

Examples

Connecting to the API:

from hackthebox import HTBClient
client = HTBClient(email="user@example.com", password="S3cr3tP455w0rd!")

challenge_cooldown

Time when next download is allowed

Type

int

Authenticates to the API.

If cache is set, the client will attempt to load access tokens from the given path. If they cannot be found, or are expired, normal API authentication will take place, and the tokens will be dumped to the file for the next launch.

Parameters

• email – The authenticating user’s email address

• password – The authenticating user’s password

• otp – The current OTP of the user, if 2FA is enabled

• cache – The path to load/store access tokens from/to

• remember – Whether to create a long-lasting ‘remember me’ token

• app_token – Authenticate using a provided App Token

do_login(email: Optional[str] = None, password: Optional[str] = None, otp: Optional[str | int] = None, remember: Optional[bool] = False, app_token: Optional[str] = None)

Authenticates against the API. If credentials are not provided, they will be prompted for.

do_request(endpoint, json_data=None, data=None, authorized=True, download=False, post=False) → Union[dict, bytes]

Parameters

• endpoint – The API endpoint to request

• json_data – Data to be sent in JSON format

• data – Data to be sent in application/x-www-form-urlencoded format

• authorized – If the request requires an Authorization header

• download – If we are downloading raw data

• post – Force POST request

Returns

The JSON response from the API or the raw data (if download is set)

dump_to_cache(cache)

Dumps the current access and refresh tokens to a file :param cache: The path to the cache file

get_active_machine(release_arena: bool = False) → Optional[MachineInstance]

Retrieve Machine currently assigned to user

Returns: The Machine currently assigned (or active) to user

get_all_vpn_servers(release_arena=False) → List[VPNServer]

Returns: A list of VPNServer

Parameters

release_arena – Use the release arena VPN servers

get_challenge(challenge_id: int | str) → Challenge

Parameters

challenge_id – The platform ID or name of the Challenge to fetch

Returns: The requested Challenge

get_challenges(limit=None, retired=False) → List[Challenge]

Requests a list of Challenge from the API

Parameters

• limit – The maximum number of Challenge to fetch

• retired – Whether to fetch from the retired list instead of the active list

Returns: A list of Challenge

get_current_vpn_server(release_arena=False) → VPNServer

Returns: The currently assigned VPNServer

Parameters

release_arena – Get the current release arena VPN server

get_endgame(endgame_id: int) → Endgame

Requests an Endgame from the API

Parameters

endgame_id – The ID of the Endgame to fetch

Returns: An Endgame

get_endgames(limit: Optional[int] = None) → List[Endgame]

Requests a list of Endgames from the API

Parameters

limit – The maximum number of Endgames to fetch

Returns: A list of Endgames

get_fortress(fortress_id: int) → Fortress

Requests an Fortress from the API

Parameters

fortress_id – The ID of the Fortress to fetch

Returns: A Fortresse

get_fortresses(limit: Optional[int] = None) → List[Fortress]

Requests a list of Fortresses from the API

Parameters

limit – The maximum number of Fortresses to fetch

Returns: A list of Fortresses

get_hof(vip: bool = False) → Leaderboard

Returns: A Leaderboard of the top 100 Users

get_hof_countries() → Leaderboard

Returns: A Leaderboard of the top 100 Countries

get_hof_teams() → Leaderboard

Returns: A Leaderboard of Teams

get_hof_universities() → Leaderboard

Returns: A Leaderboard of Universities

get_machine(machine_id: int | str) → Machine

Parameters

machine_id – The platform ID or name of the Machine to fetch

Returns: The requested Machine

get_machines(limit: Optional[int] = None, retired: bool = False) → List[Machine]

Retrieve a list of Machine from the API

Parameters

• limit – The maximum number to fetch

• retired – Whether to fetch from the retired list instead of the active list

Returns: A list of Machine

get_team(team_id: int) → Team

Parameters

team_id – The platform ID of the Team to fetch

Returns: The requested Team

get_todo_machines(limit: Optional[int] = None) → List[int]

Retrieve a list of Machine ID’s from the API based on the users todo list

Parameters

limit – The maximum number to fetch

Returns: A list of Machine ID’s

get_user(user_id: int) → User

Parameters

user_id – The platform ID of the User to fetch

Returns: The requested User

load_from_cache(cache: str) → bool

Parameters

cache – The cache file path

Returns: Whether loading from the cache was successful

search(search_term: str) → Search

Parameters

search_term – The search term to pass to the API

Returns: A Search object with lists of the items retrieved from the API

property user: User

The User associated with the current HTBClient

Type

Returns