Christophe Delaure

QualysGuard 7.12 Update API Notification

Blog Post created by Christophe Delaure on Nov 25, 2013

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>

Outcomes