Qualys API (VM, PC) User Guide

Qualys API

(VM, PC)

User Guide

Version 10.29.1

August 21, 2024

Qualys and the Qualys logo are registered trademarks of Qualys, Inc. All other trademarks

are the property of their respective owners.

Qualys, Inc.

919 E Hillsdale Blvd

4th Floor

Foster City, CA 94404

1 (650) 801 6100

Verity Confidential

Table of Contents

Preface.................................................................................................................9

Welcome ........................................................................................................... 10

API Conventions .................................................................................................................... 10

Qualys User Account ...................................................................................................... 10

Qualys API Server URL ..........................................................................................................11

Making API requests .............................................................................................................. 12

API Limits ............................................................................................................................... 13

Tracking API usage by user .................................................................................................. 14

HTTP Response Headers ....................................................................................................... 14

Activity Log ............................................................................................................................. 17

Authentication to your account ...................................................................18

What do I need to know? ...................................................................................................... 18

Using Basic HTTP Authentication ....................................................................................... 18

Using Session Based Authentication ................................................................................... 19

Session Login .......................................................................................................................... 22

Session Logout ....................................................................................................................... 24

Scans ..................................................................................................................26

VM Scans ................................................................................................................................ 27

VM Scan List .................................................................................................................... 27

List Last ‘N’ Scan References for a Schedule ............................................................... 30

Launch VM Scan ............................................................................................................. 33

Launch VM Scan on EC2 assets ..................................................................................... 35

Manage VM Scans ........................................................................................................... 38

Compliance Scans ................................................................................................................. 41

Compliance Scan List ..................................................................................................... 42

List Last ‘N’ Scan References for a Schedule ............................................................... 43

SCAP Scan List .................................................................................................................46

Launch Compliance Scan ............................................................................................... 48

Launch Compliance Scan on EC2 assets ...................................................................... 49

Manage Compliance Scans ............................................................................................ 51

Cloud Perimeter Scans ..........................................................................................................54

Create/Update Cloud Perimeter Scan ........................................................................... 54

VM Scan Schedules ............................................................................................................... 57

PC Scan Schedules ................................................................................................................. 68

Scan List Parameters ............................................................................................................. 78

Scan Parameters .................................................................................................................... 80

Cloud Perimeter Scan Parameters ....................................................................................... 85

Scan Schedule Parameters ................................................................................................... 89

VM Scan Statistics ................................................................................................................. 93

VM Scan Summary ................................................................................................................96

Scan Summary ..................................................................................................................... 107

Scanner Details .................................................................................................................... 110

Share PCI Scan ..................................................................................................................... 112

Discovery Scans (maps) ...................................................................................................... 116

Scan Configuration....................................................................................... 129

Scanner Appliance List ....................................................................................................... 130

Manage Virtual Scanner Appliances ................................................................................. 135

Update Physical Scanner Appliance .................................................................................. 140

Replace Scanner Appliance ................................................................................................ 144

Scanner Appliance VLANs and Static Routes ................................................................... 146

Option Profile Export ........................................................................................................... 151

Option Profile Import ..........................................................................................................184

Option Profiles for VM .........................................................................................................209

Option Profiles for PCI ......................................................................................................... 243

Option Profiles for Compliance .......................................................................................... 251

KnowledgeBase .................................................................................................................... 330

KnowledgeBase QVS Download in JSON Format .............................................................. 336

Editing Vulnerabilities ......................................................................................................... 339

Static Search Lists ................................................................................................................ 342

Dynamic Search Lists .......................................................................................................... 347

Vendor IDs and References ................................................................................................ 358

Manage Containerized Scanner Appliance ....................................................................... 361

Create New Containerized Scanner Appliance .......................................................... 361

List Containerized Scanner Appliance ........................................................................ 363

Update Containerized Scanner Appliance ................................................................. 366

Delete Containerized Scanner Appliance ................................................................... 369

Scan Authentication..................................................................................... 371

User Permissions Summary ............................................................................................... 372

List Authentication Records ............................................................................................... 373

List Authentication Records by Type ................................................................................ 375

Apache Cassandra Record .................................................................................................. 380

Application Server Records ................................................................................................. 386

Azure MS SQL Record .......................................................................................................... 391

Cisco APIC 4.x Authentication Record ............................................................................... 396

DNS BIND Authentication Record ..................................................................................... 403

Docker Record ...................................................................................................................... 409

HTTP Record ......................................................................................................................... 412

IBM DB2 Record .................................................................................................................... 415

InformixDB Record ..............................................................................................................420

Infoblox Record .................................................................................................................... 425

JBoss Server record .............................................................................................................. 431

Kubernetes Record ..............................................................................................................435

MariaDB Record ................................................................................................................... 438

MarkLogic Record ................................................................................................................ 442

Microsoft SharePoint Record .............................................................................................. 449

MongoDB Record .................................................................................................................459

System created MongoDB records .............................................................................. 462

MS Exchange Server ............................................................................................................ 469

MS SQL Record ..................................................................................................................... 474

MySQL Record ...................................................................................................................... 484

Neo4j Record ........................................................................................................................ 503

Nginx Record ........................................................................................................................ 508

Oracle Record ....................................................................................................................... 512

System created Oracle records .................................................................................... 518

Oracle Listener Record ........................................................................................................ 520

Oracle WebLogic Server Record ......................................................................................... 522

Palo Alto Firewall Record .................................................................................................... 525

Pivotal Greenplum Record .................................................................................................. 529

PostgreSQL Record ............................................................................................................... 536

SAP Hana Record ................................................................................................................. 543

SAP IQ Record ...................................................................................................................... 548

SNMP Record ........................................................................................................................ 553

Sybase Record ...................................................................................................................... 558

Unix Record .......................................................................................................................... 564

Network SSH Record ........................................................................................................... 581

VMware Record .................................................................................................................... 588

Windows Record .................................................................................................................. 594

Oracle HTTP Server Record ................................................................................................ 602

vCenter - ESXi Mapping Records ........................................................................................ 612

Vault Support................................................................................................. 618

Vault Support matrix .......................................................................................................... 618

Vault Definition ................................................................................................................... 625

List Vaults ............................................................................................................................. 632

Manage Vaults ..................................................................................................................... 635

Assets..............................................................................................................646

IP List ..................................................................................................................................... 647

Add IPs .................................................................................................................................. 650

Update IPs ............................................................................................................................. 652

Host List ................................................................................................................................ 657

Host Update ......................................................................................................................... 670

Host List Detection .............................................................................................................. 674

Host List Detection - Normalized Data ............................................................................. 701

Host List Detection - Use Cases .......................................................................................... 702

Host List Detection - Best Practices ................................................................................... 703

Excluded Host List ............................................................................................................... 704

Excluded Hosts Change History ......................................................................................... 707

Manage Excluded Hosts ...................................................................................................... 710

Virtual Host List ................................................................................................................... 714

Manage Virtual Hosts .......................................................................................................... 715

Restricted IPs List ................................................................................................................. 717

Manage Restricted IPs ......................................................................................................... 719

Asset Group List ................................................................................................................... 722

Manage Asset Groups .......................................................................................................... 725

Purge Hosts ........................................................................................................................... 730

Patch List .............................................................................................................................. 737

IPv6 Assets.....................................................................................................739

API Support for IPv6 Asset Management and Scanning .................................................. 739

IPv6 Mapping Record List .................................................................................................... 744

Add IPv6 Mapping Records ................................................................................................. 745

Networks........................................................................................................ 747

Network List ......................................................................................................................... 747

Create Network .................................................................................................................... 748

Update Network ................................................................................................................... 750

Assign Scanner Appliance to Network .............................................................................. 751

Reports............................................................................................................753

Report List ............................................................................................................................ 754

Launch Report ...................................................................................................................... 756

Launching Reports Using Asset Tags .......................................................................... 763

Launching and Fetching Compliance Reports in CSV Format ................................. 764

Report Template List ...........................................................................................................767

Launch Scorecard ................................................................................................................ 769

Cancel Running Report ....................................................................................................... 776

Download Saved Report ...................................................................................................... 777

Delete Saved Report ............................................................................................................783

Scheduled Reports List ........................................................................................................ 784

Launch Scheduled Report ................................................................................................... 785

Asset Search Report ............................................................................................................. 785

VM Report Templates................................................................................. 798

API Support for Report Templates ..................................................................................... 798

Scan Template ..................................................................................................................... 799

Cloud Asset Metadata Fields in CSV Format .............................................................. 807

Cloud Asset Metadata Fields in XML Format ............................................................. 807

PCI Scan Template ..............................................................................................................814

Patch Template .................................................................................................................... 816

Map Template ...................................................................................................................... 824

VM Remediation Tickets ............................................................................ 838

Remediation Tickets overview ........................................................................................... 838

Ticket Parameters ................................................................................................................ 840

View Ticket List .................................................................................................................... 842

Edit Tickets ........................................................................................................................... 844

Delete Tickets ...................................................................................................................... 846

View Deleted Ticket List ..................................................................................................... 848

Get Ticket Information ....................................................................................................... 849

Set Vulnerabilities to Ignore on Hosts ............................................................................... 851

Compliance.................................................................................................... 856

Compliance Control List ..................................................................................................... 857

Compliance Policy List ........................................................................................................ 883

Compliance Policy - Export ................................................................................................ 887

Compliance Policy - Import ................................................................................................ 907

Compliance Policy - Merge ................................................................................................. 909

Compliance Policy - Manage Asset Tags ........................................................................... 915

Compliance Policy - Manage Asset Groups ...................................................................... 919

Compliance Posture Information ...................................................................................... 922

PC Posture Information APIs ........................................................................................ 922

PC Posture Streaming APIs ........................................................................................... 942

Get Policy List ................................................................................................................943

Resolve Host IDs ............................................................................................................ 945

Get Posture Info ............................................................................................................. 948

Control Criticality ................................................................................................................ 975

Exceptions ............................................................................................................................ 976

SCAP Cyberscope Report ..................................................................................................... 985

SCAP ARF Report ................................................................................................................. 989

SCAP Policy List .................................................................................................................... 990

Users and Activity Log ............................................................................... 994

User List ................................................................................................................................ 994

Add/Edit User ....................................................................................................................... 996

User Registration Process ................................................................................................. 1005

Accept Qualys EULA .......................................................................................................... 1006

Activate/Deactivate Users ................................................................................................ 1007

User Password Change ...................................................................................................... 1008

Export User Activity Log ................................................................................................... 1010

Appendix A - API Documentation .......................................................... 1013

Appendix B - Ports used for scanning................................................... 1014

Appendix C - Scan Results JSON............................................................ 1016

Appendix D - Error Codes / Descriptions.............................................1022

PCRS Error Codes ...............................................................................................................1024

Appendix E - Streaming Posture API Client Sample Code (Python)1026

Index ..............................................................................................................1033

Preface

9

Preface

Using the Qualys API, third parties can integrate their own applications with Qualys cloud

security and compliance solutions using an extensible XML interface. The APIs described

in this guide are available to customers using Qualys Cloud Platform (VM, PC).

About Qualys

Qualys, Inc. (NASDAQ: QLYS) is a pioneer and leading provider of cloud-based security

and compliance solutions. The Qualys Cloud Platform and its integrated apps help

businesses simplify security operations and lower the cost of compliance by delivering

critical security intelligence on demand and automating the full spectrum of auditing,

compliance and protection for IT systems and web applications.

Founded in 1999, Qualys has established strategic partnerships with leading managed

service providers and consulting organizations including Accenture, BT, Cognizant

Technology Solutions, Deutsche Telekom, Fujitsu, HCL, HP Enterprise, IBM, Infosys, NTT,

Optiv, SecureWorks, Tata Communications, Verizon and Wipro. The company is also a

founding member of the Cloud Security Alliance (CSA). For more information, please visit

www.qualys.com.

Contact Qualys Support

Qualys is committed to providing you with the most thorough support. Through online

documentation, telephone help, and direct email support, Qualys ensures that your

questions will be answered in the fastest time possible. We support you 7 days a week,

24 hours a day. Access support information at www.qualys.com/support/.

10

Welcome

API Conventions

Welcome

The Qualys API allows third parties to integrate their own applications with Qualys cloud

security and compliance solutions using an extensible XML interface. APIs in this user

guide are supported using Qualys Cloud Platform (VM, PC).

We recommend you join our Community and subscribe to our API Notifications RSS Feeds

for announcements and discussions.

API Conventions

Qualys User Account

Authentication with valid Qualys user account credentials is required for making Qualys

API requests to the Qualys API servers. These servers are hosted at the Qualys platform,

also referred to as the Security Operations Center (SOC), where your account is located. If

you need assistance with obtaining a Qualys account, please contact your Qualys account

representative.

Users with a Qualys user account may access the API functions. When a subscription has

multiple users, all users with any user role (except Contact) can use the Qualys API. Each

user’s permissions correspond to their assigned user role.

Qualys user accounts that have been enabled with VIP two-factor authentication can be

used with the Qualys API, however two-factor authentication will not be used when

making API requests. Two-factor authentication is only supported when logging into the

Qualys GUI.

Get API Notifications

Join our Community

API Notifications RSS Feeds

Welcome

Qualys API Server URL

11

Qualys API Server URL

The Qualys API URL you should use for API requests depends on the Qualys platform

where your account is located.

Click here to identify your Qualys platform and get the API URL

This documentation uses the API server URL for Qualys US Platform 1

(https://qualysapi.qualys.com) in sample API requests. If you’re on another platform,

please replace this URL with the appropriate server URL for your account.

Still have questions? You can easily find the API server URL for your account.

Just log in to your Qualys account and go to Help > About. You’ll see this information

under Security Operations Center (SOC).

12

Welcome

Making API requests

Curl samples in our API docs

We use curl in our API documentation to show an example how to form REST API calls,

and it is not meant to be an actual production example of implementation.

GET and POST Methods

Qualys API functions allow API users to submit parameters (name=value pairs) using the

GET and/or POST method. There are known limits for the amount of data that can be sent

using the GET method, and these limits are dependent on the toolkit used. Please refer to

the individual descriptions of the API function calls to learn about the supported methods

for each function.

Parameters in URLs

API parameters, as documented in this user guide, should be specified one time for each

URL. In the case where the same parameter is specified multiple times in a single URL, the

last parameter takes effect and the previous instances are silently ignored.

Date Format in API Results

The Qualys API has adopted a date/time format to provide consistency and

interoperability of the Qualys API with third-party applications. The date format follows

standards published in RFC 3339 and ISO 8601, and applies throughout the Qualys API.

The date format is:

yyyy

-mm-ddThh-mm-ssZ

This represents a UTC value (GMT time zone).

URL Encoding in API Code

You must URL encode variables when using the Qualys API. This is standard practice for

HTTP communications. If your application passes special characters, like the single quote

(‘), parentheses, and symbols, they must be URL encoded.

For example, the pound (#) character cannot be used as an input parameter in URLs. If “#”

is specified, the Qualys API returns an error. To specify the “#” character in a URL you

must enter the encoded value “%23”. The “#” character is considered by browsers and

other Internet tools as a separator between the URL and the results page, so whatever

follows an un-encoded “#” character is not passed to the Qualys API server and returns an

error.

UTF-8 Encoding

The Qualys API uses UTF-8 encoding. The encoding is specified in the XML output header

as shown below.

<?xml version="1.0" encoding="UTF-8" ?>

Welcome

API Limits

13

URL Elements are Case Sensitive

URL elements are case sensitive. The sample URL below will retrieve a previously saved

scan report that has the reference code “scan/987659876.19876”. The parameter name

“ref” is defined in lower-case characters. This URL will return the specified scan report:

https://qualysapi.qualys.com/msp/scan_report.php?

ref=scan/987659876.19876

The sample URL below is incorrect and will not return the specified scan report because

the parameter name “Ref” appears in mixed-case characters:

https://qualysapi.qualys.com/msp/scan_report.php?

Ref=scan/987659876.19876

Decoding XML Reports

There are a number of ways to parse an XML file. Select the method which is most

appropriate for your application and its users. Qualys publishes DTDs for each report on

its Web site. For example, the scan list output DTD is found at the URL shown:

https://qualysapi.qualys.com/api/2.0/fo/scan/scan_list_output.dtd

The URLs to current report DTDs are included with the function descriptions in this

document.

Occasionally Qualys updates the report DTDs. It is recommended that you request the

most recent DTDs from the Qualys platform to decode your reports. The URLs to the

report DTDs are included in this user guide.

Detailed information about each XML report is provided in the document Qualys API for

VM and Compliance XML/DTD Reference

Some parts of the XML report may contain HTML tags or other special characters (such as

accented letters). Therefore, many elements contain CDATA sections, which allow HTML

tags to be included in the report. “High” ASCII and other non-printable characters are

escaped using question marks.

API Limits

Qualys Cloud Platform enforces limits on the API calls subscription users can make. The

limits apply to the use of all APIs, except “session” API (session login/logout).

API controls are applied per subscription based on your subscription’s service level.

Default settings are provided and these may be customized per subscription by Qualys

Support.

There’s 2 controls defined per subscription:

- Concurrency Limit per Subscription (per API). The maximum number of API calls

allowed within the subscription during the configured rate limit period (as per service

level).

14

Welcome

Tracking API usage by user

- Rate Limit per Subscription (per API). The period of time that defines a window when API

calls are counted within the subscription for each API. The window starts from the

moment each API call is received by the service and extends backwards 1 hour or 1 day.

Individual rate and count settings are applied (as per service level).

Click here to learn more about the controls and settings per service level.

How it works - Qualys checks the concurrency limit and rate limit each time an API

request is received. In a case where an API call is received and our service determines a

limit has been exceeded, the API call is blocked and an error is returned (the concurrency

limit error takes precedence).

Tracking API usage by user

You can track API usage per user without the need to provide user credentials such as the

username and password. Contact Qualys Support to get the X-Powered-By HTTP header

enabled. Once enabled, the X-Powered-By HTTP header is returned for each API request

made by a user. The X-Powered-By value includes a unique ID generated for each

subscription and a unique ID generated for each user. See sample headers below.

Click here to learn more.

HTTP Response Headers

Your subscription’s API usage and quota information is exposed in the HTTP response

headers generated by Qualys APIs (all APIs except “session” API).

The HTTP response headers generated by Qualys APIs are described below.

The HTTP status code “OK” (example: “HTTP/1.1 200 OK”) is returned in the header for

normal (not blocked) API calls. The HTTP status code “Conflict” (example: “HTTP/1.1 409

Conflict”) is returned for API calls that were blocked.

Header Description

X-RateLimit-Limit Maximum number of API calls allowed in any given

time period of <number-seconds> seconds, where

<number-seconds> is the value of X-RateLimit-

Window-Sec.

X-RateLimit-Window-Sec Time period (in seconds) during which up to <number-

limit> API calls are allowed, where <number-limit> is

the value of X-RateLimit-Limit.

X-RateLimit-Remaining Number of API calls you can make right now before

reaching the rate limit <number-limit> in the last

<number-seconds> seconds.

X-RateLimit-ToWait-Sec The wait period (in seconds) before you can make the

next API call without being blocked by the rate limiting

rule.

X-Concurrency-Limit-Limit Number of API calls you are allowed to run

concurrently.

Welcome

HTTP Response Headers

15

Sample HTTP Response Headers

Sample 1: Normal API call (API call not blocked)

Returned from API call using HTTP authentication.

HTTP/1.1 200 OK

Date: Fri, 22 Apr 2018 00:13:18 GMT

Server: qweb

X-RateLimit-Limit: 15

X-RateLimit-Window-Sec: 360

X-Concurrency-Limit-Limit: 3

X-Concurrency-Limit-Running: 1

X-RateLimit-ToWait-Sec: 0

X-RateLimit-Remaining: 4

Transfer-Encoding: chunked

Content-Type: application/xml

Sample 2: API Call Blocked (Rate Limit exceeded)

Returned from API call using HTTP authentication.

HTTP/1.1 409 Conflict

Date: Fri, 22 Apr 2018 00:13:18 GMT

Server: qweb

X-RateLimit-Limit: 15

X-RateLimit-Window-Sec: 360

X-Concurrency-Limit-Limit: 3

X-Concurrency-Limit-Running: 1

X-RateLimit-ToWait-Sec: 181

X-RateLimit-Remaining: 0

Transfer-Encoding: chunked

Content-Type: application/xml

Sample 3: API Call Blocked (Concurrency Limit exceeded)

Returned from API call using API session authentication.

X-Concurrency-Limit-

Running

Number of API calls that are running right now

(including the one identified in the current HTTP

response header).

X-Powered-By This header is only returned when the X-Powered-By

header is enabled for your subscription. It includes a

unique ID generated for each subscription and a

unique ID generated for each user. Click here to learn

more.

Header Description

16

Welcome

HTTP Response Headers

HTTP/1.1 409 Conflict

Date: Fri, 22 Apr 2018 00:13:18 GMT

Server: qweb

Expires: Mon, 24 Oct 1970 07:30:00 GMT

Cache-Control: post-check=0,pre-check=0

Pragma: no-cache

X-RateLimit-Limit: 15

X-RateLimit-Window-Sec: 360

X-Concurrency-Limit-Limit: 3

X-Concurrency-Limit-Running: 3

Transfer-Encoding: chunked

Content-Type: application/xml

In case where the concurrency limit has been reached, no information about rate limits

will appear in the HTTP headers.

Sample 4: Tracking API usage through the X-Powered-By HTTP header

HTTP/1.1 200 OK

Date: Fri, 22 Apr 2018 00:13:18 GMT

Server: qweb

X-Powered-By: Qualys:USPOD1:d9a7e94c-0a9d-c745-82e9-

980877cc5043:f178af1e-4049-7fce-81ca-75584feb8e93

X-RateLimit-Limit: 15

X-RateLimit-Window-Sec: 360

X-Concurrency-Limit-Limit: 3

X-Concurrency-Limit-Running: 1

X-RateLimit-ToWait-Sec: 0

X-RateLimit-Remaining: 4

Transfer-Encoding: chunked

Content-Type: application/xml

Once X-Powered-By HTTP header is enabled, information is returned in the following

format:

X-Powered-By Qualys:<POD_ID>:<SUB_UUID>:<USER_UUID>

Where,

POD_ID is the shared POD or a PCP. Shared POD is USPOD1, USPOD2, etc.

SUB_UUID is the unique ID generated for the subscription

USER_UUID is the unique ID generated for the user

For example,

X-Powered-By: Qualys:USPOD1:d9a7e94c-0a9d-c745-82e9-

980877cc5043:f178af1e-4049-7fce-81ca-75584feb8e93

You can use the USER_UUID to track API usage per user.

Welcome

Activity Log

17

Activity Log

You can view the Activity Log using the Qualys user interface and the Activity Log API

(/api/2.0/fo/activity_log). The Activity Log shows details about user actions taken.

To view the Activity Log, log into your Qualys account. Go to Users and click the Activity

Log tab. Select Filters > Recent API Calls. You’ll see the API Processes list showing the API

calls subject to the API limits (all APIs except “session” API) made by subscription users

and/or updated by the service in the past week.

Tip - You can search the processes list to find API processes. You can search by process

state (Queued, Running, Expired, Finished and/or Blocked), by submitted date and by last

updated date. You can search for API processes that were blocked due to exceeding the

API rate limit and/or the API concurrency limit.

18

Authentication to your account

What do I need to know?

Authentication to your account

Authentication with valid Qualys account credentials is required for making Qualys API

requests to the Qualys API servers. When calling the V2 APIs (i.e. APIs with /2.0/ as URL

element), users have the option to choose between session based authentication (using

login and logout operations) and basic HTTP authentication (method supported for V1

APIs (i.e. APIs with /msp/ as URL element).

What do I need to know?

Using the API Session Resource

Session Login

Session Logout

What do I need to know?

Here’s some things to know about making authenticated API requests to Qualys API

servers.

Required Header Parameter

The following header parameter must be included in all API calls using basic HTTP

authentication and session based authentication:

"X-Requested-With: <user description, like a user agent>"

Specifying the required “X-Requested-With” parameter helps to protect Qualys API users

from cross-site request forgery (CSRF) attacks.

Using Basic HTTP Authentication

Using this method, Qualys account credentials are transmitted using the “Basic

Authentication Scheme” over HTTPS for each API call. For information, see the “Basic

Authentication Scheme” section of RFC #2617:

http://www.faqs.org/rfcs/rfc2617.html

The exact method of implementing authentication will vary according to which

programming language is used.

A sample asset/host API request (Curl) using basic HTTP authentication:

curl -H "X-Requested-With: Curl Sample" -u "acme_ab12:passwd"

"https://qualysapi.qualys.com/api/2.0/fo/asset/host/?action=list"

Authentication to your account

Using Session Based Authentication

19

Using Session Based Authentication

Using this method, the user makes a sequence of API requests as follows (supported for

V2 API calls):

Step 1: Make session login request

Use the Qualys API session resource to make a login request. Upon success, the request

returns a session ID in the Set-Cookie HTTP header:

curl -H "X-Requested-With: Curl Sample" -D headers

-d "action=login&username=acme_ab12&password=<PASSWORD>"

"https://qualysapi.qualys.com/api/2.0/fo/session/"

Step 2: Make resource requests

Use the API resources to make API requests, as described in this user guide, and include

the session ID in the cookie header for each request.

You’ll notice the session cookie (QualysSession) was extracted from the “headers” file

contents returned from the session login API call (Step 1 above):

curl -H "X-Requested-With: Curl Sample"

-b "QualysSession=71e6cda2a35d2cd404cddaf305ea0208; path=/api;

secure" -d "action=list"

"https://qualysapi.qualys.com/api/2.0/fo/report/"

Step 3: Make session logout request

Once logged in to Qualys you can make multiple API requests. Use the Qualys API

session resource to logout of the current session. Logging out of the session closes the

open session and ensures secure, ongoing access to your account. Access may be denied if

a user makes too many session login requests without closing sessions properly:

curl -H "X-Requested-With: Curl Sample"

-b "QualysSession=10b8eb6d4553b4d1ecb860c2b3c247d4; path=/api;

secure" -d "action=logout"

"https://qualysapi.qualys.com/api/2.0/fo/session/"

Using the API Session Resource

Sessions created using the Qualys API via the session resource are equivalent in every

way to sessions created by users logging into the Qualys user interface. Too many open

sessions, whether created via the API and/or via user interface login, will lock out new

session login attempts from both interfaces (user and API).

20

Authentication to your account

Using Session Based Authentication

The request URL has several elements. The following elements appear in every request

URL based on the API V2 architecture.

Session Login Request

The session login request includes the Qualys user login credentials, the request URL, and

the location where the HTTP response headers will be saved.

The sample API call below saves the HTTP headers in a local file named “headers”:

curl -H "X-Requested-With: Curl Sample" -D headers

-d "action=login&username=acme_ab12&password=<PASSWORD>"

"https://qualysapi.qualys.com/api/2.0/fo/session/"

If you do not wish to store this information in the “headers” file, you can save the HTTP

header in a cookie as shown below:

curl -H "X-Requested-With: Curl Sample" -c cookie.txt

-d "action=login&username=acme_ab12&password=<PASSWORD>"

"https://qualysapi.qualys.com/api/2.0/fo/session/"

Upon success, the sample Qualys API call returns an XML response with the message

“Logged in” and the Qualys API session ID in the Set-Cookie HTTP header. See “HTTP

Response Headers” for further information.

Resource Requests

When session based authentication is used, the session cookie returned in the XML

response from the session login request must be included in the cookie header of

subsequent API requests. Multiple API requests can be made using the same session

cookie (this is supported using V2 API requests).

The resource request includes the Qualys user login credentials, the Qualys API session

ID, the request URL, and the location where the HTTP response headers are saved.

The sample API request below is used to request a list of reports in the user’s Report Share

storage space. You’ll notice the session cookie (QualysSession) was extracted from the

“headers” file contents returned from the session login API call.

URL element Description

qualysapi.qualys.com:443 FQDN of the Qualys API server and option port (443 if

specified).

api

Qualys Application component name.

2.0 Qualys API version number.

fo Qualys interface component name.

session|scan|report or other

component name

Qualys API resource name, i.e. session or some other

component like scan or report etc.

action={value} Qualys API resource-specific action. In the sample session

login URL above, the action is “login”.

Authentication to your account

Using Session Based Authentication

21

curl -H "X-Requested-With: Curl Sample"

-d "action=list"

-b "QualysSession=71e6cda2a35d2cd404cddaf305ea0208; path=/api;

secure" "https://qualysapi.qualys.com/api/2.0/fo/report/"

If you saved the HTTP response headers (from the session login request) in a cookie file,

make an API request to obtain the cookie from the cookie file as shown below:

curl -H "X-Requested-With: Curl Sample"

-d "action=list"

-b "cookie.txt" "https://qualysapi.qualys.com/api/2.0/fo/report/"

Upon success, the sample report list API call returns an XML response listing the reports

in the user’s Report Share. In progress and completed reports are included.

HTTP Response Headers

These API requests return HTTP response headers: session login requests, session logout

requests, and fetch (download) report requests. These requests provide information to the

third party application about the XML output.

Sample XML output showing HTML response headers returned from a session logout

request:

HTTP/1.1 200 OK

Date: Wed, 20 Jun 2007 16:21:03 GMT

Server: qweb/3.3h

Set-Cookie: QualysSession=71e6cda2a35d2cd404cddaf305ea0208;

path=/api; secure

Expires: Mon, 24 Oct 1970 07:30:00 GMT

Cache-Control: post-check=0,pre-check=0

Pragma: no-cache

Connection: close

Transfer-Encoding: chunked

Content-Type: text/xml

Sample XML output showing HTML response headers returned from a fetch (download)

report request, where the report format is HTML:

HTTP/1.1 200 OK

Date: Wed, 20 Jun 2007 16:36:42 GMT

Server: qweb/3.3h

Expires: Mon, 24 Oct 1970 07:30:00 GMT

Cache-Control: post-check=0,pre-check=0

Pragma: no-cache

Content-Disposition: attachment;

filename=scan_report__1182357402.zip

Content-length: 98280

Connection: close

22

Authentication to your account

Session Login

Content-Type: application/zip

Expires HTTP Header - For the Expires header, Qualys complies with RFC #2109 and sets

the Expires date to an old date (a date long in the past). Currently Qualys sets the Expires

date to “Mon, 24 Oct 1970 07:30:00 GMT”. Note that Qualys cookie expiration is managed

on the server side, and Qualys does not rely on clients to drop their expired cookies.

Session Logout Request

A sample session logout request (POST method) is shown below. Upon success, the

sample Qualys API call returns an XML response with the message “Logged out”.

curl -H "X-Requested-With: Curl Sample"

-d "action=logout"

-b "QualysSession=71e6cda2a35d2cd404cddaf305ea0208; path=/api;

secure" "https://qualysapi.qualys.com/api/2.0/fo/session/"

See “Session Logout” below for further information.

Session Timeout

Every Qualys user account has a session timeout setting. This setting is configurable at

the subscription level by Manager users in the Qualys user interface (go to Users > Setup >

Security). For a new subscription, this is set to 60 minutes.

The session timeout applies to sessions started using the user interface and sessions

started using the Qualys APIs, including APIs based on the new API architecture.

When you launch a scan or report (using Report Share), the task is launched in the

background, and processing does not timeout until the task has completed.

Session Login

/api/2.0/fo/session/?action=login

[POST]

Make a request to Qualys API server for session login.

A session login request is used to authenticate to the Qualys API and receive a Qualys API

session ID, which must be included in the cookie header of subsequent API resource

requests.

Input Parameters

Parameter Description

action=login (Required) A flag used to make a session login request.

username (Required) The user name (login) of a Qualys user account.

Authentication to your account

Session Login

23

A sample session login request (POST method) is shown below. Upon success, the sample

Qualys API call returns an XML response with the message “Logged in” and the Qualys API

session ID as shown.

curl -H "X-Requested-With: Curl Sample" -D headers.4

-d "action=login&username=acme_ab12&password=<PASSWORD>"

"https://qualysapi.qualys.com/api/2.0/fo/session/"

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE GENERIC SYSTEM

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>Logged in</TEXT>

</RESPONSE>

</SIMPLE_RETURN>

cat headers.4

HTTP/1.1 200 OK

Date: Wed, 20 Jun 2007 16:21:03 GMT

Server: qweb/3.3h

Set-Cookie: QualysSession=71e6cda2a35d2cd404cddaf305ea0208;

path=/api; secure

Expires: Mon, 24 Oct 1970 07:30:00 GMT

Cache-Control: post-check=0,pre-check=0

Pragma: no-cache

password

(Required) The password of a Qualys user account.

When using -d in the curl request for login, you must URL

encode any special characters in the password. For

example, if your password is Peas+Carrots then you must

specify it as password=Peas%2BCarrots or authentication

will not be successful.

When using -u in the curl request for login, you can enter

the password as is without URL encoding special

characters. Using the same example, you’d specify

password=Peas+Carrots as part of the request.

echo_request={0|1} (Optional) Specifies whether to echo the request’s input

parameters (names and values) in the XML output. When

not specified, parameters are not included in the XML

output. Specify 1 to view parameters in the XML output.

Parameter Description

24

Authentication to your account

Session Logout

Connection: close

Transfer-Encoding: chunked

Content-Type: text/xml

Session Logout

/api/2.0/fo/session/?action=logout

[POST]

Make a request to Qualys API server for session logout.

When you’re done making V2 API resource requests, the third party application must

make a session logout request. This results in closing the session ID for the user’s

account, preventing future API requests from running.

Input Parameters

A sample session logout request (POST method) is shown below. Upon success, the

sample Qualys API call returns an XML response with the message “Logged out” as shown.

curl -H "X-Requested-With: Curl Sample"

-d "action=logout"

-b "QualysSession=71e6cda2a35d2cd404cddaf305ea0208; path=/api;

secure" "https://qualysapi.qualys.com/api/2.0/fo/session/"

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE GENERIC SYSTEM

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>Logged out</TEXT>

</RESPONSE>

</SIMPLE_RETURN>

cat headers.18

HTTP/1.1 200 OK

Parameter Description

action=logout (Required) A flag used to make a session logout request.

echo_request={0|1} (Optional) Specifies whether to echo the request’s input

parameters (names and values) in the XML output. When

not specified, parameters are not included in the XML

output. Specify 1 to view parameters in the XML output.

Authentication to your account

Session Logout

25

Date: Wed, 20 Jun 2007 21:50:36 GMT

Server: qweb/3.3h

Expires: Mon, 24 Oct 1970 07:30:00 GMT

Cache-Control: post-check=0,pre-check=0

Pragma: no-cache

Set-Cookie: QualysSession=71e6cda2a35d2cd404cddaf305ea0208;

expires=Wed, 13-Jun-2007 21:50:37 GMT; path=/fo

Connection: close

Transfer-Encoding: chunked

Content-Type: text/xml

26

Scans

Launch and manage vulnerability scans, compliance scans, discovery scans (maps).

VM Scans | Compliance Scans | Cloud Perimeter Scans

VM Scan Schedules | PC Scan Schedules

Scan List Parameters | Scan Parameters | Cloud Perimeter Scan Parameters | Scan

Schedule Parameters

VM Scan Statistics

VM Scan Summary | Scan Summary

Scanner Details

Share PCI Scan

Discovery Scans (maps) | Domain List | Add/Edit Domain

Scans

VM Scans

27

VM Scans

The VM Scan API (/api/2.0/fo/scan/) is used to obtain a list of vulnerability scans in your

account and to take actions on them like cancel, pause, resume, and fetch (download)

finished results.

Express Lite: This API is available to Express Lite users.

Permissions

VM Scan List

/api/2.0/fo/scan/?action=list

[GET] [POST]

List vulnerability scans in the user’s account. By default the XML output lists scans

launched in the past 30 days.

Input Parameters

The input parameters for requesting a VM scan list are shown below. See Scan List

Parameters for complete details.

User Role Permissions

Manager Manage scans on all IPs in the subscription.

Unit Manager Launch, list and fetch scans on IPs in the user’s business

unit. And take actions on scans launched by users in the

same business unit (cancel, pause, resume and delete).

Scanner Launch, list and fetch scans on IPs in the user’s account.

And take actions on scans that the user owns (cancel,

pause, resume and delete).

Reader View scans with targets containing IPs in the user’s

account. Download scan results when the target includes

at least one IP in the user’s account.

Auditor No permissions.

Typ e Parameter List

Request action=list (required), echo_request

Scan List Filters scan_ref, state, processed, type, target, user_login,

launched_after_datetime, launched_before_datetime,

scan_type=certview, scan_type=ec2certview, client_id and

client_name (only for Consultant type subscriptions)

Show/Hide Information show_ags, show_op, show_status, show_last, ignore_target

28

Scans

VM Scans

Samples

List all scans in the user account.

curl -H "X-Requested-With: Curl Sample"

-b "QualysSession=71e6cda2a35d2cd404cddaf305ea0208; path=/api;

secure" "https://qualysapi.qualys.com/api/2.0/fo/scan/

?action=list&echo_request=1&show_ags=1&show_op=1"

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SCAN_LIST_OUTPUT SYSTEM

"https://qualysapi.qualys.com/api/2.0/fo/scan/scan_list_output.dtd

">

<SCAN_LIST_OUTPUT>

<USER_LOGIN>acme_ab</USER_LOGIN>

<RESOURCE>https://qualysapi.qualys.com/api/2.0/fo/scan/

</RESOURCE>

<PARAM_LIST>

<PARAM>

<KEY>action</KEY>

</PARAM>

<PARAM>

<KEY>echo_request</KEY>

</PARAM>

<PARAM>

</PARAM>

<PARAM>

</PARAM>

</PARAM_LIST>

</REQUEST>

<SCAN_LIST>

<SCAN>

<TYPE>On-Demand</TYPE>

<USER_LOGIN>acme_ab</USER_LOGIN>

<LAUNCH_DATETIME>2018-05-25-25T08:10:43Z</LAUNCH_DATETIME>

Scans

VM Scans

29

<STATE>Finished</STATE>

</STATUS>

<OPTION_PROFILE>

<DEFAULT_FLAG>1</DEFAULT_FLAG>

</OPTION_PROFILE>

</SCAN>

<SCAN>

<TYPE>Scheduled</TYPE>

<USER_LOGIN>acme_sb3</USER_LOGIN>

<LAUNCH_DATETIME>2018-05-24T15:40:02Z</LAUNCH_DATETIME>

<STATE>Finished</STATE>

</STATUS>

<OPTION_PROFILE>

<DEFAULT_FLAG>1</DEFAULT_FLAG>

</OPTION_PROFILE>

</SCAN>

</SCAN_LIST>

</RESPONSE>

</SCAN_LIST_OUTPUT>

...

List all running scans that were launched by the user with the login ID “acme_ab”:

curl -H "X-Requested-With: Curl Sample"

-b "QualysSession=71e6cda2a35d2cd404cddaf305ea0208; path=/api;

secure" "https://qualysapi.qualys.com/api/2.0/fo/scan/

?action=list&state=Running&user_login=acme_ab"

List all scheduled scans that were launched after June 5, 2018.

curl -H "X-Requested-With: Curl Sample"

-b "QualysSession=71e6cda2a35d2cd404cddaf305ea0208; path=/api;

secure" "https://qualysapi.qualys.com/api/2.0/fo/scan/

?action=list&type=Scheduled&launched_after_datetime=2018-06-05"

30

Scans

VM Scans

List all scans for AFCO Company client (only for Consultant type subscriptions).

curl -u "USERNAME:PASSWORD" -H "content-type:

text/xml""https://qualysapi.qualys.com/api/2.0/fo/scan/?action=lis

t&client_name=AFCO Company"

DTD

<platform API server>/api/2.0/fo/scan/scan_list_output.dtd

List Last ‘N’ Scan References for a Schedule

api/2.0/fo/scan/schedules/runhistory/?action=list

[GET]

Provides a list of the most recent "N" scan references associated with a particular schedule

ID, allowing you to monitor and track automated scans initiated for that schedule.

Note: This API does not work for MAP schedule scan ids.

Input Parameters

Sample

List the last 'n' scan references for the given schedule IDs.

API request:

curl --location

'<qualys_base_url>/api/2.0/fo/scan/schedules/runhistory/?action=li

st&output_format=xml&schedule_executions_count=4&schedule_scan_ids

=99446%2C85403%2C144180%2C144181%2C6666%2C657657%2C125485' \

--header 'X-Requested-With: test' \

--header 'Authorization: Basic <token>'

XML output:

<?xml version="1.0" encoding="UTF-8"?>

Parameter Description

action=list (Required)

schedule_scan_ids (Required) Specify schedule ids in a comma-separated list.

Maximum 500 schedule ids are supported.

output_format (Optional) Specify output file format. Default value is “xml”

format.

Supported values are “xml” & “json”.

schedule_executions_count (Optional) Specify a schedule execution count. You can specify a

value form 1 to 10. When not specified, 3 is taken as the default.

Scans

VM Scans

31

<!DOCTYPE SCHEDULES_RUN_HISTORY SYSTEM

"<platform_API_server>/api/2.0/fo/scan/schedules/runhistory/output

.dtd">

<SCHEDULES_RUN_HISTORY>

<SCHEDULE_LIST>

<SCHEDULE_ID>85403</SCHEDULE_ID>

<SCHEDULE_RUN_HISTORY>

<SCHEDULE_RUN>

<SCAN_LAUNCH_INFO>

<SCAN_ID>99408</SCAN_ID>

<SCAN_REFERENCE>scan/1634824016.99408</SCAN_REFERENCE>

<LAUNCH_DATETIME>2021-10-21

13:46:56</LAUNCH_DATETIME>

<STATUS>FINISHED</STATUS>

<DURATION>86 Seconds</DURATION>

<SUBSCRIPTION_ID>237630</SUBSCRIPTION_ID>

<OPTION_PROFILE_TITLE>Initial

Options</OPTION_PROFILE_TITLE>

<IS_PROCESSED>1</IS_PROCESSED>

</SCAN_LAUNCH_INFO>

</SCHEDULE_RUN>

</SCHEDULE_RUN_HISTORY>

</SCHEDULE>

<SCHEDULE_ID>99446</SCHEDULE_ID>

<SCHEDULE_RUN_HISTORY>

<SCHEDULE_RUN>

<SCAN_LAUNCH_INFO>

<SCAN_ID>99561</SCAN_ID>

<SCAN_REFERENCE>scan/1635442781.99561</SCAN_REFERENCE>

<LAUNCH_DATETIME>2021-10-28

17:39:41</LAUNCH_DATETIME>

<TARGET>list of target ips</TARGET>

<STATUS>FINISHED</STATUS>

<DURATION>434 Seconds</DURATION>

<SUBSCRIPTION_ID>237630</SUBSCRIPTION_ID>

32

Scans

VM Scans

<OPTION_PROFILE_TITLE>Initial

Options</OPTION_PROFILE_TITLE>

<IS_PROCESSED>1</IS_PROCESSED>

</SCAN_LAUNCH_INFO>

</SCHEDULE_RUN>

<SCHEDULE_RUN>

<SCAN_LAUNCH_INFO>

<SCAN_ID>99554</SCAN_ID>

<SCAN_REFERENCE>scan/1635431408.99554</SCAN_REFERENCE>

<LAUNCH_DATETIME>2021-10-28

14:30:08</LAUNCH_DATETIME>

<STATUS>FINISHED</STATUS>

<DURATION>9 Seconds</DURATION>

<SUBSCRIPTION_ID>237630</SUBSCRIPTION_ID>

<OPTION_PROFILE_TITLE>Initial

Options</OPTION_PROFILE_TITLE>

<IS_PROCESSED>1</IS_PROCESSED>

</SCAN_LAUNCH_INFO>

</SCHEDULE_RUN>

<SCHEDULE_RUN>

<SCAN_LAUNCH_INFO>

<SCAN_ID>99553</SCAN_ID>

<SCAN_REFERENCE>scan/1635431408.99553</SCAN_REFERENCE>

<LAUNCH_DATETIME>2021-10-28

14:30:08</LAUNCH_DATETIME>

<STATUS>FINISHED</STATUS>

<DURATION>79 Seconds</DURATION>

<SUBSCRIPTION_ID>237630</SUBSCRIPTION_ID>

<OPTION_PROFILE_TITLE>Initial

Options</OPTION_PROFILE_TITLE>

<IS_PROCESSED>1</IS_PROCESSED>

</SCAN_LAUNCH_INFO>

</SCHEDULE_RUN>

</SCHEDULE_RUN_HISTORY>

</SCHEDULE>

</SCHEDULE_LIST>

</RESPONSE>

</SCHEDULES_RUN_HISTORY>

Scans

VM Scans

33

DTD

<platform_API_server>/api/2.0/fo/scan/schedules/runhistory/output.dtd

Launch VM Scan

/api/2.0/fo/scan/?action=launch

[POST]

Launch vulnerability scan in the user’s account.

Good to Know

- The Launch Scan API is asynchronous. When you make a request to launch a scan using

this API, the service will return a scan reference ID right away and the call will quit

without waiting for the complete scan results.

- When you launch a VM scan using the API, we check to see if the IPs in the scan target

are available to the user making the scan request. To determine this, we check that each

IP is in the subscription, in the VM license, and in the user’s assigned scope. If any IP in the

target is not available to the user, then it will be skipped from the scan job.

For example, let’s say you specify the IP range 10.10.10.100-10.10.10.120, but IPs

10.10.10.115 and 10.10.10.120 are not available to you. In this case, we will launch the

scan on 10.10.10.100-10.10.10.114, 10.10.10.116-10.10.10.119, and we’ll skip 10.10.10.115

and 10.10.10.120.

- Using networks? Choose the Global Default Network to scan IPs on your network

perimeter.

Input Parameters

The input parameters for launching a VM scan are shown below. See Scan Parameters for

complete details.

Typ e Parameter List

Request action=launch (required), echo_request,

runtime_http_header

Scan Title scan_title

Option Profile option_id or option_title

Scanner Appliance iscanner_id or iscanner_name, ec2_instance_ids

Processing Priority priority

Asset IPs/Groups ip, asset_group_ids, asset_groups, exclude_ip_per_scan,

default_scanner, scanners_in_ag

34

Scans

VM Scans

Sample - Launch scan on IP address

API request:

curl -H "X-Requested-With: Curl" -u "USERNAME:PASSWORD" -X "POST"

-d

"action=launch&scan_title=My+Vulnerability+Scan&ip=10.10.10.10&opt

ion_id=43165&iscanner_name=scanner1"

"https://qualysapi.qualys.com/api/2.0/fo/scan/" > outputfile.txt

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>New vm scan launched</TEXT>

<ITEM_LIST>

<ITEM>

</ITEM>

<ITEM>

<KEY>REFERENCE</KEY>

</ITEM>

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

Asset Tags target_from=tags, use_ip_nt_range_tags_include,

use_ip_nt_range_tags_exclude, use_ip_nt_range_tags,

tag_include_selector, tag_exclude_selector, tag_set_by,

tag_set_exclude, tag_set_include

Network ip_network_id (when the Network Support feature is

enabled)

Client client_id and client_name (only for Consultant type

subscriptions)

Typ e Parameter List

Scans

VM Scans

35

Sample - Launch Scan Samples

API request (FQDN only):

curl -H "X-Requested-With: Curl" -u "USERNAME:PASSWD" -X "POST" -d

"action=launch&option_title=Initial+Options&fqdn=domain.qualys.com

&iscanner_name=scanner_us"

"https://qualysapi.qualys.com/api/2.0/fo/scan/" > outputfile.txt

API request (FQDN and asset group):

curl -H "X-Requested-With: Curl" -u "USERNAME:PASSWD" -X "POST" -d

"action=launch&option_title=Initial+Options&fqdn=domain.qualys.com

&iscanner_name=scanner_us&scan_title=My+Scan&asset_groups=My+AG"

"https://qualysapi.qualys.com/api/2.0/fo/scan/" > outputfile.txt

Sample - Launch scan using asset tags

API request:

curl -H "X-Requested-With: Curl" -u "USERNAME:PASSWD" -X "POST" -d

"action=launch&scan_title=My+Vulnerability+Scan&target_from=tags&t

ag_set_by=name&tag_set_include=Windows&option_id=43165&iscanner_na

me=scanner1" "https://qualysapi.qualys.com/api/2.0/fo/scan/" >

file.txt

Sample - Launch scan using All Scanners in Network

API request:

curl -u "username:password" -H "X-Requested-With:curl demo" -d

"action=launch&scan_title=scan3&option_title=Initial+Options&ip_ne

twork_id=12807913&scanners_in_network=1&asset_groups=AG1-GDN"

"https://qualysapi.qualys.com/api/2.0/fo/scan/"

Launch VM Scan on EC2 assets

/api/2.0/fo/scan/?action=launch

[POST]

Launch vulnerability scan on your Amazon EC2 hosts (in your Amazon Web Services

account).

A few things to consider...

- EC2 Scanning must be enabled for your Qualys account.

- Managers and Unit Managers can launch EC2 scans.

- Before scanning you’ll need to complete some set up steps. See Securing Amazon Web

Services with Qualys

36

Scans

VM Scans

Input Parameters

The input parameters for launching an EC2 scan are shown below. See Scan Parameters

for complete details.

Sample - Launch EC2 Vulnerability scan

Launch an EC2 vulnerability scan using the connector “EC2_Connector” on assets that

match tags with IDs 1558997 and 1559222.

API request:

curl -H "X-Requested-With: Curl" -u "USERNAME:PASSWD" -X "POST" -d

"action=launch&scan_title=My+EC2+Scan&connector_name=EC2_Connector

&ec2_endpoint=us-east-1&target_from=tags&use_ip_nt_range_tags=0

&tag_include_selector=any&tag_set_by=id&tag_set_include=1558997,15

59222&option_id=43165&iscanner_name=EC2-1"

"https://qualysapi.qualys.com/api/2.0/fo/scan/" > outputfile.txt

Typ e Parameter List

Request action=launch (required), echo_request

Scan Title scan_title

EC2 environment connector_name (required), ec2_endpoint (required)

Option Profile option_id or option_title

Scanner Appliance iscanner_id or iscanner_name

Processing Priority priority

Target Hosts

Note: You can use either

ec2_instance_ids or tags

parameter or both

target_from=tags

Use tags to select the EC2 hosts you want to scan.

These parameters provide separate options for including

and excluding tags for network IP ranges.

use_ip_nt_range_tags_include={0|1} (default in bold)

Important - This cannot be set to “1” for EC2 scanning.

use_ip_nt_range_tags_exclude={0|1} (default in bold)

Important - This cannot be set to “1” for EC2 scanning.

This parameter has been replaced with the include/exclude

options above but it is still supported.

use_ip_nt_range_tags={0|1} (default in bold)

Important - This cannot be set to “1” for EC2 scanning.

These tag parameters are used to select tags:

tag_set_include={tag1,tag2,...} (required)

tag_set_exclude={tag1,tag2,...} (optional)

tag_include_selector={any|all} (default in bold)

tag_exclude_selector={any|all} (default in bold)

tag_set_by={id|name} (default in bold)

ec2_instance_ids={value}

The ID of the target EC2 instance to launch the VM or

compliance scan. Multiple ec2 instance ids are comma

separated. You can add up to maximum 10 instance Ids.

Scans

VM Scans

37

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>New vm scan launched</TEXT>

<ITEM_LIST>

<ITEM>

</ITEM>

<ITEM>

<KEY>REFERENCE</KEY>

</ITEM>

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

Sample - Launch EC2 Vulnerability scan for EC2 instance

Launch a VM scan on EC2 instances using the parameter ec2_instance_ids.

This sample is for a vulnerability scan with a mix of valid and invalid instance IDs. The

scan is launched on the valid instance IDs and the invalid instance IDs are listed in the

output with the reasons they were considered invalid. Some did not belong to the EC2

environment and some were not activated for VM.

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With:curl" -d

"action=launch&scan_title=Sample2&connector_name=EC2

Connector&ec2_endpoint=us-east-1&option_title=Initial

Options&iscanner_name=EC2_Scanner&ec2_instance_ids=i-

01f234ce567ae890f,i-

0be12cb3da4567e8a,i-0d1f23d4ba5c67e8b,i-0123e456f7890f123,i-

012f3ceb4a5d6789d,i-0c123e4f567890123,i-012345a67bba89012,i-

01ba23a45cba678af,i-012345678dfc90efe,i-0ab12e3456baadeb7"

"https://qualysapi.qualys.com/api/2.0/fo/scan/"

XML output:

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://qualysapi.qualys.com/api/2.0/fo/scan/dtd/launch_output.dt

d">

38

Scans

VM Scans

<SIMPLE_RETURN>

<TEXT>New vm scan launched</TEXT>

<NOTIFICATION>The following instances were skipped because they do

not belong to the selected EC2 environment: i-012f3ceb4a5d6789d,i-

0c123e4f567890123, i-012345a67bba89012. The following instances

were skipped because they are not activated for VM: i-

01ba23a45cba678af, i-012345678dfc90efe, i-

0ab12e3456baadeb7.</NOTIFICATION>

<ITEM_LIST>

<ITEM>

</ITEM>

<ITEM>

<KEY>REFERENCE</KEY>

</ITEM>

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

Manage VM Scans

/api/2.0/fo/scan/?action={action}

Take actions on vulnerability scans in their account, like cancel, pause, resume, delete

and fetch completed scan results.

Parameter Description

action={action} (Required) One action required for the request:

cancel - Stop a scan in progress (POST method)

pause - Stop a scan in progress and change status to “Paused”

(POST method)

resume - Restart a scan that has been paused (POST method)

delete - Delete a scan in your account (POST method)

fetch - Download scan results for a scan with status of

“Finished”, “Canceled”, “Paused” or “Error” (GET or POST method)

echo_request={0|1} (Optional) Specify 1 to echo the input parameters in the XML

output. When unspecified, parameters are not listed in the XML

output.

scan_ref={value} (Required) The scan reference for a vulnerability scan. This will

have the format: scan/nnnnnnnnnn.nnnnn

Scans

VM Scans

39

Input Parameters

Samples - Take actions on scans

Cancel a scan (POST method) is shown below.

curl -H "X-Requested-With: Curl Sample"

-d "action=cancel&scan_ref=234234234.12345"

-b "QualysSession=71e6cda2a35d2cd404cddaf305ea0208; path=/api;

secure" "https://qualysapi.qualys.com/api/2.0/fo/scan/"

Parameter Description

action={action} (Required) An action for the request:

cancel - stop a scan in progress, “Running” or “Paused”

pause - stop a scan in progress and change status to “Paused”

resume - restart a scan that has been paused

fetch - download scan results for a scan with the status

“Finished”, “Canceled”, “Paused” or “Error”.

echo_request={0|1} (Optional) Specifies whether to echo the request’s input

parameters (names and values) in the XML output. When not

specified, parameters are not included in the XML output.

Specify 1 to view parameters in the XML output.

scan_ref={value} (Required) Specifies a scan reference. A scan reference has the

format

“scan/987659876.19876”.

ips={value} (Optional for a fetch request) Show only certain IP

addresses/ranges in the scan results. One or more IPs/ranges

may be specified. A range entry is specified using a hyphen (for

example, 10.10.10.1-10.10.10.20). Multiple entries are comma

separated.

mode={brief|extended} (Optional for fetch request) The verbosity of the scan results

details: brief (the default) or extended. The brief output includes

this information: IP address, DNS hostname, NetBIOS hostname,

QID and scan test results if applicable. The extended output

includes the brief output plus this extended information:

protocol, port, an SSL flag (“yes” is returned when SSL was used

for the detection, “no” is returned when SSL was not used), and

FQDN if applicable.

output_format={csv|json|

csv_extended|

json_extended}

(Optional for fetch request) The output format of the

vulnerability scan results. A valid value is: csv (the default), json

(for JavaScript Object Notation(), csv_extended, json_extended.

Click here for information on Scan Results JSON

client_id={value} (Optional for fetch request) Id assigned to the client (Consultant

type subscription only). Parameter client_id or client_name may

be specified for the same request.

client_name={value} (Optional for fetch request) Name of the client (Consultant type

subscription only). Parameter client_id or client_name may be

specified for the same request.

40

Scans

VM Scans

Pause a scan (POST method) is shown below.

curl -H "X-Requested-With: Curl Sample"

-d "action=pause&scan_ref=234234234.12345"

-b "QualysSession=71e6cda2a35d2cd404cddaf305ea0208; path=/api;

secure" "https://qualysapi.qualys.com/api/2.0/fo/scan/"

Resume a scan (POST method) is shown below.

curl -H "X-Requested-With: Curl Sample"

-d "action=resume&scan_ref=234234234.12345"

-b "QualysSession=71e6cda2a35d2cd404cddaf305ea0208; path=/api;

secure" "https://qualysapi.qualys.com/api/2.0/fo/scan/"

Fetch/download a scan result is shown below.

curl -H "X-Requested-With: Curl Sample"

-d "action=fetch&scan_ref=234234234.12345"

-b "QualysSession=71e6cda2a35d2cd404cddaf305ea0208; path=/api;

secure" "https://qualysapi.qualys.com/api/2.0/fo/scan/"

DTD

<platform API server>/api/2.0/simple_return.dtd

Scans

Compliance Scans

41

Compliance Scans

The Compliance Scan API (/api/2.0/fo/scan/compliance/) is used to launch compliance

scans, get a list of compliance scans in your account and manage them. The SCAP Scan

API (/api/2.0/fo/scan/scap/) is used to get a list of SCAP scans in your account.

Permissions

Note: The Compliance Scan APIs are available as part of one of the following subscription

combinations only:

- PC and API add-on

- PC, SCA, and API add-on

- VMDR, SCA, and API add-on

Role-based user permissions are described below.

User Role Permissions

Manager Manage compliance scans on all compliance IPs in the

subscription.

Unit Manager When the "Manage compliance" permission is enabled in the

user’s account settings: 1) ability to launch, list and fetch

compliance scans on IPs in the user’s business unit, 2) ability to

take actions on scans launched by users in the same business

unit (cancel, pause, resume and delete).

Scanner When the "Manage compliance" permission is enabled in the

user’s account settings: 1) ability to launch, list and fetch

compliance scans on IPs in the user’s account, 2) ability to take

actions on scans that the user owns (cancel, pause, resume and

delete).

Reader No permissions to manage compliance scans.

Auditor No permissions to manage compliance scans.

42

Scans

Compliance Scans

Compliance Scan List

/api/2.0/fo/scan/compliance/ with action=list

[GET] [POST]

List of compliance scans in your account. By default the XML output lists scans launched

in the past 30 days.

The input parameters for requesting a PC scan list are below. See Scan List Parameters for

complete details.

API Request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST"

-d

"action=list&state=Finished&scan_ref=compliance/1344842952.1340"

"https://qualysapi.qualys.com/api/2.0/fo/scan/compliance/"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SCAN_LIST_OUTPUT SYSTEM

"https://qualysapi.qualys.com/api/2.0/fo/scan/scan_list_output.dtd

">

<SCAN_LIST_OUTPUT>

<SCAN_LIST>

<SCAN>

<REF>compliance/1344842952.1340</REF>

<TYPE>Scheduled</TYPE>

<USER_LOGIN>USERNAME</USER_LOGIN>

<LAUNCH_DATETIME>2018-05-13T07:30:09Z</LAUNCH_DATETIME>

<STATE>Finished</STATE>

Typ e Parameter List

Request action=list (required), echo_request

Scan List Filters scan_id (compliance scan ID), scan_ref, state, processed,

type, target, user_login, launched_after_datetime,

launched_before_datetime, client_id and client_name (only

for Consultant type subscriptions)

Show Information show_ags, show_op, show_status, show_last

Scans

Compliance Scans

43

</STATUS>

</SCAN>

</SCAN_LIST>

</RESPONSE>

</SCAN_LIST_OUTPUT>

DTD:

<platform API server>/api/2.0/fo/scan/scan_list_output.dtd

List Last ‘N’ Scan References for a Schedule

api/2.0/fo/scan/schedules/runhistory/?action=list

[GET]

Provides a list of the most recent "N" scan references associated with a particular schedule

ID, allowing you to monitor and track automated scans initiated for that schedule.

Note: This API does not work for MAP schedule scan ids.

Input Parameters

Sample

List the last 'n' scan references for the given schedule IDs.

API request:

curl --location

'<qualys_base_url>/api/2.0/fo/scan/schedules/runhistory/?action=li

st&output_format=xml&schedule_executions_count=4&schedule_scan_ids

=99446%2C85403%2C144180%2C144181%2C6666%2C657657%2C125485' \

--header 'X-Requested-With: test' \

--header 'Authorization: Basic <token>'

Parameter Description

action=list (Required)

schedule_scan_ids (Required) Specify schedule ids in a comma-separated list.

Maximum 500 schedule ids are supported.

output_format (Optional) Specify output file format. Default value is “xml”

format.

Supported values are “xml” & “json”.

schedule_executions_count (Optional) Specify a schedule execution count. You can specify a

value form 1 to 10. When not specified, 3 is taken as the default.

44

Scans

Compliance Scans

API request:

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE SCHEDULES_RUN_HISTORY SYSTEM

"<platform_API_server>/api/2.0/fo/scan/schedules/runhistory/output

.dtd">

<SCHEDULES_RUN_HISTORY>

<SCHEDULE_LIST>

<SCHEDULE_ID>85403</SCHEDULE_ID>

<SCHEDULE_RUN_HISTORY>

<SCHEDULE_RUN>

<SCAN_LAUNCH_INFO>

<SCAN_ID>99408</SCAN_ID>

<SCAN_REFERENCE>scan/1634824016.99408</SCAN_REFERENCE>

<LAUNCH_DATETIME>2021-10-21

13:46:56</LAUNCH_DATETIME>

<STATUS>FINISHED</STATUS>

<DURATION>86 Seconds</DURATION>

<SUBSCRIPTION_ID>237630</SUBSCRIPTION_ID>

<OPTION_PROFILE_TITLE>Initial

Options</OPTION_PROFILE_TITLE>

<IS_PROCESSED>1</IS_PROCESSED>

</SCAN_LAUNCH_INFO>

</SCHEDULE_RUN>

</SCHEDULE_RUN_HISTORY>

</SCHEDULE>

<SCHEDULE_ID>99446</SCHEDULE_ID>

<SCHEDULE_RUN_HISTORY>

<SCHEDULE_RUN>

<SCAN_LAUNCH_INFO>

<SCAN_ID>99561</SCAN_ID>

<SCAN_REFERENCE>scan/1635442781.99561</SCAN_REFERENCE>

<LAUNCH_DATETIME>2021-10-28

17:39:41</LAUNCH_DATETIME>

<TARGET>list of target ips</TARGET>

<STATUS>FINISHED</STATUS>

Scans

Compliance Scans

45

<DURATION>434 Seconds</DURATION>

<SUBSCRIPTION_ID>237630</SUBSCRIPTION_ID>

<OPTION_PROFILE_TITLE>Initial

Options</OPTION_PROFILE_TITLE>

<IS_PROCESSED>1</IS_PROCESSED>

</SCAN_LAUNCH_INFO>

</SCHEDULE_RUN>

<SCHEDULE_RUN>

<SCAN_LAUNCH_INFO>

<SCAN_ID>99554</SCAN_ID>

<SCAN_REFERENCE>scan/1635431408.99554</SCAN_REFERENCE>

<LAUNCH_DATETIME>2021-10-28

14:30:08</LAUNCH_DATETIME>

<STATUS>FINISHED</STATUS>

<DURATION>9 Seconds</DURATION>

<SUBSCRIPTION_ID>237630</SUBSCRIPTION_ID>

<OPTION_PROFILE_TITLE>Initial

Options</OPTION_PROFILE_TITLE>

<IS_PROCESSED>1</IS_PROCESSED>

</SCAN_LAUNCH_INFO>

</SCHEDULE_RUN>

<SCHEDULE_RUN>

<SCAN_LAUNCH_INFO>

<SCAN_ID>99553</SCAN_ID>

<SCAN_REFERENCE>scan/1635431408.99553</SCAN_REFERENCE>

<LAUNCH_DATETIME>2021-10-28

14:30:08</LAUNCH_DATETIME>

<STATUS>FINISHED</STATUS>

<DURATION>79 Seconds</DURATION>

<SUBSCRIPTION_ID>237630</SUBSCRIPTION_ID>

<OPTION_PROFILE_TITLE>Initial

Options</OPTION_PROFILE_TITLE>

<IS_PROCESSED>1</IS_PROCESSED>

</SCAN_LAUNCH_INFO>

</SCHEDULE_RUN>

</SCHEDULE_RUN_HISTORY>

</SCHEDULE>

46

Scans

Compliance Scans

</SCHEDULE_LIST>

</RESPONSE>

</SCHEDULES_RUN_HISTORY>

DTD

<platform_API_server>/api/2.0/fo/scan/schedules/runhistory/output.dtd

SCAP Scan List

/api/2.0/fo/scan/scap/ with action=list

[GET] [POST]

List SCAP scans in your account. By default the XML output lists scans launched in the

past 30 days.

The input parameters for requesting a SCAP scan list are below. See Scan List Parameters

for complete details.

API request 1: all SCAP scans

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -d

"action=list" "https://qualysapi.qualys.com/api/2.0/fo/scan/scap/"

API request 2: SCAP scan by reference number

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -d

"action=list&scan_ref=qscap/1402642816.80342"

"https://qualysapi.qualys.com/api/2.0/fo/scan/scap/"

API request 3: On Demand SCAP scans only

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -d

"action=list&type=On-Demand"

"https://qualysapi.qualys.com/api/2.0/fo/scan/scap/"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

Typ e Parameter List

Request action=list (required), echo_request

Scan List Filters scan_id (compliance scan ID), scan_ref, state, type, target,

user_login, launched_after_datetime,

launched_before_datetime

Show Information show_ags, show_op, show_status, show_last

Scans

Compliance Scans

47

<!DOCTYPE SCAN_LIST_OUTPUT SYSTEM

"https://qualysapi.qualys.com/api/2.0/fo/scan/scap/qscap_scan_list

_output.dtd">

<SCAN_LIST_OUTPUT>

<SCAN_LIST>

<SCAN>

<REF>qscap/1402694682.80366</REF>

<TYPE>On-Demand</TYPE>

<TITLE><![CDATA[<IMG

SRC="http://www.google.com/images/logos/ps_logo2.png">]]></TITLE>

</POLICY>

<USER_LOGIN>acme_ab</USER_LOGIN>

<LAUNCH_DATETIME>2018-06-13T21:24:42Z</LAUNCH_DATETIME>

<STATE>Finished</STATE>

</STATUS>

...

</SCAN_LIST>

</RESPONSE>

</SCAN_LIST_OUTPUT>

DTD:

<platform API server>/api/2.0/fo/scan/qscap_scan_list_output.dtd

48

Scans

Compliance Scans

Launch Compliance Scan

/api/2.0/fo/scan/compliance/?action=launch

[POST]

Launch compliance scan in the user’s account.

Using networks? Choose the Global Default Network to scan IPs on your network

perimeter.

Input Parameters

The input parameters for launching a compliance scan are shown below. See Securing

Amazon Web Services with Qualys

Sample - Launch a Compliance Scan

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST"

-d

"action=launch&ip=10.10.25.52&iscanner_name=iscan_er5&option_title

=Initial+PC+Options&echo_request=1"

"https://qualysapi.qualys.com/api/2.0/fo/scan/compliance/" >

apiOutputScan.txt

Typ e Parameter List

Request action=launch (required), echo_request,

runtime_http_header

Scan Title scan_title

Option Profile option_id or option_title

Scanner Appliance iscanner_id or iscanner_name

Asset IPs/Groups ip, asset_group_ids, asset_groups, exclude_ip_per_scan,

default_scanner, scanners_in_ag

Asset Tags target_from=tags, use_ip_nt_range_tags_include,

use_ip_nt_range_tags_exclude, use_ip_nt_range_tags,

tag_include_selector, tag_exclude_selector, tag_set_by,

tag_set_exclude, tag_set_include

Network ip_network_id (when the Network Support feature is

enabled)

Client client_id and client_name (only for Consultant type

subscriptions)

Scans

Compliance Scans

49

Sample - Launch a compliance scan using all scanners in network

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With:curl demo 2" -d

"action=launch&scan_title=pc+scan+API&option_id=3262&ip_network_id

=12807913&scanners_in_network=1&ip=10.10.10.10,10.10.10.11"

"https://qualysapi.qualys.com/api/2.0/fo/scan/compliance/"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>New compliance scan launched</TEXT>

<ITEM_LIST>

<ITEM>

</ITEM>

<ITEM>

<KEY>REFERENCE</KEY>

<VALUE>compliance/1473976536.18198</VALUE>

</ITEM>

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

Launch Compliance Scan on EC2 assets

/api/2.0/fo/scan/compliance/?action=launch

[POST]

Launch a compliance scan on your Amazon EC2 hosts (in your Amazon Web Services

account).

A few things to consider...

- EC2 Scanning must be enabled for your Qualys account.

- Managers and Unit Managers can launch EC2 scans.

- Before scanning you’ll need to complete some set up steps. See Securing Amazon Web

Services with Qualys

50

Scans

Compliance Scans

Input Parameters

The input parameters for launching an EC2 scan are shown below. Please see Scan

Parameters for complete details.

Sample - Launch EC2 compliance scan

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST"

-d

"action=launch&scan_title=My+EC2+Scan+via+API&connector_name=EC2-

Connector-Lab&ec2_endpoint=us-east-

1&target_from=tags&tag_include_selector=any&tag_set_by=id&tag_set_

include=270325&option_id=61769&iscanner_name=my-ec2-scanner"

"https://qualysapi.qualys.com/api/2.0/fo/scan/compliance/"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

Typ e Parameter List

Request action=launch (required), echo_request

Scan Title scan_title

EC2 environment connector_name (required), ec2_endpoint (required)

Option Profile option_id or option_title

Scanner Appliance iscanner_id or iscanner_name

Target Hosts target_from=tags (required)

Use tags to select the EC2 hosts you want to scan.

These parameters provide separate options for including

and excluding tags for network IP ranges.

use_ip_nt_range_tags_include={0|1} (default in bold)

Important - This cannot be set to “1” for EC2 scanning.

use_ip_nt_range_tags_exclude={0|1} (default in bold)

Important - This cannot be set to “1” for EC2 scanning.

This parameter has been replaced with the include/exclude

options above but it is still supported.

use_ip_nt_range_tags={0|1} (default in bold)

Important - This cannot be set to “1” for EC2 scanning.

These tag parameters are used to select tags:

tag_set_include={tag1,tag2,...} (required)

tag_set_exclude={tag1,tag2,...} (optional)

tag_include_selector={any|all} (default in bold)

tag_exclude_selector={any|all} (default in bold)

tag_set_by={id|name} (default in bold)

Scans

Compliance Scans

51

<USER_LOGIN>USERNAME</USER_LOGIN>

<RESOURCE>https://qualysapi.qualys.com/api/2.0/fo/scan/compliance/

</RESOURCE>

</REQUEST>

<TEXT>New compliance scan launched</TEXT>

<ITEM_LIST>

<ITEM>

</ITEM>

<ITEM>

<KEY>REFERENCE</KEY>

<VALUE>compliance/1347771234.36444</VALUE>

</ITEM>

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

Manage Compliance Scans

/api/2.0/fo/scan/compliance/?action={action}

Take actions on compliance scans in their account, like cancel, pause, resume, delete and

fetch completed scan results.

Parameter Description

action={action} (Required) One action required for the request:

cancel - Stop a scan in progress (POST method)

pause - Stop a scan in progress and change status to

“Paused” (POST method)

resume - Restart a scan that has been paused (POST

method)

delete - Delete a scan in your account (POST method)

fetch - Download scan results for a scan with status of

“Finished”, “Canceled”, “Paused” or “Error” (GET or POST

method)

echo_request={0|1} (Optional) Specify 1 to echo the input parameters in the

XML output. When unspecified, parameters are not listed

in the XML output.

scan_ref={value} (Required) The scan reference for a compliance scan. This

will have the format: compliance/nnnnnnnnnn.nnnnn

52

Scans

Compliance Scans

Sample - Fetch PC Scan Results

API request:

curl -u USERNAME:PASSWORD -H "X-Requested-With: Curl"

"https://qualysapi.qualys.com/api/2.0/fo/scan/compliance/?

action=fetch&scan_ref=compliance/1347709693.37303" >

apiOutputScanFetch.txt

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE COMPLIANCE_SCAN_RESULT_OUTPUT SYSTEM

"https://qualysapi.qualys.com/api/2.0/fo/scan/compliance/complianc

e_scan_result_output.dtd">

<COMPLIANCE_SCAN_RESULT_OUTPUT>

<COMPLIANCE_SCAN>

<GENERATION_DATETIME>2012-09-

17T10:23:53Z</GENERATION_DATETIME>

<COMPANY_INFO>

<ZIP_CODE><![CDATA[94065]]></ZIP_CODE>

</COMPANY_INFO>

<USER_INFO>

<USERNAME>USERNAME</USERNAME>

<ROLE>Manager</ROLE>

</USER_INFO>

<KEY value="USERNAME">USERNAME</KEY>

<KEY value="SCAN_HOST">10.10.21.122 (Scanner 6.6.28-1,

Vulnerability Signatures 2.2.215-2)</KEY>

Scans

Compliance Scans

53

<KEY value="REPORT_TYPE">Scheduled</KEY>

<KEY value="OPTIONS">File Integrity Monitoring: Enabled,

Scanned Ports: Standard Scan, Hosts to Scan in Parallel - External

Scanners: 15, Hosts to Scan in Parallel - Scanner Appliances: 30,

Total Processes to Run in Parallel: 10, HTTP Processes to Run in

Parallel: 10,

Packet (Burst) Delay: Medium, Intensity: Normal, Overall

Performance: Normal, ICMP Host Discovery, Ignore RST packets: Off,

Ignore firewall-generated SYN-ACK packets: Off, Do not send ACK or

SYN-ACK packets during host discovery: Off</KEY>

<KEY value="STATUS">FINISHED</KEY>

<OPTION_PROFILE>

<OPTION_PROFILE_TITLE

option_profile_default="0"><![CDATA[11412]]

></OPTION_PROFILE_TITLE>

</OPTION_PROFILE>

</HEADER>

<TARGET_HOSTS>

<HOSTS_SCANNED>10.10.10.29</HOSTS_SCANNED>

</TARGET_HOSTS>

<TARGET_DISTRIBUTION>

</SCANNER>

</TARGET_DISTRIBUTION>

<AUTH>

<TYPE>Windows</TYPE>

</SUCCESS>

</AUTH>

</AUTHENTICATION>

</APPENDIX>

</COMPLIANCE_SCAN>

</RESPONSE>

</COMPLIANCE_SCAN_RESULT_OUTPUT>

54

Scans

Cloud Perimeter Scans

/api/2.0/fo/scan/cloud/perimeter/job/

[POST]

Cloud perimeter scans are available for VM and PC modules. Only Managers and Unit

Managers have permission to configure cloud perimeter scans.

The input parameters for requesting a Cloud Perimeter scan are below. See Cloud

Perimeter Scan Parameters for complete details.

Create/Update Cloud Perimeter Scan

We allow you to create/update a cloud perimeter scan job through Cloud Perimeter Scan

API even if no scan targets are resolved from the provided details. At the time of scan, if

no scan targets are resolved from the provided details, the scan will not be launched, and

we add the error in the Activity log and Run history of the schedule scan job.

API Request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl"

"action=create&tag_set_by=name&tag_include_selector=any&tag_set_in

clude=ec2-Virginia,Unassigned Business

Unit&connector_name=conn1&region_code=us-east-

1&active=1&option_title=Initial

Options&module=vm&schedule=now&cloud_provider=aws&platform_type=cl

assic&&after_notify=1&after_notify_message=Scan Finished"

"https://

qualysapi.qualys.com/api/2.0/fo/scan/cloud/perimeter/job/"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://

qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>Scan has been created successfully</TEXT>

<ITEM_LIST>

Typ e Parameter List

Request action={create|update}

Scan List Filters id, module, cloud_provider, cloud_service,

connector_name, connector_uuid, scan_title, active,

option_title, option_id, priority, scanner_id,

iscanner_name, platform_type, region_code, vpc_id,

tag_include_selector, tag_exclude_selector, tag_set_by,

tag_set_include, tag_set_exclude, elb_dns, schedule

Scans

Cloud Perimeter Scans

55

<ITEM>

</ITEM>

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

Example - Create Cloud Perimeter Scan Job (Recurring Schedule)

API Request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl"

"action=create&tag_set_by=name&tag_include_selector=any&tag_set_in

clude=EC2_Targets&tag_exclude_selector=any&tag_set_exclude=EC2_Tes

t&connector_name=EC2 Connector&region_code=us-east-

1&active=0&occurrence=daily&start_date=04/02/2018&start_hour=10&st

art_minute=30&time_zone_code=IN&option_title=Initial

Options&frequency_days=364&observe_dst=no&module=vm&schedule=recur

ring&cloud_provider=aws&platform_type=classic&after_notify=1&recip

ient_group_ids=4229"

"https://

qualysapi.qualys.com/api/2.0/fo/scan/cloud/perimeter/job/"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://

qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>Scan has been created successfully</TEXT>

<ITEM_LIST>

<ITEM>

</ITEM>

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

Example - Update Cloud Perimeter Scan Job

API Request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl"

"action=update&id=1352071&connector_name=EC2Connector-

2&platform_type=vpc_peered&region_code=us-west-1"

56

Scans

Cloud Perimeter Scans

"https://qualysapi.qualys.com/api/2.0/fo/scan/cloud/perimeter/job/"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://

qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>Scan has been updated successfully</TEXT>

<ITEM_LIST>

<ITEM>

</ITEM>

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

DTD

<platform API server>/api/2.0/fo/scan/simple_return.dtd

Scans

VM Scan Schedules

57

VM Scan Schedules

The Schedule Scan API (/api/2.0/fo/schedule/scan/) is used to define schedules for

vulnerability scans in the user’s account.

Permissions

* Qualys includes an account permission setting that restricts Unit Managers, Scanners,

and Readers from viewing scheduled tasks on unassigned assets.

List scan schedules

/api/2.0/fo/schedule/scan/?action=list

[GET] [POST]

Input Parameters

User Role Permissions

Manager Create scan schedules for all assets in the subscription

Remove all scan schedules

View all scan schedules in the subscription

Unit Manager Create scan schedules for assets in user’s business unit

Remove scan schedules in user’s business unit.

View scan schedules in the subscription*

Scanner Create scan schedules for assets in user’s account.

Remove user’s scan schedules

View scan schedules in the subscription*

Readers No permission to create or remove scan schedules

View scan schedules in the subscription*

Parameter Description

action=list (Required)

echo_request={0|1} (Optional) Specify 1 to echo the request’s input parameters

(names and values) in the XML output. Otherwise parameters are

not displayed in the output.

id={value} (Optional) The ID of the scan schedule you want to display.

active={0|1} (Optional) Specify 1 for active schedules only, or 0 for deactivated

schedules only.

show_notifications={0|1} (Optional) Specify 1 to include the notification settings for each

schedule in the XML output.

scan_type=certview (Optional) Launch a CertView type VM scan. This option will be

supported when CertView GA is released and enabled for your

account.

scan_type=ec2certview (Optional) Launch a CertView type VM scan for EC2 assets.

58

Scans

VM Scan Schedules

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl"

"https://qualysapi.qualys.com/api/2.0/fo/schedule/scan/?action=lis

t&id=160642&show_notifications=1"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SCHEDULE_SCAN_LIST_OUTPUT SYSTEM

"https://qualysapi.qualys.com/api/2.0/fo/schedule/scan/schedule_sc

an_list_output.dtd">

<SCHEDULE_SCAN_LIST_OUTPUT>

<SCHEDULE_SCAN_LIST>

<SCAN>

<USER_LOGIN>qualys_ps</USER_LOGIN>

<NETWORK_ID><![CDATA[0]]></NETWORK_ID>

<ISCANNER_NAME><![CDATA[External

Scanner]]></ISCANNER_NAME>

<USER_ENTERED_IPS>

<RANGE>

fqdn={value} (Optional) The target FQDN for a vulnerability scan. You must

specify at least one target i.e. IPs, asset groups or FQDNs.

Multiple values are comma separated.

show_cloud_details={0|1} (Optional) Set to 1 to display the cloud details (Provider,

Connector, Scan Type and Cloud Target) in the XML output.

Otherwise the details are not displayed in the output.

client_id={value} (Optional) Id assigned to the client (Consultant type subscription

only). Parameter client_id or client_name may be specified for

the same request.

client_name={value} (Optional) Name of the client (Consultant type subscription

only). Parameter client_id or client_name may be specified for

the same request.

scan_type=perimeter (Optional) List cloud perimeter scans only. This option will be

supported for Cloud Perimeter Scans in future release.

show_cloud_details={0|1} (Optional) Set to 1 to display cloud details in the XML output. The

cloud details will show scan type "Cloud Perimeter" for cloud

perimeter scans.

Parameter Description

Scans

VM Scan Schedules

59

</RANGE>

</USER_ENTERED_IPS>

<OPTION_PROFILE>

<DEFAULT_FLAG>1</DEFAULT_FLAG>

</OPTION_PROFILE>

<PROCESSING_PRIORITY>0 - No Priority</PROCESSING_PRIORITY>

<START_DATE_UTC>2017-11-30T00:30:00Z</START_DATE_UTC>

<START_HOUR>16</START_HOUR>

<START_MINUTE>30</START_MINUTE>

<NEXTLAUNCH_UTC>2017-12-02T00:30:00</NEXTLAUNCH_UTC>

<TIME_ZONE>

<TIME_ZONE_CODE>US-CA</TIME_ZONE_CODE>

<TIME_ZONE_DETAILS>(GMT-0800) United States:

America/Los_Angeles</TIME_ZONE_DETAILS>

</TIME_ZONE>

<DST_SELECTED>1</DST_SELECTED>

</SCHEDULE>

<BEFORE_LAUNCH>

<MESSAGE><![CDATA[This is my custom before scan email

message.]]></MESSAGE>

</BEFORE_LAUNCH>

<AFTER_COMPLETE>

<MESSAGE><![CDATA[This is my custom after scan email

message.]]></MESSAGE>

</AFTER_COMPLETE>

</NOTIFICATIONS>

</SCAN>

</SCHEDULE_SCAN_LIST>

</RESPONSE>

</SCHEDULE_SCAN_LIST_OUTPUT>

60

Scans

VM Scan Schedules

Example: Users can filter the schedule scan list to only show cloud perimeter scan jobs.

Also, when you include cloud details in the output, we’ll show scan type "Cloud

Perimeter".

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl"

"https://qualysapi.qualys.com/api/2.0/fo/schedule/scan/?action=lis

t&id=1340788&scan_type=perimeter&show_cloud_details=1"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SCHEDULE_SCAN_LIST_OUTPUT SYSTEM

"https://qualysapi.qualys.com/api/2.0/fo/schedule/scan/schedule_sc

an_list_output.dtd">

<SCHEDULE_SCAN_LIST_OUTPUT>

<SCHEDULE_SCAN_LIST>

<SCAN>

<USER_LOGIN>utwrx_mp</USER_LOGIN>

<ISCANNER_NAME><![CDATA[External Scanner]]></ISCANNER_NAME>

<EC2_INSTANCE>

<CONNECTOR_UUID><![CDATA[8047abce-c3ac-42e0-ad49-

be4181d22c84]]></CONNECTOR_UUID>

<EC2_ENDPOINT><![CDATA[1507b6c1-07a7-4d88-acf2-

8c6b63e749c4]]></EC2_ENDPOINT>

<EC2_ONLY_CLASSIC><![CDATA[1]]></EC2_ONLY_CLASSIC>

</EC2_INSTANCE>

<CLOUD_DETAILS>

</CONNECTOR>

<SCAN_TYPE>Cloud Perimeter</SCAN_TYPE>

<CLOUD_TARGET>

<PLATFORM>Classic</PLATFORM>

Scans

VM Scan Schedules

61

</REGION>

<VPC_SCOPE>None</VPC_SCOPE>

</CLOUD_TARGET>

</CLOUD_DETAILS>

<ASSET_TAGS>

<TAG_INCLUDE_SELECTOR>any</TAG_INCLUDE_SELECTOR>

<TAG_SET_INCLUDE><![CDATA[EC2_Targets]]></TAG_SET_INCLUDE>

<TAG_EXCLUDE_SELECTOR>any</TAG_EXCLUDE_SELECTOR>

<TAG_SET_EXCLUDE><![CDATA[EC2_Test]]></TAG_SET_EXCLUDE>

<USE_IP_NT_RANGE_TAGS>0</USE_IP_NT_RANGE_TAGS>

</ASSET_TAGS>

<ELB_DNS>

</ELB_DNS>

<OPTION_PROFILE>

<DEFAULT_FLAG>1</DEFAULT_FLAG>

</OPTION_PROFILE>

<PROCESSING_PRIORITY>0 - No Priority</PROCESSING_PRIORITY>

<START_DATE_UTC>2018-04-02T05:00:00Z</START_DATE_UTC>

<START_HOUR>10</START_HOUR>

<START_MINUTE>30</START_MINUTE>

<TIME_ZONE>

<TIME_ZONE_CODE>IN</TIME_ZONE_CODE>

<TIME_ZONE_DETAILS>(GMT+0530) India:

Asia/Calcutta</TIME_ZONE_DETAILS>

</TIME_ZONE>

<DST_SELECTED>0</DST_SELECTED>

</SCHEDULE>

</SCAN>

</SCHEDULE_SCAN_LIST>

</RESPONSE>

</SCHEDULE_SCAN_LIST_OUTPUT>

DTD

<platform API server>/api/2.0/fo/schedule/scan/schedule_scan_list_output.dtd

62

Scans

VM Scan Schedules

Create scan schedule

/api/2.0/fo/schedule/scan/?action=create

[POST]

Create a scan schedule in the user’s account.

Input Parameters

The input parameters for creating a scan schedule are below. For complete details see

Scan Parameters and Scan Schedule Parameters.

Typ e Parameter List

Request action=create (required), echo_request

Scan scan_title (required), active=0|1 (required)

Option Profile option_id or option_title (one is required)

Scanner Appliance iscanner_id or iscanner_name

Processing Priority priority

Asset IPs/Groups ip, asset_group_ids, asset_groups, exclude_ip_per_scan,

default_scanner, scanners_in_ag

Asset Tags target_from=tags, tag_include_selector,

tag_exclude_selector, tag_set_by, tag_set_exclude,

tag_set_include, use_ip_nt_range_tags_include,

use_ip_nt_range_tags_exclude, use_ip_nt_range_tags

Network ip_network_id to filter IPs/ranges in “ip” parameter (valid

when the networks feature is enabled)

EC2 Hosts target_from=tags (required)

use_ip_nt_range_tags_include=0 (optional)

use_ip_nt_range_tags_exclude=0 (optional)

use_ip_nt_range_tags=0 (optional)

tag_set_include (required)

More Asset Tags parameters (optional)

EC2 Environment connector_name or connector_uuid (one is required)

ec2_endpoint (required)

Scheduling start_date (current date by default)

start_hour, start_minute, time_zone_code, occurrence

(required)

observe_dst, recurrence, end_after, pause_after_hours,

resume_in_days

Daily Scan occurrence=daily, frequency_days (required)

Weekly Scan occurrence=weekly, frequency_weeks, weeks (required)

Scans

VM Scan Schedules

63

Sample - Create scan schedule

API request:

curl -u "USERNAME:PASSWD" -H "X-Requested-With: curl" -X "POST" -d

"scan_title=My+Scan+Schedule&active=1&option_id=3456&target_from=t

ags&tag_set_include=tag1,tag2,tag3&iscanner_name=scanner1&occurren

ce=daily&frequency_days=5&time_zone_code=US-CA&observe_dst=yes&sta

rt_hour=14&start_minute=0"

"https://qualysapi.qualys.com/api/2.0/fo/schedule/scan/?action=cre

ate"

Sample - Create Scan Schedule, Cancel after 45 minutes

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -d

"action=create&scan_title=My_Weekly_Scan&option_title=InitialOptio

ns&ip=10.20.31.73,10.20.31.106&active=1&occurrence=weekly&start_ho

ur=13&start_minute=30&time_zone_code=IN&frequency_weeks=1&weekdays

=Sunday&end_after=0&end_after_mins=45&iscanner_name=scanner1,scann

er2&before_notify=1&before_notify_unit=hours&before_notify_time=20

&recipient_group_ids=4228,5628"

"https://qualysapi.qualys.com/api/2.0/fo/schedule/scan/"

XML output:

?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>New scan scheduled successfully</TEXT>

<ITEM_LIST>

<ITEM>

</ITEM>

Monthly Scan occurrence=monthly, frequency_months (required)

Nth day of month: day_of_month (required)

Day in Nth week: day_of_week, week_of_month (required)

Notifications before_notify, before_notify_unit, before_notify_time,

before_notify_message, after_notify, after_notify_message,

recipient_group_ids, delay_notify, delay_notify_message,

skipped_notify, skipped_notify_message, deactivate_notify,

deactivate_notify_message

Typ e Parameter List

64

Scans

VM Scan Schedules

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

Sample - Create scan schedule using all scanners in network

API request:

curl -u "USERNAME:PASSWD" -H "X-Requested-With:curl demo 2" -d

"action=create&scan_title=API+Schedule+scan&option_title=Initial+O

ptions&ip_network_id=12807913&scanners_in_network=1&ip=10.10.10.10

,10.10.10.11&occurrence=monthly&frequency_months=12&day_of_month=2

0&start_minute=00&start_hour=22&time_zone_code=IN&observe_dst=no&p

ause_after_hours=3&resume_in_days=4&recurrence=5&start_date=08/20/

2016&active=1"

"https://qualysapi.qualys.com/api/2.0/fo/schedule/scan/"

XML output:

?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>New scan scheduled successfully</TEXT>

<ITEM_LIST>

<ITEM>

</ITEM>

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

Sample - Create scan schedule (with FQDN and asset group)

API request:

curl -u "USERNAME:PASSWD" -H "X-Requested-With: Curl" -X "POST" -d

"action=create&scan_title=My+Schedule&active=1&time_zone_code=US-

OR&start_hour=18&start_minute=50&occurrence=daily&option_title=Ini

tial+Options&frequency_days=1&asset_groups=My+AG&fqdn=domain.qualy

s.com"

"https://qualysapi.qualys.com/api/2.0/fo/schedule/scan/"

Scans

VM Scan Schedules

65

Update a scan schedule

/api/2.0/fo/schedule/scan/?action=update

[POST]

Update a scan schedule in the user’s account. During an update request you must specify

target_from=assets when fqdn is specified in the same request. This is true for

vulnerability scans and CertView type vulnerability scans.

When fqdn is not specified during an update request for a scheduled scan that already

has fqdn defined, we will keep the existing value.

Input Parameters

The input parameters for updating a scan schedule are below. For complete details see

Scan Parameters and Scan Schedule Parameters.

Typ e Parameter List

Request action=update (required), id (required), echo_request

Scan Title scan_title

Status active=0|1

Option Profile option_id or option_title

Scanner Appliance iscanner_id, iscanner_name, default_scanner,

scanners_in_ag, scanners_in_network, scanners_in_tagset

Processing Priority priority

Asset IPs/Groups ip, asset_group_ids or asset_groups, exclude_ip_per_scan

Asset Tags target_from=tags, use_ip_nt_range_tags_include,

use_ip_nt_range_tags_exclude, use_ip_nt_range_tags,

tag_include_selector, tag_exclude_selector, tag_set_by,

tag_set_exclude, tag_set_include

EC2 Environment connector_name or connector_uuid, ec2_endpoint,

ec2_only_classic

Network ip_network_id (when the Network Support feature is

enabled)

Start Time Must be specified together:

set_start_time=1, start_date, start_hour, start_minute,

time_zone_code, observe_dst

Recurrence recurrence

Daily Scan Must be specified together:

occurrence=daily, frequency_days

Weekly Scan Must be specified together:

occurrence=weekly, frequency_weeks, weekdays

66

Scans

VM Scan Schedules

Sample - Update scan schedule, Pause after 15 minutes

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST"

-d

"action=update&id=146754&pause_after_hours=0&pause_after_mins=15&r

esume_in_days=2&resume_in_hours=5"

"https://qualysapi.qualys.com/api/2.0/fo/schedule/scan/"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>Edit scheduled Scan Completed successfully</TEXT>

<ITEM_LIST>

<ITEM>

</ITEM>

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

Monthly Scan Must be specified together:

occurrence=monthly, frequency_months,

Nth day of month: day_of_month,

Day in Nth week: day_of_week, week_of_month

End end_after, end_after_mins

Pause and Resume pause_after_hours, pause_after_mins, resume_in_days,

resume_in_hours

Notifications before_notify, before_notify_unit, before_notify_time,

before_notify_message, after_notify, after_notify_message,

recipient_group_ids, delay_notify, delay_notify_message,

skipped_notify, skipped_notify_message, deactivate_notify,

deactivate_notify_message

Typ e Parameter List

Scans

VM Scan Schedules

67

Delete scan schedule

/api/2.0/fo/schedule/scan/?action=delete

[POST]

Delete a scan schedule in the user’s account.

Input Parameters

Sample - Delete scan schedule

API request:

curl -u "USERNAME:PASSWD" -H "X-Requested-With: curl" -X "POST" -d

"id=123456"

"https://qualysapi.qualys.com/api/2.0/fo/schedule/scan/?action=del

ete"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>Schedule scan deleted successfully</TEXT>

<ITEM_LIST>

<ITEM>

</ITEM>

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

Parameter Description

action=delete (Required)

echo_request={0|1} (Optional) Specify 1 to echo the request’s input parameters

(names and values) in the XML output. Otherwise parameters are

not displayed in the output.

id={value} (Optional) The ID of the scan schedule you want to delete.

68

Scans

PC Scan Schedules

The PC Schedule Scan API (/api/2.0/fo/schedule/scan/compliance) allows you to create,

update, list, and delete schedule scans for Policy Compliance.

Permissions

Note: The PC Scan schedule APIs are available as part of one of the following subscription

combinations only:

- PC and API add-on

- PC, SCA, and API add-on

- VMDR, SCA, and API add-on

*Qualys includes an account permission setting that restricts Unit Managers, Scanners,

and Readers from viewing scheduled tasks on unassigned assets.

User Role Permissions

Manager Create scan schedules for all assets in the subscription

Remove all scan schedules

View all scan schedules in the subscription

Unit Manager Create scan schedules for assets in user’s business unit

Remove scan schedules in user’s business unit.

View scan schedules in the subscription*

Scanner Create scan schedules for assets in user’s account.

Remove user’s scan schedules

View scan schedules in the subscription*

Readers No permission to create or remove scan schedules

View scan schedules in the subscription*

Scans

PC Scan Schedules

69

List compliance scan schedules

/api/2.0/fo/schedule/scan/compliance/?action=list

[GET]

Input Parameters

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl"

"https://qualysapi.qualys.com/api/2.0/fo/schedule/scan/compliance/

?action=list"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE COMPLIANCE_SCHEDULE_SCAN_LIST_OUTPUT SYSTEM

"https://qualysapi.qualys.com/api/2.0/fo/schedule/scan/compliance/

compliance_schedule_scan_list_output.dtd">

<COMPLIANCE_SCHEDULE_SCAN_LIST_OUTPUT>

<COMPLIANCE_SCHEDULE_SCAN_LIST>

<SCAN>

<TITLE>

Parameter Description

action=list (Required)

echo_request={0|1} (Optional) Specify 1 to echo the request’s input parameters

(names and values) in the XML output. Otherwise parameters are

not displayed in the output.

id={value} (Optional) The ID of the scan schedule you want to display.

active={0|1} (Optional) Specify 1 for active schedules only, or 0 for deactivated

schedules only.

show_notifications={0|1} (Optional) Specify 1 to include the notification settings for each

schedule in the XML output.

show_cloud_details={0|1} (Optional) Set to 1 to display the cloud details (Provider,

Connector, Scan Type and Cloud Target) in the XML output.

Otherwise the details are not displayed in the output.

client_id={value} (Optional) Id assigned to the client (Consultant type subscription

only). Parameter client_id or client_name may be specified for

the same request.

client_name={value} (Optional) Name of the client (Consultant type subscription

only). Parameter client_id or client_name may be specified for

the same request.

70

Scans

PC Scan Schedules

<![CDATA[My Scan Schedule api6]]>

</TITLE>

<USER_LOGIN>quays_sp1</USER_LOGIN>

<![CDATA[10.10.10.185]]>

</TARGET>

<NETWORK_ID>

<![CDATA[0]]>

</NETWORK_ID>

<ISCANNER_NAME>

<![CDATA[pyscandsp]]>

</ISCANNER_NAME>

<ASSET_GROUP_TITLE_LIST>

<ASSET_GROUP_TITLE>

<![CDATA[policyred7]]>

</ASSET_GROUP_TITLE>

</ASSET_GROUP_TITLE_LIST>

<OPTION_PROFILE>

<TITLE>

<![CDATA[duplicate IO]]>

</TITLE>

<DEFAULT_FLAG>0</DEFAULT_FLAG>

</OPTION_PROFILE>

<START_DATE_UTC>2019-11-

19T22:00:00Z</START_DATE_UTC>

<START_HOUR>14</START_HOUR>

<START_MINUTE>0</START_MINUTE>

<NEXTLAUNCH_UTC>2019-11-

19T22:00:00</NEXTLAUNCH_UTC>

<TIME_ZONE>

<TIME_ZONE_CODE>US-CA</TIME_ZONE_CODE>

<TIME_ZONE_DETAILS>(GMT-0800) United States:

America/Los_Angeles</TIME_ZONE_DETAILS>

</TIME_ZONE>

<DST_SELECTED>1</DST_SELECTED>

</SCHEDULE>

</SCAN>

</COMPLIANCE_SCHEDULE_SCAN_LIST>

</RESPONSE>

</COMPLIANCE_SCHEDULE_SCAN_LIST_OUTPUT>

Scans

PC Scan Schedules

71

DTD

<platform API

server>/api/2.0/fo/schedule/scan/compliance/compliance_schedule_scan_list_output.dtd

"

Create a Compliance Scan Schedule

/api/2.0/fo/schedule/scan/compliance/?action=create

[POST]

Create a scan schedule in the user’s account.

Input Parameters

The input parameters for creating a scan schedule are below. For complete details see

Scan Parameters and Scan Schedule Parameters.

Typ e Parameter List

Request action=create (required),

echo_request={0|1} (Optional) Specify 1 to echo the request’s input parameters

(names and values) in the XML output. Otherwise

parameters are not displayed in the output.

Scan scan_title (required), active=0|1 (required)

Compliance Profile option_id or option_profile (one is required)

Scanner Appliance iscanner_id or iscanner_name

Asset IPs/Groups ip, asset_group_ids, asset_groups, exclude_ip_per_scan,

default_scanner, scanners_in_ag

Asset Tags target_from=tags, tag_include_selector,

tag_exclude_selector, tag_set_by, tag_set_exclude,

tag_set_include, use_ip_nt_range_tags_include,

use_ip_nt_range_tags_exclude, use_ip_nt_range_tags

Network ip_network_id to filter IPs/ranges in “ip” parameter (valid

when the networks feature is enabled)

Scheduling start_date (current date by default)

start_hour, start_minute, time_zone_code, occurrence

(required)

observe_dst, recurrence, end_after, pause_after_hours,

resume_in_days

Daily Scan occurrence=daily, frequency_days (required)

Weekly Scan occurrence=weekly, frequency_weeks, weeks (required)

72

Scans

PC Scan Schedules

Sample - Create compliance scan schedule

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl"

"https://qualysapi.qualys.com/api/2.0/fo/schedule/scan/compliance/

?action=create&scan_title=My+Scan+Schedule+api6&active=1&option_id

=76960&asset_groups=policyred7&iscanner_name=pyscandsp&occurrence=

daily&frequency_days=5&time_zone_code=US-

CA&observe_dst=yes&start_hour=14&start_minute=0"

XML output:

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>New compliance scan scheduled successfully</TEXT>

<ITEM_LIST>

<ITEM>

</ITEM>

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

Sample - Create compliance scan schedule and cancel after 45 minutes

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl"

"https://qualysapi.qualys.com/api/2.0/fo/schedule/scan/compliance/

?action=create&scan_title=My_Weekly_Scan&option_title=nordea

windows&ip=10.10.10.10&active=1&occurrence=weekly&start_hour=13&st

art_minute=30&time_zone_code=IN&frequency_weeks=1&weekdays=Sunday&

end_after=0&end_after_mins=45&iscanner_name=pyscandsp&before_notif

y=1&before_notify_unit=hours&before_notify_time=20"

Monthly Scan occurrence=monthly, frequency_months (required)

Nth day of month: day_of_month (required)

Day in Nth week: day_of_week, week_of_month (required)

Notifications before_notify, before_notify_unit, before_notify_time,

before_notify_message, after_notify, after_notify_message,

recipient_group_ids, delay_notify, delay_notify_message,

skipped_notify, skipped_notify_message, deactivate_notify,

deactivate_notify_message

Typ e Parameter List

Scans

PC Scan Schedules

73

XML output:

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>New compliance scan scheduled successfully</TEXT>

<ITEM_LIST>

<ITEM>

</ITEM>

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

Sample - Create compliance scan schedule using all scanners in network

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl"

"https://qualysapi.qualys.com/api/2.0/fo/schedule/scan/compliance/

?action=create&scan_title=API+Schedule+scan&option_title=nordea

windows&ip_network_id=52010&scanners_in_network=1&ip=10.10.10.10

,10.10.10.11&occurrence=monthly&frequency_months=12&day_of_month=2

0&start_minute=00&start_hour=22&time_zone_code=IN&observe_dst=no&p

ause_after_hours=3&resume_in_days=4&recurrence=5&start_date=08/20/

2020&active=1"

XML output:

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>New compliance scan scheduled successfully</TEXT>

<ITEM_LIST>

<ITEM>

</ITEM>

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

74

Scans

PC Scan Schedules

Sample - Create EC2 compliance scan schedule

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl"

"https://qualysapi.qualys.com/api/2.0/fo/schedule/scan/compliance/

?

action=create&scan_title=API_Schedule_EC2_PC&target_from=tags&tag_

set_by=name&tag_include_selector=any&tag_set_include=Auth&connecto

r_name=AWS+Connector&ec2_endpoint=us-east-

1&active=0&occurrence=daily&start_date=05/21/2020&start_hour=20&st

art_minute=30&time_zone_code=IN&option_title=Initial+PC+Options&fr

equency_days=364&end_after=1&observe_dst=no&iscanner_name=EC2_Scan

ner"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>New compliance scan scheduled successfully</TEXT>

<ITEM_LIST>

<ITEM>

</ITEM>

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

Scans

PC Scan Schedules

75

Update a Compliance Scan Schedule

/api/2.0/fo/schedule/scan/compliance/?action=update&id=<id>

[POST]

Update a scan schedule in the user’s account.

Input Parameters

The input parameters for updating a scan schedule are below. For complete details see

Scan Parameters and Scan Schedule Parameters.

Typ e Parameter List

Request action=update (required)

echo_request={0|1} (Optional) Specify 1 to echo the request’s input parameters

(names and values) in the XML output. Otherwise

parameters are not displayed in the output.

Scan Title scan_title

id={value} (Required)The ID of the scan schedule you want to update.

Status active=0|1

Compliance Profile option_id or option_title

Scanner Appliance iscanner_id, iscanner_name, default_scanner,

scanners_in_ag, scanners_in_network, scanners_in_tagset

Asset IPs/Groups ip, asset_group_ids or asset_groups, exclude_ip_per_scan

Asset Tags target_from=tags, use_ip_nt_range_tags_include,

use_ip_nt_range_tags_exclude, use_ip_nt_range_tags,

tag_include_selector, tag_exclude_selector, tag_set_by,

tag_set_exclude, tag_set_include

Network ip_network_id (when the Network Support feature is

enabled)

Start Time Must be specified together:

set_start_time=1, start_date, start_hour, start_minute,

time_zone_code, observe_dst

recurrence={value} (Optional) The number of times the scan will be run before

it is deactivated. For example, if you set recurrence=2, the

scan schedule will be deactivated after it runs 2 times. By

default no value is set. A valid value is an integer from 1 to

99.

Daily Scan Must be specified together:

occurrence=daily, frequency_days

Weekly Scan Must be specified together:

occurrence=weekly, frequency_weeks, weekdays

76

Scans

PC Scan Schedules

Sample - Update compliance scan schedule.

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl"

"http://qualysapi.qualys.com/api/2.0/fo/schedule/scan/compliance/?

action=update&id=57360&option_id=39594"

XML output:

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>Edit scheduled Scan Completed successfully</TEXT>

<ITEM_LIST>

<ITEM>

</ITEM>

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

Monthly Scan Must be specified together:

occurrence=monthly, frequency_months,

Nth day of month: day_of_month,

Day in Nth week: day_of_week, week_of_month

End end_after, end_after_mins

Pause and Resume pause_after_hours, pause_after_mins, resume_in_days,

resume_in_hours

Notifications before_notify, before_notify_unit, before_notify_time,

before_notify_message, after_notify, after_notify_message,

recipient_group_ids, delay_notify, delay_notify_message,

skipped_notify, skipped_notify_message, deactivate_notify,

deactivate_notify_message

Typ e Parameter List

Scans

PC Scan Schedules

77

Delete a Compliance Scan Schedule

/api/2.0/fo/schedule/scan/compliance/?action=delete&id=<id>

[POST]

Delete a scan schedule in the user’s account.

Input Parameters

Sample - Delete compliance scan schedule

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl"

"https://qualysapi.qualys.com/api/2.0/fo/schedule/scan/compliance/

?action=delete&id=57360"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SIMPLE_RETURN SYSTEM

"https://qualysapi.qualys.com/api/2.0/simple_return.dtd">

<SIMPLE_RETURN>

<TEXT>Schedule scan deleted successfully</TEXT>

<ITEM_LIST>

<ITEM>

</ITEM>

</ITEM_LIST>

</RESPONSE>

</SIMPLE_RETURN>

Parameter Description

action=delete (Required)

id={value} (Required) The ID of the scan schedule you want to delete.

echo_request={0|1} (Optional) Specify 1 to echo the request’s input parameters

(names and values) in the XML output. Otherwise parameters are

not displayed in the output.

78

Scans

Scan List Parameters

Request Type

Filters

Several parameters allow you to set filters to restrict the scan list output. When no filters

are specified, the service returns all scans launched by all users within the past 30 days.

Parameter Description

action=list (Required) A flag used to make a request for a scan list.

echo_request={0|1} (Optional) Specifies whether to echo the request’s input

parameters (names and values) in the XML output. When not

specified, parameters are not included in the XML output.

Specify 1 to view parameters in the XML output.

Parameter Description

scan_ref={value} (Optional) Show only a scan with a certain scan reference code.

When unspecified, the scan list is not restricted to a certain scan.

For a vulnerability scan, the format is:

scan/987659876.19876

For a compliance scan the format is:

compliance/98765456.12345

For a SCAP scan the format is:

qscap/987659999.22222

scan_id={value} (Optional) Show only a scan with a certain compliance scan ID.

state={value} (Optional) Show only one or more scan states. By default, the

scan list is not restricted to certain states. A valid value is:

Running, Paused, Canceled, Finished, Error, Queued (scan job is

waiting to be distributed to scanner(s)), or Loading (scanner(s)

are finished and scan results are being loaded onto the platform).

Multiple values are comma separated.

processed={0|1} (Optional) Specify 0 to show only scans that are not processed.

Specify 1 to show only scans that have been processed. When not

specified, the scan list output is not filtered based on the

processed status.

type={value} (Optional) Show only a certain scan type. By default, the scan list

is not restricted to a certain scan type. A valid value is:

On-Demand, Scheduled, or API.

target={value} (Optional) Show only one or more target IP addresses. By default,

the scan list includes all scans on all IP addresses. Multiple IP

addresses and/or ranges may be entered. Multiple entries are

comma separated. You may enter an IP address range using the

hyphen (-) to separate the start and end IP address, as in:

10.10.10.1-10.10.10.2

user_login={value} (Optional) Show only a certain user login. The user login

identifies a user who launched scans. By default, the scan list is

not restricted to scans launched by a particular user. Enter the

login name for a valid Qualys user account.

Scans

Scan List Parameters

79

Show/Hide

These parameters specify whether certain information will be shown in the XML output.

launched_after_datetime=

{date}

(Optional) Show only scans launched after a certain date and

time (optional). The date/time is specified in YYYY-MM-

DD[THH:MM:SSZ] format (UTC/GMT), like “2007-07-01” or “2007-

01-25T23:12:00Z”.

When launched_after_datetime and launched_before_datetime

are unspecified, the service selects scans launched within the

past 30 days.

A date/time in the future returns an empty scans list.

launched_before_datetime

=

{date}

(Optional) Show only scans launched before a certain date and

time (optional). The date/time is specified in YYYY-MM-

DD[THH:MM:SSZ] format (UTC/GMT), like “2007-07-01” or “2007-

01-25T23:12:00Z”.

When launched_after_datetime and launched_before_datetime

are unspecified, the service selects scans launched within the

past 30 days.

A date/time in the future returns a list of all scans (not limited to

scans launched within the past 30 days).

scan_type=certview (Optional) List CertView in VM scans only. This option will be

supported when CertView GA is released and enabled for your

account.

scan_type=ec2certview (Optional) List EC2 CertView VM scans only.

client_id={value} (Optional) Id assigned to the client (Consultant type

subscriptions).

client_name={value} (Optional) Name of the client (Consultant type subscriptions).

Note: The client_id and client_name parameters are mutually

exclusive and cannot be specified together in the same request.

Parameter Description

show_ags={0|1} (Optional) Specify 1 to show asset group information for each

scan in the XML output. By default, asset group information is

not shown.

show_op={0|1} (Optional) Specify 1 to show option profile information for each

scan in the XML output. By default, option profile information is

not shown.

show_status={0|1} (Optional) Specify 0 to not show scan status for each scan in the

XML output. By default, scan status is shown.

show_last={0|1} (Optional) Specify 1 to show only the most recent scan (which

meets all other search filters in the request) in the XML output.

By default, all scans are shown in the XML output.

Parameter Description

80

Scans

Scan Parameters

Input parameters used to launch a VM or PC scan are below.

pci_only={0|1} (Optional) Specify 1 to show only external PCI scans in the XML

output. External PCI scans are vulnerability scans run with the

option profile “Payment Card Industry (PCI) Options”

. When

pci_only=1 is specified, the XML output will not include other

types of scans run with other option profiles.

ignore_target={0|1} (Optional) Specify 1 to hide target information from the scan list.

Specify 0 to display the target information.

Parameter Description

action={launch} (Required) Specify “launch” to launch a new scan.

echo_request={

0|1} (Optional) Specify 1 to list the input parameters in the XML

output. When unspecified, parameters are not listed in the XML

output.

scan_title={value} (Optional) The scan title. This can be a maximum of 2000

characters (ascii).

target_from={assets|tags} (Optional) Specify “assets” (the default) when your scan target

will include IP addresses/ranges and/or asset groups. Specify

“tags” when your scan target will include asset tags.

ip={value} (Optional) The IP addresses to be scanned. You may enter

individual IP addresses and/or ranges. Multiple entries are

comma separated. One of these parameters is required: ip,

asset_groups or asset_group_ids.

ip is valid only when target_from=assets is specified.

asset_groups={value} (Optional) The titles of asset groups containing the hosts to be

scanned. Multiple titles are comma separated. One of these

parameters is required: ip, asset_groups or asset_group_ids.

asset_groups is valid only when target_from=assets is specified.

These parameters are mutually exclusive and cannot be

specified in the same request: asset_groups and asset_group_ids.

asset_group_ids={value} (Optional) The IDs of asset groups containing the hosts to be

scanned. Multiple IDs are comma separated. One of these

parameters is required: ip, asset_groups or asset_group_ids.

asset_group_ids is valid only when target_from=assets is

specified.

These parameters are mutually exclusive and cannot be

specified in the same request: asset_groups and asset_group_ids.

Parameter Description

Scans

Scan Parameters

81

exclude_ip_per_scan={valu

e}

(Optional) The IP addresses to be excluded from the scan when

the scan target is specified as IP addresses (not asset tags). You

may enter individual IP addresses and/or ranges. Multiple entries

are comma separated.

exclude_ip_per_scan is valid only when target_from=assets is

specified.

tag_include_selector=

{all|any}

(Optional) Select “any” (the default) to include hosts that match

at least one of the selected tags. Select “all” to include hosts that

match all of the selected tags.

tag_include_selector is valid only when target_from=tags is

specified.

tag_exclude_selector=

{all|any}

(Optional) Select “any” (the default) to exclude hosts that match

at least one of the selected tags. Select “all” to exclude hosts that

match all of the selected tags.

tag_exclude_selector is valid only when target_from=tags is

specified.

tag_set_by={id|name} (Optional) Specify “id” (the default) to select a tag set by

providing tag IDs. Specify “name” to select a tag set by providing

tag names.

tag_set_by is valid only when target_from=tags is specified.

tag_set_include={value} (Optional) Specify a tag set to include. Hosts that match these

tags will be included. You identify the tag set by providing tag

name or IDs. Multiple entries are comma separated.

tag_set_include is valid only when target_from=tags is specified.

tag_set_exclude={value} (Optional) Specify a tag set to exclude. Hosts that match these

tags will be excluded. You identify the tag set by providing tag

name or IDs. Multiple entries are comma separated.

tag_set_exclude is valid only when target_from=tags is specified.

use_ip_nt_range_tags_inclu

de={0|1}

(Optional) Specify “0” (the default) to select from all tags (tags

with any tag rule). Specify “1” to scan all IP addresses defined in

tag selection. When this is specified, only tags with the dynamic

IP address rule called “IP address in Network Range(s)” can be

selected.

use_ip_nt_range_tags_include is valid only when

target_from=tags is specified.

use_ip_nt_range_tags_exclu

de={0|1}

(Optional) Specify “0” (the default) to select from all tags (tags

with any tag rule). Specify “1” to exclude all IP addresses defined

in tag selection. When this is specified, only tags with the

dynamic IP address rule called “IP address in Network Range(s)”

can be selected.

use_ip_nt_range_tags_exclude is valid only when

target_from=tags is specified.

Parameter Description

82

Scans

Scan Parameters

use_ip_nt_range_tags={0|1} (Optional) Specify “0” (the default) to select from all tags (tags

with any tag rule). Specify “1” to scan all IP addresses defined in

tags. When this is specified, only tags with the dynamic IP

address rule called “IP address in Network Range(s)” can be

selected.

This parameter has been replaced by

use_ip_nt_range_tags_include and

use_ip_nt_range_tags_exclude parameters.

The use_ip_nt_range_tag parameter is still supported.

use_ip_nt_range_tags is valid only when target_from=tags is

specified.

iscanner_id={value} (Optional) The IDs of the scanner appliances to be used. Multiple

entries are comma separated. For an Express Lite user, Internal

Scanning must be enabled in the user’s account.

One of these parameters must be specified in a request:

iscanner_name, iscanner_id, default_scanner, scanners_in_ag,

scanners_in_tagset. When none of these are specified, External

scanners are used.

These parameters are mutually exclusive and cannot be

specified in the same request: iscanner_id and iscanner_name.

iscanner_name={value} (Optional) The friendly names of the scanner appliances to be

used or “External” for external scanners. Multiple entries are

comma separated. For an Express Lite user, Internal Scanning

must be enabled in the user’s account.

One of these parameters must be specified in a request for an

internal scan: iscanner_name, iscanner_id, default_scanner,

scanners_in_ag, scanners_in_tagset. When none of these are

specified, External scanners are used.

These parameters are mutually exclusive and cannot be

specified in the same request: iscanner_id and iscanner_name.

default_scanner={0|1} (Optional) Specify 1 to use the default scanner in each target

asset group. For an Express Lite user, Internal Scanning must be

enabled in the user’s account.

One of these parameters must be specified in a request for an

internal scan: iscanner_name, iscanner_id, default_scanner,

scanners_in_ag, scanners_in_tagset. When none of these are

specified, External scanners are used.

default_scanner is valid when the scan target is specified using

one of these parameters: asset_groups, asset_group_ids.

Parameter Description

Scans

Scan Parameters

83

scanners_in_ag={0|1} (Optional) Specify 1 to distribute the scan to the target asset

groups’ scanner appliances. Appliances in each asset group are

tasked with scanning the IPs in the group. By default up to 5

appliances per group will be used and this can be configured for

your account (please contact your Account Manager or Support).

For an Express Lite user, Internal Scanning must be enabled in

the user’s account.

One of these parameters must be specified in a request for an

internal scan: iscanner_name, iscanner_id, default_scanner,

scanners_in_ag, scanners_in_tagset. When none of these are

specified, External scanners are used.

scanners_in_ag is valid when the scan target is specified using

one of these parameters: asset_groups, asset_group_ids.

scanners_in_tagset={0|1} (Optional) Specify 1 to distribute the scan to scanner appliances

that match the asset tags specified for the scan target.

One of these parameters must be specified in a request for an

internal scan: iscanner_name, iscanner_id, default_scanner,

scanners_in_ag, scanners_in_tagset. When none of these are

specified, External scanners are used.

scanners_in_tagset is valid when the target_from=tags is

specified.

scanners_in_network=

{value}

(Optional) Specify 1 to distribute the scan to all scanner

appliances in the network.

option_title={value} (Optional) The title of the option profile to be used.

One of these parameters must be specified in a request:

option_title or option_id. These are mutually exclusive and

cannot be specified in the same request.

option_id={value} (Optional) The ID of the option profile to be used.

One of these parameters must be specified in a request:

option_title or option_id. These are mutually exclusive and

cannot be specified in the same request.

priority={value} (Optional for VM scans only) Specify a value of 0 - 9 to set a

processing priority level for the scan. When not specified, a value

of 0 (no priority) is used. Valid values are:

0 = No Priority (the default)

1 = Emergency

2 = Ultimate

3 = Critical

4 = Major

5 = High

6 = Standard

7 = Medium

8 = Minor

9 = Low

Parameter Description

84

Scans

Scan Parameters

connector_name={value} (Required for an EC2 scan) (VM scan only) The name of the EC2

connector for the AWS integration you want to run the scan on.

ec2_endpoint={value} (Required for an EC2 scan) The EC2 region code or the ID of the

Virtual Private Cloud (VPC) zone. Need help finding the region

code? See the following:

http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-

regions-availability-zones.html#concepts-regions-availability-

zones

ec2_instance_ids={value} (Optional) (VM scan only) The ID of the EC2 instance on which

you want to launch the VM or compliance scan. Multiple ec2

instance ids are comma separated. You can add up to maximum

10 instance Ids. When you launch an EC2 scan and specify EC2

instance IDs as part of the scan target, we can identify and skip

any invalid instances and continue the scan on the valid

instances.

ip_network_id={value} (Optional, and valid only when the Network Support feature is

enabled for the user’s account)

The ID of a network used to filter the IPs/ranges specified in

the“ip” parameter. Set to a custom network ID (note this does not

filter IPs/ranges specified in “asset_groups” or “asset_group_ids”).

Or set to “0” (the default) for the Global Default Network - this is

used to scan hosts outside of your custom networks.

runtime_http_header=

{value}

(Optional) Set a custom value in order to drop defenses (such as

logging, IPs, etc) when an authorized scan is being run. The value

you enter will be used in the “Qualys-Scan:” header that will be

set for many CGI and web application fingerprinting checks.

Some discovery and web server fingerprinting checks will not

use this header.

scan_type=

certview

(Optional) (VM scan only) Launch a CertView type scan. This

option will be supported when CertView GA is released and

enabled for your account.

fqdn={value} (Optional) The target FQDN for a vulnerability scan. You must

specify at least one target i.e. IPs, asset groups or FQDNs.

Multiple values are comma separated.

- DNS Tracking must be enabled for the subscription. A Manager

user can enable this feature in the Qualys UI by going to Scans >

Setup > DNS Tracking and checking the “Enable DNS Tracking

for hosts” option.

- You can specify FQDNs in combination with IPs and asset

groups but not with asset tags.

client_id={value} (Optional) Id assigned to the client (Consultant type

subscriptions).

Parameter Description

Scans

Cloud Perimeter Scan Parameters

85

Cloud Perimeter Scan Parameters

The input parameters for creating or updating a Cloud Perimeter scan are below.

client_name={value} (Optional) Name of the client (Consultant type subscriptions).

Note: The client_id and client_name parameters are mutually

exclusive and cannot be specified together in the same request.

include_agent_targets={0|1} (Optional) Specify 1 when your scan target includes agent hosts.

This lets you scan private IPs where agents are installed when

these IPs are not in your VM/PC license.

Supported capabilities

- This parameter is supported for internal scans using scanner

appliance(s). This option is not supported for scans using

External scanners.

- This parameter is supported when launching on demand scans

only. It is not supported for scheduled scans.

Parameter iscanner_id or iscanner_name must be specified in

the same request.

Parameter Description

action={create|update} (Required) Specify "create" to configure a new cloud

perimeter scan job. Specify "update" to make changes to an

existing scan job.

id={value} (Required and only applicable for Update request) The ID

of the scan schedule you want to update.

module={vm|pc} (Required for Create request) Specify "vm" for a

vulnerability scan and "pc" for a compliance scan.

cloud_provider={value} (Optional) Specify "azure" for an Azure scan. Specify "aws"

for an AWS EC2 scan. Specify "gcp" for a GCP scan.The

cloud_provider value cannot be changed during an update

request.

When cloud_provider=azure, the following parameters

cannot be specified in the same request: platform_type,

region_code, vpc_id, include_micro_nano_instances,

include_lb_from_connector. These parameters only apply

when cloud_provider=aws is specified.

cloud_service={value} (Optional) Specify "vm" (Azure virtual machine) for an

Azure scan. Specify "ec2" for an AWS EC2 scan. Specify

"compute_engine" for GCP scan.The cloud_service value

cannot be changed during an update request.

Parameter Description

86

Scans

Cloud Perimeter Scan Parameters

connector_name={value} (Optional) The name of the connector to be used. We will

check if the specified connector_name exists for your

Qualys subscription. If not, then API request returns an

error message “Invalid connector_name provided”.

One of these parameters must be specified in the request:

conector_name or connector_uuid. These are mutually

exclusive and cannot be specified in the same request.

connector_uuid={value} (Optional) The ID of the connector to be used. We will

check if the specified connector_uuid exists for your

Qualys subscription. If not, then API request returns an

error message “Invalid connector_uuid provided”

One of these parameters must be specified in the request:

conector_name or connector_uuid. These are mutually

exclusive and cannot be specified in the same request.

scan_title={value} (Optional) The scan title. When not specified the default

scan title is "AWS EC2 Perimeter Scan <date>"

active={0|1} (Required for Create request) Specify "1" to create an active

schedule. Specify "0" to create an inactive schedule.

option_title={value} (Optional) The title of the option profile to be used.

One of these parameters must be specified in the request:

option_title or option_id. These are mutually exclusive and

cannot be specified in the same request.

option_id={value} (Optional) The ID of the option profile to be used.

One of these parameters must be specified in a request:

option_title or option_id. These are mutually exclusive and

cannot be specified in the same request.

priority={value} (Optional) Specify a value of 0 - 9 to set a processing

priority level for the scan. When not specified, a value of 0

(no priority) is used. Valid values are:

0 = No Priority (the default)

1 = Emergency

2 = Ultimate

3 = Critical

4 = Major

5 = High

6 = Standard

7 = Medium

8 = Minor

9 = Low

iscanner_id={value} (Optional, only valid when your account is configured to

allow internal scanners) The IDs of the scanner appliances

to be used. Specify "0" for external scanners. Multiple

entries are comma separated.

These parameters cannot be specified in the same request:

iscanner_id and iscanner_name.

Parameter Description

Scans

Cloud Perimeter Scan Parameters

87

iscanner_name={value} (Optional, only valid when your account is configured to

allow internal scanners) The friendly names of the scanner

appliances to be used or "External" for external scanners.

Multiple entries are comma separated.

These parameters cannot be specified in the same request:

iscanner_id and iscanner_name.

platform_type={value} (Optional) The platform type. Valid values are: classic,

vpc_peered or selected_vpc.

region_code={value} (Optional) The EC2 region code. Valid values are:

ap-northeast-1, ap-southeast-1, ap-southeast-2, ap-east-1,

eu-west-1, eu-north-1, asa-east-1, us-east-1, us-west-1, us-

west-2, me-south-1, eu-south-1, and af-south-1

One of these parameters must be specified in the request:

region_code or vpc_id. These are mutually exclusive and

cannot be specified in the same request.

vpc_id={value} (Optional) The ID of the Virtual Private Cloud (VPC) zone.

The ID value must start with vpc-*. We will check if the

specified vpc_id exists for the selected connector

One of these parameters must be specified in the request:

region_code or vpc_id. These are mutually exclusive and

cannot be specified in the same request.

include_micro_nano_instan

ces={

0|1}

(Optional) Specify 1 to include EC2 assets with instance

types t2.nano, t3.nano, t1.micro and m1.small in the scan

job. By default, this parameter value is set to 0.

Note that these instance types must be activated for your

account.

Warning

AWS EC2 assets with instance types t2.nano, t3.nano,

t1.micro and m1.small have very limited CPU. When

scanning these instance types we recommend you choose

an option profile with Light port scanning and no

authentication. Alternatively, use Qualys Cloud Agent to

perform the equivalent of authenticated scanning for the

least performance impact for these instance types.

tag_include_selector=

{all|any}

(Optional) Select “any” (the default) to include hosts that

match at least one of the selected tags. Select “all” to

include hosts that match all of the selected tags.

tag_exclude_selector=

{all|any}

(Optional) Select “any” (the default) to exclude hosts that

match at least one of the selected tags. Select “all” to

exclude hosts that match all of the selected tags.

tag_set_by={id|name} (Optional) Specify “id” (the default) to select a tag set by

providing tag IDs. Specify “name” to select a tag set by

providing tag names. We will check if the tag ids or tag

names are valid.

Parameter Description

88

Scans

Cloud Perimeter Scan Parameters

tag_set_include={value} (Optional) Specify a tag set to include. Hosts that match

these tags will be included. You identify the tag set by

providing tag name or IDs. Multiple entries are comma

separated.

tag_set_exclude={value} (Optional) Specify a tag set to exclude. Hosts that match

these tags will be excluded. You identify the tag set by

providing tag name or IDs. Multiple entries are comma

separated.

include_lb_from_connector

={

0|1}

(Optional) Specify 1 to include public load balancers from

the selected connector in the scan job. By default, this

parameter value is set to 0.

When you set this parameter to 1, we fetch public load

balancers from the AWS connector in CloudView that has

the same configuration as that of the selected connector. If

you select this option, ensure that you have the connector

created in your CloudView account with a configuration

similar to that of the selected connector. If the connector

in CloudView is not found, then we can't fetch the public

load balancers from the connector.

Note

To create the connector, your account must have

CloudView subscription and your platform has access to

CloudView base URL “qweb_cloud_view_base_url”

elb_dns={value} (Optional) One or more load balancer DNS names to

include in the scan job. Multiple values are comma-

separated.

schedule={value} (Required for Create request) Specify "now" to schedule the

scan job for now. Specify "recurring" to schedule the scan

job to start at a later time or on a recurring basis. See

Scheduling Parameters in the next section.

Parameter Description

Scans

Scan Schedule Parameters

89

Scan Schedule Parameters

Scan Schedule - Occurrence

Scan Schedule - Start Time

Parameter Description

occurrence=daily Required for a daily scan.

frequency_days={value} Required for a daily scan. The scan will run every N number of

days. Value is an integer from 1 to 365.

occurrence=weekly Required for a weekly scan.

frequency_weeks={value} Required for a weekly scan. The scan will run every N number of

weeks. Value is an integer from 1 to 52.

weekdays={value} Required for a weekly scan. The scan will run on the one or more

weekdays. Value is one or more days: sunday, monday, tuesday,

wednesday, thursday, friday, saturday. Multiple days are comma

separated.

occurrence=monthly Required for a monthly scan.

frequency_months={value} Required for a monthly scan. The scan will run every N number

of months. Value is an integer from 1 to 12.

day_of_month={value} Required for monthly scan - Nth day of the month. The scan will

run on the Nth day of the month. Value is an integer from 1 to 31.

day_of_week={value} Required for monthly scan - day in Nth week. The scan will run

on this day of the week. Value is and integer from 0 to 6, where 0

is Sunday and 2 is Tuesday.

week_of_month={value} Required for monthly scan - day in Nth week. The scan will run

on this week of the month. Value is one of: first, second, third,

fourth, last.

Parameter Description

start_date={mm/dd/yyyy} (Optional) By default the start date is the date when the schedule

is created. You can define another start date in mm/dd/yyyy

format.

start_hour={hour} (Required) The hour when a scan will start. The hour is an

integer from 0 to 23, where 0 represents 12 AM, 7 represents 7

AM, and 22 represents 10 PM.

start_minute={minute} (Required) The minute when a scan will start. A valid value is an

integer from 0 to 59.

time_zone_code={value} (Required) The time zone code for starting a scan, in upper case.

For example, the time zone code for US California is US-CA. Valid

codes are returned by the Time Zone Code API

(/msp/time_zone_code_list.php).

observe_dst={yes|no} (Optional) Specify yes to observe Daylight Saving Time (DST).

This parameter is valid when the time zone code specified in

time_zone_code supports DST.

90

Scans

Scan Schedule Parameters

recurrence={value} (Optional) The number of times the scan will be run before it is

deactivated. For example, if you set recurrence=2, the scan

schedule will be deactivated after it runs 2 times. By default no

value is set. A valid value is an integer from 1 to 99.

end_after={value} (Optional) End a scan after some number of hours. A valid value

is from 0 to 119.

end_after_mins={value} (Optional) End a scan after some number of minutes. A valid

value is an integer from 0 to 59.

Must be specified with end_after. For example, to end the scan

after 2 hours and 30 minutes, you would specify end_after=2 and

end_after_mins=30.

When end_after is set to 0, the minimum value for

end_after_mins is 15.

pause_after_hours={value} (Optional) Pause a scan after some number of hours if the scan

has not finished by then. A valid value is an integer from 0 to 119.

pause_after_mins={value} (Optional) Pause a scan after some number of minutes if the scan

has not finished by then. A valid value is an integer from 0-59.

Must be specified with pause_after_hours. For example, to pause

the scan after 2 hours and 30 minutes, you would specify

pause_after_hours=2 and pause_after_mins=30.

When pause_after_hours is set to 0, the minimum value for

pause_after_mins is 15.

resume_in_days={value} (Optional) Resume a paused scan in some number of days. A

valid value is an integer from 0 to 9 or Manually.

resume_in_hours={value} (Optional) Resume a paused scan in some number of hours. A

valid value is an integer from 0-23.

Must be specified with pause_after_hours and resume_in_days.

For example, to resume your scan in 5 hours, specify

resume_in_days=0 and resume_in_hours=5. To resume your

scan in 1 day and 12 hours, specify resume_in_days=1 and

resume_in_hours=12.

Note - The value you set for pause will determine the minimum

value for resume. For example, if you set the scan to pause after

1 hour then you can set it to resume in 2 or more hours. If you set

the scan to pause between 1-2 hours (from 1hr, 1min to 1 hr,

59min) then you can set it to resume in 3 hours or more.

set_start_time={0|1} (Optional for Update only) Specify set_start_time=1 to update

any of the start time parameters.

Must be specified with all start time parameters together:

start_date, start_hour, start_minute, time_zone_code,

observe_dst

Parameter Description

Scans

Scan Schedule Parameters

91

Scan Schedule - Notifications

Parameter Description

before_notify={0|1} (Optional) Specify before_notify=1 to send a notification before

the scan starts. When not specified during a create request no

notification is sent. When not specified during an update request

we keep the previous setting.

before_notify_unit={value} (Optional) Specify the time unit for when to send the before scan

notification. Possible values are: days, hours, minutes.

This parameter is required when before_notify=1. Not valid when

before_notify=0.

before_notify_time={value} (Optional) Indicates the number of days, hours or minutes before

the scan starts the notification will be sent. For days, enter a

value of 1-31. For hours, enter a value of 1-24. For minutes, enter

a value of 5-120.

This parameter is required when before_notify=1. Not valid when

before_notify=0.

before_notify_message=

{value}

(Optional) Specify a custom message to add to the before scan

notification. The notification will always include certain details

like the scan title, owner, option profile and start time. Include

up to 4000 characters, no HTML tags.

For update requests:

- When not specified we keep the previous setting.

- Specify an empty string to delete the last saved message.

This parameter is only valid when before_notify=1.

after_notify={0|1} (Optional) Specify after_notify=1 to send a notification after the

scan is finished. When not specified during a create request no

notification is sent. When not specified during an update request

we keep the previous setting.

after_notify_message=

{value}

(Optional) Specify a custom message to add to the after scan

notification. When not specified during a create request, no

notification message is saved. Include up to 4000 characters, no

HTML tags.

For update requests:

- When not specified we keep the previous setting.

- Specify an empty string to delete the last saved message.

- If both notifications are disabled (before_notify=0 and

after_notify=0) we will delete the after notify message.

This parameter is only valid when after_notify=1.

92

Scans

Scan Schedule Parameters

Scan Schedule - Consultant type subscriptions

recipient_group_ids={value} (Optional) The notification recipients in the form of one or more

valid distribution group IDs. When not specified during a create

request, only the task owner will be notified.

For update requests:

- When not specified we keep the previous setting.

- Specify an empty string to delete the list of IDs.

- If both notifications are disabled (before_notify=0 and

after_notify=0) we will delete the list of IDs.

This parameter is only valid when before_notify=1 or

after_notify=1 is specified in the same request.

delay_notify={0|1} (Optional) Specify to send a notification if a scheduled scan is

delayed.

delay_notify_message={val

ue}

(Optional) Specify a message to send notification for a delayed

scheduled scan. If a message is not specified or if the

delay_notify=1, the following default message is shown:

“The Qualys scan launch has been delayed and will be tried

again.”

This parameter is only valid when delay_notify=1.

skipped_notify={0|1} (Optional) Specify to send a notification if a scheduled scan is

skipped.

skipped_notify_message={v

alue}

(Optional) Specify a message to send notification for a skipped

scheduled scan. If a message is not specified or if the

skipped_notify=1, the following default message is shown:

“The Qualys scan launch has been skipped.”

This parameter is only valid when skipped_notify=1.

deactivate_notify={0|1} (Optional) Specify to send a notification if a scheduled scan is

deactivated.

deactivate_notify_message

={value}

(Optional) Specify a message to send notification for a

deactivated scheduled scan. If a message is not specified or if the

deactivate_notify=1, the following default message is shown:

“The Qualys scan has been deactivated by the service.”

This parameter is only valid when deactivate_notify=1.

Parameter Description

client_id={value} (Optional) Id assigned to the client (Consultant type

subscriptions).

client_name={value} (Optional) Name of the client (Consultant type subscriptions).

Note: The client_id and client_name parameters are mutually

exclusive and cannot be specified together in the same request.

Parameter Description

Scans

VM Scan Statistics

93

VM Scan Statistics

/api/2.0/fo/scan/stats/?action=list

[GET] [POST]

List details about vulnerability scans and assets that are waiting to be processed.

Permissions - Manager role is required.

You’ll see these sections in the XML output:

UNPROCESSED SCANS - The total number of scans that are not processed, including

scans that are queued, running, loading, finished, etc.

VM RECRYPT BACKLOG - The total number of assets across your finished scans that are

waiting to be processed.

VM RECRYPT BACKLOG BY SCAN - Scan details for vulnerability scans that are waiting to

be processed. For each scan, you’ll see the scan ID, scan title, scan status, processing

priority and number of hosts that the scan finished but not processed.

VM RECRYPT BACKLOG BY TASK - Processing task details for vulnerability scans that are

waiting to be processed. For each task, you’ll see the same scan details as VM RECRYPT

BACKLOG BY SCAN plus additional information like the total hosts alive for the scan, the

number of hosts from the scan that have been processed, the number of hosts waiting to

be processed, the scan start date, the task type and task status.

Sample - List VM statistics

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With:curl"

"https://qualysapi.qualys.com/api/2.0/fo/scan/stats/?action=list"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE TASK_PROCESSING SYSTEM

"https://qualysapi.qualys.com/api/2.0/fo/scan/stats/vm_recrypt_res

ults.dtd">

<TASK_PROCESSING>

<UNPROCESSED_SCANS><![CDATA[366]]></UNPROCESSED_SCANS>

<VM_RECRYPT_BACKLOG><![CDATA[116]]></VM_RECRYPT_BACKLOG>

<VM_RECRYPT_BACKLOG_BY_SCAN>

<SCAN>

<PROCESSING_PRIORITY><![CDATA[None]]></PROCESSING_PRIORITY>

94

Scans

VM Scan Statistics

</SCAN>

<SCAN>

<PROCESSING_PRIORITY><![CDATA[None]]></PROCESSING_PRIORITY>

</SCAN>

<SCAN>

<PROCESSING_PRIORITY><![CDATA[None]]></PROCESSING_PRIORITY>

</SCAN>

<SCAN>

<PROCESSING_PRIORITY><![CDATA[None]]></PROCESSING_PRIORITY>

</SCAN>

...

</VM_RECRYPT_BACKLOG_BY_SCAN>

<VM_RECRYPT_BACKLOG_BY_TASK>

<SCAN>

<PROCESSING_PRIORITY><![CDATA[None]]></PROCESSING_PRIORITY>

<TO_PROCESS><![CDATA[3]]></TO_PROCESS>

<SCAN_DATE><![CDATA[2018-01-04T08:46:13Z]]></SCAN_DATE>

<SCAN_UPDATED_DATE><![CDATA[2018-01-

04T08:58:05Z]]></SCAN_UPDATED_DATE>

<TASK_TYPE><![CDATA[VM Scan Processing]]></TASK_TYPE>

<TASK_STATUS><![CDATA[Queued]]></TASK_STATUS>

<TASK_UPDATED_DATE><![CDATA[2018-01-

12T08:17:09Z]]></TASK_UPDATED_DATE>

</SCAN>

<SCAN>

Scans

VM Scan Statistics

95

<PROCESSING_PRIORITY><![CDATA[None]]></PROCESSING_PRIORITY>

<TO_PROCESS><![CDATA[0]]></TO_PROCESS>

<SCAN_DATE><![CDATA[2018-01-12T07:30:42Z]]></SCAN_DATE>

<SCAN_UPDATED_DATE><![CDATA[2018-01-

12T08:01:10Z]]></SCAN_UPDATED_DATE>

<TASK_TYPE><![CDATA[VM Scan Processing]]></TASK_TYPE>

<TASK_STATUS><![CDATA[Queued]]></TASK_STATUS>

<TASK_UPDATED_DATE><![CDATA[2018-01-

12T08:17:11Z]]></TASK_UPDATED_DATE>

</SCAN>

<SCAN>

<PROCESSING_PRIORITY><![CDATA[None]]></PROCESSING_PRIORITY>

<TO_PROCESS><![CDATA[0]]></TO_PROCESS>

<SCAN_DATE><![CDATA[2018-01-12T07:30:58Z]]></SCAN_DATE>

<SCAN_UPDATED_DATE><![CDATA[2018-01-

12T08:14:45Z]]></SCAN_UPDATED_DATE>

<TASK_TYPE><![CDATA[VM Scan Processing]]></TASK_TYPE>

<TASK_STATUS><![CDATA[Queued]]></TASK_STATUS>

<TASK_UPDATED_DATE><![CDATA[2018-01-

12T08:17:11Z]]></TASK_UPDATED_DATE>

</SCAN>

...

</VM_RECRYPT_BACKLOG_BY_TASK>

</TASK_PROCESSING>

DTD

<platform API server>/api/2.0/fo/scan/stats/vm_recrypt_results.dtd

96

Scans

VM Scan Summary

/api/2.0/fo/scan/vm/summary/

[GET] [POST]

This API can be used as an alternative to the original Scan Summary API. It’s easier to use,

has more filter options and enhanced output content.

This API helps you to identify hosts that were scanned or not scanned and why. You can

choose to get a scan summary for a particular scan by specifying the scan reference ID or

for all scans launched since a certain date/time or within a date range.

This API will return details for all scans. Note, however, that the output will not include

the <SCAN_RESULTS> block if the scan did not return results for some reason.

Permissions

Manager role is required.

Input Parameters

The following input parameters are supported.

Parameter Description

action=list (Required) The list action.

output_format=xml (Optional) The only supported output format at this time is XML.

scan_reference={value} (Optional) Specifies a unique scan reference ID. Use this option to

include scan summary information for a single scan only. For VM

scans, the scan reference has the format scan/987654321.98765.

One of these parameters must be specified in the request:

scan_datetime_since or scan_reference. You cannot specify

scan_reference in the same request as scan_datetime_since and

scan_datetime_until.

scan_datetime_since=

{value}

(Optional) Include scans started since a certain date. The date

must be less than or equal to today’s date. Specify the date in

GMT timezone in RFC 3339 format: yyyy-mm-ddThh-mm-ssZ.

Example: 2020-10-01T09:30:48Z

One of these parameters must be specified in the request:

scan_datetime_since or scan_reference. You cannot specify

scan_datetime_since in the same request as scan_reference.

scan_datetime_until=

{value}

(Optional) Include scans started up to a certain date. The date

must be more than or equal to scan_datetime_since, and less

than or equal to today’s date. Specify the date in GMT timezone

in RFC 3339 format: yyyy-mm-ddThh-mm-ssZ.

Example: 2020-10-01T09:30:48Z

The parameter scan_datetime_until can only be specified when

scan_datetime_since is also specified. You cannot specify

scan_datetime_until in the same request as scan_reference.

Scans

VM Scan Summary

97

Host Summary Categories

The following host summary categories may be included in the scan summary output:

Scanned - The hosts were scanned successfully.

Excluded - The hosts were excluded. Hosts may be excluded on a per scan basis (by the

user launching or scheduling the scan) or globally for all scans. Managers and Unit

Managers have privileges to edit the global excluded hosts list for the subscription.

Cancelled - Hosts were not scanned because the scan was cancelled. Scans may be

cancelled by a user, by an administrator or automatically by the service as specified in

scheduled scan settings.

include_scan_input={0|1} (Optional) By default, scan input information is included in the

XML output in the <SCAN_INPUT> block. Specify

include_scan_input=0 if you don’t want this entire block to

appear in the output. Scan input information includes the scan

title, user login (for user who launched the scan), whether or not

the scan was scheduled, scan target, network, option profile, etc.

include_scan_details={0|1} (Optional) By default, scan details are included in the XML output

in the <SCAN_DETAILS> block. Specify include_scan_details=0 if

you don’t want this entire block to appear in the output. Scan

details include the scan status, launch date/time, and scan

duration.

include_hosts_summary=

{0|1}

(Optional) By default, hosts summary information is included in

the XML output in the <HOSTS> block under <SCAN_RESULTS>.

Specify include_hosts_summary=0 if you don’t want the

<HOSTS> block to appear in the output. The hosts summary

shows the total number of hosts scanned, and lists the IP

addresses, DNS hostnames and NetBIOS hostnames in the scan.

include_detections_summa

ry={0|1}

(Optional) By default, detections summary information is

included in the XML output in the <DETECTIONS> block under

<SCAN_RESULTS>. Specify include_detections_summary=0 if you

don’t want the <DETECTIONS> block to appear in the output. The

detections summary includes the total number of detections, and

the number of detections by severity for confirmed, potential and

information gathered.

include_hosts_summary_ca

tegories={value}

(Optional) When unspecified, all categories are included in the

XML output. To filter the categories, provide a comma-separated

list of the categories to include in the output. Possible values are:

scanned, excluded, cancelled, unresolved, duplicate,

not_vulnerable, dead, aborted, blocked, failed_slice,

exceeded_scan_duration.

See Host Summary Categories below for more information on

each category. Each category appears a block inside

<SCAN_RESULTS> <HOSTS>. If a category is filtered out, the

respective category block does not appear in the output.

Parameter Description

98

Scans

VM Scan Summary

Unresolved - Hosts were scanned but they could not be reported because the NetBIOS or

DNS hostname, whichever tracking method is specified for each host, could not be

resolved.

Duplicate - The hosts were duplicated within a single segment/slice of the scan job. For

example, two different hostnames resolving to the same IP with tracking by IP.

Not Vulnerable - Hosts were found to be not vulnerable during host discovery without

having to run a full scan. This could happen for example if the list of QIDs to be scanned

are limited to certain ports and those ports are found to be closed.

Dead - The hosts were not “alive” at the time of the scan, meaning that they did not

respond to probes sent by the scanning engine, and the option to Scan Dead Hosts was not

enabled.

Aborted - The scan was abruptly discontinued. This is a rare occurrence that may be

caused for different reasons. For example, it's possible that a connection timed out or

there were connection errors on a particular port or the scan time elapsed.

Blocked - Hosts were blocked from scanning for some reason. For example, user provided

blacklisted IPs to scan and after the scan was launched it was blocked due to improper

configuration.

Failed Slice Hosts - The scan failed for these hosts.

Exceeded Scan Duration - Applicable when the Maximum Scan Duration per Asset feature

is enabled and a maximum scan duration is specified in the option profile used for the

scan. This setting determines how long a scan can run on a single asset. The scan on these

hosts exceeded the scan duration allowed so the scan on these hosts was aborted.

Sample 1 - Get scan summary by scan reference

In this sample, the scan reference ID is included as part of the request.

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl"

"http://qualysapi.qualys.com/api/2.0/fo/scan/vm/summary/?action=list&incl

ude_scan_input=1&include_hosts_summary=1&output_format=xml&include_detect

ions_summary=1&scan_reference=scan/9876543210.12345"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SCAN_SUMMARY_OUTPUT SYSTEM

"http://qualysapi.qualys.com/api/2.0/fo/scan/vm/summary/output.dtd">

<SCAN_SUMMARY_OUTPUT>

<SCAN_SUMMARY_LIST>

<SCAN_SUMMARY>

<SCAN_REFERENCE>scan/9876543210.12345</SCAN_REFERENCE>

<SCAN_INPUT>

<TITLE>CustomAgScan</TITLE>

<USER>

<USERNAME>qualys_joe</USERNAME>

Scans

VM Scan Summary

99

</USER>

<SCAN_DATETIME>2020-04-01 06:55:55</SCAN_DATETIME>

<NAME>Custom Network</NAME>

</NETWORK>

<OPTION_PROFILE>

<NAME>Initial Options</NAME>

</OPTION_PROFILE>

<IP_LIST>

<IP_DATA>

</RANGES>

</IP_DATA>

</IP_LIST>

<DNS_LIST>

<DNS_DATA>

<DNS_CSV>sample2.com,sample3.com,sample1.com</DNS_CSV>

</DNS_DATA>

</DNS_LIST>

<NETBIOS_LIST>

<NETBIOS_DATA>

<NETBIOS_CSV>NB1.COM,NB3.COM,NB2.COM</NETBIOS_CSV>

</NETBIOS_DATA>

</NETBIOS_LIST>

<ASSET_GROUP_LIST>

<ASSET_GROUP_DATA>

<ASSET_GROUP>

<NAME>Custom Network Asset Group</NAME>

</ASSET_GROUP>

</ASSET_GROUP_DATA>

</ASSET_GROUP_LIST>

</TARGETS>

</SCAN_INPUT>

<SCAN_DETAILS>

<STATUS>ERROR</STATUS>

<LAUNCH_DATETIME>2020-04-01 06:55:55</LAUNCH_DATETIME>

</SCAN_DETAILS>

<SCAN_RESULTS>

<HOSTS>

<HOSTS_DATA>

100

Scans

VM Scan Summary

<IP_LIST>

<IP_DATA>

<RANGE>43.56.78.111-

43.56.78.119</RANGE>

</RANGES>

</IP_DATA>

</IP_LIST>

</SCANNED>

<FAILED_SLICE_HOSTS>

<IPV4_LIST>

<IPV4_DATA>

<IPV4_CSV>10.10.10.1,10.20.10.10-

10.20.10.13,10.10.10.3,10.20.10.7,10.10.10.8,10.20.10.11</IPV4_CSV>

</IPV4_DATA>

</IPV4_LIST>

<IPV6_LIST>

<IPV6_DATA>

<IPV6_CSV>::ff01,::ff02,::ff02</IPV6_CSV>

</IPV6_DATA>

</IPV6_LIST>

<DNS_LIST>

<DNS_DATA>

<DNS_CSV>sample4.com, sample5.com,

sample6.com, sample7.com</DNS_CSV>

</DNS_DATA>

</DNS_LIST>

<NETBIOS_LIST>

<NETBIOS_DATA>

<NETBIOS_CSV>WIN2KB,

SATEELITE,WIN4KB, KRWSDG</NETBIOS_CSV>

</NETBIOS_DATA>

</NETBIOS_LIST>

</FAILED_SLICE_HOSTS>

</HOSTS_DATA>

</HOSTS>

<IG>

<TOTAL_COUNT>7216</TOTAL_COUNT>

<COUNT_BY_SEVERITY>

<SEVERITY_1>4467</SEVERITY_1>

<SEVERITY_2>2232</SEVERITY_2>

<SEVERITY_3>517</SEVERITY_3>

<SEVERITY_4>0</SEVERITY_4>

<SEVERITY_5>0</SEVERITY_5>

</COUNT_BY_SEVERITY>

</IG>

Scans

VM Scan Summary

101

<VULN>

<TOTAL_COUNT>8054</TOTAL_COUNT>

<COUNT_BY_SEVERITY>

<SEVERITY_1>238</SEVERITY_1>

<SEVERITY_2>985</SEVERITY_2>

<SEVERITY_3>2124</SEVERITY_3>

<SEVERITY_4>2546</SEVERITY_4>

<SEVERITY_5>2161</SEVERITY_5>

</COUNT_BY_SEVERITY>

</CONFIRMED>

<TOTAL_COUNT>1497</TOTAL_COUNT>

<COUNT_BY_SEVERITY>

<SEVERITY_1>17</SEVERITY_1>

<SEVERITY_2>420</SEVERITY_2>

<SEVERITY_3>579</SEVERITY_3>

<SEVERITY_4>304</SEVERITY_4>

<SEVERITY_5>177</SEVERITY_5>

</COUNT_BY_SEVERITY>

</POTENTIAL>

</VULN>

</DETECTIONS>

</SCAN_RESULTS>

</SCAN_SUMMARY>

</SCAN_SUMMARY_LIST>

</RESPONSE>

</SCAN_SUMMARY_OUTPUT>

Sample 2 - Get scan summary by scan date

In this sample, all scans within the date range will be returned.

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl"

"https://qualysapi.qualys.com/api/2.0/fo/scan/vm/summary/?action=list&out

put_format=xml&scan_datetime_since=2020-04-

06T02:30:00Z&scan_datetime_until=2020-04-06T02:30:00Z"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SCAN_SUMMARY_OUTPUT SYSTEM

"https://qualysapi.qualys.com/api/2.0/fo/scan/vm/summary/output.dtd">

<SCAN_SUMMARY_OUTPUT>

<SCAN_SUMMARY_LIST>

<SCAN_SUMMARY>

<SCAN_REFERENCE>scan/1234567890.12345</SCAN_REFERENCE>

<SCAN_INPUT>

<USER>

102

Scans

VM Scan Summary

<USERNAME>qualys_joe</USERNAME>

</USER>

<SCAN_DATETIME>2020-04-06 07:17:45</SCAN_DATETIME>

<NAME>Global Default Network</NAME>

</NETWORK>

<OPTION_PROFILE>

<NAME>Initial Options</NAME>

</OPTION_PROFILE>

<IP_LIST>

<IP_DATA>

</RANGES>

</IP_DATA>

</IP_LIST>

</TARGETS>

</SCAN_INPUT>

<SCAN_DETAILS>

<STATUS>FINISHED</STATUS>

<LAUNCH_DATETIME>2020-04-06 07:17:45</LAUNCH_DATETIME>

</SCAN_DETAILS>

<SCAN_RESULTS>

<HOSTS>

<HOSTS_DATA>

<IP_LIST>

<IP_DATA>

</RANGES>

</IP_DATA>

</IP_LIST>

</SCANNED>

<DEAD>

<IP_LIST>

<IP_DATA>

<IP_CSV>10.10.30.12</IP_CSV>

</IP_DATA>

</IP_LIST>

</DEAD>

<FAILED_SLICE_HOSTS>

<IPV4_LIST>

<IPV4_DATA>

Scans

VM Scan Summary

103

<IPV4_CSV>10.10.10.1,10.20.10.10-

10.20.10.13,10.10.10.3,10.20.10.7,10.10.10.8,10.20.10.11</IPV4_CSV>

</IPV4_DATA>

</IPV4_LIST>

<IPV6_LIST>

<IPV6_DATA>

<IPV6_CSV>::ff01,::ff02,::ff02</IPV6_CSV>

</IPV6_DATA>

</IPV6_LIST>

<DNS_LIST>

<DNS_DATA>

<DNS_CSV>sample1.com, sample2.com, sample3.com,

sample4.com</DNS_CSV>

</DNS_DATA>

</DNS_LIST>

<NETBIOS_LIST>

<NETBIOS_DATA>

<NETBIOS_CSV>SAMPLE1, SAMPLE2, SAMPLE3, SAMPLE4</NETBIOS_CSV>

</NETBIOS_DATA>

</NETBIOS_LIST>

</FAILED_SLICE_HOSTS>

</HOSTS_DATA>

</HOSTS>

<IG>

<TOTAL_COUNT>77</TOTAL_COUNT>

<COUNT_BY_SEVERITY>

<SEVERITY_1>52</SEVERITY_1>

<SEVERITY_2>12</SEVERITY_2>

<SEVERITY_3>5</SEVERITY_3>

<SEVERITY_4>2</SEVERITY_4>

<SEVERITY_5>6</SEVERITY_5>

</COUNT_BY_SEVERITY>

</IG>

<VULN>

<TOTAL_COUNT>17</TOTAL_COUNT>

<COUNT_BY_SEVERITY>

<SEVERITY_1>0</SEVERITY_1>

<SEVERITY_2>3</SEVERITY_2>

<SEVERITY_3>10</SEVERITY_3>

<SEVERITY_4>0</SEVERITY_4>

<SEVERITY_5>4</SEVERITY_5>

</COUNT_BY_SEVERITY>

</CONFIRMED>

<TOTAL_COUNT>18</TOTAL_COUNT>

<COUNT_BY_SEVERITY>

<SEVERITY_1>2</SEVERITY_1>

<SEVERITY_2>4</SEVERITY_2>

<SEVERITY_3>10</SEVERITY_3>

104

Scans

VM Scan Summary

<SEVERITY_4>1</SEVERITY_4>

<SEVERITY_5>1</SEVERITY_5>

</COUNT_BY_SEVERITY>

</POTENTIAL>

</VULN>

</DETECTIONS>

</SCAN_RESULTS>

</SCAN_SUMMARY>

...

Sample 3 - Filter list of categories in output

In this sample, only the Cancelled category is included.

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl"

"https://qualysapi.qualys.com/api/2.0/fo/scan/vm/summary/?action=list&out

put_format=xml&scan_reference=scan/1234567890.12345&include_hosts_summary

_categories=cancelled"

XML output:

<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE SCAN_SUMMARY_OUTPUT SYSTEM

"https://qualysapi.qualys.com/api/2.0/fo/scan/vm/summary/output.dtd">

<SCAN_SUMMARY_OUTPUT>

<SCAN_SUMMARY_LIST>

<SCAN_SUMMARY>

<SCAN_REFERENCE>scan/1234567890.12345</SCAN_REFERENCE>

<SCAN_INPUT>

<USER>

<USERNAME>qualys_joe</USERNAME>

</USER>

<SCAN_DATETIME>2020-08-06 03:52:30</SCAN_DATETIME>

<NAME>My-Custom-Network</NAME>

</NETWORK>

<OPTION_PROFILE>

<NAME>Initial Options</NAME>

</OPTION_PROFILE>

</TARGETS>

</SCAN_INPUT>

<SCAN_DETAILS>

<STATUS>CANCELED</STATUS>

<LAUNCH_DATETIME>2020-08-06 03:52:30</LAUNCH_DATETIME>

Scans

VM Scan Summary

105

</SCAN_DETAILS>

<SCAN_RESULTS>

<HOSTS>

<HOSTS_DATA>

<IP_LIST>

<IP_DATA>

<IP_CSV>10.10.25.232, 10.10.25.240</IP_CSV>

</IP_DATA>

</IP_LIST>

<DNS_LIST>

<DNS_DATA>

<DNS_CSV>dns1.qualys.com,dns2.qualys.com</DNS_CSV>

</DNS_DATA>

</DNS_LIST>

</CANCELLED>

</HOSTS_DATA>

</HOSTS>

<IG>

<TOTAL_COUNT>0</TOTAL_COUNT>

<COUNT_BY_SEVERITY>

<SEVERITY_1>0</SEVERITY_1>

<SEVERITY_2>0</SEVERITY_2>

<SEVERITY_3>0</SEVERITY_3>

<SEVERITY_4>0</SEVERITY_4>

<SEVERITY_5>0</SEVERITY_5>

</COUNT_BY_SEVERITY>

</IG>

<VULN>

<TOTAL_COUNT>0</TOTAL_COUNT>

<COUNT_BY_SEVERITY>

<SEVERITY_1>0</SEVERITY_1>

<SEVERITY_2>0</SEVERITY_2>

<SEVERITY_3>0</SEVERITY_3>

<SEVERITY_4>0</SEVERITY_4>

<SEVERITY_5>0</SEVERITY_5>

</COUNT_BY_SEVERITY>

</CONFIRMED>

<TOTAL_COUNT>0</TOTAL_COUNT>

<COUNT_BY_SEVERITY>

<SEVERITY_1>0</SEVERITY_1>

<SEVERITY_2>0</SEVERITY_2>

<SEVERITY_3>0</SEVERITY_3>

<SEVERITY_4>0</SEVERITY_4>

<SEVERITY_5>0</SEVERITY_5>

</COUNT_BY_SEVERITY>

</POTENTIAL>

</VULN>

106

Scans

VM Scan Summary

</DETECTIONS>

</SCAN_RESULTS>

</SCAN_SUMMARY>

</SCAN_SUMMARY_LIST>

</RESPONSE>

</SCAN_SUMMARY_OUTPUT>

DTD

<platform API server>/api/2.0/fo/scan/vm/summary/output.dtd

Scans

Scan Summary

107

Scan Summary

/api/2.0/fo/scan/summary/

[GET] [POST]

This is the original VM Scan Summary API for identifying hosts that were not scanned and

why. We recommend you try the new improved VM Scan Summary API which has more

filter options and enhanced output content. See VM Scan Summary.

Permissions

Manager role is required.

How it works

First we’ll find all the scans launched since the date (or within the date range) that you

specify. Then we’ll identify hosts that were included in the scan target but not scanned for

some reason. For each host you’ll see the category/reason it was not scanned and the

host’s tracking method.

Categories for hosts not scanned: