Pentests
Scheduled pentests
Repeat a pentest on a cadence, in your own time zone, with a price ceiling per run, and read why a scheduled run was skipped.
A schedule starts a pentest of one repository on a cadence, so new code is tested without anyone remembering to start it. Each run is an ordinary pentest: it is priced on the code as it is that day, has its own reports, and includes its own retest.
#What you need first
- The admin or owner role, or an API key with the
adminscope, to create, change or remove a schedule. Any member, or a key with thereadscope, can list them. - A repository Nullgap can read.
- A way to pay for each run: a payment method or pentest credits, as agreed for your workspace.
An organisation can have up to 50 schedules.
#Creating a schedule in the console
- Open Pentests. The Scheduled pentests card is on that page.
- Press Schedule a pentest.
- Choose the Repository and the Branch or tag. The branch is looked up again at every run, so a branch always means its latest commit.
- Under How often, choose Every day, Every week, Every month, Every quarter or Custom (cron), then the day and the time.
- Give the Time zone, and optionally a Price ceiling per run, Folders in scope and Context for the tester.
- Press Create schedule.
The first run is the next slot, never the moment of creation. To test today, start a pentest by hand.
#Creating a schedule by API
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"repoId":"repo_5b2e8a1c9d3f","cadence":"weekly","daysOfWeek":[1],"time":"02:00","timezone":"Europe/Berlin","paths":["services/api"]}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentest-schedules"
{
"id": "sch_3e8a1f6b0d24",
"repoId": "repo_5b2e8a1c9d3f",
"repoFullName": "acme/shop",
"ref": "main",
"paths": ["services/api"],
"applicationId": null,
"context": "",
"cadence": "weekly",
"cron": "0 2 * * 1",
"timezone": "Europe/Berlin",
"maxPriceUsd": null,
"enabled": true,
"nextRunAt": "2026-11-23T01:00:00.000Z",
"lastRunAt": null,
"lastPentestId": null,
"lastError": null,
"createdBy": "dana@acme.example",
"createdAt": "2026-11-16T09:30:00.000Z"
}
| Field | Meaning |
|---|---|
repoId | The repository. Required. |
cadence | daily, weekly, monthly, quarterly or custom. Required. |
time | Time of day as HH:MM. Default 02:00. |
timezone | An IANA time zone name such as Europe/Berlin. Default UTC. |
daysOfWeek | For weekly: numbers from 0 (Sunday) to 6 (Saturday). Default Monday. |
dayOfMonth | For monthly and quarterly: 1 to 28, so the day exists in every month. Default 1. |
cron | For custom: a five-field expression. See Cron limits. |
maxPriceUsd | The price ceiling for one run. See The price ceiling. |
ref | Branch or tag. Default: the repository's default branch. |
paths, context, applicationId | As for a pentest started by hand. See Scoping a pentest. |
A scheduled pentest never includes live testing. There are no fields for it on a schedule.
#Cadences
cadence | Runs | Stored as |
|---|---|---|
daily | Every day at time | M H * * * |
weekly | On each of daysOfWeek at time | M H * * d,d |
monthly | On dayOfMonth at time | M H D * * |
quarterly | On dayOfMonth in January, April, July and October at time | M H D 1,4,7,10 * |
custom | As your cron says | Your expression |
A schedule created with a time, a time zone, days or a cron expression is stored as a cron expression in cron, read in timezone.
#Time zones
The expression is read in the schedule's time zone. "Every Monday at 02:00" in Europe/Berlin stays at 02:00 local time when the clocks change.
- Use an IANA name such as
Europe/BerlinorAsia/Kolkata, orUTC. Anything else is refused with400bad_request. nextRunAtis always given in UTC.- If the local time does not exist on a day, because the clocks skipped over it, that day's run does not happen and the schedule moves to the next day that matches.
#Cron limits
A custom expression has five fields: minute, hour, day of month, month, day of week.
| Field | Range |
|---|---|
| Minute | 0 to 59. One value only. |
| Hour | 0 to 23. One value only. |
| Day of month | 1 to 31 |
| Month | 1 to 12 |
| Day of week | 0 to 7. Both 0 and 7 are Sunday. |
- At most one run a day. The minute and the hour must each be a single number.
0 */6 * * *is refused. - The other three fields accept
*, lists (1,15), ranges (1-5) and steps (*/2,1-10/3). - Numbers only. Names such as
MONorJANare refused. - When both the day of month and the day of week are restricted, a day matches if either does. This is the standard cron rule.
- An expression that never matches a real date in the next five years, such as the 31st of February, is refused with "This schedule never runs".
- The expression may be up to 80 characters.
curl -s -X POST -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"repoId":"repo_5b2e8a1c9d3f","cadence":"custom","cron":"30 3 1,15 * *","timezone":"UTC"}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentest-schedules"
#The price ceiling
maxPriceUsd protects you from a run that has become larger than you expected, for example after a big merge.
- Each time the schedule comes due, the code is checked out and priced, the same way as the estimate.
- If the price is above the ceiling, the run is not started and nothing is charged. The reason is written to
lastError, and the schedule waits for its next slot. - If the price is at or below the ceiling, the run starts and is charged like a pentest started by hand.
The value is a whole number. null, or leaving it out, means no ceiling. The ceiling compares prices only: it does not cap what a started run costs, because a run's price is fixed before it starts.
#Skips and lastError
A schedule that cannot start a run does not retry. It records why in lastError, up to 300 characters, and waits for its next slot. The console shows the reason on the schedule's row.
| Why a slot was skipped | What lastError says |
|---|---|
| The previous run of this schedule is still queued or running | "Skipped: the previous scheduled pentest is still running" |
| The repository was disconnected or removed | "The repository is no longer connected" |
The price is above maxPriceUsd | That the run would cost more than the ceiling set for it |
| No payment method and not enough pentest credits | That a payment method or pentest credits are needed |
| The workspace reached its monthly usage limit, or is suspended | The same message as for a pentest started by hand |
| The codebase has grown past the size that needs a custom quote | That it needs a custom quote |
| The branch or tag no longer exists | The error from checking out the code |
How the three "last" fields move:
| Field | Meaning |
|---|---|
lastRunAt | When the schedule last came due. It is updated whether or not a pentest started. |
lastPentestId | The last pentest this schedule actually started. |
lastError | Why the last due slot did not start a run. null after a slot that did. |
So lastError set with a recent lastRunAt means the latest slot was skipped. A run that starts clears it.
To hear about runs without polling, subscribe to the pentest.started, pentest.completed and pentest.failed events. See Webhooks. A skipped slot sends no event: check lastError.
#Changing, pausing and removing
curl -s -X PATCH -H "Authorization: Bearer $NULLGAP_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled":false}' \
"$NULLGAP_URL/api/orgs/$NULLGAP_ORG/pentest-schedules/sch_3e8a1f6b0d24"
PATCH can change three things:
- The timing. Send
cadencetogether withtime,timezone,daysOfWeek,dayOfMonthorcron. Timing fields sent withoutcadenceare ignored.nextRunAtis worked out again from now. maxPriceUsd. Sendnullto remove the ceiling.enabled.falsepauses the schedule; in the console this is Switch off. When a schedule is switched back on after its slot has passed, it waits for the next slot instead of running at once.
The repository, the branch, the folders, the context and the application cannot be changed. Remove the schedule and create a new one.
DELETE /pentest-schedules/{id}, or Remove in the console, removes the schedule. Pentests it already ran are kept. Removing an uploaded archive or a public repository from Repositories removes its schedules with it.
#What a scheduled run looks like
- It appears in Pentests like any other, with
scheduleas the person who started it. - Findings it reports that were seen before are not duplicated. See One finding across runs.
- Findings your team has dismissed are not raised again by the next run. See Memory of dismissals.
- It is subject to the same limits as any run. See What one run covers.
The full field list is in the pentest schedules reference.
Nullgap documentation