Eric Perraudeau

QualysGuard 7.4 API Notification

Blog Post created by Eric Perraudeau Employee on Aug 16, 2012

Update: An incorrect version of this notification was posted by mistake last week. We apologize for the confusion, and you will find below the correct version that reflects the availability date for this release.


A new release of QualysGuard, Version 7.4, will be available in production on September 5th in the US datacenter, and on September 11th in the EU datacenter. More information specific to this release are communicating via the Release Notification pages here:

 

This API notification provides an early preview into the coming API changes, allowing you to proactively figure out any changes that might be required for your automated scripts or programs that make API calls the following functions:

  • New "show_pci_flag=1" parameter for "https://[QUALYSAPISERVER]/msp/knowledgebase_download.php" to return reasons for PCI Compliance Status.
  • New "show_pci_reasons=1" parameter for "https://[QUALYSAPISERVER]/api/2.0/fo/knowledge_base/vuln/" to return reasons for PCI Compliance Status.
  • New "action=edit" parameter for "https://[QUALYSAPISERVER]/api/2.0/fo/auth/vmware/" to create and edit VMWare authentication records.
  • New "Error" value for "<STATUS>" for "https://[QUALYSAPISERVER]/compliance/posture/info/?action=list" to report control with error status.
  • New API function to list PC/FDCC policies: "https://[QUALYSAPISERVER]/api/2.0/fo/compliance/fdcc_policy/?action=list".

 

Changes to "/msp/knowledgebase_download.php"

With QualysGuard 7.4 the reasons for passing or failing PCI compliance have been added to the KnowledgeBase for vulnerabilities that are impacted by PCI compliance requirements, as defined by the PCI Council. QualysGuard is compliant with the requirements in the PCI ASV Program Guide.

 

Requests to the following API "/msp/knowledgebase_download.php?show_pci_flag=1" now returns in the XML output new XML elements that provide details about the PCI complinace requirements for each vulneraiblity like in this example:

 

$ curl -u "LOGIN:PASSWORD" "https://qualysapi.qualys.com/msp/knowledgebase_download.php?show_pci_flag=1"
[...]
<VULN>
    <QID>155754</QID>
    <VULN_TYPE>Vulnerability</VULN_TYPE>
    <SEVERITY_LEVEL>4</SEVERITY_LEVEL>
    <TITLE><![CDATA[Oracle Enterprise Linux Update for Kernel (ELSA-2009-1541)]]></TITLE>
    <CATEGORY>OEL</CATEGORY>
     [...]
    <CVSS_BASE>6.9</CVSS_BASE>
    <CVSS_TEMPORAL>5.4</CVSS_TEMPORAL>
    <PCI_FLAG>1</PCI_FLAG>
    <PCI_REASONS>
      <PCI_REASON>CVSS basescore of 4.0 or greater results in an automatic failure.</PCI_REASON>
    </PCI_REASONS>
</VULN>
[...]

 

The DTD "knowledgebase_download.dtd" has been updated with the new XML elements <PCI_REASONS> and <PCI_REASON>.

 

Changes to "/api/2.0/fo/knowledge_base/vuln/"

For the same reasons than above, a new parameter "show_pci_reasons=1" has been added to "/api/2.0/fo/knowledge_base/vuln/" to return reasons for PCI Compliance Status.

Example:

 

$ curl -u "LOGIN:PASSWORD" -H "X-Requested-With: curl" "https://qualysapi.qualys.com/api/2.0/fo/knowledge_base/vuln/?show_pci_reasons=1"
[...]
      <VULN>
        <QID>155754</QID>
        <VULN_TYPE>Vulnerability</VULN_TYPE>
        <SEVERITY_LEVEL>4</SEVERITY_LEVEL>
        <TITLE><![CDATA[Oracle Enterprise Linux Update for Kernel (ELSA-2009-1541)]]></TITLE>
[...]        <PCI_FLAG>1</PCI_FLAG>
        <PCI_REASONS>
          <PCI_REASON>CVSS basescore of 4.0 or greater results in an automatic failure.</PCI_REASON>
        </PCI_REASONS>
[...]
      </VULN>
[...]

 

The DTD "knowledge_base_vuln_list_output.dtd" has been updated with the new XML elements <PCI_REASONS> and <PCI_REASON>.

 

Changes to "/api/2.0/fo/auth/vmware/"

The new parameter "action=edit" can now be used with "/api/2.0/fo/auth/vmware/" to create and edit VMWare authentication records like in this example:

 

$ curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST" -d "action=create&title=NewVMwareRecordWithAPI&username=USERNAME&password=PASSWORD&ips=10.10.10.2-10.10.10.4" "https://prod01.qa.qualys.com/api/2.0/fo/auth/vmware/"
[...]
         <RESPONSE>
           <DATETIME>2012-02-03T21:16:41Z</DATETIME>
           <BATCH_LIST>
             <BATCH>
               <TEXT>Successfully Created</TEXT>
               <ID_SET>
                 <ID>30486</ID>
               </ID_SET>
             </BATCH>
           </BATCH_LIST>
         </RESPONSE>
[...]

 

There is no DTD change.

 

Changes to "/compliance/posture/info/"

To reflect the changes of the UI, a new "Error" value of the "<STATUS>" XML element can be returned in the output of the API "/compliance/posture/info/?action=list" like in this example:

 

 

$ curl -u USERNAME:PASSWORD -H "X-Requested-With: Curl" "https://qualysapi.qualys.com/api/2.0/fo/compliance/posture/info/?action=list&policy_id=10299"
[...]
      <INFO>
        <ID>1626484</ID>
        <HOST_ID>2139743</HOST_ID>
        <CONTROL_ID>3777</CONTROL_ID>
        <TECHNOLOGY_ID>2</TECHNOLOGY_ID>
        <STATUS>Error</STATUS>
      </INFO>
[...]

 

There is no DTD change.

 

New "/api/2.0/fo/compliance/fdcc_policy/"

The new FDCC policy list API "/api/2.0/fo/compliance/fdcc_policy/?action=list" is used to obtain a list of the FDCC policies in the user’s account. This function can be used in conjunction with the Cyberscope API to generate reports based on specific FDCC policies.

Example:

 

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" "https://qualysapi.qualys.com/api/2.0/fo/compliance/fdcc_policy/?action=list&details=All"
[...]
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE POLICY_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/compliance/fdcc_policy/fdcc_policy_list_output.dtd">
<FDCC_POLICY_LIST_OUTPUT>
          <RESPONSE>
                    <DATETIME>2012-07-19T22:10:16Z</DATETIME>
                    <FDCC_POLICY_LIST>
                              <FDCC_POLICY>
                                        <ID>10235</ID>
                                        [...]
                              </FDCC_POLICY>
                    </FDCC_POLICY_LIST>
          </RESPONSE>
</FDCC_POLICY_LIST_OUTPUT>
[...]

 

A new DTD "fdcc_policy_list_output.dtd" has been published.

 

Additions to Policy Report XML - Host Last Scan Date and Error Posture Status

The compliance policy report can be downloaded using: a) the QualysGuard user interface, and b) the report share API v2 (/api/2.0/fo/report/?action=fetch). The policy report XML output uses the posture_info_list_output.dtd.

 

For the 7.4 release, the policy report XML output has these enhancements:

  • New “Last scan date” for each host in the report.
  • New Error posture status for user defined controls, reported in cases where evaluation errors occur at scan time.

 

Example:

 

[...]
<COMPLIANCE_POLICY_REPORT>
          [...]
          <HOST_LIST>
                    <HOST>
                              <TRACKING_METHOD><![CDATA[IP]]></TRACKING_METHOD>
                              <IP><![CDATA[10.10.10.92]]></IP>
                              [...]
                              <LAST_SCAN_DATE>2012-07-30T23:36:48Z</LAST_SCAN_DATE>
                              [...]
                              <TOTAL_ERROR>0</TOTAL_ERROR>
                              <CONTROL_LIST>
                                        <CONTROL>
                                        [...]
                                        </CONTROL>
                              </CONTROL_LIST>
                    </HOST>
          </HOST_LIST>
</COMPLIANCE_POLICY_REPORT>

 

The DTD posture_info_list_output.dtd has been updated with the XML elements <LAST_SCAN_DATE> and <TOTAL_ERROR>

 

Full release notes will be available to customers from within the Resources section of your QualysGuard account.

Outcomes