Installation and initial setup
The steps below will get you up and running quickly with h3-cli. These instructions were tested on Linux machines, and generally should work on any POSIX-compliant system with bash support.
If you plan to run internal pentests using h3-cli, you should install h3-cli on the same Docker Host where you launch NodeZero.
It is assumed you already have an account with Horizon3.ai. If not, sign up at https://portal.horizon3ai.com/.
Create an API key
An API key is required to access the H3 API. You can create one in the Portal under the User -> Account Settings menu.
When creating an API key you must assign it a role that controls its permissions. The available roles are:
- User: Basic read/write permissions. The API key can run pentests and read results.
- Read-only: The API key can read pentest results, but cannot run pentests.
- NodeZero Runner: A specialized, heavily restricted role designed specifically for NodeZero Runners.
We recommend the User role if you're testing out h3-cli and want to experiment with all its features. After that, you may want to use more restrictive permissions, based on your use case. For example, if you only want to use h3-cli to set up a NodeZero Runner, we recommend using the NodeZero Runner role.
You can easily manage multiple API keys within the same h3-cli install. Learn more here.
❗ Keep your API key secure, as anyone with your API key can access your H3 account. Think of an API key as
a username + password rolled into one. Anyone with the API key can access your account from anywhere. h3-cli
will store your API key under the $HOME/.h3 directory. This directory is created during installation and
configured with permissions such that only you can read or write to it.
Install h3-cli
Install the h3-cli git repo on your machine by executing the following git command within a shell/terminal session.
git clone https://github.com/horizon3ai/h3-cli
This will create a new directory, h3-cli, and download the contents of the repo to it. The h3-cli directory
will be created in the directory where you run the git command. You can install h3-cli anywhere on the filesystem.
If you don't have git, you can download the repo as a zip archive from the menu above, and unzip it anywhere on the filesystem.
Run the h3-cli install script
Run the following commands to install and configure h3-cli. Substitute your-api-key-here with your actual API key.
cd h3-cli
bash install.sh your-api-key-here
The install script will install dependencies (jq) and create your default h3-cli profile under the $HOME/.h3 directory.
Your API key is stored in your h3-cli profile. The directory and profile permissions are restricted so that no other
users (besides yourself) can read or write to it.
The install script will ask you to edit your shell profile ($HOME/.bash_profile or $HOME/.bash_login or $HOME/.profile, depending
on your operating system) to set the following environment variables:
H3_CLI_HOME: this environment variable is used by h3-cli to locate itself and its supporting files.PATH: this environment variable specifies the directories to be searched to find a shell command.
After updating your shell profile, re-login or restart your shell session to pick up the profile changes, then verify you can invoke h3 by running it from the command prompt:
h3
If everything's installed correctly, you should see the h3-cli help text.