Launch Report

POST /api/2.0/fo/report/?action=launch

Launch reports in the user's account. The Report Share feature must be enabled in the user's subscription. When a report is launched, the report is run in the background, and the report generation processing does not timeout until the report has completed.

Permissions - Managers and Auditors can launch reports on all assets in the subscription, Unit Managers can launch reports on assets in their own business unit, Scanners and Readers can launch reports on assets in their own account.

Note: The Launch report API for Compliance Policy reports is 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

Input ParametersInput Parameters

Parameter

Required/Optional

Data
Type

Description

action=launch

Required

String

Specify action to launch report.

echo_request={0|1}

Optional

Integer

Specify 1 to view (echo) input parameters in the XML output. By default these are not included.

template_id={value}

Required

Integer

The template ID of the report you want to launch. Run report_template.list.php to find the template ID you're interested in.

report_title=[value}

Optional

String

A user-defined report title. The title may have a maximum of 128 characters. For a PCI compliance report, the report title is provided by Qualys and cannot be changed.

output_format={value}

Required

File

One output format may be specified. Supported formats for various reports are below.

map report - pdf, html (a zip file), mht, xml, csv

scan report - pdf, html (a zip file), mht, xml, csv, docx

remediation report - pdf, html (a zip file), mht, csv

compliance report - pdf, html (a zip file), mht

PCI compliance report - pdf, html (a zip file)

compliance policy report - pdf, html (a zip file), mht, xml, csv

Qualys patch report - pdf, online, csv, xml

hide_header={0|1}

 

Integer

(Valid for CSV format report only). Specify hide_header=1 to omit the header information from the report. By default this information is included.

pdf_password={value}

Required for secure PDF distribution, Manager or Unit Manager only.

Alpha
numeric

Used for secure PDF report distribution when this feature is enabled in the user's account (under Reports > Setup > Report Share). The password to be used for encryption.

- the password must have a minimum of 8 characters (ascii), and a maximum of 32 characters

- the password must contain alpha and numeric characters

- the password cannot match the password for the user’s Qualys account.

- the password must follow the password security guidelines defined for your subscription (under Users > Setup > Security)

recipient_group={value}

Optional for secure PDF distribution, Manager or Unit Manager only

String

Used for secure PDF distribution. The report recipients in the form of one or more distribution group names, as defined using the Qualys UI. Multiple distribution groups are comma separated. A maximum of 50 distribution groups may be entered.

The recipient_group parameter can only be specified when the pdf_password parameter is also specified.

The recipient_group parameter cannot be specified in the same request as recipient_group_id

recipient_group_id={value}

Optional for secure PDF distribution, Manager or Unit Manager only.

Integer

The report recipients in the form of one or more distribution group IDs. Multiple distribution group IDs are comma separated. Where do I find this ID? Log in to your Qualys account, go to Users > Distribution Groups and select Info for a group in the list.

The recipient_group_id parameter can only be specified when the pdf_password parameter is also specified.

The recipient_group_id parameter cannot be specified in the same request as recipient_group

Map Report

 


 

report_type=Map

Optional


 

domain={value}

Required

String

Specifies the target domain for the map report. Include the domain name only; do not enter "www." at the start of the domain name. When the special “none” domain is specified as a parameter value, the ip_restriction parameter is required.

ip_restriction={value}

Optional

Integer

For a map report, specifies certain IPs/ranges to include in the report. Multiple IPs and/or ranges are comma separated.

This parameter is required when the domain parameter is specified with the value “none” (for the special "none" domain).

report_refs={value}

Required

Integer

Specifies the map references (1 or 2) to include. A map reference starts with the string "map/" followed by a reference ID number. When two map references are given, the report compares map results. Two map references are comma separated.

Scan Report - Scan Based Findings

 


 

report_type=Scan

Optional


 

report_refs={value}

Required

String

This parameter specifies the scan references to include. A scan reference starts with the string "scan/" followed by a reference ID number. Multiple scan references are comma separated.

ip_restriction={value}

Optional

Integer

For a scan report, the report content will be restricted to the specified IPs/ranges. Multiple IPs and/or ranges are comma separated.

Scan Report - Host Based Findings

 


 

report_type=Scan

Optional


 

ips={value}

Optional

Integer

Specify IPs/ranges to change (overwrite) the report target, as defined in the report template. Multiple IPs/ranges are comma separated. When specified, hosts defined in the report template are not included in the report.

You can specify ips and/or asset_group_ids, or asset tags (see “Using Asset Tags”).

asset_group_ids={value}

Optional

Integer

Specify asset group IDs to change (overwrite) the report target, as defined in the report template. When specified, hosts defined in the report template are not included in the report. Run /msp/asset_group_list.php to get a list of asset groups and their IDs.

You can specify ips and/or asset_group_ids, or asset tags (see “Using Asset Tags”).

ips_network_id={value}

Optional and valid only when the Network Support feature is enabled for the user’s account.

Integer

The ID of a network that is used to restrict the report’s target to the IPs/ranges specified in the "ips" parameter. Set to a custom network ID (note this does not filter IPs/ranges specified in "asset_group_ids"). Or set to "0" (the default) for the Global Default Network - this is used to report on hosts outside of your custom networks.

Patch Report

 


 

ips={value}

Optional

Integer

Specify IPs/ranges to change (override) the report target, as defined in the patch report template. Multiple IPs/ranges are comma separated. When specified, hosts defined in the report template are not included in the report.

You can specify ips and/or asset_group_ids, or asset tags (see “Using Asset Tags”).

asset_group_ids={value}

Optional

Integer

Specify IPs/ranges to change (override) the report target, as defined in the patch report template. Multiple asset group IDs are comma separated. When specified, hosts defined in the report template are not included in the report. Run /msp/asset_group_list.php to get a list of asset groups and their IDs.

You can specify ips and/or asset_group_ids, or asset tags (see “Using Asset Tags”).

Remediation Report

 


 

report_type=Remediation

Optional


 

ips={value}

Optional

Integer

Specify IPs/ranges you want to include in the report. Multiple IPs and/or ranges are comma separated.

You can specify ips and/or asset_group_ids, or asset tags (see “Using Asset Tags”).

asset_group_ids={value}

Optional

Integer

Specify asset group IDs that identify hosts you want to include in the report. Multiple asset group IDs are comma separated. Run /msp/asset_group_list.php to get a list of asset groups and their IDs.

You can specify ips and/or asset_group_ids, or asset tags (see “Using Asset Tags”).

assignee_type={User|All}

Optional

Boolean

Specifies whether the report will include tickets assigned to the current user (value User), or all tickets in the user account (value All). By default tickets assigned to the current user are included.

Compliance Report

 


 

report_type=Compliance

 Optional


 

ips={value}

Optional

Integer

Specify the IPs/ranges you want to include in the report. Multiple IPs and/or ranges are comma separated.

This parameter or the asset_group_ids parameter must be specified for these reports: Qualys Top 20 Report, 2008 SANS Top 20 Report.

You can specify ips and/or asset_group_ids, or asset tags (see “Using Asset Tags”).

asset_group_ids={value}

Optional

Integer

Specify asset groups IDs which identify hosts to include in the report. Multiple asset group IDs are comma separated. Looking for asset group IDs. Run /msp/asset_group_list.php to get a list of asset groups and their IDs.

You can specify ips and/or asset_group_ids, or asset tags (see “Using Asset Tags”).

report_refs={value}

Required for PCI compliance report

String

Specifies the scan reference to include. A scan reference starts with the string "scan/" followed by a reference ID number. The scan reference must be for a scan that was run using the PCI Options profile. Only one scan reference may be specified.

Applies to PCI Technical Report and PCI Executive Report

Compliance Policy Report

 


 

report_type=Policy

Optional



policy_id={value}

Required

Integer

Specifies the policy to run the report on. A valid policy ID must be entered.

ips={value}

Optional

Integer

Specify IPs/ranges if you want to include only certain IP addresses in your report. These IPs must be assigned to the policy you’re reporting on. Multiple entries are comma separated.

You can specify ips and/or asset_group_ids, or asset tags (see “Using Asset Tags”).

asset_group_ids={value}

Optional

Integer

Specify asset groups IDs which identify hosts to include in the report. Multiple asset group IDs are comma separated. Looking for asset group IDs. Run /msp/asset_group_list.php to get a list of asset groups and their IDs.

You can specify ips and/or asset_group_ids, or asset tags (see “Using Asset Tags”).

host_id={value}

Optional

Integer

Show only results for a single host instance. Specify the ID for the host to include in the report. A valid host ID must be entered.

This parameter must be specified with instance_string.

instance_string={value}

Optional

String

Specifies a single instance on the selected host. The instance string may be "os" or a string like "oracle10:1:1521:ora10204u". Use the Compliance Posture Info API to find the instance string you're looking for.

This parameter must be specified with: host_id.

Sample- Launch ReportSample- Launch Report

API Request

curl -H "X-Requested-With: Curl Sample" -d "action=launch&template_id=55469&output_format=pdf" -b "QualysSession=71e6cda2a35d2cd404cddaf305ea0208; path=/api; secure" "https://<qualys_base_url>/api/2.0/fo/report/"

XML Output

 <?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE GENERIC SYSTEM 
"https://<qualys_base_url>/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
 <RESPONSE>
 <DATETIME>2017-06-20T21:45:23Z</DATETIME>
 <TEXT>New report launched</TEXT>
 <ITEM_LIST>
 <ITEM>
 <KEY>ID</KEY>
 <VALUE>1665</VALUE>
 </ITEM>
 </ITEM_LIST>
 </RESPONSE>
</SIMPLE_RETURN>

DTD

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