Assessment Scan: Recurring

Related Endpoints:

📘

Note

Scheduled scans do not run if they are in the scan owner's trash folder.

To schedule a recurring scan, specify the following settings parameters in the request body:

ParameterRequired?Action
settings.enabledNoSet this parameter to true to enable the schedule. If your request omits this parameter, but includes the other schedule parameters, Vulnerability Management sets the parameter to true automatically.
settings.starttimeYesUse this parameter to specify the first date on which the scan schedule is active and the time at which recurring scans launch based on the rrules parameter. This parameter must be in the following format:
YYYYMMDDTHHMMSS
For more information about this format, see Date Formats.
settings.rrulesYesUse this parameter to specify the interval at which the scan repeats. For more information, see rrules Format.
settings.timezoneYesUse this parameter to specify the timezone of the scheduled start time for the scan (as specified in the starttime parameter). For a full list of supported timezone values, use the GET /scans/timezones endpoint.

rrules Format

The settings.rrules parameter supports a string value in the following format:

FREQ=value;INTERVAL=value;BYDAY=value

This format consists of the following elements:

ElementDescriptionSupported Values
FREQSpecifies how often you want the scan to repeat.Supported frequency codes are:
  • ONETIME—The scan launches a single time on the day and time specified in startime.
  • DAILY—The scan launches daily on the day and time specified in startime.
  • WEEKLY—The scan launches once a week on the day and time specified in startime.
  • MONTHLY—The scan launches once a month on the day and time specified in startime.
  • YEARLY—The scan launches once a year on the day and time specified in startime.
INTERVALSpecifies how often you want the scan to repeat.An integer representing how many of the specified unit of time should elapse between scans. For example, if you specify 3 for a weekly scan, the scan repeats every three weeks.
BYDAYSpecifies the day or days of the week on which you want the scan to repeat.Supported month codes are:
  • SU—Sunday
  • MO—Monday
  • TU—Tuesday
  • WE—Wednesday
  • TH—Thursday
  • FR—Friday
  • SA—Saturday
If you want a scan to repeat on multiple days in the same week, you can use multiple month codes in a comma-delimited list. For example:MO,WE,FR.

For example:

Scan Recurrencerrules Value
Run once on MondayFREQ=ONETIME;INTERVAL=0;BYDAY=MO
Run every week on MondayFREQ=WEEKLY;INTERVAL=1;BYDAY=MO
Run every month on the specified MondayFREQ=MONTHLY;INTERVAL=1;BYDAY=MO

Request Body

This example request body configures an Advanced Network scan to run every Monday at 1 p.m. Mountain time.

This example also uses a target group, instead of listing individual targets.

{
  "uuid": "329692d8-ea42-4e96-acd6-7da6c3571c27d24bd260ef5f9e66",
  "settings": {
    "name": "western-region-assets",
    "enabled": true,
    "starttime": "20181017T130000",
    "rrules": "FREQ=WEEKLY;INTERVAL=1;BYDAY=MO",
    "timezone": "US/Mountain",
    "target_groups": [2, 8, 12],
    "emails": "[email protected],[email protected]",
    "acls": [
      {
        "permissions": 0,
        "owner": null,
        "display_name": null,
        "name": null,
        "id": null,
        "type": "default"
      },
      {
        "permissions": 16,
        "owner": 0,
        "display_name": "Analyst Group",
        "name": "Analyst Group",
        "id": 1,
        "type": "group"
      },
      {
        "permissions": 128,
        "owner": 1,
        "display_name": "[email protected]",
        "name": "[email protected]",
        "id": 2,
        "type": "user"
      }
    ]
  }
}