Eric Perraudeau

QualysGuard 7.7 API Notification

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

A new release of QualysGuard, Version 7.7, will be available in production by the end of December 2012. The final date has not been determined yet, but this release contains changes to the APIs and DTDs that requires a 30-day notification. More information specific to this release, including the date of global availability, will be communicating 2 weeks before the release date 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 use the following functions or XML outputs:

  • Detailed Asset Tag Information added to XML Reports
  • Improvements of “PC Scan” API v2 for Asset Tag Selection
  • Support for Agentless Tracking added to “Scan Authentication” API v2

 

Warning: all the examples provided below use “qualysapi.qualys.com”. Replace this FQDN by the API server FQDN of your QualysGuard datacenter (for instance: “qualysapi.qualys.eu”).

 

Detailed Asset Tag Information Added to XML Reports

 

With QualysGuard 7.7, XML reports show tags resolved to host assets when a user runs a report using asset tags. The DTDs for these reports were updated:

 

  • "asset_data_report.dtd": Used for the automatic vulnerability reports generated in the XML format using the User Interface or the APIs "/api/2.0/fo/report/" and "/msp/asset_data_report.php"

New "<ASSET_TAG_LIST>" and "<ASSET_TAGS>" XML parent elements have been introduced as shown in the example below:

 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE ASSET_DATA_REPORT SYSTEM "https://qualysguard.qualys.com/asset_data_report.dtd">
<ASSET_DATA_REPORT>
 <HEADER>
  [..]
  <TARGET>
   <ASSET_TAG_LIST>
    <INCLUDED_TAGS scope="any">
     <ASSET_TAG><![CDATA[Linux]]></ASSET_TAG>
     <ASSET_TAG><![CDATA[US]]></ASSET_TAG>
    </INCLUDED_TAGS>
    <EXCLUDED_TAGS scope="all">
     <ASSET_TAG><![CDATA[Redhat]]></ASSET_TAG>
     <ASSET_TAG><![CDATA[California]]></ASSET_TAG>
    </INCLUDED_TAGS>
   </ASSET_TAG_LIST>
  </TARGET>
 </HEADER>
 <HOST_LIST>
  <HOST>
   <IP>10.10.10.65</IP>
   <TRACKING_METHOD>IP</TRACKING_METHOD>
   <ASSET_TAGS>
    <ASSET_TAG><![CDATA[Linux]]></ASSET_TAG>
    <ASSET_TAG><![CDATA[Milwaukee]]></ASSET_TAG>
   </ASSET_TAGS>
   <DNS><![CDATA[krb5.corp1.corp.com]]></DNS>
   <OPERATING_SYSTEM><![CDATA[Debian Linux 4.0]]></OPERATING_SYSTEM>
   <OS_CPE><![CDATA[cpe:/o:debian:debian_linux:4.0:::]]></OS_CPE>
   <ASSET_GROUPS>[...]</ASSET_GROUPS>
   <VULN_INFO_LIST>
    <VULN_INFO>[...]</VULN_INFO>
   </VULN_INFO_LIST>
  </HOST>
  [...]
 </HOST_LIST>
</ASSET_DATA_REPORT>

 

  • "asset_search_report.dtd": Used for the XML Asset Search Report generated using the User Interface via "Asset > Asset Search" or using the API "/msp/asset_search.php"

New "<ASSET_TAGS>" and "<HOST_TAGS>" XML parent elements have been introduced as shown in the example below:

 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE ASSET_SEARCH_REPORT SYSTEM "https://qualysguard.qualys.com/asset_search_report.dtd">
<ASSET_SEARCH_REPORT>
 <HEADER>
  <COMPANY>Qualys, Inc.</COMPANY>
  <USERNAME>Bill Smith</USERNAME>
  <GENERATION_DATETIME>2012-11-14T20:35:27Z</GENERATION_DATETIME>
  <FILTERS>
   <ASSET_TAGS>
    <INCLUDED_TAGS scope="any">
     <ASSET_TAG><![CDATA[US]]></ASSET_TAG>
    </INCLUDED_TAGS>
   </ASSET_TAGS>
  </FILTERS>
 </HEADER>
 <HOST_LIST>
  <HOST>
   <IP>10.10.10.65</IP>
   <HOST_TAGS>
    <![CDATA[10.10.10-network, Linux, Milwaukee, US;]]>
   </HOST_TAGS>
   <TRACKING_METHOD>IP</TRACKING_METHOD>
   <DNS><![CDATA[krb5.corp1.corp.com]]></DNS>
   <OPERATING_SYSTEM><![CDATA[Debian Linux 4.0]]></OPERATING_SYSTEM>
   <OS_CPE><![CDATA[cpe:/o:debian:debian_linux:4.0:::]]></OS_CPE>
   <LAST_SCAN_DATE>2012-11-12T21:50:51Z</LAST_SCAN_DATE>
  </HOST>
 </HOST_LIST>
 [...]
<ASSET_SEARCH_REPORT>

 

  • "compliance_authentication_report.dtd": Used for XML Policy Compliance Authentication Report generated via the API or using the "/api/2.0/fo/report/"

New "<ASSET_TAG_LIST>" XML parent elements have been introduced as shown in the example below:

 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE COMPLIANCE_AUTHENTICATION_REPORT SYSTEM "https://qualysapi.qualys.com/compliance_authentication_report.dtd">
<COMPLIANCE_AUTHENTICATION_REPORT>
 <HEADER>
  <NAME><![CDATA[Authentication Report]]></NAME>
  <GENERATION_DATETIME>2012-11-14T00:47:04Z</GENERATION_DATETIME>
  <COMPANY_INFO>[...]</COMPANY_INFO>
  <USER_INFO>[...]</USER_INFO>
  <FILTERS>
   <ASSET_TAG_LIST>
    <INCLUDED_TAGS scope="any">
     <TAG_ITEM><![CDATA[24 Range -3 Ips]]></TAG_ITEM>
     <TAG_ITEM><![CDATA[2 IPs-24 range]]></TAG_ITEM>
     <TAG_ITEM><![CDATA[Windows XP tag]]></TAG_ITEM>
    </INCLUDED_TAGS>
    <EXCLUDED_TAGS scope="any">
     <TAG_ITEM><![CDATA[10.10.10.29]]></TAG_ITEM>
     <TAG_ITEM><![CDATA[29 and 54]]></TAG_ITEM>
     <TAG_ITEM><![CDATA[33]]></TAG_ITEM>
    </EXCLUDED_TAGS>
   </ASSET_TAG_LIST>
  </FILTERS>
 </HEADER>
 <ASSET_TAG_LIST>
  <ASSET_TAG>
   <INCLUDED_TAGS scope="any">
    <TAG_ITEM><![CDATA[2 IPs-24 range]]></TAG_ITEM>
    <TAG_ITEM><![CDATA[Windows XP tag]]></TAG_ITEM>
    <TAG_ITEM><![CDATA[24 Range -3 Ips]]></TAG_ITEM>
   </INCLUDED_TAGS>
   <EXCLUDED_TAGS scope="any">
    <TAG_ITEM><![CDATA[10.10.10.29]]></TAG_ITEM>
    <TAG_ITEM><![CDATA[29 and 54]]></TAG_ITEM>
    <TAG_ITEM><![CDATA[33]]></TAG_ITEM>
   </EXCLUDED_TAGS>
   <AUTH_PASSED>7</AUTH_PASSED>
   <AUTH_INSUFFICIENT>0</AUTH_INSUFFICIENT>
   <AUTH_TOTAL>7</AUTH_TOTAL>
   <PASSED_PERCENTAGE>100</PASSED_PERCENTAGE>
   <TECHNOLOGY_LIST>
    <TECHNOLOGY>
     <NAME><![CDATA[Windows]]></NAME>
     <HOST_LIST>[...]</HOST_LIST>
    </TECHNOLOGY>
    [...]
   </TECHNOLOGY_LIST>
  </ASSET_TAG>
 </ASSET_TAG_LIST>
</COMPLIANCE_AUTHENTICATION_REPORT>

 

Improvements of “PC Scan” API v2 for Asset Tag Selection

 

The API v2 "/api/2.0/fo/scan/compliance/" with "action=launch" allows users to launch compliance scans using asset tags.

 

QualysGuard 7.7 will now allows users to launch scans using more complex tag selections (match any tags, include and exclude tags) and launch scans on IPs defined in tags. Details about the new input parameters for asset tag selection are going to be provided in the release note and the update API v2 user guide the day of the release.

 

No change was made to the DTD.

 

Support for Agentless Tracking added to “Scan Authentication” API v2

 

The new "Agentless Tracking" feature allows customers to track hosts by host ID, instead of IP address (or DNS name or NetBIOS name). When enabled, the service tags target Windows and/or Unix hosts with a unique host ID during the scanning process and reports on the host ID for the current and future scans of the same host. This provides a scan option for customers who would like to scan systems with multiple IP addresses.

 

How it works: Once this feature enabled by the Manager primary contact of the subscription, users can select agentless tracking on a per scan basis by selecting this option in Windows and/or Unix authentication records. During the scanning process the service assigns a unique host ID to each target host, storing the host ID on the host’s local file system or registry. In future scans of the same host the service references the host ID and reports on it.

 

The following APIs were updated in this release:

  • Windows authentication API "/api/2.0/fo/auth/windows/" has new a input parameter to setup the Agentless Tracking feature and the DTD "auth_windows_list_output.dtd" has been updated with a new "<USE_AGENTLESS_TRACKING>" XML element as shown in the example below:

 

curl -n -H "X-Requested-With:curl" "https://qualysapi.qualys.com/api/2.0/fo/auth/windows/?action=list"

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE AUTH_WINDOWS_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/auth/windows/auth_windows_list_output.dtd">
<AUTH_WINDOWS_LIST_OUTPUT>
 <REQUEST>
  [...]
 </REQUEST>
 <RESPONSE>
  <DATETIME>2012-11-14T20:55:53Z</DATETIME>
  <AUTH_WINDOWS_LIST>
   <AUTH_WINDOWS>
    <ID>35102</ID>
    <TITLE><![CDATA[Windows]]></TITLE>
    [...]
    <USE_AGENTLESS_TRACKING><![CDATA[1]]></USE_AGENTLESS_TRACKING>
   </AUTH_WINDOWS>
  </AUTH_WINDOWS_LIST>
 </RESPONSE>
</AUTH_WINDOWS_LIST_OUTPUT>

 

  • Unix authentication API "/api/2.0/fo/auth/unix/" has new a input parameter to setup the Agentless Tracking feature and the DTD "auth_windows_list_output.dtd" has been updated with a new "<USE_AGENTLESS_TRACKING>" and "<AGENTLESS_TRACKING_PATH>" XML elements as shown in the example below:

 

curl -n -H "X-Requested-With:curl" "https://qualysapi.qualys.com/api/2.0/fo/auth/unix/?action=list"

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE AUTH_UNIX_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/auth/unix/auth_unix_list_output.dtd">
<AUTH_UNIX_LIST_OUTPUT>
 <REQUEST>
  [...]
 </REQUEST>
 <RESPONSE>
  <DATETIME>2012-11-14T19:57:57Z</DATETIME>
  <AUTH_UNIX_LIST>
   <AUTH_UNIX>
    <ID>35103</ID>
    <TITLE><![CDATA[Unix - Qualys Host ID]]></TITLE>
    [...]
    <USE_AGENTLESS_TRACKING><![CDATA[1]]></USE_AGENTLESS_TRACKING>
    <AGENTLESS_TRACKING_PATH><![CDATA[/tmp]]></AGENTLESS_TRACKING_PATH>
   </AUTH_UNIX>
  </AUTH_UNIX_LIST>
 </RESPONSE>
</AUTH_UNIX_LIST_OUTPUT>

 

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


Outcomes