Launch Report Using Asset Tags

Parameter	Required/Optional	Data Type	Description
use_tags={0|1}	Optional	Integer	Specify "1" when your report target will include asset tags. Specify “0” (the default) when your report target will include IP addresses/ranges and/or asset groups. When not specified, use_tags=0 is used.
tag_include_selector={all|any}	Optional	Boolean	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 use_tags=1 is specified.
tag_exclude_selector={all|any}	Optional	Boolean	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 use_tags=1 is specified.
tag_set_by={id|name}	Optional	Integer	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 use_tags=1 is specified.
tag_set_include={value}	Optional	Integer	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 use_tags=1 is specified.
tag_set_exclude={value}	Optional	Integer	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 use_tags=1 is specified.

API Request

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST" -d "action=launch&template_id=55469&report_title=My+Windows+Report&output_format=pdf&use_tags=1&tag_set_by=name&tag_set_include=Windows" "https://<qualys_base_url>/api/2.0/fo/report/"
<?xml version="1.0" encoding="UTF-8" ?>

XML Output

<!DOCTYPE GENERIC SYSTEM "https://<qualys_base_url>/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
    <RESPONSE>
        <DATETIME>2018-02-20T21:45:23Z</DATETIME>
        <TEXT>New report launched</TEXT>
        <ITEM_LIST>
            <ITEM>
                <KEY>ID</KEY>
                <VALUE>1665</VALUE>
            </ITEM>
        </ITEM_LIST>
    </RESPONSE>
</SIMPLE_RETURN>

Policy Compliance Reporting Service (PCRS) is a new reporting service to improve performance in Policy Compliance report generation. With PCRS, we’ve enhanced policy reports in CSV format by automatically compressing large size reports. When you run a policy report in CSV format, the report will be in ZIP format if the report size is between 1 GB and 5 GB; while reports less than 1 GB will be in CSV format. Similar improvements to other report formats will be added soon. You can download reports from the user interface or fetch reports by using APIs.

Note: This feature will be automatically enabled for customers with the release of Qualys Policy Compliance Reporting Service 1.0.0. Contact Qualys Support if you do not want this feature to be enabled for your subscription.

Important: If you are currently using the Report API to launch and fetch compliance policy reports in CSV format, then it’s important to note that once PCRS is enabled for your subscription, any CSV compliance policy report that is over 1GB in size will be compressed automatically and you will get a ZIP file instead of a CSV file. You’ll need to update your code or work with your 3rd party vendor to monitor the response header and if the report is compressed, add a step to uncompress the ZIP file before parsing the data.

When fetching a report using the API, the response header will indicate if the report is compressed or not. See the API samples that follow.
- In case of compressed reports, header content-type is - application/zip
- In case of uncompressed reports, header content-type is - text/csv

In this sample, the report being downloaded is more than 1GB in size.

API Request

curl -u "USERNAME:PASSWORD" -H "X-Requested-With:curl" -d "action=fetch&id=" "https://<qualys_base_url>/api/2.0/fo/report/" 

You’ll notice that the header Content-Type is "application/zip"

XML Output

* About to connect() to qualysapi.xxx.qualys.com port <PORT NUMBER> (#0)
    * Trying xx.xx.x.xxx ...
    * Connected to qualysapi.xxx.qualys.com (xx.xx.x.xxx) port <PORT NUMBER> 
    (#0)
    * Initializing NSS with certpath: sql:/etc/pki/nssdb
    * skipping SSL peer certificate verification
    * SSL connection using TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    * Server certificate:
    * subject: CN=*.xxx.qualys.com,OU=Engineering,O="Qualys, 
    Inc.",L=Foster City,ST=California,C=US
    * start date: Sep 16 09:45:00 2020 GMT
    * expire date: Sep 16 09:45:00 2022 GMT
    * common name: *.xxx.qualys.com
    * issuer: E=xx@qualys.com,CN=Qualys Ops 
    T2v1,OU=Operations,O="Qualys, Inc.",L=Redwood City,ST=California,C=US
    * Server auth using Basic with user '<USER NAME>'
    > POST /api/2.0/fo/report/ HTTP/1.1
    > Authorization: <AUTHORIZATION TOKEN>
    > User-Agent: curl/7.29.0
    > Host: qualysapi.xxx.qualys.com
    > Accept: */*
    > X-Requested-With:curl demo2
    > Content-Length: 22
    > Content-Type: application/x-www-form-urlencoded
    >
    } [data not shown]
    * upload completely sent off: 22 out of 22 bytes
    < HTTP/1.1 200 OK
    < Date: Thu, 07 Oct 2021 11:15:03 GMT
    < Server: Qualys
    < Strict-Transport-Security: max-age=63072000;
    < X-XSS-Protection: 1; mode=block
    < X-Content-Type-Options: nosniff
    < X-Frame-Options: SAMEORIGIN
    < Strict-Transport-Security: max-age=31536000; includeSubDomains
    < X-RateLimit-Limit: 300
    < X-RateLimit-Window-Sec: 3600
    < X-Concurrency-Limit-Limit: 2
    < X-Concurrency-Limit-Running: 0
    < X-RateLimit-ToWait-Sec: 0
    < X-RateLimit-Remaining: 297
    < Content-Length: 221540169
    < Connection: keep-alive
    < Content-Disposition: attachment; filename=<FILENAME>.zip
    < Content-Type: application/zip

In this sample, the report being downloaded is less than 1GB in size.

API Request

curl -u "USERNAME:PASSWORD" -H "X-Requested-With:curl" -d "action=fetch&id=" "https://<qualys_base_url>/api/2.0/fo/report/  

You’ll notice that the header Content-Type is "text/csv;charset=UTF-8"

XML Output

* About to connect() to qualysapi.xxx.qualys.com port <PORT NUMBER> (#0)
    * Trying xx.xx.x.xxx...
    * Connected to qualysapi.xxx.qualys.com (xx.xx.x.xxx) port <PORT NUMBER> 
    (#0)
    * Initializing NSS with certpath: sql:/etc/pki/nssdb
    * skipping SSL peer certificate verification
    * SSL connection using TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
    * Server certificate:
    * subject: CN=*.xxx.qualys.com,OU=Engineering,O="Qualys, 
    Inc.",L=Foster City,ST=California,C=US
    * start date: Sep 16 09:45:00 2020 GMT
    * expire date: Sep 16 09:45:00 2022 GMT
    * common name: *.xxx.qualys.com
    * issuer: E=xx@qualys.com,CN=Qualys Ops 
    T2v1,OU=Operations,O="Qualys, Inc.",L=Redwood City,ST=California,C=US
    * Server auth using Basic with user '<user name>'
    > POST /api/2.0/fo/report/ HTTP/1.1
    > Authorization: <AUTHORIZATION TOKEN>
    > User-Agent: curl/7.29.0
    > Host: qualysapi.xxx.qualys.com
    > Accept: */*
    > X-Requested-With:curl demo2
    > Content-Length: 22
    > Content-Type: application/x-www-form-urlencoded
    >
    * upload completely sent off: 22 out of 22 bytes
    < HTTP/1.1 200 OK
    < Date: Thu, 07 Oct 2021 11:16:21 GMT
    < Server: Qualys
    < Strict-Transport-Security: max-age=63072000;
    < X-XSS-Protection: 1; mode=block
    < X-Content-Type-Options: nosniff
    < X-Frame-Options: SAMEORIGIN
    < Strict-Transport-Security: max-age=31536000; includeSubDomains
    < X-RateLimit-Limit: 300
    < X-RateLimit-Window-Sec: 3600
    < X-Concurrency-Limit-Limit: 2
    < X-Concurrency-Limit-Running: 0
    < X-RateLimit-ToWait-Sec: 0
    < X-RateLimit-Remaining: 296
    < Content-Length: 294850
    < Connection: keep-alive
    < Content-Disposition: attachment; 
    filename=Compliance_Report_PCRA_326___xxx.csv
    < Content-Type: text/csv;charset=UTF-8