Eric Perraudeau

QualysGuard 7.11 API Notification

Blog Post created by Eric Perraudeau Employee on Jul 12, 2013

A new release of QualysGuard, Version 7.11, will be available in production in August 2013. 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 in QualysGuard 7.11, allowing you to proactively figure out any changes that might be required for your automated scripts or programs that make call to the API functions describe provided below:

  • Enhancements to “/api/2.0/fo/asset/host” API
    • support for asset tags as input parameter for host selection
    • support for asset tags in the XML output
    • support for Qualys Host ID in the XML output when Agentless Tracking is used
    • support for custom page size output
    • “host_list_output.dtd” updated
  • Enhancements to “/api/2.0/fo/asset/host/vm/detection”
    • support for asset tags as input parameter for host selection
    • support for asset tags in the XML output
    • support for Qualys Host ID in the XML output when Agentless Tracking is used
    • “host_list_vm_detection_output.dtd” updated
  • New technology available in Authentication API V2 “/api/2.0/fo/auth”
    • support for Apache 2.2 (IBM http Server 7.x running on RHEL 5.x and 6.x)
    • support for Apache 2.2 (VMWare vFabric Web Server 5.2)
    • support for Microsoft IIS 6.x and 7.x
    • support for IBM WebSphere Application Server 7.0
  • Enhancements to “/api/2.0/fo/auth” API
    • output contains new authentication records mentioned above
    • “auth_records.dtd” updated

 

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


Enhancements to “/api/2.0/fo/asset/host” API

New input parameters

New input parameters allow you to list hosts using asset tags, and return the list of asset tags in the XML output. The example provided below is a request to list all the hosts tagged with the tag "US-HQ" but not tagged with the tag "US-HQ-FINANCE", and return the list of the asset tags for all the hosts record in the XML output:

 

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST" -d
     "action=list&use_tags=1&show_tags=1&tag_set_by=name&tag_include_selector=any&
     tag_exclude_selector=any&tag_set_include=US-HQ&tag_set_exclude=US-HQ-FINANCE"
     "https://qualysapi.qualys.com/api/2.0/fo/asset/host/"

 

Support for custom page size output

To optimize the processing of the XML output by the API client, the output of the Host List API is paginated. By default, a maximum of 1,000 host records are returned per page. Now with QualysGuard 7,11, you can customize the page size (i.e. the number of host records) by using the parameter “truncation_limit=10000” for instance. In this case the results will be return with pages of 10,000 host records.

 

When using “truncation_limit=0” it means that the output is not paginated and all the records are returned in a single output.

 

XML output includes new elements

The XML output returned from a Host List API v2 request now includes new information and the output DTD was updated. This information is returned:

  • The QG Host ID assigned to each host when Agentless Tracking is used
  • The tags associated with each host when show_tags=1 is specified

 

"host_list_output.dtd" changes

[...]

<!ELEMENT HOST_LIST (HOST+)>

<!ELEMENT HOST (ID, IP?, TRACKING_METHOD?, DNS?, EC2_INSTANCE_ID?,

                      NETBIOS?, OS?, QG_HOSTID?, TAGS?, LAST_VULN_SCAN_DATETIME?,

                      LAST_COMPLIANCE_SCAN_DATETIME?, OWNER?, COMMENTS?,

                      USER_DEF?, ASSET_GROUP_IDS?)>

<!ELEMENT TAGS (TAG+)>

<!ELEMENT TAG (TAG_ID, NAME)>

[...]

 

Sample Output


<HOST_LIST>
  <HOST>
    <ID>2162066</ID>
    <IP>10.10.10.33</IP>
    <TRACKING_METHOD>IP</TRACKING_METHOD>
    <DNS><![CDATA[dhcp-33.qualys.com]]></DNS>
    <OS><![CDATA[AIX 5.3]]></OS>
    <QG_HOSTID><![CDATA[51da79a3-0375-0002-605b-005056a91eec]]></QG_HOSTID>
    <TAGS>
      <TAG>
        <TAG_ID><![CDATA[301370]]></TAG_ID>
        <NAME><![CDATA[US-HQ]]></NAME>
      </TAG>
      <TAG>
        <TAG_ID><![CDATA[262969]]></TAG_ID>
        <NAME><![CDATA[port-111]]></NAME>
      </TAG>
    </TAGS>
  </HOST>
</HOST_LIST>

 

Enhancements to “/api/2.0/fo/asset/host/vm/detection”

New input parameters

New input parameters allow you to list host detections using asset tags, and return the list of asset tags in the XML output. It is similar to the changes explained below for the host API.

 

XML output includes new elements

The XML output returned from a vulnerability detection API request now includes new information and the output DTD was updated. This information is returned:

  • The QG Host ID assigned to each host when Agentless Tracking is used
  • The tags associated with each host when show_tags=1 is specified
  • The fixed date/time for each vulnerability with a Fixed status (when the vulnerability was verified fixed by a scan)

 

"host_list_vm_detection_output.dtd" changes

[...]

<!ELEMENT HOST_LIST (HOST+)>

<!ELEMENT HOST (ID, IP?, IPV6?, TRACKING_METHOD?, OS?, OS_CPE?, DNS?,

                      NETBIOS?, QG_HOSTID?, TAGS?, LAST_SCAN_DATETIME?,

                      DETECTION_LIST?)>

<!ELEMENT TAGS (TAG+)>

<!ELEMENT TAG (TAG_ID, NAME)>

<!ELEMENT DETECTION_LIST (DETECTION+)>

<!ELEMENT DETECTION_LIST (DETECTION+)>

<!ELEMENT DETECTION (QID, TYPE, PORT?, PROTOCOL?, FQDN?, SSL?, INSTANCE?,

                     RESULTS?, STATUS?, FIRST_FOUND_DATETIME?, LAST_FOUND_DATETIME?,

                     LAST_TEST_DATETIME?, LAST_UPDATE_DATETIME?, LAST_FIXED_DATETIME?)>

[...]

 

Sample Output

 

 

<HOST_LIST>
  <HOST>
    <ID>2167925</ID>
    <IP>10.10.30.156</IP>
    <TRACKING_METHOD>IP</TRACKING_METHOD>
    <OS><![CDATA[Linux 2.4-2.6 / Embedded Device / F5 Networks Big-IP]]></OS>
    <LAST_SCAN_DATETIME>2013-06-11T18:04:43Z</LAST_SCAN_DATETIME>
    <TAGS>
      <TAG>
        <TAG_ID><![CDATA[299373]]></TAG_ID>
        <NAME><![CDATA[US-HQ]]></NAME>
      </TAG>
    </TAGS>
    <DETECTION_LIST>
      <DETECTION>
        <QID>12476</QID>
        <TYPE>Confirmed</TYPE>
        <PORT>8080</PORT>
        <PROTOCOL>tcp</PROTOCOL>
        <SSL>0</SSL>
        <RESULTS><![CDATA[JBoss HttpAdaptor JMXInvokerServlet is accessible to Unauthenticated Remote Users]]></RESULTS>
        <STATUS>New</STATUS>
        <FIRST_FOUND_DATETIME>2013-06-11T17:40:35Z</FIRST_FOUND_DATETIME>
        <LAST_FOUND_DATETIME>2013-06-11T17:40:35Z</LAST_FOUND_DATETIME>
        <LAST_TEST_DATETIME>2013-06-11T17:40:35Z</LAST_TEST_DATETIME>
        <LAST_FIXED_DATETIME>2013-06-11T18:04:43Z</LAST_FIXED_DATETIME>
      </DETECTION>
    </DETECTION_LIST>
  </HOST>
<HOST_LIST>

 

Update to the Authentication API to support new application server technologies

QualysGuard 7.11 now provides the ability to manage authentication record for the following technologies using the Authentication API V2 “/api/2.0/fo/auth”:

  • support for Apache 2.2 (IBM http Server 7.x runnign on RHEL 5.x and 6.x)
  • support for Apache 2.2 (VMWare vFabric Web Server 5.2)
  • support for Microsoft IIS 6.x and 7.x
  • support for IBM WebSphere Application Server 7.0

 

The Authentication API V2 includes the ability manage authentication records for the technologies listed above and:

  • Create new authentication records
  • Update authentication records
  • Delete authentication records
  • List Authentication records

 

Example: Create a new Apache record

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST"

          -d "action=create&title=Apache+Record&unix_apache_config_file=/opt/IBM/HTTPServer/conf/httpd.conf1&

     unix_apache_control_command=/opt/IBM/HTTPServer/bin2&ips=10.10.25.25"

          "https://qualysapi.qualys.com/api/2.0/fo/auth/apache/"

 

Example: Update an Apache record

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST"

          -d "action=update&ids=1234&unix_apache_config_file=/opt/IBM/HTTPServer/conf/httpd.conf2"

          "https://qualysapi.qualys.com/api/2.0/fo/auth/apache/"

 

Example: Delete an Apache record

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST"

          -d "action=delete&ids=1234"

          "https://qualysapi.qualys.com/api/2.0/fo/auth/apache/"

 

Example: List Apache records

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST"

          -d "action=list"

          "https://qualysapi.qualys.com/api/2.0/fo/auth/apache/"

 

Sample Apache record output:


 <?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE AUTH_APACHE_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/auth/apache/auth_apache_list_output.dtd">
<AUTH_APACHE_LIST_OUTPUT>
  <RESPONSE>
    <DATETIME>2013-06-25T17:55:32Z</DATETIME>
      <AUTH_APACHE_LIST>
        <AUTH_APACHE>
          <ID>8795</ID>
          <TITLE><![CDATA[Apache - IBM HTS 7.0]]></TITLE>
          <IP_SET>
            <IP>10.10.26.26</IP>
            <IP>10.10.30.38</IP>
            <IP>10.10.30.71</IP>
          </IP_SET>
        <UNIX_CONFIGURATION_FILE><![CDATA[/opt/IBM/HTTPServer/conf/httpd.conf2]]></UNIX_CONFIGURATION_FILE>
        <UNIX_CONTROL_COMMAND><![CDATA[/opt/IBM/HTTPServer/bin2]]></UNIX_CONTROL_COMMAND>
        <CREATED>
          <DATETIME>2013-05-07T20:38:06Z</DATETIME>
          <BY>quays_cd3</BY>
        </CREATED>
        <LAST_MODIFIED>
          <DATETIME>2013-06-20T18:12:37Z</DATETIME>
        </LAST_MODIFIED>
        <COMMENTS><![CDATA[some comment text]]></COMMENTS>
      </AUTH_APACHE>
    </AUTH_APACHE_LIST>
  </RESPONSE>
</AUTH_APACHE_LIST_OUTPUT>

 

Enhancements to “/api/2.0/fo/auth” API

The “Authentication List” API v2 lists all authentication records in the user’s account.

 

Example:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST" -d

       "action=list" "https://qualysapi.qualys.com/api/2.0/fo/auth/"

 

XML output modified and “/api/2.0/fo/auth/auth_records.dtd” updated:

 

[...]

<!ELEMENT RESPONSE (DATETIME, AUTH_RECORDS?, WARNING_LIST?)>

<!ELEMENT AUTH_RECORDS (AUTH_UNIX_IDS?, AUTH_WINDOWS_IDS?, AUTH_ORACLE_IDS?,

                                                AUTH_ORACLE_LISTENER_IDS?, AUTH_SNMP_IDS?, AUTH_MS_SQL_IDS?,

                                                AUTH_IBM_DB2_IDS?, AUTH_VMWARE_IDS?, AUTH_MS_IIS_IDS?, AUTH_APACHE_IDS?,

                                                AUTH_IBM_WEBSPHERE_IDS?)

<!ELEMENT AUTH_MS_IIS_IDS (ID_SET)>

<!ELEMENT AUTH_APACHE_IDS (ID_SET)>

<!ELEMENT AUTH_IBM_WEBSPHERE_IDS (ID_SET)>

[...]

Outcomes