Skip to content

Getting Started

h3-cli: CLI tool for the Horizon3.ai API

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:

  • schedule an autonomous pentest
  • download and run NodeZero™
  • monitor the status of a pentest while it is running
  • retrieve a pentest report after it's complete

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.

Installation and initial setup

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

1. Obtain an API key

An API key is required to access the H3 API. Obtain one from the Portal under the User -> Settings menu: https://portal.horizon3ai.com/settings/api.

Keep your API key secure, as anyone with your API key can access your H3 account.

2. Install this git repo

First, install this repo on your machine using the following git command within a shell/terminal. 

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.

3. 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 h3-cli profile under the $HOME/.h3 directory. Your API key is stored in your h3-cli profile. The profile permissions are restricted so that no other users (besides yourself) can read 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.

Getting started

1. Verify connectivity with the API

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.

2. Query the list of pentests in your account

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

3. Query a specific pentest from your account

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.

4. Run a pentest

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.

Horizon3.ai provides new users with a default op template named Default 1 - Recommended. This template is always up-to-date with our latest attack parameters and recommended configuration. The default template does not define a scope, in which case NodeZero will use Intelligent Scope - NodeZero's host subnet will provide the initial scope, and it will expand organically during the pentest as more hosts and subnets are discovered. For more information on Intelligent Scope and other deployment options, visit our product documentation.

For experienced users, custom op template(s) may be created via the Horizon3.ai Portal. To create a custom op template, walk through the Run a Pentest modal until you see the option to customize the pentest configuration. The op template can be created without actually running the pentest.

To provision a pentest using the default op template and Intelligent Scope:

h3 run-pentest

The JSON response contains the details for the newly created pentest. You can verify the pentest is provisioning by checking your Horizon3.ai Portal, or by running h3 pentest.

There are several ways to specify additional parameters when creating pentests. For more information see additional examples here.

❗ WAIT! YOU'RE NOT DONE!

For internal pentests (which are the default), additional steps are required before the pentest will begin running. See the next section about downloading and running NodeZero in order to complete the initiation of your pentest.

If you are running an external pentest, NodeZero is launched for you automatically in the H3 cloud as part of h3 run-pentest, in which case there are no additional steps on your end to initiate the pentest.

5. Run NodeZero

❗ ️The following step applies to internal pentests only; for external pentests, NodeZero is launched for you automatically in the H3 cloud.

After creating an internal pentest, you then have to run our NodeZero container on a Docker Host inside your network. This is done by running the NodeZero Launch Script on your Docker Host.

To run the NodeZero Launch Script for your most recently created pentest:

h3 run-nodezero

YOUR PENTEST HAS BEEN LAUNCHED! Assuming all commands ran without error, then you have successfully created and launched your pentest. You should see output from the NodeZero Launch Script being logged to the console. The script will first verify your system is compatible with NodeZero before downloading and running it. When the pentest is complete, NodeZero will automatically shut itself down.

NodeZero is a Docker container. You can view it using docker ps. The container name will be of the form n0-xxxx.

6. Download pentest reports

After your pentest has finished, use the following command to download a zip file containing all PDF and CSV reports for the most recently created pentest:

h3 pentest-reports

The above command will download the zip file to pentest-reports-{op_id}.zip in the current directory.

Use cases

Touchless NodeZero deployment. Deploy NodeZero on your Docker Host in a "touchless" way, without having to manually copy+paste the NodeZero Launch Script. See this guide to learn how to deploy NodeZero automatically using the h3-cli agent.

Schedule recurring pentests. A common use case for h3-cli is running pentests automatically on a recurring basis, for example once a week or once a month. See this guide to learn how to set up recurring pentests using h3-cli.

Monitoring pentests. See this guide to learn how to monitor pentests using h3-cli.

Paginating results. See this guide to learn how to paginate through large result sets using h3-cli.

Authentication & h3-cli profiles

Authentication happens seamlessly and automatically when you invoke the h3 command. There's nothing explicit you need to do to authenticate. This section documents the underlying mechanics.

h3-cli reads your H3_API_KEY from your h3-cli profile (under $HOME/.h3) to authenticate to the Horizon3.ai API and establishes a (temporary) session. The session token (a JWT) is cached under $HOME/.h3. The session token expires after 1 hour, at which point h3-cli will automatically re-authenticate and re-establish a session.

You can explicitly authenticate using the following command: 

h3 auth

The above command will output the session token (and also cache it under $HOME/.h3). If you already have an established (non-expired) session token, h3 auth will continue to use that session token rather than re-authenticate.

If you want to force h3-cli to re-authenticate, use the force option:

h3 auth force

h3-cli profiles

You can manage multiple h3-cli authentication profiles under the same $HOME/.h3 directory. When you first install h3-cli it will automatically create an initial profile named default. If you wish to create a new profile, use the following command:

h3 save-profile my-profile {api-key}

This will create a profile named my-profile under $HOME/.h3 and will apply the given {api_key} to it. To switch to this profile, use the following command (note the leading dot .): 

. h3 profile my-profile

To switch back to the default profile:

. h3 profile default

To list out all your profiles:

h3 profiles

To list the currently active profile:

h3 profile

Running pentests with h3-cli

This section contains additional examples for running pentests using h3-cli.

The simplest way to provision a pentest is to use the default op template and Intelligent Scope:

h3 run-pentest

To provision a pentest AND launch NodeZero on the local machine (for internal pentests only):

h3 run-pentest-and-nodezero

Note that this only applies to internal pentests. For external pentests, NodeZero is launched for you automatically in the H3 cloud as part of h3 run-pentest.

If you happen to run h3 run-pentest-and-nodezero for an external pentest, it will simply skip the part where it downloads and runs NodeZero, since that is handled automatically in the H3 cloud.

To run a pentest using a custom op template, specify it as a parameter to schedule_op_template.graphql:

h3 run-pentest '{"op_template_name":"your-op-template-here"}'

To run a pentest using the default op template but assign it a name of your choosing, use the optional op_name parameter: 

h3 run-pentest '{"op_name":"your-op-name-here"}'

To run a pentest using the default op template but specify its name and scope, use the optional schedule_op_form parameter:

h3 run-pentest '{"schedule_op_form":{"op_name":"your-op-name-here", "op_param_max_scope": "192.168.0.0/24"}}'

Note that h3 run-pentest and h3 run-pentest-and-nodezero accept all the same optional parameters.

Powered by GraphQL

The Horizon3.ai API is powered by GraphQL. In addition to this CLI document, relevant documentation includes:

Advanced: Writing your own GraphQL queries

h3-cli provides a simple mechanism to run your own GraphQL queries. First you define the GraphQL query in a file (typically with a .graphql extension, although that is not required). Then pass the file to h3 gql:

h3 gql {your-query-file}

For example, define the following in a file named my_session.graphql:

query {
    session_user_account {
        email
        name
        company_name
    }
}

Then run:

h3 gql ./my_session.graphql

You should see the raw JSON response from the GraphQL server. You can pretty-print the JSON response using jq:

h3 gql ./my_session.graphql | jq .

Important! You must specify the path to the graphql file (full or relative, ie. ./my_session.graphql instead of just my_session.graphql), otherwise you risk colliding with graphql files that h3-cli uses internally.

Advanced: Parameterized GraphQL queries

GraphQL queries can also define parameters, which are passed to h3 gql as a JSON object.

For example, define the following in a file named my_pentest.graphql:

query q($op_id: String!) {
    pentest(op_id:$op_id) {
        op_id
        name
        state
    }
}

In this example, $op_id is a parameter that must be provided in order to run the query. The parameter is passed to the query within a JSON object:

h3 gql ./my_pentest.graphql '{"op_id":"your-op-id-here"}' | jq .

Substitute your-op-id-here with an actual op_id.