Unlike its leading competitor, the Qualys Cloud Agent scans automatically. This is good and bad. It means you don’t have to schedule scans, but it also means the Qualys agent essentially has free will. The results wander in whenever they feel like wandering in, and some people want more control than that. Especially at the end of a maintenance window. How to initiate an agent scan was easily the most frequent question I got when I was supporting Qualys for a living. And for a long time, you couldn’t. Then, when Qualys released the feature, they did so about as quietly as can be. Here’s how to force a Qualys Cloud Agent scan.

You can force a Qualys Cloud Agent scan on Windows by toggling a registry key, or from Linux by running the cloudagentctl.sh shell script.

Remember, you force a scan from the client

force a Qualys cloud agent scan

Yes, you force a Qualys cloud agent scan with a registry key. But that means anyone with access to the machine can initiate a cloud agent scan, without having to sign into Qualys.

Counter-intuitively, you force an agent scan from the client where the agent is running, not from the Qualys UI. In theory there’s no reason Qualys couldn’t allow you to control it from both, but at least for now, you launch it from the client. This may seem weird, but it’s convenient. It means a sysadmin can launch a scan as soon as they finish doing maintenance on the system, without needing to log into Qualys. They can just get into the habit of toggling the registry key or running a shell script, and not have to worry if they’ll get credit for their work. No need to mess with Qualys at all.

Both the Windows and Linux agent have this capability, but the way you force a Qualys Cloud Agent scan from each is a little different. The result is the same, it’s just a different process to get there.

At the moment, the agents for Mac OS X and AIX do not have this capability. But when they do get it, if I had to guess, the process will be about the same as it is for Linux.

I presume if you’re reading this, you know what the Qualys agent is and does, but if not, here’s a primer.

Force a Qualys Cloud Agent scan from Linux

To force a Qualys Cloud Agent scan on Linux platforms, use the script /usr/local/qualys/cloud-agent/bin/cloudagentctl.sh.

The command looks like this:

/usr/local/qualys/cloud-agent/bin/cloudagentctl.sh action=demand type=vm cputhrottle=0

This launches a VM scan on demand with no throttling. Allowed options for type are vm, pc, inv, udc, sca, or vmpc, though the vmpc option is deprecated. VM is vulnerability management (think missing patches), PC is policy compliance. SCA is the cheaper subset of Policy Compliance that only evaluates CIS benchmarks. UDC is custom policy compliance controls. INV is an asset inventory scan.

Using 0, the default, unthrottles the CPU. The higher the value, the less CPU time the agent gets to use. If you’re doing an on demand scan, you’ll probably want to use a low value because you probably want the scan to finish as quickly as possible. Even when you unthrottle the CPU, the Qualys agent rarely uses much CPU time. Generally when I’ve observed it, I’ve seen it max out at around 10 percent, and usually stay closer to 2-3 percent.

Force a Qualys Cloud Agent scan from Windows

To force a Qualys Cloud Agent scan on Windows, you toggle one or more registry keys. This is convenient because you can remotely push the keys to any systems you want to scan on demand, so you can bulk scan a lot of Windows agents very easily.

In Windows, the registry key to use is HKLM\Software\Qualys\QualysAgent\ScanOnDemand\Vulnerability. You control the behavior with three 32-bit DWORDS: CpuLimit, ScanOnDemand, and ScanOnStartup. Setting ScanOnDemand to 1 initiates a scan right away, and it really only takes a second. Setting ScanOnStartup initiates a scan after the system comes back from a reboot, which is really useful for maintenance windows. CpuLimit sets the maximum CPU percentage to use. Unlike the Linux client, this is just a value between 1 and 100 in decimal. Even when I set it to 100, the agent generally bounces between 2 and 11 percent. After trying several values, I don’t see much benefit to setting it any higher than about 20.

You can also force an Inventory, Policy Compliance, SCA, or UDC scan by using the following appropriately named keys:

  • HKLM\Software\Qualys\QualysAgent\ScanOnDemand\Inventory
  • HKLM\Software\Qualys\QualysAgent\ScanOnDemand\PolicyCompliance
  • HKLM\Software\Qualys\QualysAgent\ScanOnDemand\SCA
  • HKLM\Software\Qualys\QualysAgent\ScanOnDemand\UDC

You use the same 32-bit DWORDS.

Control the Qualys Cloud Agent from the Windows command line

You can also control the Qualys Cloud Agent from the Windows command line. Be sure to use an administrative command prompt.

REG ADD "HKLM\SOFTWARE\Qualys\QualysAgent\ScanOnDemand\Vulnerability" /v CpuLimit /t REG_DWORD /d 20
REG ADD "HKLM\SOFTWARE\Qualys\QualysAgent\ScanOnDemand\Vulnerability" /v ScanOnDemand /t REG_DWORD /d 1
REG ADD "HKLM\SOFTWARE\Qualys\QualysAgent\ScanOnDemand\Vulnerability" /v ScanOnStartup /t REG_DWORD /d 1

And you can set these on a remote machine by adding \\machinename right after the ADD parameter. Here’s a slick trick to run through machines in bulk:

FOR %%I in (PC1 PC2 PC3 PC4) DO (
REG ADD \\%%I "HKLM\SOFTWARE\Qualys\QualysAgent\ScanOnDemand\Vulnerability" /v CpuLimit /t REG_DWORD /d 20
REG ADD \\%%I "HKLM\SOFTWARE\Qualys\QualysAgent\ScanOnDemand\Vulnerability" /v ScanOnDemand /t REG_DWORD /d 1
REG ADD \\%%I "HKLM\SOFTWARE\Qualys\QualysAgent\ScanOnDemand\Vulnerability" /v ScanOnStartup /t REG_DWORD /d 1)

Specify your machine names in line 1, separated by spaces like I did PC1 PC2 etc.

I recommend only pushing one or the other of the ScanOnDemand or ScanOnStartup lines, depending on which you want. Rebooting while the Qualys agent is scanning won’t hurt anything, but it could delay processing.

One more thing

Here’s one more agent trick. Ever ended up with duplicate agents in Qualys? Here’s a trick to rebuild systems with agents without creating ghosts.