Eric Perraudeau

QualysGuard 7.5 API Notification

Blog Post created by Eric Perraudeau Employee on Sep 17, 2012

A new release of QualysGuard, Version 7.5, will be available in production by the end of October 2012. The final date has not been determined yet but this release contains changes to the API that requires a 30 day notification. More information specific to this release, including the date of global availability, will be 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 API to launch Policy Compliance scans: “/api/2.0/fo/scan/compliance/” with “action=launch
  • Update to “scan_list_output.dtd” DTD for XML output of the new “/api/2.0/fo/scan/compliance/?action=list” API request only
  • Update to Policy Compliance XML scan results with a new section to show scan authentication issues
  • Update to Policy Compliance XML reports generated with the UI or the API “/api/2.0/fo/report/?action=fetch”.  <HOST_STATISTICS> section now contains the Operating System information
  • Update to “/api/2.0/fo/auth/oracle” with a option to support “invPtrLoc” file path
  • Update to “/msp/ticket_edit.php” API with a new option to support reopen date
  • /msp/scheduled_scans.php” XML output updated to show continuous tasks

 

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”).

 

New API to launch and manage Policy Compliance scans

 

QualysGuard 7.5 now includes a new API to manage Policy Compliance scans. This API includes 5 key functions:

  • Launch, to start a compliance scan
  • Pause, to pause a compliance scan
  • Resume, to resume a previously paused scan
  • List, to retrieve the list of compliance scans with their respective status, reference key, etc...
  • Fetch, to retrieve information for a specific compliance scan
  • Cancel, to cancel a compliance scan

 

The “New Scanner Services” is required for these API, please refer to the link here after for more information: https://community.qualys.com/docs/DOC-3695

 

A new DTD “compliance_scan_result_output.dtd” has been released.

 

Example: launch a new Policy Compliance scan:

HTTP POST is required for "action=launch"

 

 
$ curl -u "USER:PASSWORD" -H "X-Requested-With: curl" -X "POST" -d "action=launch&option_title=SCAN_OPTION_PROFILE_TITLE&ip=IP_ADDRESS&iscanner_name=SCANNER_APPLIANCE_NAME" "https://qualysapi.qualys.com/api/2.0/fo/scan/compliance/"

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SIMPLE_RETURN SYSTEM "https://qualysapi.qualys.com/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
  <RESPONSE>
    <DATETIME>2012-09-17T18:55:29Z</DATETIME>
    <TEXT>New compliance scan launched</TEXT>
    <ITEM_LIST>
      <ITEM>
        <KEY>ID</KEY>
        <VALUE>3337xxx</VALUE>
      </ITEM>
      <ITEM>
        <KEY>REFERENCE</KEY>
        <VALUE>compliance/1347908128.37xxx</VALUE>
      </ITEM>
    </ITEM_LIST>
  </RESPONSE>
</SIMPLE_RETURN>

 

 

Update to “scan_list_output.dtd” DTD

 

This DTD describes the XML results of the existing “/api/2.0/fo/scan/?action=list” output and the new “/api/2.0/fo/scan/compliance/?action=list” output.

 

There is a new optional <ID> XML element which is only returned by the new “/api/2.0/fo/scan/compliance/” API.

 

The output of “/api/2.0/fo/scan/?action=list” has not been changed even if the XML output is described by the same DTD.

 

Example: list Policy Compliance scans:

 

 

$ curl -k -u "USER:PASSWORD" -H "X-Requested-With: curl" -X "POST" -d "action=list" "https://qualysapi.qualys.com/api/2.0/fo/scan/compliance/"

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SCAN_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/scan/scan_list_output.dtd">
<SCAN_LIST_OUTPUT>
  <RESPONSE>
    <DATETIME>2012-09-17T23:15:40Z</DATETIME>
    <SCAN_LIST>
      <SCAN>
        <ID>3337xxx</ID>
        <REF>compliance/1347920xxx.37xxx</REF>
        <TYPE>API</TYPE>
        <TITLE><![CDATA[N/A]]></TITLE>
        <USER_LOGIN>manager</USER_LOGIN>
        <LAUNCH_DATETIME>2012-09-17T22:26:00Z</LAUNCH_DATETIME>
        <STATUS>
          <STATE>Finished</STATE>
        </STATUS>
        <TARGET><![CDATA[10.10.10.29]]></TARGET>
      </SCAN>
      </SCAN_LIST>
  </RESPONSE>
</SCAN_LIST_OUTPUT>

 

Updates to “compliance_scan.dtd” and “compliance_scan_result_output.dtd” DTD to show host reasons for authentication issues

 

With QualysGuard 7.5, detailed reasons for authentication issues are returned in the policy compliance XML scan results downloaded with the UI (compliance_scan.dtd), and the policy compliance XML scan results downloaded with the API (compliance_scan_result_output.dtd) like in this example:

 

$ curl -k -u "USER:PASSWORD" -H "X-Requested-With: curl" -X "POST" "https://qualysapi.qualys.com/api/2.0/fo/scan/compliance/?action=fetch&scan_ref=compliance/1347909093.37xxx"

 

A new <AUTH_SCAN_ISSUES> XML section has been added and provides additional information when host authentication issues happened, including failed authentication or insufficient privileges.

 

Example:

 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE COMPLIANCE_SCAN SYSTEM "https://qualysapi.qualys.com/compliance_scan.dtd">
<COMPLIANCE_SCAN>
          <HEADER>[...]</HEADER>
          <AUTH_SCAN_ISSUES>
                    <AUTH_SCAN_FAILED>
                              <HOST_INFO>
                                        <DNS><![CDATA[u-wxp-10-25]]></DNS>
                                        <IP><![CDATA[10.10.10.25]]></IP>
                                        <NETBIOS><![CDATA[U-WXP-10-25]]></NETBIOS>
                                        <INSTANCE><![CDATA[os]]></INSTANCE>
                                        <CAUSE><![CDATA[Unable to complete Windows login for host=10.10.10.25, user=Administrator, domain=, ntstatus=c000006d]]></CAUSE>
                              </HOST_INFO>
                              <HOST_INFO>
                                        <DNS><![CDATA[-]]></DNS>
                                        <IP><![CDATA[10.10.10.95]]></IP>
                                        <NETBIOS><![CDATA[-]]></NETBIOS>
                                        <INSTANCE><![CDATA[os]]></INSTANCE>
                                        <CAUSE><![CDATA[Unable to complete login for host=10.10.10.95, user=root]]></CAUSE>
                              </HOST_INFO>
                    </AUTH_SCAN_FAILED>
                    <AUTH_SCAN_INSUFFICIENT>
                              <HOST_INFO>
                                        <DNS><![CDATA[cisco2600.corp.com]]></DNS>
                                        <IP><![CDATA[10.10.10.101]]></IP>
                                        <NETBIOS><![CDATA[-]]></NETBIOS>
                                        <INSTANCE><![CDATA[os]]></INSTANCE>
                                        <CAUSE><![CDATA[Insufficient privileges]]></CAUSE>
                              </HOST_INFO>
                    </AUTH_SCAN_INSUFFICIENT>
          </AUTH_SCAN_ISSUES>
          <APPENDIX>[...]</APPENDIX>
</COMPLIANCE_SCAN>

 

 

Update to “compliance_policy_report.dtd” DTD to add Operating System informatio to Policy Compliance XML reports

 

The policy compliance reports returned in XML are now displaying a new <OPERATING_SYSTEM> XML element for each host lke in this example:

 

$ curl -k -u "USER:PASSWORD" -H "X-Requested-With: curl" "https://qualysapi.qualys.com/api/2.0/fo/report/?action=fetch&id=320xxx"

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE COMPLIANCE_POLICY_REPORT SYSTEM "https://qualysguard.qualys.com/compliance_policy_report.dtd">
<COMPLIANCE_POLICY_REPORT>
  <HEADER>...</HEADER>
  <SUMMARY>
    <TOTAL_ASSETS>14</TOTAL_ASSETS>
    <TOTAL_CONTROLS>20</TOTAL_CONTROLS>
    <CONTROL_INSTANCES>...</CONTROL_INSTANCES>
    <HOST_STATISTICS>
      <HOST_INFO>
        <IP><![CDATA[10.10.10.29]]></IP>
        <DNS><![CDATA[xpsp3-10-29.patch.ad.corp.com]]></DNS>
        <NETBIOS><![CDATA[XPSP3-10-29]]></NETBIOS>
        <OPERATING_SYSTEM><![CDATA[Windows XP Service Pack 3]]></OPERATING_SYSTEM>
        <LAST_SCAN_DATE><![CDATA[2012-08-09T23:00:59Z]]></LAST_SCAN_DATE>
        <PERCENTAGE>66.67% (4 of 6)</PERCENTAGE>
      </HOST_INFO>
    </HOST_STATISTICS>
  </SUMMARY>
  [...]
</COMPLIANCE_POLICY_REPORT>

 

“/api/2.0/fo/auth/oracle” option to support “invPtrLoc”

 

QualysGuard 7.5 supports the “invPtrLoc” parameter for OPatch detections. This parameter identifies the location of the oraInst.loc file. Using this parameter allows users to identify a custom inventory for patches.

 

Using the “Oracle authentication” API v2 (/api/2.0/fo/auth/oracle/), users have the option to define the “invPtrLoc” parameter when creating and editing Oracle records.

 

$ curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST" -d
       "action=create&title=TITLE&
       username=USERNAME&password=PASSWORD&
       ips=10.10.10.5&
       sid=SID_NAME&
       perform_unix_os_checks=1&
       perform_unix_opatch_checks=1&
       [...]
       unix_invptrloc=/usr/opt/oracle/network/admin/tnsnames.ora"
       "https://qualysapi.qualys.com/api/2.0/fo/auth/oracle/" 

 

When defined for an Oracle record, this parameter is included in the Oracle authentication records list. The “auth_oracle_list_output.dtd” DTD has been updated.

 

$ curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" "https://qualysapi.qualys.com/api/2.0/fo/auth/oracle/?action=list"

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE AUTH_ORACLE_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/auth/oracle/auth_oracle_list_output.dtd">
<AUTH_ORACLE_LIST_OUTPUT>
     <RESPONSE>
          <DATETIME>2012-09-17T17:38:06Z</DATETIME>
          <AUTH_ORACLE_LIST>
               <AUTH_ORACLE>
                    <ID>34xxx</ID>
                    <TITLE>TITLE</TITLE>
                    <USERNAME><![CDATA[oracle_user]]></USERNAME>
                    <SID><![CDATA[oraInst]]></SID>
                    <PORT>All</PORT>
                    <IP_SET>[...]</IP_SET>
                    <WINDOWS_OS_CHECKS>0</WINDOWS_OS_CHECKS>
                    <UNIX_OPATCH_CHECKS>1</UNIX_OPATCH_CHECKS>
                    <UNIX_OS_CHECKS>1</UNIX_OS_CHECKS>
                    <UNIX_OS_OPTIONS>
                         [...]
                         <UNIX_INVPTRLOC_PATH><![CDATA[/usr/opt/oracle/network/admin/oraInst.loc]]></UNIX_INVPTRLOC_PATH>
                    </UNIX_OS_OPTIONS>
                    <CREATED>[...]</CREATED>
                    <LAST_MODIFIED>[...]</LAST_MODIFIED>
                    <COMMENTS>[...]</COMMENTS>
               </AUTH_ORACLE>
          </AUTH_ORACLE_LIST>
     </RESPONSE>
</AUTH_ORACLE_LIST_OUTPUT>

 

“/msp/ticket_edit.php” new option to support “reopen” date

 

The “/msp/ticket_edit.php” function supports a new parameter “reopen_ignored_days” which may be specified to automatically reopen Closed/Ignored tickets in a set number of days. This new parameter was added to the XML output and the “ticket_edit_output.dtd” DTD was updated.

 

$ curl -u USERNAME:PASSWORD -H "X-Requested-With: Curl" "https://qualysapi.qualys.com/msp/ticket_edit.php?ticket_numbers=907xx&reopen_ignored_days=30"

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE TICKET_EDIT_OUTPUT SYSTEM "https://qualysapi.qualys.com/ticket_edit_output.dtd">
<TICKET_EDIT_OUTPUT>
     <HEADER>
          <USER_LOGIN>qualys_user</USER_LOGIN>
          <COMPANY><![CDATA[Qualys]]></COMPANY>
          <DATETIME>2012-09-17T10:33:53Z</DATETIME>
          <UPDATE>
               <REOPEN_IGNORED_DAYS>30</REOPEN_IGNORED_DAYS>
          </UPDATE>
          <WHERE>
               <TICKET_NUMBERS>90783</TICKET_NUMBERS>
          </WHERE>
     </HEADER>
</TICKET_EDIT_OUTPUT>

 

“/msp/scheduled_scans.php” XML output updated to show continuous tasks

 

QualysGuard 7.5 supports a new type of scheduled scan, also called “continuous scanning”. When a scheduled task is configured as a continuous scan, a new instance of a scan is launched right after the previous instanced is finished. The XML output of “/msp/scheduled_scan.php” has been updated with a new <RELAUNCH_ON_FINISH> XML element and the “scheduled_scans.dtd" has been updated.

 

$ curl -u "USER:PASSWORD" -H "X-Requested-With: curl" "https://qualysapi.qualys.com/msp/scheduled_scans.php"

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SCHEDULEDSCANS SYSTEM "https://qualysapi.qualys.com/scheduled_scans.dtd">
<SCHEDULEDSCANS>
     <SCAN active="no" ref="647xx">
          <TITLE><![CDATA[TITLE]]></TITLE>
          <TARGETS>[...]</TARGETS>
          <SCHEDULE>
               <RELAUNCH_ON_FINISH />
               <START_DATE_UTC>2012-09-17T18:35:00</START_DATE_UTC>
               <START_HOUR>11</START_HOUR>
               <START_MINUTE>35</START_MINUTE>
               <TIME_ZONE>[...]</TIME_ZONE>
               <DST_SELECTED>1</DST_SELECTED>
          </SCHEDULE>
          [...]
</SCAN>
</SCHEDULEDSCANS>

 

 

 

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


Outcomes