Qualys Vulnerability Management Automation Guide
Reading Time: 5.8 minutes
Prototype Build: 0.75 days (accounts, debugging, settings, templates)
Download+Customize: 3 minutes
Collective Time Saved: weeks
To begin to manage risk for your digital footprint, you require some form of Vulnerability Management (VM). Much of the work revolves around education, awareness, and overcoming friction. Embedding security baselines as a gating mechanism into project lifecycles is often a hard-fought battle, but one that works best for everyone if done as early as possible.
Expectation setting around any security gating should happen from the outset of a project. Still, it can sometimes be perceived as a surprise, labeled as a blocker, or result in acrimonious finger-pointing right before go-live. Yet, by empowering non-security staff and project management to perform the initial scans themselves (i.e. to self-serve), security teams can frictionlessly enable product and development teams to adhere to their go-live requirements faster and more easily.
Let’s look at how to automate aspects of your vulnerability management, allowing you to scale yourself, your team, and even get some precious time back, all without any ensuing grumpiness!
Qualys Automation and APIs
These days Qualys is so much more than just Vulnerability Management software (and related scanning), yet enumerating vulnerabilities is still as relevant as it ever was. As a cornerstone of any objective security practice, identifying known unknowns is not just achievable, but something that’s countable and measurable in terms of real risk. Today we’re going to focus on leveraging some basic Qualys automation to maximize your impact and efficacy. Let’s start by familiarizing ourselves with the Qualys VM/PC REST API. We will combine some simple steps into a more complex (but not complicated) outcome.
When you first encounter any API, the first few questions tend to be:
- Where and what sort of documentation does the API have?
- What specific endpoint do I access?
- How do I authenticate?
- Are there any limitations (including rate-limits) or 'gotchas' ?
- What tooling can I use to quickly prototype and test?
Qualys API Documentation
- Searchable Web API Guide here.
- Official PDF API guide here and ‘quick’ reference here.
- API client examples here for a whole range of languages!
- Developer API forum here.
Note: We were, unfortunately, unable to locate an OpenAPI / Swagger file for the VM/PC API.
Qualys API Endpoints
Your API endpoint is determined by, and dependent on your account, explained here.
Qualys API Authentication
Basic HTTP authentication (RFC 2617) and a form of session-based authentication are available. A custom header detailing the client type or user agent must also be provided irrespective: 'X-Requested-With: xxxxxx'
Qualys API Limitations
Qualys VM/PC API rate and concurrency limits per account type here. Your remaining API call limits (and related time windows) are reflected back in the headers of each API response.
cURL on the CLI or a more fully-featured environment like Postman (Postman collection v3.0 for Qualys). Later we will also look at using Tines for workflow automation.
Starting Simple with Curl
Let’s start simply with cURL to perform 4 fundamental API actions. Let’s add an IP address as a host-based asset, list available host assets, request a scan, and then request the scan report.
By using the command line -d switch we automatically issue a POST request with cURL. Also, note the 'Content-Type' used below:
With this POST operation, we also need to ensure we’ve set enable_vm=1 to enable vulnerability management for the asset. The '|' pipe to xq is also an additional handy tool to return JSON from XML (XML being the default response type from Qualys). We then get the below response:
OK, let’s check if it really has been added as an asset:
And the response:
Now let’s run a custom scan on this test host. We’ve also created two new scan types (over and above the default pre-loaded scan templates) called 'FastScan' and 'FullScan' which have the respective option_id's of 1181621 and 1181652. Let’s invoke our custom 'FullScan' and ensure it gets processed quickly by asking for it with a priority of 1.
And the response is:
Ok, so far, so good. Now let’s ask for the scan results, and then subsequently, we’ll ask for a full PDF scan report. We’re not sure how long the initial scan takes or if the scan has been fully processed yet, but let’s ask for it and see what happens?
This time, the response is not such a favorable one:
So let’s wait a minute or so and then try again! Success, we now get a large array of scan data, including specific vulnerability results (a little too big to show all of them here):
Finally, let’s ask for the creation of a nicely formatted PDF report (and just as before, we may have to poll the endpoint until the report is ready. However, we’ll skip that part for brevity and go on to show an example of tying the whole workflow together faster!).
Looking good, let’s get the report (assuming it’s ready!)...
… which results in the below fully-fledged 12 page PDF report (though we’re only showing pages 1 and 2 for now). This was a test Linux based host running only a few services.
This is by no means automated or self-serve yet, so let’s see how we can simply orchestrate these steps into something a little smarter and smoother (without using any code) by using a platform like Tines…
Further and Faster with Tines
Let’s evolve this use case a little further by creating a simple visual workflow in Tines. It will also benefit from the addition of a self-serve form on the front-end of the story while allowing for both logic and flow control on the back-end. This will also email the scan report to the requester and also update a Jira case (as the chosen case management system, albeit ServiceNow or TheHive could also be easily used).
The blue ‘HTTP’ agent steps above mimic our curl steps (but are now simply dragged and dropped on to the storyboard). They look like this (below) behind the scenes:
We wire these building blocks together to create a repeatable and consistent story workflow. At the top of the story, we will receive the details from a form using the 'Webhook' agent. At the bottom, we will use a 'Send To Story' agent to make it modular and enable further chaining of this story to others. In between, we handle simple extraction of any information we need, including looping with delays until Qualys has finished processing our scans and built our reports.
We can rapidly create a reusable form using some simple fields to capture the IP asset and project details:
Now let’s submit the above form to see what happens next! Qualys has been tasked to scan and report on a Windows server that’s, unfortunately, been misconfigured and is running a whole host of exposed and unneeded services. First, we receive an email with the scan report directly attached. This is a simple way for a Project Manager to be empowered to talk to their technical team about security related issues without directly engaging the security team (yet!).
The first two pages are shown below but feel free to download the full report here, which includes all vulnerability and prescriptive remediation tasks.
So, scan early, and scan often to empower your project teams to help themselves (while making your life easier too)! What fields would you add to a self-serve security form? What other repetitive tasks could you make 'self-serve' to help optimize and empower teams?