horizon3ai/h3-cliCLI tool for the Horizon3.ai API
The NodeZero MCP Server is now available, enabling you to run and manage a locally hosted MCP Server that brings NodeZero’s Find, Fix, Verify (FFV) capabilities directly to your development and security workflows.
h3-cli is a convenient CLI (command-line interface) for accessing the Horizon3.ai API. The Horizon3.ai API provides programmatic access to a subset of functionality available through the Horizon3.ai Portal. At a high level, the API allows you to:
The API can be used for a variety of use cases such as scheduling periodic assessments of your environment or kicking off a pentest as part of a continuous integration build pipeline.
The steps below will get you up and running quickly with h3-cli. These instructions were tested on macOS and 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/.
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:
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 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 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.
We release new features, bug fixes, and other updates for the h3-cli every month. Upgrade your installation using one of the methods below.
h3 upgrade command (recommended)As of June, 2023, you can use the h3 upgrade command to upgrade to the latest version of h3-cli.
If you get an ERROR: unrecognized command: "upgrade", then you are on a previous version of h3-cli that does not
support the upgrade command. Use one of the methods below to upgrade h3-cli.
easy_install.sh (recommended if h3 upgrade is unavailable)Run this command from h3-cli's parent directory (i.e. the directory that contains the h3-cli/ directory):
curl https://raw.githubusercontent.com/horizon3ai/h3-cli/public/easy_install.sh | bash
If you used git clone to install the repo, then simply run git pull to install the latest version.
If you downloaded the repo as a zip file, then re-download the zip file and unzip it to the same location (in other words replace your existing h3-cli installation with the new zip).
As of June, 2023, you can view your current version of h3-cli via:
h3 version
You can view the full history of versions and release notes via:
h3 version -v
Run the following command to verify connectivity with the API.
h3 hello-world
You should see the response:
{
"data": {
"hello": "world!"
}
}
❗️ If you are getting an error response, please contact H3 via the chat icon in the Horizon3.ai Portal.
The command below will return the list of pentests in your account, most recent first.
h3 pentests
To filter for pentests that match a given search term, pass the search term as a parameter:
h3 pentests sample
To query the most recent pentest in your account:
h3 pentest
To query any pentest in your account, pass the op_id of the pentest as a parameter:
h3 pentest your-op-id-here
Several h3-cli commands will use the most recent pentest as the default,
unless an op_id is passed as a parameter.
The terms "op" and "pentest" are often used interchangeably.
Running a pentest requires specifying an op template. An op template specifies a full pentest configuration, which includes scope, attack parameters, and other (optional) configuration.