Nullgap.dev Docs

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 admin scope, to create, change or remove a schedule. Any member, or a key with the read scope, 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

  1. Open Pentests. The Scheduled pentests card is on that page.
  2. Press Schedule a pentest.
  3. 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.
  4. Under How often, choose Every day, Every week, Every month, Every quarter or Custom (cron), then the day and the time.
  5. Give the Time zone, and optionally a Price ceiling per run, Folders in scope and Context for the tester.
  6. 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"
}
FieldMeaning
repoIdThe repository. Required.
cadencedaily, weekly, monthly, quarterly or custom. Required.
timeTime of day as HH:MM. Default 02:00.
timezoneAn IANA time zone name such as Europe/Berlin. Default UTC.
daysOfWeekFor weekly: numbers from 0 (Sunday) to 6 (Saturday). Default Monday.
dayOfMonthFor monthly and quarterly: 1 to 28, so the day exists in every month. Default 1.
cronFor custom: a five-field expression. See Cron limits.
maxPriceUsdThe price ceiling for one run. See The price ceiling.
refBranch or tag. Default: the repository's default branch.
paths, context, applicationIdAs 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

cadenceRunsStored as
dailyEvery day at timeM H * * *
weeklyOn each of daysOfWeek at timeM H * * d,d
monthlyOn dayOfMonth at timeM H D * *
quarterlyOn dayOfMonth in January, April, July and October at timeM H D 1,4,7,10 *
customAs your cron saysYour 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/Berlin or Asia/Kolkata, or UTC. Anything else is refused with 400 bad_request.
  • nextRunAt is 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.

FieldRange
Minute0 to 59. One value only.
Hour0 to 23. One value only.
Day of month1 to 31
Month1 to 12
Day of week0 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 MON or JAN are 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 skippedWhat 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 maxPriceUsdThat the run would cost more than the ceiling set for it
No payment method and not enough pentest creditsThat a payment method or pentest credits are needed
The workspace reached its monthly usage limit, or is suspendedThe same message as for a pentest started by hand
The codebase has grown past the size that needs a custom quoteThat it needs a custom quote
The branch or tag no longer existsThe error from checking out the code

How the three "last" fields move:

FieldMeaning
lastRunAtWhen the schedule last came due. It is updated whether or not a pentest started.
lastPentestIdThe last pentest this schedule actually started.
lastErrorWhy 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 cadence together with time, timezone, daysOfWeek, dayOfMonth or cron. Timing fields sent without cadence are ignored. nextRunAt is worked out again from now.
  • maxPriceUsd. Send null to remove the ceiling.
  • enabled. false pauses 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 schedule as 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