Release 10.30 API
September 06, 2024
Before understanding the API release highlights, learn more about the API server URL to be used in your API requests by referring to the Know Your Qualys API Server URL section. For this API Release Notes, <qualys_base_url> is mentioned in the sample API requests..
What’s New?
Qualys Vulnerability Management (VM)
Enhanced Option Profiles API
| New or Updated API | Updated |
| API Endpoint | /api/2.0/fo/subscription/option_profile/vm/ |
| Method | POST |
| DTD or XSD changes | No |
As a part of our continuous efforts to enhance Qualys products, we have updated the Qualys Option Profiles API and the default settings applied when creating new profiles. These updates are designed to optimize scanning efficiency and ensure compliance with best practices.
The default settings are summarized as below:
- The Enable Parallel Scaling for Scanner Appliances setting is now enabled in Option Profiles by default, which helps enhance scan performance and reduces scan completion time.
- The profile purges old host data when the operating system is updated, which enhances scan performance, and improves record authentication. The Purge action is initiated only when the Operating System is accurately detected during the Authenticated Scans or by the Cloud Agent.
- Windows and Unix are now enabled by default when creating an Option Profile to help reduce the issues that are encountered due to profiles that are not properly configured.
Input ParametersInput Parameters
The details of optional input parameters that are set by default are listed in the following table:
| Parameter Name | Description |
|
purge_host_data Default value (1) |
(Optional) Specify 1 to purge host data. This option is especially useful if you have systems that are regularly decommissioned or replaced. By specifying this option you are telling us you want to purge the host if we detect a change in the host's Operating System (OS) vendor at scan time, for example the OS changed from Linux to Windows or Debian to Ubuntu. We will not purge the host for an OS version change like Linux 2.8.13 to Linux 2.9.4. |
|
scan_parallel_scaling Default value (1) |
(Optional) Specify 1 to enable parallel scaling. This setting can be useful in subscriptions that have physical and virtual scanner appliances with different performance characteristics (For example, CPU, RAM). Specify this option to dynamically scale up the number of hosts to scan in parallel (at scan time) to a calculated value which is based upon the computing resources available on each appliance. Note that the number of hosts to scan in parallel value determines how many hosts each appliance will target concurrently, not how many appliances will be used for the scan. |
|
enable_dissolvable_ Default value (1) |
(Optional) Specify 1 to enable dissolvable agent. This is required for certain scan features like Windows Share Enumeration. How does it work? At scan time the Agent is installed on Windows devices to collect data, and once the scan is complete it removes itself completely from target systems. |
|
authentication Default value |
(Optional) Want to run authenticated scans? When you use authentication we will perform a more in-depth assessment and get you the most accurate results with fewer false positives. Specify one or more technologies for the hosts you want to scan. Be sure that you have configured authentication records (under Scans > Authentication) before running your scan. The following options are available: - Windows - Unix - Oracle - Oracle Listener - SNMP - VMware - DB2 - HTTP - MySQL - MongoDB - Tomcat Server - Palo Alto Networks Firewall - Sybase Note: If the end-user does not pass this parameter (authentication=unauth). |
|
authentication_least_ Default value (Unix) |
(Optional) Specify authentication_least_privilege=Unix (this value is case sensitive) to use the least privileges required for Unix authentication. When specified, the scanner will not pass root delegation information specified in the Unix record to the scanner for vulnerability scans. When not specified (the default), root delegation will be used if specified in the Unix record. Note: Unix authentication must be enabled in the same option profile (authentication=Unix). |
|
icmp Default value (0) |
(Optional) Specify 1 to only discover live hosts that respond to an ICMP ping. Default setting is 1. |
|
ignore_firewall_ Default value (1) |
(Optional) Specify 1 to ignore all TCP RESET packets - firewall-generated and live-host-generated. |
|
ignore_firewall_generated_ Default value (1) |
(Optional) Specify 1 to determine if TCP SYN-ACK packets are generated by a filtering device and ignore packets that appear to originate from such devices |
Sample- Create Option ProfileSample- Create Option Profile
API Request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With:curl" -X POST"?action=create&purge_host_data=1&scan_parallel_scaling=1&scan_scanner
_appliances=50&scan_total_process=20&scan
_http_process=20&authentication_
least_privilege=Unix&enable_dissolvable_agent=1&icmp=0&ignore_
firewall_generated_tcp_rst_packets=1&ignore_firewall_generated_
tcp_syn_ack_packets=1&title=VM_API_Option_profile&scan_tcp_
ports=none&scan_udp_ports=none&vulnerability_detection=
complete&basic_information_gathering=none&scan_overall_
performance=custom&authentication=Unix" '<qualys_base_url>/api/2.0/fo/subscription/option_profile/vm/'
XML Response
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SIMPLE_RETURN SYSTEM
"<qualys_base_url>/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
<RESPONSE>
<DATETIME>2024-08-23T07:45:54Z</DATETIME>
<TEXT>Option profile successfully added.</TEXT>
<ITEM_LIST>
<ITEM>
<KEY>ID</KEY>
<VALUE>2665297</VALUE>
</ITEM>
</ITEM_LIST>
</RESPONSE>
</SIMPLE_RETURN>
Sample- Import Option ProfileSample- Import Option Profile
API Request
curl --location --request POST '<qualys_base_url>/api/2.0/fo/subscription/option_profile/?action=import'
\
--header 'X-Requested-With: test' \
--data 'sample body to pass'XML Response
<?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE SIMPLE_RETURN SYSTEM "<qualys_base_url>/api/2.0/simple_return.dtd"> <SIMPLE_RETURN> <RESPONSE> <DATETIME>2024-08-12T11:27:42Z</DATETIME> <TEXT>Successfully imported Option profile for the subscription Id 75299</TEXT> <ITEM_LIST> <ITEM> <KEY>70018</KEY> <VALUE> OptionProfile-Import6 </VALUE> </ITEM> </ITEM_LIST> </RESPONSE> </SIMPLE_RETURN>
Qualys Policy Compliance (PC)
Launch Report-CSV Report Format Enhancement for Policy Report
| New or Updated API | Updated |
| API Endpoint | /api/2.0/fo/report/ |
| Method | POST |
| DTD or XSD changes | Not applicable |
The CSV format of the Policy report has been enhanced to include a new section called "Possible reason for empty report" under RESULTS. This section displays the reason for an empty report, along with the corresponding reason code. Knowing the reason helps you to identify and address any issues from your end. Depending on the type of problem causing no data in the report, this section will display different reasons and their corresponding reason codes:
| Reason Code | Reason |
| R001 | No HostIDs resolved. |
| R002 | No HostIDs matching with policy technology. |
| R003 | No posture data available. |
| R004 | Template setting may not be configured properly. Please verify the template setting. |
There is no change in the input parameters of the API. Only the CSV report format has been enhanced.
The following image illustrates the empty report displaying the reason and reason code:
Sample - Download Policy Report in CSV FormatSample - Download Policy Report in CSV Format
API Request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With:curl" -d
"https://<qualys_base_url>/api/2.0/fo/report/?action=fetch&id=123456"
CSV Response
"api_pcrs_call","09/02/2024 at 13:18:00 (GMT+0530)"
"test","add1","add2","Pune","None","Iceland","222"
"M N","test_mn4","Manager"
"SUMMARY"
"Policy Id","Policy Title","Policy Locking","Policy Modified","Policy Last Evaluated","Asset Groups","IPs","Asset Tags","PC Agent IPs","Technologies","Controls","Assets","Control Instances","Passed","Failures","Error","Approved Exceptions","Pending Exceptions"
"5655289","Asset Tag Only","Unlocked","04/17/2024 at 12:10:04 (GMT+0530)","04/17/2024 at 12:10:45 (GMT+0530)","","","","No","CentOS 7.x,CentOS 8.x","1","0","0","0(0%)","0(0%)","0","0","0"
Control Statistics (Percentage of Hosts Passed per Control)
"Order","Control ID","Deprecated","Statement","Criticality Label","Criticality Value","Percentage"
"1.1","8327","0","Status of the 'world-writable' files on the host","CRITICAL","4","N/A"
Host Statistics (Percentage of Controls Passed per Host)
"IP Address","Tracking Method","DNS Name","Netbios Name","Operating System","Last Scan Date","Percentage","Qualys Host ID","Host ID"
ASSET TAGS
RESULTS
"Host IP","DNS Hostname","NetBIOS Hostname","Tracking Method","Operating System","OS CPE","NETWORK","Last Scan Date","Evaluation Date","Control ID","Technology","Control","Criticality Label","Criticality Value","Instance","Rationale","Status","Remediation","Deprecated","Evidence","Exception Assignee","Exception Status","Exception End Date","Exception Creator","Exception Created Date","Exception Modifier","Exception Modified Date","Exception Comments History","Cause of Failure","Qualys Host ID","Previous Status","First Fail Date","Last Fail Date","First Pass Date","Last Pass Date","Control Comments"
Possible reason for empty report
R001 - No HostIDs resolved.