Skip navigation

API Notifications

3 Posts authored by: Christophe Delaure

A new release of QualysGuard, Version 7.13, will be available in production in February, 2014. The final date has not been determined, but this release contains changes to the APIs and DTDs that require 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.13, allowing you to proactively figure out any changes that might be required for your automated scripts or programs that make call to the API function describe provided below.

 

 

PC Policy Report XML - Control References Added

 

The QualysGuard Policy Compliance (PC) application allows you to add references to each control by using the new policy editor or by editing control details. With this release you can choose to create policy reports with your custom control references in XML format - just follow the steps below. The policy report XML output now lists the control references defined for each control. We’ve updated the policy report DTD (compliance_policy_report.dtd) to add a new element <CONTROL_REFERENCES>.

 

Step 1 - Configure the template settings

Configure your policy report template using the user interface (under PC > Reports > Templates). Be sure to choose the Group by Controls option and under Sections choose Control References.

 

Step 2 - Launch a PC policy report

API request:

 

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

       "action=launch&template_id=55469&output_format=xml"

       "https://qualysapi.qualys.com/api/2.0/fo/report/"

 

 

XML output:

 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE GENERIC SYSTEM "https://qualysapi.qualys.com/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
  <RESPONSE>
    <DATETIME>2013-12-11T21:45:23Z</DATETIME>
    <TEXT>New report launched</TEXT>
      <ITEM_LIST>
        <ITEM>
          <KEY>ID</KEY>
          <VALUE>1665</VALUE>
        </ITEM>
      </ITEM_LIST>
     </RESPONSE>
</SIMPLE_RETURN>

 

 

Step 3 - Download report XML

 

API request:

 

curl -k -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST" -d "action=fetch&id=1665" "https://qualysapi.qualys.com/api/2.0/fo/report/"

 

XML output:

 

...<CONTROL_LIST>
  <CONTROL>
    <CID>1376</CID>
    <STATEMENT><![CDATA[Status of the 'Interactive Logon: Do not require CTRL+ALT+DEL' setting]]></STATEMENT>
    <CONTROL_REFERENCES>ABC123,4.6.88</CONTROL_REFERENCES> 
    <RATIONALE><![CDATA[The Windows OS behaves differently when the 'CTRL+ALT+Delete' is invoked before login--this guarantees that the authentication process for the system is engaged. Otherwise, when only the two-line login screen is presented, it is possible that a Trojan program is displaying a phony userid/password login screen, which will collect the credentials and exit, leaving the user believing that he/she simply mistyped one or both of the required values. NOTE: As this is one of the reverse-logic controls, it is important to remember that this should be DISABLED to actually be enabled.]]></RATIONALE>
  <STATUS><![CDATA[Passed]]></STATUS>
  <EVIDENCE><![CDATA[CHECK1]]></EVIDENCE>
</CONTROL>

 

 

Updated DTD (updates in bold):

 

...
<!ELEMENT CONTROL_LIST (CONTROL*)>
<!ELEMENT CONTROL (CID, STATEMENT, CONTROL_REFERENCES?, DEPRECATED?,
                   RATIONALE?, INSTANCE?, STATUS, EVIDENCE?, EXCEPTION?)>
<!ELEMENT CID (#PCDATA)>
<!ELEMENT STATEMENT (#PCDATA)>
<!ELEMENT CONTROL_REFERENCES (#PCDATA)>
<!ELEMENT RATIONALE (#PCDATA)>
<!ELEMENT STATUS (#PCDATA)>
<!ELEMENT INSTANCE (#PCDATA)>
<!ELEMENT EVIDENCE (#PCDATA)>
<!ELEMENT EXCEPTION (ASSIGNEE, STATUS, END_DATE, CREATED_BY, CREATED_DATE,
...
MODIFIED_BY, MODIFIED_DATE, COMMENT_LIST?)>

An update of QualysGuard, Version 7.12, will be available in production in the coming weeks.

 

Enhancements include a set of new API inputs to:

  • Download posture data for multiple policies
  • Filter posture data to include certain asset groups

More information specific to this release, including the date of global availability, will be communicated 2 weeks before the release date via the Release Notification pages:

 

“Compliance Posture Info” API v2 - Enhancements

With this release we've added new input parameters to the "Compliance Posture Info" API v2 (with the endpoint /api/2.0/fo/compliance/posture/info/) to give you more flexibility with downloading compliance posture data from your account. The update to the DTD should not impact current integrations.

 

Download posture data for multiple policies

With this release the new “policy_ids” input parameter allows you to request compliance posture data (info records) for up to 10 policies. You can request posture data using the new parameter “policy_ids” or “policy_id” parameter (available in previous releases).

 

New Parameter:

policy_ids={value}

 

New Parameter Description:

(Optional) A comma-separated list of policy IDs for the policies you want to download compliance posture data for. You can specify up to 10 policies. When this parameter is specified, all posture data is downloaded (and the “truncation_limit” parameter is invalid). When ”policy_ids” is specified you can’t specify these parameters in the same request: “policy_id” and/or “truncation_limit”.

 

The compliance posture info list output DTD was updated (posture_info_list_output.dtd). When “policy_ids” is specified, the XML output shows policy information under the <POLICY> tag, and the <DATETIME> tag under this tag indicates when the policy’s posture data was collected from the API user’s account.

 

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST" -d "action=list&policy_ids=1678,1738" "https://qualysapi.qualys.com/api/2.0/fo/compliance/posture/info/"

 

 

XML output:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE POSTURE_INFO_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/compliance/posture/info/posture_info_list_output.dtd">

<POSTURE_INFO_LIST_OUTPUT>
    <RESPONSE>
        <DATETIME>2013-10-17T21:03:53Z</DATETIME>
        <POLICY>
            <ID>1678</ID>
            <DATETIME>2013-10-17T21:03:53Z</DATETIME>
            <INFO_LIST>
                   <INFO>
                        <ID>5563330</ID>
                        <HOST_ID>927326</HOST_ID>
                        <CONTROL_ID>1200</CONTROL_ID>
                        <TECHNOLOGY_ID>1</TECHNOLOGY_ID>
                        <INSTANCE></INSTANCE>
                        <STATUS>Failed</STATUS>
                   </INFO>
                   <INFO>
                        <ID>5563332</ID>
                        <HOST_ID>927326</HOST_ID>
                        <CONTROL_ID>1198</CONTROL_ID>
                        <TECHNOLOGY_ID>1</TECHNOLOGY_ID>
                        <INSTANCE></INSTANCE>
                        <STATUS>Failed</STATUS>
                   </INFO>
              </INFO_LIST>
          </POLICY>
          <POLICY>
              <ID>1738</ID>
              <DATETIME>2013-10-17T21:04:09Z</DATETIME>
              <INFO_LIST>
                     <INFO>
                         <ID>5585969</ID>
                         <HOST_ID>943039</HOST_ID>
                         <CONTROL_ID>1336</CONTROL_ID>
                         <TECHNOLOGY_ID>7</TECHNOLOGY_ID>
                         <INSTANCE>oracle9:1:1527:ora9208p</INSTANCE>
                         <STATUS>Error</STATUS>
                     </INFO>
                     <INFO>
                         <ID>5586112</ID>
                         <HOST_ID>943048</HOST_ID>
                         <CONTROL_ID>1336</CONTROL_ID>
                         <TECHNOLOGY_ID>9</TECHNOLOGY_ID>
                         <INSTANCE>oracle11:1:1521:orcl</INSTANCE>
                         <STATUS>Error</STATUS>
                      </INFO>
                      <INFO>
                         <ID>5592798</ID>
                         <HOST_ID>940048</HOST_ID>
                         <CONTROL_ID>1336</CONTROL_ID>
                         <TECHNOLOGY_ID>9</TECHNOLOGY_ID>
                         <INSTANCE>oracle11:1:1521:qa11g2lu</INSTANCE>
                         <STATUS>Error</STATUS>
                       </INFO>
                </INFO_LIST>
        </POLICY>
    </RESPONSE>
</POSTURE_INFO_LIST_OUTPUT>

 

 

Updated DTD (updates in bold):

<!-- QUALYS POSTURE_INFO_LIST_OUTPUT DTD -->
<!ELEMENT POSTURE_INFO_LIST_OUTPUT (REQUEST?,RESPONSE)>
<!ELEMENT REQUEST (DATETIME, USER_LOGIN, RESOURCE, PARAM_LIST?,POST_DATA?)>
<!ELEMENT DATETIME (#PCDATA)>
<!ELEMENT USER_LOGIN (#PCDATA)>
<!ELEMENT RESOURCE (#PCDATA)>
<!ELEMENT PARAM_LIST (PARAM+)>
<!ELEMENT PARAM (KEY, VALUE)>
<!ELEMENT KEY (#PCDATA)>
<!ELEMENT VALUE (#PCDATA)>
<!-- if returned, POST_DATA will be urlencoded -->
<!ELEMENT POST_DATA (#PCDATA)>
<!ELEMENT RESPONSE (DATETIME, ((INFO_LIST?, WARNING_LIST?, GLOSSARY?) | POLICY+))>
<!ELEMENT POLICY (ID, DATETIME, INFO_LIST?, WARNING_LIST?, GLOSSARY?)>
<!ELEMENT INFO_LIST (INFO+)>
<!ELEMENT INFO (ID, HOST_ID, CONTROL_ID, TECHNOLOGY_ID, INSTANCE?, STATUS,
...
EXCEPTION?, EVIDENCE?)>

 

 

Filter posture data to include certain asset groups

Use the new “asset_group_ids” parameter to download compliance posture data for hosts in certain asset groups.

 

New Parameter:

asset_group_ids={value}

 

New Parameter Description:

(Optional) A comma-separated list of asset group IDs for the asset groups you want to download compliance posture data for. The asset groups specified do not need to be assigned to the one or more policies requested. Posture data will be returned as long as there are common hosts specified by “asset_group_ids” and asset groups that are assigned to the policies requested.

 

API request:

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST" -d "action=list&echo_request=1&policy_ids=13888,15234,14028&asset_group_ids=456144,451051" "https://qualysapi.qualys.com/api/2.0/fo/compliance/posture/info/"

 

XML output:

Compliance posture data is filtered to include only hosts in asset group ID 56144 and/or 451051. For policy ID 1 5234 compliance posture data is returned for host IDs 2162141 and 2162152 - you can check out the glossary section to see details on these hosts. No posture data is returned for policy IDs 13888 and 14028 (no hosts with posture data are in asset group ID 56144 or 451051).

 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE POSTURE_INFO_LIST_OUTPUT SYSTEM
"https://qualysapi.qualys.com/api/2.0/fo/compliance/posture/info/posture_info_list_output.dtd">
<POSTURE_INFO_LIST_OUTPUT>
  <REQUEST>
    <DATETIME>2013-11-16T17:09:23Z</DATETIME>
    <USER_LOGIN>spt_km</USER_LOGIN>
    <RESOURCE>https://qualysapi.qualys.com/api/2.0/fo/compliance/posture/info/</RESOURCE>
    <PARAM_LIST>
      <PARAM>
        <KEY>action</KEY>
        <VALUE>list</VALUE3E
      </PARAM>
      <PARAM>
        <KEY>echo_request</KEY>
        <VALUE>1</VALUE>
      </PARAM>
      <PARAM>
        <KEY>policy_ids</KEY>
        <VALUE>13888,15234,14028</VALUE>
      </PARAM>
      <PARAM>
        <KEY>asset_group_ids</KEY>
        <VALUE>456144,451051</VALUE>
      </PARAM>
    </PARAM_LIST>
  </REQUEST>
  <RESPONSE>
    <DATETIME>2013-11-16T17:09:23Z</DATETIME>
    <POLICY>
      <ID>13888</ID>
      <DATETIME>2013-11-16T17:09:23Z</DATETIME>
    </POLICY>
    <POLICY>
      <ID>15234</ID>
      <DATETIME>2013-11-16T17:09:28Z</DATETIME>
      <INFO_LIST>
        <INFO>
          <ID>2104640</ID>
          <HOST_ID>2162141</HOST_ID>
          <CONTROL_ID>2016</CONTROL_ID>
          <TECHNOLOGY_ID>2</TECHNOLOGY_ID>
          <INSTANCE></INSTANCE>
          <STATUS>Passed</STATUS>
        </INFO>
        <INFO>
          <ID>2104641</ID>
          <HOST_ID>2162141</HOST_ID>
          <CONTROL_ID>3773</CONTROL_ID>
          <TECHNOLOGY_ID>2</TECHNOLOGY_ID>
          <INSTANCE></INSTANCE>
          <STATUS>Passed</STATUS>
        </INFO>
        <INFO>
          <ID>2104676</ID>
          <HOST_ID>2162152</HOST_ID>
          <CONTROL_ID>2127</CONTROL_ID>
          <TECHNOLOGY_ID>2</TECHNOLOGY_ID>
          <INSTANCE></INSTANCE>
          <STATUS>Passed</STATUS>
        </INFO>
      </INFO_LIST>
      <GLOSSARY>
        <HOST_LIST>
          <HOST>
            <ID>2162141</ID>
            <IP>10.10.25.69</IP>
            <TRACKING_METHOD>IP</TRACKING_METHOD>
            <DNS><![CDATA[2k3-sp2-josh.com-25-69.vuln.qa.qualys.com]]></DNS>
            <NETBIOS><![CDATA[2K3-SP2-JOSH]]></NETBIOS>
            <OS><![CDATA[Windows 2003 Server AD Service Pack 2]]></OS>
          </HOST>
          <HOST>
            <ID>2162152</ID>
            <IP>10.10.25.88</IP>
            <TRACKING_METHOD>IP</TRACKING_METHOD>
            <DNS><![CDATA[2k364sp1-25-88p.2k364sp1.patch.ad.vuln.qa.qualys.com]]></DNS>
            <NETBIOS><![CDATA[2K364SP1-25-88P]]></NETBIOS>
            <OS><![CDATA[Windows 2003 Server 64 bit Edition AD Service Pack 2]]></OS>
          </HOST>
        </HOST_LIST>
      ...
      </GLOSSARY>
    </POLICY>
      <POLICY>
      <ID>14028</ID>
      <DATETIME>2013-11-16T17:09:36Z</DATETIME>
    </POLICY>
  </RESPONSE>
</POSTURE_INFO_LIST_OUTPUT>

A new release of QualysGuard, Version 7.12, will be available in production in Nov 2013.

 

Enhancements include a set of new APIs and a report related change

  • API Support for QualysGuard Express Lite Users
  • “Compliance Posture Info” API v2 - Support for retrieving batches of compliance posture info records “Compliance Control” API v2
  • “Asset IP” API v2 Enhancements - Ability to add and update IP addresses (VM and PC)
  • PC Authentication Report - Host Technology Added

 

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:

 

API Support for QualysGuard Express Lite Users

QualysGuard API now support for Express Lite users. Express Lite users have the ability to use the QualysGuard API to manage scans, assets (IP addresses and domains) and user accounts. Several APIs are available:

 

“Compliance Posture Info” API v2 - Support for retrieving batches of compliance posture info records

 

The Compliance Posture Info API v2 (with the endpoint /api/2.0/fo/compliance/posture/info/) is used to return a list of compliance posture info records for a selected policy in the user’s account.

 

The output of the Compliance Posture Info API is paginated. By default, a maximum of 5,000 posture info records are returned per request. You can customize the page size (i.e. the number of posture info records) by using the parameter:

  • “truncation_limit=10000” will be return with pages of 10,000 records.
  • “truncation_limit=0” will be return in a single page with all the records.

 

WARNING: “truncation_limit=0” can generate very large output and processing large XML files can consume a lot of resources on the client side. In this case it is recommended to use the pagination logic and parallel processing. The previous page can be processed while the next page is being downloaded.

 

API request:

 

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST" -d "action=list&echo_request=1&policy_id=13906&truncation_limit=1000"

"https://qualysapi.qualys.com//api/2.0/fo/compliance/posture/info/"

 

XML output:

 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE POSTURE_INFO_LIST_OUTPUT SYSTEM
"https://qualysapi.qualys.com/api/2.0/fo/compliance/posture/info/posture_info_list_output.dtd">
<POSTURE_INFO_LIST_OUTPUT>
<REQUEST>
...
<RESPONSE>
  <DATETIME>2013-08-06T12:28:16Z</DATETIME>
  <INFO_LIST>
<INFO> ...
  </INFO_LIST>
  <WARNING_LIST>
    <WARNING>
      <CODE>1980</CODE>
      <TEXT>1000 record limit exceeded. Use URL to get next batch of results.</TEXT>
       <URL><![CDATAhttps://qualysapi.qualys.com/api/2.0/fo/compliance/posture/info/action=list&echo_request=1&policy_id=13906&truncation_limit=1000&id_min=1958791]>          
       </URL>
  </WARNING>
</WARNING_LIST>

 

“Compliance Control” API v2 - Support for retrieving batches of compliance controls

The Compliance Control API v2 (with the endpoint /api/2.0/fo/compliance/control/) is used to return a list of compliance controls in the user’s account.

 

Customize the Page Size using “truncation_limit” parameter

The output of the Compliance Control API is paginated. By default, a maximum of 1,000 control records are returned per request. You can customize the page size (i.e. the number of control records) by using the parameter:

  • “truncation_limit=10000” will be return with pages of 10,000 records.
  • “truncation_limit=0” will be return in a single page with all the records.

 

API request:


curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST" -d "action=list&echo_request=1&truncation_limit=200&details=Basic" "https://qualysapi.qualys.com//api/2.0/fo/compliance/control/"

 

XML output:

 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE CONTROL_LIST_OUTPUT SYSTEM
"https://qualysapi.qualys.com/api/2.0/fo/compliance/control/control_list_output.dtd">
<CONTROL_LIST_OUTPUT>
  <REQUEST>
 ...
  <RESPONSE>
    <DATETIME>2013-09-09T05:57:25Z</DATETIME>
    <CONTROL_LIST>
      <CONTROL>
        <ID>1044</ID>
        <UPDATE_DATE>2012-06-08T00:00:00Z</UPDATE_DATE>
        <CREATED_DATE>2007-10-12T00:00:00Z</CREATED_DATE>
...
    </CONTROL_LIST>
    <WARNING>
      <CODE>1980</CODE>
      <TEXT>200 record limit exceeded. Use URL to get next batch of
results.</TEXT>
<URL><![CDATA[https://qualysapi.qualys.com/api/2.0/fo/compliance/control/
?action=list&echo_request=1&truncation_limit=200&details=Basic&id_min=104
6]]></URL>
    </WARNING>
  </RESPONSE>
</CONTROL_LIST_OUTPUT>

 

“Asset IP” API v2 Enhancements - Ability to add and update IP addresses

 

The “Asset IP” API v2 (with the endpoint /api/2.0/fo/asset/ip/) now gives you the ability to add IP addresses for scanning to the subscription, and update them. You can choose to add IP addresses to VM and/or PC, depending on your license.

 

For additional information on the parameters available and additional examples, please refer to the release notes or documentations.

 

Add IP(s) Example

 

API request (POSTED raw data in CSV format):

curl -H "X-Requested-With: Curl" -H "Content-Type:text/csv" -u "USERNAME:PASSWORD" --data-binary @ips_list.csv "https://qualysapi.qualys.com/api/2.0/fo/asset/ip/?action=add&enable_vm=1&enable_pc=1&tracking_method=IP&owner=quays_es1"

 

API request (“ips” parameter):

curl -H "X-Requested-With: demo" -u "USERNAME:PASSWORD" -X "POST" -d "action=add&enable_vm=1&enable_pc=1&ips=10.10.10.1,10.10.10.10-

10.10.10.20,10.10.10.200" "https://qualysapi.qualys.com/api/2.0/fo/asset/ip/"

 

XML output:

 

<?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>2013-08-07T01:21:03Z</DATETIME>
<TEXT>IPs successfully added to Vulnerability Management/Compliance Management</TEXT>
    </RESPONSE>

 

PC Authentication Report - Host Technology Added

The Policy Compliance (PC) Authentication Report tells you whether hosts scanned for compliance passed authentication. If authentication failed, we give you the reason so you can look into it.

With this release, the PC Authentication Report includes the host technology associated with each host instance - this is the compliance technology the host’s operating system is mapped to. We added a new element <HOST_TECHNOLOGY> to the XML output and updated the report DTD.

 

Updated Report DTD

The report DTD can be found at the following URL (where qualysapi.qualys.com is the API server URL where your account is located):

       https://qualysapi.qualys.com/compliance_authentication_report.dtd

The new <HOST_TECHNOLOGY> appears under the <HOST> element.

 

...

<!ELEMENT TECHNOLOGY_LIST (TECHNOLOGY*)>

<!ELEMENT TECHNOLOGY (NAME, HOST_LIST)>

<!ELEMENT HOST_LIST (HOST*)>

<!ELEMENT HOST (TRACKING_METHOD, IP, DNS?, NETBIOS?, HOST_TECHNOLOGY?,

                INSTANCE?, STATUS, CAUSE?)>

<!ELEMENT TRACKING_METHOD (#PCDATA)>

<!ELEMENT IP (#PCDATA)>

<!ELEMENT DNS (#PCDATA)>

<!ELEMENT HOST_TECHNOLOGY (#PCDATA)> <!ELEMENT NETBIOS (#PCDATA)> <!ELEMENT INSTANCE (#PCDATA)>

...

 

Sample Report XML


<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE COMPLIANCE_AUTHENTICATION_REPORT SYSTEM

"https://qualysapi.qualys.com/compliance_authentication_report.dtd">

<COMPLIANCE_AUTHENTICATION_REPORT>

...

<TECHNOLOGY_LIST>

      <TECHNOLOGY>

        <NAME><![CDATA[Unix/Cisco IOS]]></NAME>

        <HOST_LIST>

          <HOST>

            <TRACKING_METHOD><![CDATA[IP]]></TRACKING_METHOD>

            <IP><![CDATA[10.10.24.12]]></IP>

            <DNS><![CDATA[]]></DNS>

            <NETBIOS><![CDATA[]]></NETBIOS>

            <HOST_TECHNOLOGY><![CDATA[Solaris 9.x]]></HOST_TECHNOLOGY>

            <STATUS><![CDATA[Passed]]></STATUS>

           </HOST>

...           

Filter Blog

By date: By tag: