NodeZero^® Runner with Easy Install Script

This guide walks you through setting up a NodeZero Runner on your Docker Host using the Easy Install Script. A NodeZero Runner simplifies internal pentesting by automating the deployment of the NodeZero Docker container, allowing you to schedule and execute pentests directly from the Horizon3.ai Portal without manual intervention.

Figure 1 - Setting up a NodeZero Runner using the Easy Install Script, from initiation in the Portal to scheduling pentests and viewing results.

What is the Easy Install Script?

The Easy Install Script is a one-step solution for setting up a NodeZero Runner on your Docker Host. It automates the installation of necessary tools, configures the Runner, and registers it with the NodeZero Portal. This method is ideal for users who want a fast, hassle-free setup with minimal manual steps.

Note: NodeZero Runners are designed exclusively for internal pentests. For external pentests, NodeZero is deployed automatically in the Horizon3.ai cloud.

When to use

The Easy Install Script is the best choice in the following scenarios:

• You need to quickly deploy a NodeZero Runner with default settings.
• You prefer an automated setup process over manual configuration.
• Your environment supports systemd for auto-restart functionality (Linux-based Docker Hosts).

If you require custom configurations or your system lacks systemd, consider the Manual Setup method instead.

Requirements

Before proceeding, ensure you have:

• A NodeZero Portal account.
• A Docker Host within your private network, running a Linux distribution.
• SSH or terminal access with permissions to run installation commands.

If you do not meet these requirements, see steps 1 and 2 in the Quickstart Guide.

Step-by-step instructions

Follow these steps to install and configure a NodeZero Runner using the Easy Install Script:

1. Access the Runners page:

   • Log in to the NodeZero Portal and navigate to Runners.

   

   Figure 1 - Screenshot of the NodeZero Runner page
   
   

2. Initiate Runner installation:

   • Click the Install Runner button.
   • Enter a unique, descriptive name for your Runner (e.g., "Main-Office-Runner"). Choose a name that reflects the Runner’s location or purpose for easy identification later.
   • Click Submit.

   

   Figure 2 - Screenshot of the Install NodeZero Runner form
   
   

3. Obtain the installation command:

   • The Portal will display a command starting with curl or wget. Copy this command to your clipboard.

   

   Figure 3 - Screenshot of the NodeZero Runner initialization command
   
   

4. Execute the command on your Docker host:

   • SSH into your Docker Host or open a terminal.
   • Paste and run the copied command.

   ssh nodezero@xxx.xxx.xxx.xxx  // Replace with IP address of your Docker Host.
   

   

   Figure 4 - Screenshot of pasting Runner command into Docker host terminal
   
   

   • Wait for the script to complete; it will install h3-cli, configure the Runner, and start the service.
   • If you encounter permission issues, ensure you are running as a user with Docker privileges.

   

   Figure 5 - Screenshot of successful Runner command in your Docker host terminal
   
   

5. Verify the Runner registration:

   • Return to the Runners page in the Portal and refresh it.
   • Your new Runner should appear in the list.

   

   Figure 6 - Screenshot of NodeZero Runner listed in the Portal
   
   

Behind the scenes

Here’s what happens in the background when setting up the Runner:

• An API key with NodeZero Runner permissions is created, restricting it to polling for pentests and running the launch script.
• The h3-cli tool is installed in a new h3-cli directory on your Docker Host.
• The Runner starts via the h3 start-runner command.
• On Linux systems with systemd, the script registers the Runner as a service for automatic restarts after reboots.

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 7 - 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 8 - Screenshot of Create Schedule button for pentests
   
   

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

   

   Figure 9 - 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 successfully set up a NodeZero Runner using the Easy Install Script. This automation will streamline your internal pentesting process, saving time and ensuring consistent security assessments. As your needs grow, consider deploying additional Runners across different network segments for comprehensive coverage.