Unlike its leading competitor, the Qualys Cloud Agent scans automatically. This means you don’t have to schedule scans, which is good, but it also means the Qualys agent essentially has free will. The latest results may or may not show up as quickly as you’d like. How to initiate an agent scan on demand was easily the most frequent question I got during the five years I supported Qualys for a living. 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 or Mac OS X by running the cloudagentctl.sh shell script.

Remember, Qualys agent scan on demand happens 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, or scan on demand, 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 the Qualys UI 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 Unix (AIX, Solaris, and FreeBSD) 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 or Mac OS X

To force a Qualys Cloud Agent scan on Linux platforms, also known as scan on demand, use the script /usr/local/qualys/cloud-agent/bin/cloudagentctl.sh. On Mac OS X, use /Applications/QualysCloudAgent.app/Contents/MacOS/cloudagentctl.sh.

The command looks like this:

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

And here’s the equivalent Mac command:

/Applications/QualysCloudAgent.app/Contents/MacOS/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 (system hardening). 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. If you just deployed patches, VM is the option you want. If you just hardened the system, PC is the option you want.

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, spikes over 10 percent are rare, the spikes are brief, and CPU time tends to dwell in the neighborhood of 2-3 percent. Agents as a whole get a bad rap but the Qualys agent behaves well.

You can run the command directly from the console or SSH, or you can run it remotely using tools like Ansible, Chef, or Puppet. This is convenient if you use those tools for patching as well.

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. This works a little differently from the Linux client. On Windows, 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. Usually I just omit it and let the agent do its thing.

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. Just like Linux, Vulnerability and PolicyCompliance are usually the options you’ll want. Vulnerability if you just finished patching, and PolicyCompliance if you just finished hardening a system.

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 with 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.