Automate Scheduling of Pentests

A common use case is running pentests automatically on a recurring basis, for example once a week or once a month. This enables continuous autonomous pentesting without any user intervention - no need to sign-in to the Portal to create the pentest, no need to copy+paste the NodeZero launch script to deploy it.

The instructions below walk through how to create a pentest schedule in the Horizon3.ai Portal.

Looking for scheduling via CLI instead of Portal?

Refer to our h3-cli guide on Scheduling from CLI.

How it works

Creating a pentest schedule involves three steps:

Select a pentest template
Specify the schedule
Verify the pentest schedule is working as expected (optional)

Click the Create Schedule button in the Portal to get started.

1. Select a pentest template

A pentest template specifies the scope and attack configuration for a pentest. Pentest templates can be created within the Run Pentest wizard in the Portal. Note that you can create a template in the wizard without having to run the pentest.

NodeZero Runner required for internal pentests

Creating a pentest schedule for internal pentests requires first setting up a NodeZero Runner. A NodeZero Runner handles the automated deployment of NodeZero on your Docker Host within your internal network.

Once a NodeZero Runner has been set up, you can save it to your pentest template, or you can select it when you create the pentest schedule.

2. Specify the schedule

Once you have created and selected your pentest template, the next step is to specify when you want the pentest to run. You have two options for specifying the schedule:

Create a simple weekly or monthly schedule using the convenient scheduling form in the Create Schedule wizard.
Specify a CRON expression for greater precision and control over the schedule.

CRON expressions are an industry-standard way for specifying a recurring schedule. CRON expressions were originally developed for use with the cron job-scheduling service on Unix systems, but they are now widely supported by a number of modern job-scheduling services.

See the section on CRON expressions below for examples and more information.

❗️ Schedule precision: pentest schedules support a minimum precision of 1 hour. For example you can schedule a pentest to run at 5:00pm, but you cannot schedule it to run at 5:30pm. Therefore the minute field in your CRON expression (the first field) must always be 0.

❗️ Schedule time zone: scheduled times use UTC time zone. This applies to both the scheduling form and CRON expressions.

3. Test and verify the pentest schedule (optional)

Now that you have created a pentest schedule, you can verify everything is working as expected by clicking the Trigger Now button. This will trigger the schedule to run immediately, rather than waiting for its normally scheduled time.

The Trigger Now feature gives you an opportunity to test the entire flow and address any issues right away instead of discovering them later when the schedule is normally triggered.

If you don't want to actually run the pentest right now, you can cancel it from Portal once it gets started.

Enabling and disabling a pentest schedule

You can enable or disable a pentest schedule at any time by toggling its status in the Portal.

Troubleshooting

If a pentest schedule fails to execute at its normally scheduled time, you will receive an email notification alerting you about the error. The error message is also surfaced on the pentest schedule in the Portal.

For further assistance, contact H3 support via the chat icon in the Portal.

CRON expressions

CRON expressions are an industry-standard way for specifying a recurring schedule. A CRON expression is structured as a series of 5 elements:

{minute} {hour} {day-of-month} {month} {day-of-week}

There are a number of articles that document CRON expressions and outline how to build them.

Below are several examples of CRON expressions for various time intervals - weekly, monthly, quarterly, etc. You can use these examples as a guide for building your own CRON expressions.

You can verify your CRON expression by plugging it into an online utility like cronhub or crontab.guru.

0 8 1 * *: runs on the first of every month, at 8am UTC.
0 8 * * THU: runs every Thursday (weekly) at 8am UTC.
0 8 * * THU#2: runs on the 2nd Thursday (THU#2) of every month.
0 8 1 */3 *: runs on the 1st day of every 3rd month (quarterly).

Running a one-off pentest at a specific date and time

It is not possible to specify a CRON expression that runs only once. Therefore it is not possible to create a pentest schedule that runs only once. However you can approximate this behavior by setting the CRON expression to a specific date and time, then disabling the schedule after the pentest completes.

For example, to schedule the pentest to run at 8am UTC on June 1st, use the following CRON expression:

0 8 1 JUN *

Note this will run the schedule every June 1st, annually. So if you want to run the pentest only once, disable the schedule after the pentest completes.

References: