Scan on Demand and Scan on Startup
Cloud Agent Windows 3.0 introduces client-side initiated "ScanOnDemand" and client-side initiated "ScanOnStartup" functions. This feature is used to trigger the agent to initiate an on-demand manifest collection or when the agent service starts for supported activated applications: Vulnerability Management, Policy Compliance, and Inventory.
This capability is introduced primarily to support patch management use cases where one needs to verify that newly installed patches have remediated the associated local host vulnerabilities.
Scan on Demand is a single use execution that is initiated manually on the host itself, using locally or remotely executed scripts or GPO, or from software distribution tools at the end of a patch deployment job.
Scan on Startup is a configuration option, that once set, will initiate a manifest scan when the Qualys Cloud Agent service starts up. The primary use case is to reassess the asset when a patch deployment job requires the host to reboot to fully remediate the vulnerability or when gold images are being built to verify that there are no vulnerabilities in the image.
In addition to initiating Scan on Demand or setting the Scan on Startup, you can set the CPU Limit to a performance value for the on demand or startup scans. This CPU Limit is only for the on demand or startup execution and is separate from the CPU Limit set in the Configuration Profile. The most common use case is setting a high CPU Limit or no throttle (100%) for this scan so that the agent portion of the processing can run as fast as possible. This allows for fast collection as part of patch deployment jobs during change management windows while keeping a low-performance profile for normal production usage.
This feature only manages when the agent initiates a manifest scan to collect the required metadata. After collection, the agent calculates the delta changes and sends any changes to the Qualys Cloud Platform for processing. Platform processing is per the normal assessment pipeline for assessments to be available in VM reports, API, VM dashboard, PC Reports, and AssetView. The Scan on Demand feature does not change or accelerate the normal assessment pipeline for assessment processing on the platform.
Registry Configuration
The configuration for this feature is set and managed in Qualys Agent hive in the registry. This allows integration into patch deployment and gold image workflows without requiring access to the Qualys platform UI or API.
The agent monitors the Qualys registry hive at HKLM/Software/Qualys/QualysAgent/ScanOnDemand key in real-time for specific values and initiates the scan for each supported manifest based on the values set.
For Cloud Agent for Windows version 4.8 or later, when an application is activated, the agent automatically creates the registry structure and subkeys for the on-demand scan. For versions earlier than 4.8, only root keys are created. The subkeys, data, and values to configure and execute the scans need to be set manually using scripts or registry configuration tools.
HKEY_LOCAL_MACHINE
SOFTWARE
Qualys
QualysAgent
ScanOnDemand
Inventory
CpuLimit
ScanOnDemand
ScanOnStartup
Vulnerability
CpuLimit
ScanOnDemand
ScanOnStartup
PolicyCompliance
CpuLimit
ScanOnDemand
ScanOnStartup
UDC
CpuLimit
ScanOnDemand
ScanOnStartup
SCA
CpuLimit
ScanOnDemand
ScanOnStartup
Registry Configuration Settings
The following table describes the configuration settings and functionality for the Scan on Demand and Scan on Startup features.
|
Module Key |
Value |
Type |
Data |
Description |
|---|---|---|---|---|
|
Inventory Vulnerability PolicyCompliance UDC SCA |
CpuLimit |
REG_DWORD (decimal) |
2 - 100 |
Sets the CPU Limit (%) for the execution. Key is not required. Default value is 100 if no value exists or the data is not valid. |
|
ScanOnDemand |
REG_DWORD (decimal)
|
0 - completed 1 - execute now 2 - in progress
|
Setting a data value of "1" will initiate the on demand scan. The data value will change to "2" when the scan is in progress. The data value will change to "0" when the scan is complete. |
|
|
ScanOnStartup |
REG_DWORD (decimal)
|
1 |
A data value of "1" will configure the agent to execute the scan when the agent service starts up. After a completed scan, the scan interval for this manifest is reset. No execution if there is no value or the data is not valid. |
Example
Configuration example for CPU Limit of 100%, Scan on Demand data of "1" to execute immediately, and Scan on Startup data of "1" to execute on agent service startup.
Functionality Notes
If the agent is already performing a manifest collection or is in the delta upload/PendingDelta state, the agent does not initiate the on-demand or on-startup scan. This ensures data integrity between the agent and the platform for the in-progress scan.
Network Blackout Windows take precedence.
- Scan on demand or scan on startup are executed even during the network blackout window, but the delta is not uploaded to the Qualys cloud platform until the agent exits the blackout window.
- In the network blackout window, the new scan on demand or scan on startup are note executed until the previous scan's delta is uploaded to Qualys Cloud Platform.
- Cloud Agent can not execute a scan on demand or scan on startup for manifests that are not activated.