NodeZero^® Runner with h3-cli

This guide provides a detailed walkthrough for setting up a NodeZero Runner on your NodeZero Host using the h3-cli tool. This method offers greater transparency and control, allowing you to customize the setup process for your specific environment. By the end, you'll have a fully operational Runner ready to automate internal pentests through the NodeZero Portal.

Figure 1 - Manual setup process using h3-cli, starting the Runner, and scheduling pentests.

When to use

Choose the Manual Setup if:

• You prefer hands-on control over each setup step.
• You need to customize the Runner configuration or troubleshoot deeply.

For a quicker setup, consider the Easy Install Script method.

NodeZero Runners are for internal pentests only. External pentests are deployed automatically in the Horizon3.ai cloud.

Requirements

Before starting, ensure you have:

• A NodeZero Portal account with access to one of the following:
  • Account Settings (or EU Account Settings)
• A NodeZero host in your private network with Docker installed. See QuickStart Guide
• SSH or terminal access to the NodeZero host (with Git, bash, and Docker privileges).
• Familiarity with command-line operations.

Step-by-step instructions

Follow these steps to manually set up your NodeZero Runner:

1. Create an API key for the Runner

The NodeZero Runner uses the h3-cli to communicate with the Horizon3.ai API, requiring an API key with specific permissions.

• Navigate to API key settings:
  • In the Portal, click the Profile Menu (upper right corner), then click Settings
  • Click My Settings to display the API Keys section.

Figure 2 - My Settings page with the API Keys section visible.

• Generate a key:
  • Create a new API key and set its permission level to NodeZero Runner.
  • This role restricts access.
    • It can only poll for assigned pentests and run the NodeZero Launch Script
    • It cannot read existing pentest data or provision new tests.
  • Save the API key securely. You will need it in the next step.

2. Install h3-cli on your NodeZero host

The h3-cli tool is required to start and manage the Runner process. Install it using the following commands:

• Clone and install h3-cli: Run these commands in a terminal on your NodeZero host:

git clone https://github.com/horizon3ai/h3-cli
cd h3-cli
bash install.sh {your-api-key-here}
export H3_CLI_HOME=`pwd`
export PATH="$H3_CLI_HOME/bin:$PATH"

Replace {your-api-key-here} with the API key from Step 1.

If git is not installed, install it using your package manager (e.g., sudo apt install git on Ubuntu).

What this does:

• Clones the h3-cli repository.
• Installs h3-cli using the provided API key.
• Adds h3-cli to your system’s $PATH.

Verify installation:

Confirm h3-cli is working and using your API key:

h3 whoami

You should see details associated with your API key. If not, double-check the key and retry.

3. Start the NodeZero Runner

Use h3-cli to launch the Runner process on your NodeZero host:

Run the Runner:

• In this example we will name the runner main-office-runner.

• Execute the following command, replacing main-office-runner with a unique name for your Runner:

h3 start-runner main-office-runner /tmp/main-office-runner.log

The Runner runs in the background, logging to /tmp/main-office-runner.log.

Naming the Runner:

• Treat Runner names as unique identifiers. Do not reuse names across your account.
• Avoid reusing names across multiple Runners in your account to prevent conflicts.

The process persists after you close the terminal session.

Verify the Runner connection: Confirm the Runner is registered with the Horizon3.ai API:

h3 runners

Look for an entry for main-office-runner with a recent last_heartbeat_at timestamp.

Figure 3 - Output of h3 runners command.

How to use after setup

Once your NodeZero Runner is operational, you can:

1. Assign pentests:

   • In the Portal, when provisioning a new Internal Pentest, select your Runner to immediately start the pentest remotely—without needing to SSH into the NodeZero host or manually run a command in the terminal.
   • Optionally, save your pentest as a Template to easily apply it when setting up a schedule for automated, recurring runs.

   For step-by-step instructions on setting up internal pentests, see Run an Internal Pentest.

   

   Figure 4 - Screenshot of selecting a Runner (and optionally as a template) for an internal pentest
   
   

2. Schedule recurring tests:

   • Use the Portal’s scheduling feature to automatically run pentest templates with a provisioned Runner at scheduled intervals.

   

   Figure 5 - Screenshot of Create Schedule button for pentests
   
   

   • Select a Pentest Template with a provisioned Runner to schedule automated, recurring runs.

   

   Figure 6 - Screenshot of schedule settings for an internal pentest
   
   

3. Monitor activity:

   • View real-time progress and results in the Portal.

Common issues

Explore solutions to frequent NodeZero Runner problems to quickly get back to testing. For a comprehensive list of potential issues, see Troubleshooting your NodeZero Runner.

Managing your runner

Learn how to effectively control and maintain your NodeZero Runner with essential commands and best practices. Visit Managing a NodeZero Runner for detailed guidance.

Conclusion

Congratulations! You’ve set up a NodeZero Runner manually using h3-cli, giving you full control over the process. Your Runner is now ready to automate internal pentests, schedule recurring tests, and help secure your network. For broader coverage, consider adding more Runners in other network segments.