Schedule recurring scans

A schedule runs a scan for you on a fixed cadence, daily or weekly at a time you choose. You can schedule a single repository, a whole git workspace, a web application or a network, and a git workspace schedule can also re-import its repositories instead of scanning them.

What it is for

Code changes every day, and a scan from last month says little about today. A schedule keeps each repository's findings and security score current without anyone having to remember to start a scan. Scheduled scans run through the same path as a scan you start by hand. Only what started them is different, and every scan records whether it was started manually, by a schedule or from CI.

How it works

• When a schedule's time comes, its scan starts within a minute and the schedule shows its next run.
• A schedule on a repository scans that repository, on the branch you chose or on its default branch.
• A schedule on a git workspace scans every enabled repository the git workspace holds at that moment, each on its own default branch. Repositories imported after you created the schedule are included automatically, and disabled ones are skipped.
• A schedule on a web application scans that web application, with its sign-in if it has one. See Scan a web application.
• A schedule on a network scans that network, through its connector agent if it has one. See Network scanning.
• A Sync repositories schedule on a git workspace re-imports its repositories, the same job as Sync now. It uses the git workspace's own valid token at the time it runs, so rotating a token does not break the schedule. A git workspace with no valid token still syncs its public repositories.
• An Email a report schedule renders a PDF report and mails it. See Reports.
• When a scheduled scan starts, Vulnara sends a scan-started notification, since nobody is watching the screen when it fires overnight.
• A scan schedule records the category it scans for. Each time it runs, it scans for that category with whatever your workspace may run at that moment.

What you can set

• Runs: on a git workspace, choose Scan, Sync repositories or Email a report. A repository, web application or network schedule always scans.
• Frequency: Daily or Weekly.
• Day: the day of the week. Shown only for weekly schedules.
• Time: the time of day, shown and entered in your own timezone. The zone is named beside the field.
• Branch: repository schedules only. Leave it blank to scan the default branch.
• What to scan for: the category a recurring scan looks for, one of the categories your workspace may run: Code analysis (SAST), Dependencies (SCA), Secrets (SECRETS) or Personal data (PII). A scan schedule must name one, and there is no default. Vulnara runs whatever serves that category and is available to your workspace at the moment the schedule fires. A sync or a report schedule does not carry one, and the field is not shown for them. Nor is it shown for a web application or a network, which are always scanned the same way.
• Send to: for a report, one or more email addresses. They do not have to be members of your account.
• Active: pause a schedule without deleting it, and resume it later.

Do it

1. Open a repository on the Repositories screen, a git workspace on the Workspaces screen, a web application on the Web applications screen, or a network on the Networks screen, and go to the Schedules tab.
2. Choose Add schedule.
3. Set the frequency, day and time. For a repository or git workspace, also choose what to scan for, and optionally the branch. On a git workspace, choose what the schedule runs.
4. Choose Save schedule. The row shows when the next run is due.

Use the switch on a row to pause or resume a schedule, and the delete action to remove it. A paused schedule reads as Paused instead of naming a next run.

With GraphQL, use createScanSchedule, updateScanSchedule, deleteScanSchedule and scanSchedules. The API takes hourUtc and minuteUtc in UTC, dayOfWeek from 0 (Monday) to 6 for weekly schedules, and exactly one of repositoryId, gitEntityId, webTargetId or networkId. A web application or network schedule takes no category. A schedule's lastRunOutcome and lastRunReason say whether its last run started and, if not, why.

Three things about category are not readable from the schema:

• It is nullable in the schema because GraphQL cannot express "required when the action is a scan", but a scan schedule must carry one. Leave it out and the mutation is refused with a VALIDATION_ERROR carrying a field error of REQUIRED on category. The action defaults to a scan, so leaving the action out does not avoid the rule.
• A sync or a report schedule must not supply one. Reading either back returns category as null.
• On updateScanSchedule, leave category out to keep the one the schedule already has, the same as every other field on that input. Sending it explicitly as null is refused with INVALID, because a scan schedule with no category could never run.

mutation NightlyScan {
  createScanSchedule(
    input: {
      repositoryId: "<repository-id>"
      category: SECRETS
      frequency: DAILY
      hourUtc: 2
      minuteUtc: 30
    }
  ) {
    id
    nextRunAt
  }
}

MCP clients can read schedules with scan_schedules and scan_schedule.

Good to know

• Times are stored in UTC and converted to your timezone for display. A conversion that crosses midnight moves the weekday with it.
• Creating, changing or deleting a schedule needs the Editor role or above, the same as starting a scan. Viewers can see schedules. See Teams and roles.
• A schedule cannot be created for a disabled repository.
• If a scheduled run could not start, for example because a plan limit was reached, a web application's address no longer points to a public site, or a network's connector agent was offline, the schedule says so under its row until a later run starts.
• Scheduled scans spend your plan's scan minutes like any other scan. If your plan's limit on parallel scans refuses a repository during a git workspace schedule, the rest of that run is skipped; scans already started keep running.
• If one repository in a git workspace schedule cannot be scanned, the others still are.
• A scheduled scan is a category scan, so it counts once against your plan's limit on parallel scans however many scanners it starts. A scheduled scan announces itself once, not once per scanner.
• If nothing available to your workspace serves a schedule's category when it fires, no scan runs that time. A scan schedule left without a category, which only a schedule created before categories existed can be, never runs: each time it is due, Vulnara sends a scan-failed notification naming the schedule. Edit it and choose what to scan for.
• A report that cannot be rendered waits for its next run rather than retrying. Report schedules do not spend scan minutes.
• There are no cron expressions. Daily or weekly at a set time covers what a schedule can do.