Scheduling scans

Depending on your security policies and routines, you may schedule certain scans to run on a monthly basis, such as patch verification checks, or on an annual basis, such as certain compliance checks. It's a good practice to run discovery scans and vulnerability checks more often—perhaps every week or two weeks, or even several times a week, depending on the importance or risk level of these assets.

Best practices for scheduling scans

Scheduling scans requires care. Generally, it’s a good idea to scan during off-hours, when more bandwidth is free and work disruption is less likely. On the other hand, your workstations may automatically power down at night, or employees may take laptops home. In this case, you may need to scan those assets during office hours. Make sure to alert staff of an imminent scan, as it may tax network bandwidth or appear as an attack.

If you plan to run scans at night, find out if backup jobs are running, as these can eat up a lot of bandwidth.

Your primary consideration in scheduling a scan is the scan window: How long will the scan take?

Many factors can affect scan times:

• A scan with an Exhaustive template will take longer than one with a Full Audit template for the same number of assets. An Exhaustive template includes more ports in the scope of a scan.
• A scan with a high number of services to be discovered will take additional time.
• Checking for patch verification or policy compliance is time-intensive because of logon challenges on the target assets.
• A site with a high number of assets will take longer to scan.
• A site with more live assets will take longer to scan than a site with fewer live assets.
• Network latency and loading can lengthen scan times.
• Scanning Web sites presents a whole subset of variables. A big, complex directory structure or a high number of pages can take a lot of time.

If you schedule a scan to run on a repeating basis, note that a future scheduled scan job will not start until the preceding scheduled scan job has completed. If the preceding job has not completed by the time the next job is scheduled to start, an error message appears in the scan log. To verify that a scan has completed, view its status. See Running a manual scan.

Scheduling scans to run with different templates

By alternating scan templates in a site, you can check the same set of assets for different needs. For example, you may schedule a recurring scan to run on a fairly routine basis with a template that is specifically tuned for the assets in a particular site. Then you can schedule a monthly scan to run with a special template for verifying Microsoft patches that have been applied after Patch Tuesday. Or you can schedule a monthly or quarterly scan with an internal PCI template to monitor compliance.

Schedule a scan

• If you want to set a schedule for an existing site, click that site's Edit icon in the Sites table on the Home page.
• If you want to set a schedule while creating a new site, click the Create site button on the Home page, or click the Create > Site.

1. In Site Configuration, click the Schedules tab.
2. Click Create Schedule.
3. Optionally, you can add a Name for the schedule. Since you can use different scan templates and Scan Engines, you can use the name to help yourself and other users keep track of the specific configuration of this schedule.
4. Select the check box labeled Enable schedule. The Security Console displays options for a start date and time, maximum scan duration in minutes, and frequency of repetition.
5. Enter a start date in mm/dd/yyyy format, or select a date from the calendar that appears when you click inside the text box.
6. Enter a start time in HH:MM format, and select AM or PM.
7. Select a template for the scheduled scan. See Scheduling scans to run with different templates for more information.

8. Select a Scan Engine for the scheduled scan. This allows you to create your schedules in a way that lets you take advantage of what you know about the availability and performance of your Scan Engines at particular times.
9. Optionally, you can specify a subset of assets to scan. To do so, select the checkbox. Note that these assets must always be among those already included in the site. Including assets or groups here means only the included assets will be scanned in this schedule. This field is required once you choose to scan a subset of assets at all. Excluding assets or groups means those assets will be excluded from the scan in this schedule, in addition to any existing inclusions configured on the site.

   NOTE

   Subset scanning criteria must be aligned with how the site is defined.

   Sites defined by asset group (or groups) can only specify Included Groups and Excluded Groups as subset criteria. Accordingly, sites defined by IP address (or range) can only specify Included and Excluded as subset criteria, and only if the specified assets fall within the range defined by the site.

   Subset field types cannot be mixed.

10. If you want to set a maximum duration, enter a numeral for the number of minutes the scan can run. When the scan reaches the duration limit, it will pause. If you don't enter a value, the scan will simply run until it completes.
11. Select an option for what you want the scan to do after reaches the duration limit: If you select the option to continue where the scan left off, the paused scan will continue at the next scheduled start time. If you select the option to restart the paused scan from the beginning, the paused scan will stop and then start from the beginning at the next scheduled start time.
12. To make it a recurring scan, select an option from the Frequency dropdown. Select Other… for additional customization options.
13. Click Save. The newly scheduled scan appears in the Scan Schedules table, which you can access by clicking Manage Schedules.

Tip: You can edit a schedule by clicking its hyperlink in the table.

Select a schedule for a site

You may want to suspend a scheduled scan. For example, a particular set of assets may be undergoing maintenance at a time when a scan is scheduled. You can enable and disable schedules as your needs dictate.

1. In Site Configuration > Schedules, click Manage Schedules .
2. Select a check box to enable a schedule, and clear a check box to disable it.
3. Configure any other site settings as desired.
4. Click Save & Scan or Save depending on your needs.

Export site schedules

You can export your scan schedules at the site level for a view of your site calendar and any potential scheduled scans that may impact performance.

Depending on the schedule data you want, you can use the Command Console for all sites and the API for more extensive results.

• Export all schedules for all sites using the Command Console

  Access the Command Console from the /admin/global/diag_console.html Run dialogue.

  In the Command Console, enter show schedule.

• Refine your export using the API

   
  1
  $Rapid7_User = Get-Credential
  2
  $Rapid7_Headers = @
  3
  
  4
  {Authorization = "Basic $([System.Convert]::ToBase64String([System.Text.Encoding]::ASCII.GetBytes("$($Rapid7_User.UserName):$($Rapid7_User.GetNetworkCredential().password)")))"}
  5
  $Rapid7_BaseUrl = 'https://<Rapid7 Host>:3780/api/3'
  6
  
  7
  $Rapid7_Sites = (Invoke-RestMethod -Uri "$Rapid7_BaseUrl/sites?size=500" -Headers $Rapid7_Headers).resources
  8
  $Rapid7_Sites_Info = @()
  9
  foreach($Rapid7_Site in $Rapid7_Sites) {
  10
  $Rapid7_Site_Schedules = (Invoke-RestMethod -Uri "$Rapid7_BaseUrl/sites/$($Rapid7_Site.id)/scan_schedules" -Headers $Rapid7_Headers).resources | select id,scanName,enabled,scanTemplateId,repeat
  11
  $Rapid7_Site_Tags = (Invoke-RestMethod -Uri "$Rapid7_BaseUrl/sites/$($Rapid7_Site.id)/tags" -Headers $Rapid7_Headers).resources | select id,name,source,type
  12
  #$Rapid7_Site_Users = (Invoke-RestMethod -Uri "$Rapid7_BaseUrl/sites/$($Rapid7_Site.id)/users" -Headers $Rapid7_Headers).resources | select id,enabled,login
  13
  $Rapid7_Site_Assets = (Invoke-RestMethod -Uri "$Rapid7_BaseUrl/sites/$($Rapid7_Site.id)/assets" -Headers $Rapid7_Headers).resources | select id,ip,hostname,os
  14
  $Rapid7_Site_IncludedTargets = (Invoke-RestMethod -Uri "$Rapid7_BaseUrl/sites/$($Rapid7_Site.id)/included_targets" -Headers $Rapid7_Headers).resources
  15
  $Rapid7_Site_ExcludedTargets = (Invoke-RestMethod -Uri "$Rapid7_BaseUrl/sites/$($Rapid7_Site.id)/excluded_targets" -Headers $Rapid7_Headers).resources
  16
  $Rapid7_Site_IncludedAssetGroups = (Invoke-RestMethod -Uri "$Rapid7_BaseUrl/sites/$($Rapid7_Site.id)/included_asset_groups" -Headers $Rapid7_Headers).resources | select id,name,type,searchCriteria
  17
  $Rapid7_Site_ExcludedAssetGroups = (Invoke-RestMethod -Uri "$Rapid7_BaseUrl/sites/$($Rapid7_Site.id)/excluded_asset_groups" -Headers $Rapid7_Headers).resources | select id,name,type,searchCriteria
  18
  
  19
  $Rapid7_Sites_Info += [pscustomobject]@
  20
  
  21
  { ID = $Rapid7_Site.id Name = $Rapid7_Site.name ScanTemplate = $Rapid7_Site.scanTemplate Type = $Rapid7_Site.type Schedules = $Rapid7_Site_Schedules Tags = $Rapid7_Site_Tags #Users = $Rapid7_Site_Users Assets = $Rapid7_Site_Assets IncludedTargets = $Rapid7_Site_IncludedTargets ExcludedTargets = $Rapid7_Site_ExcludedTargets IncludedAssetGroups = $Rapid7_Site_IncludedAssetGroups ExcludedAssetGroups = $Rapid7_Site_ExcludedAssetGroups }
  22
  }
  23
  
  24
  $Rapid7_Sites_Info | select ID,Name,ScanTemplate,Type,@{name=’Schedules’; expression={if($_.Schedules -eq $null)
  25
  
  26
  {0} elseif ($.Schedules.GetType().Name -eq 'PSCustomObject') {1} else {$.Schedules.count}}},@{name=’Tags’; expression={if($_.Tags -eq $null) {0}
  27
  elseif ($_.Tags.GetType().Name -eq 'PSCustomObject')
  28
  
  29
  {1} else {$.Tags.count}}},@{name=’Assets’; expression={if($.Assets -eq $null) {0} elseif ($_.Assets.GetType().Name -eq 'PSCustomObject') {1}
  30
  else {$.Assets.count}}},@{name=’IncludedTargets’; expression={if($.IncludedTargets -eq $null)
  31
  
  32
  {0} elseif ($.IncludedTargets.GetType().Name -eq 'PSCustomObject') {1} else {$.IncludedTargets.count}}},@{name=’ExcludedTargets’; expression={if($_.ExcludedTargets -eq $null) {0}
  33
  elseif ($_.ExcludedTargets.GetType().Name -eq 'PSCustomObject')
  34
  
  35
  {1} else {$.ExcludedTargets.count}}},@{name=’IncludedAssetGroups’; expression={if($.IncludedAssetGroups -eq $null) {0} elseif ($_.IncludedAssetGroups.GetType().Name -eq 'PSCustomObject') {1}
  36
  else {$.IncludedAssetGroups.count}}},@{name=’ExcludedAssetGroups’; expression={if($.ExcludedAssetGroups -eq $null)
  37
  
  38
  {0}
  39
  elseif ($_.ExcludedAssetGroups.GetType().Name -eq 'PSCustomObject')
  40
  
  41
  {1}
  42
  else {$_.ExcludedAssetGroups.count}}} | Export-Csv -Path .\Downloads\Rapid7_Sites.csv -NoTypeInformation