Justin Lute

QualysGuard® API Release Version 8.0 - 15 day notification

Blog Post created by Justin Lute on Apr 14, 2014

This update to QualysGuard 8.0 includes improvements to the QualysGuard API, allowing you to integrate your programs and API calls with QualysGuard Vulnerability Management (VM) and QualysGuard Policy Compliance (PC).

 

What’s New

 

 

 

QualysGuard API Server URL.

The QualysGuard API documentation and sample code use the API server URL for QualysGuard US Platform 1. If your account is located on another platform, please replace this URL with the appropriate server URL for your account.

 

 

Account LocationAPI Server URL for login
QualysGuard US Platform 1https://qualysapi.qualys.com
QualysGuard US Platform 2https://qualysapi.qg2.apps.qualys.com
QualysGuard EU Platformhttps://qualysapi.qualys.eu
QualysGuard Private Cloud Platformhttps://qualysapi.<customer_base_url>


 

QualysGuard API Documentation. API user guides and other documentation are available in your account’s Resources section (Help > Resources > API). Note: The service enforces limits on the API calls users can make within a subscription. See “QualysGuard API Limits” for details.

 

 


Vulnerability Management (VM)

“Security Risk Score” summary added to  XML and CSV reports

With this release vulnerability scan reports include a security risk score summary for the report and per host, in all report formats - earlier this was not in XML or  CSV. As before the risk score summary appears when your report template is configured for host based findings (automatic data) and the Text Summary option is selected. The asset_data_report.dtd was updated - we’ll show you the changes.

 

Tell me about the Security Risk Score. The score for the overall report is the average security risk for all hosts in the report. The score for each host is the average severity level detected (the default) or the highest severity level detected. Managers can configure the calculation method for the subscription by going to Reports > Setup > Security Risk. Are you an Express Lite user? If yes the average severity level is always used.

 

Sample reports. These reports were created using a scan report template configured with host based findings and Text Summary is selected (under Display > Detailed Results).

 

CSV report

New rows show you the security risk score summary for the report and per host.

8.0Image.png

 

XML report

New XML elements show you the security risk summary for the report (see  <RISK_SCORE_SUMMARY>)  and per host <see RISK_SCORE_PER_HOST>.

 

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE ASSET_DATA_REPORT SYSTEM "https://qualysguard.qualys.com/asset_data_report.dtd">
<ASSET_DATA_REPORT>
  <HEADER>
    <COMPANY><![CDATA[Qualys, Inc.]]></COMPANY>
    <USERNAME>USERNAME</USERNAME>
    <GENERATION_DATETIME>2014-03-11T23:56:22Z</GENERATION_DATETIME>
    ...
    <RISK_SCORE_SUMMARY>
      <TOTAL_VULNERABILITIES>14</TOTAL_VULNERABILITIES>
      <AVG_SECURITY_RISK>2.6</AVG_SECURITY_RISK>
      <BUSINESS_RISK>13/100</BUSINESS_RISK>
    </RISK_SCORE_SUMMARY>
  </HEADER>
<RISK_SCORE_PER_HOST>
  <HOSTS>
    <IP_ADDRESS>10.10.24.104</IP_ADDRESS>
    <TOTAL_VULNERABILITIES>4</TOTAL_VULNERABILITIES>
    <SECURITY_RISK>2.5</SECURITY_RISK>
  </HOSTS>
  <HOSTS>
    <IP_ADDRESS>10.10.24.106</IP_ADDRESS>
    <TOTAL_VULNERABILITIES>10</TOTAL_VULNERABILITIES>
    <SECURITY_RISK>2.6</SECURITY_RISK>
  </HOSTS>
</RISK_SCORE_PER_HOST>
  <HOST_LIST>
    <HOST>
      <IP>10.10.24.104</IP>
      <TRACKING_METHOD>IP</TRACKING_METHOD>
...

 

 

DTD updates

You’ll see the updated asset_data_report.dtd below.  There are new elements RISK_SCORE_PER_HOST and RISK_SCORE_SUMMARY.

 

<!-- QUALYS ASSET DATA REPORT DTD -->

<!ELEMENT ASSET_DATA_REPORT (ERROR | (HEADER, RISK_SCORE_PER_HOST?, HOST_LIST?, GLOSSARY?, APPENDICES?))>

<!ELEMENT ERROR (#PCDATA)*>
<!ATTLIST ERROR number CDATA #IMPLIED>


<!-- HEADER -->


<!ELEMENT HEADER (COMPANY, USERNAME, GENERATION_DATETIME, TEMPLATE,
                  TARGET, RISK_SCORE_SUMMARY?)>

<!ELEMENT COMPANY (#PCDATA)>
<!ELEMENT USERNAME (#PCDATA)>
<!ELEMENT GENERATION_DATETIME (#PCDATA)>
<!ELEMENT TEMPLATE (#PCDATA)>
<!ELEMENT TARGET (USER_ASSET_GROUPS?, USER_IP_LIST?, COMBINED_IP_LIST?, 
                  ASSET_TAG_LIST?)>

<!ELEMENT USER_ASSET_GROUPS (ASSET_GROUP_TITLE+)>
<!ELEMENT ASSET_GROUP_TITLE (#PCDATA)>

<!ELEMENT USER_IP_LIST (RANGE*)>
<!ELEMENT RANGE (START, END)>
<!ELEMENT START (#PCDATA)>
<!ELEMENT END (#PCDATA)>

<!ELEMENT COMBINED_IP_LIST (RANGE*)>

<!ELEMENT ASSET_TAG_LIST (INCLUDED_TAGS, EXCLUDED_TAGS?)>

<!ELEMENT INCLUDED_TAGS (ASSET_TAG*)>
<!ATTLIST INCLUDED_TAGS scope CDATA #IMPLIED>

<!ELEMENT EXCLUDED_TAGS (ASSET_TAG*)>
<!ATTLIST EXCLUDED_TAGS scope CDATA #IMPLIED>

<!-- AVERAGE RISK_SCORE_SUMMARY -->
<!ELEMENT RISK_SCORE_SUMMARY (TOTAL_VULNERABILITIES, AVG_SECURITY_RISK,
                              BUSINESS_RISK)>
<!ELEMENT TOTAL_VULNERABILITIES (#PCDATA)>
<!ELEMENT AVG_SECURITY_RISK (#PCDATA)>
<!ELEMENT BUSINESS_RISK (#PCDATA)>

<!-- RISK_SCORE_PER_HOST -->
<!ELEMENT RISK_SCORE_PER_HOST (HOSTS+)>
<!ELEMENT HOSTS (IP_ADDRESS, TOTAL_VULNERABILITIES, SECURITY_RISK)>
<!ELEMENT IP_ADDRESS (#PCDATA)>
<!ELEMENT SECURITY_RISK (#PCDATA)>

<!-- HOST_LIST -->

<!ELEMENT HOST_LIST (HOST+)>
...

 

 

Manage the EC2 Scan Workflow using the API

You can now manage the special Amazon EC2 Scan workflow in Vulnerability Management using the QualysGuard API. You’ll use the VM Scan API v2 (/api/2.0/fo/scan/) to launch EC2 scans and manage them within your account just like other vulnerability scans.

 

The Amazon EC2 Scan workflow using QualysGuard is pre-authorized by AWS. This workflow integrates with EC2 APIs, targets EC2 assets by their Instance ID, and allows scanning in Amazon EC2 Classic and EC2-VPC without the need to request pre-approval from AWS through their scan authorization request form. Want to learn more? Check out our Help Center for Amazon Web Services at the Qualys Community.

 

A few things to consider...

  • EC2 Scanning and EC2 Connector features must be enabled for your QualysGuard account.
  • Only a Manager user can launch EC2 scans.
  • You must have deployed an instance of the virtual scanner appliance using a QualysGuard appliance AMI published in AWS Marketplace.  Don’t have this? Log in to the user interface and go to VM > Scans > Appliances and select New > Virtual Scanner Appliance. When using the EC2 Scan workflow be certain to deploy the “Pre-Authorized Scanning” appliance and not the standard appliance.  Please see Choosing The Correct Scanner AMI (Amazon Machine Image) for more.
  • You need an EC2 Connector that you’ve configured using the user interface in QualysGuard Asset Management. Want to do this? Go to AM (Asset Management) > Connectors and select Actions > Create EC2 Connector. Our wizard will help you do this quickly. You’ll select EC2 hosts to scan and assign them asset tags. (Tip - When you launch an EC2 scan you’ll select EC2 host tags for the scan target.)

 

Ready to launch an EC2 scan? Here are the settings you’ll use. Many of the input parameters are also available for all vulnerability scans.

 

SettingParameters
Request

action=launch (Required)

echo_request (Optional)

Scan Titlescan_title (Optional)
EC2 environment

connector_name={value}

(Required) The name of the EC2 connector for the AWS integration you want to run the scan on.

ec2_endpoint={value}

(Required) The EC2 region code or the ID of the Virtual Private Cloud (VPC) zone. Need to find the region code? See: AWS Documentation-Region and Availability Zone Concepts

Option Profile

option_title={value} -or-

option_id={value}

(Required) The scan settings to be used for the scan, saved as an option profile.

Scanner Appliance

iscanner_name={value} -or-

iscanner_id={value}

(Required) The scanner appliance to be used for the scan.

Target Hosts

target_from={tags}

(Required) Use tags to select the EC2 hosts you want to scan.

use_ip_nt_range_tags={0}

The default setting is “0”.  Important - This cannot be set to “1” for EC2 scanning.

These tag parameters are used to select tags:

tag_set_include={tag1,tag2,...} (Required)

tag_set_exclude={tag1,tag2,...} (Optional)

tag_include_selector={any|all} (Default in bold)

tag_exclude_selector={any|all} (Default in bold)

tag_set_by={id|name} (Default in bold)

 

 

Show me a sample API request

This request will launch an EC2 vulnerability scan using the connector “EC2_Connector” on assets that match tags with IDs 1558997 and 1559222. You’ll notice the XML output uses the simple return DTD (simple_return.dtd).

 

API request

curl -H "X-Requested-With: Curl" -u "USERNAME:PASSWORD" -X "POST" -d "action=launch&scan_title=My+EC2+Scan&connector_name=EC2_Connector&ec2_endpoint=us-east-1&target_from=tags&use_ip_nt_range_tags=0&tag_include_selector=any&tag_set_by=id&tag_set_include=1558997,1559222&option_id=43165&iscanner_name=EC2-1" "https://qualysapi.qualys.com/api/2.0/fo/scan/" > outputfile.txt

 

XML output

cat outputfile.txt

 

<?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>2014-02-25T21:32:40Z</DATETIME>
    <TEXT>New vm scan launched</TEXT>
    <ITEM_LIST>
      <ITEM>
        <KEY>ID</KEY>
        <VALUE>136992</VALUE>
      </ITEM>
      <ITEM>
        <KEY>REFERENCE</KEY>
        <VALUE>scan/1358285558.36992</VALUE>
      </ITEM>
    </ITEM_LIST>
  </RESPONSE>
</SIMPLE_RETURN>

 

 

 


Policy Compliance (PC)

 

Limit Policy Reports to Selected IPs

Want your policy reports to show certain IPs only? Now you can select the IP addresses to report on each time you create a policy report. This way your report will show you compliance data for selected IPs only, instead of all IPs associated with your policy.

 

Ready to create your report? You’ll use the Report Share API (/api/2.0/fo/report/ with the parameter action=launch) to launch your policy report. Just add the “ips”input parameter and enter the IPs/ranges you want to include in your report -these IPs/ranges must be assigned to the policy you’re reporting on.

 

API request

This request launches a policy report on these IP addresses: 10.10.10.21,10.10.10.40-10.10.10.46. These IPs are assigned to policy ID 12345 and will be included in the report.

 

curl -u"USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X"POST" -d"action=launch&report_title=My+Policy+Report&policy_id=12345&output_format=xml&ips=10.10.10.21,10.10.10.40-10.10.10.46""https://qualysapi.qualys.com/api/2.0/fo/report/"

 

Compliance Scorecard Report XML - added NetBIOS name and DNS name

The Compliance Scorecard Report now lists the NetBIOS name and/or DNS name for each host listed under top hosts with changes, when this is available in your account. Be sure you’ve selected the layout option “Hosts with changes” in your report template.

 

We’ve updated the report DTD (compliance_scorecard_report.dtd) to include the new subelements NETBIOS and DNS (under HOST).

 

XML output

...
    <TOP_HOST_WITH_CHANGES>
     <TOP><![CDATA[10]]></TOP>
      <CHANGED_TO_PASS>
        <HOST>
         <IP_ADDRESS><![CDATA[10.10.10.29]]></IP_ADDRESS>
         <NETBIOS><![CDATA[XPSP3-10-29-1]]></NETBIOS>
         <DNS><![CDATA[xpsp3-10-29-1.corp10.com]]></DNS>
         <ASSET_GROUP_NAME><![CDATA[ComplianceHosts]]></ASSET_GROUP_NAME>
          <TECHNOLOGY>Windows XPdesktop</TECHNOLOGY>
         <NUMBER_OF_POLICIES>1</NUMBER_OF_POLICIES>
         <PASSED_TOTAL>12</PASSED_TOTAL>
         <PASSED_CHANGED>12</PASSED_CHANGED>
         <COMPLIANCE>100%</COMPLIANCE>
        </HOST>
      </CHANGED_TO_PASS>
      <CHANGED_TO_FAIL>
        <HOST>
         <IP_ADDRESS><![CDATA[10.10.10.29]]></IP_ADDRESS>
          <NETBIOS><![CDATA[XPSP3-10-29-1]]></NETBIOS>
         <DNS><![CDATA[xpsp3-10-29-1.corp123.com]]></DNS>
     ...       </HOST>
      </CHANGED_TO_FAIL>
...

 

DTD update

...
<!ELEMENT HOST(IP_ADDRESS, NETBIOS,DNS,NETWORK?, ASSET_GROUP_NAME?, ASSET_TAG_NAME?, TECHNOLOGY, NUMBER_OF_POLICIES,PASSED_TOTAL?, PASSED_CHANGED?, FAILED_TOTAL?, FAILED_CHANGED?, ERROR_TOTAL?,ERROR_CHANGED?, COMPLIANCE)>
...
<!ELEMENT NETBIOS (#PCDATA)>
<!ELEMENT DNS (#PCDATA)>

 

 

Policy XML updated to remove control checksum requirement

Now it’s possible to manually import policies without the requirement to have a checksum for control configurations. We’ve updated the XML output of the EVALUATE element. We’ll use the new XML output without the checksum when you export policies. No changes were made to the policy export output DTD (https://<baseurl>/api/2.0/fo/compliance/policy/policy_export_output.dtd).


Tell me about the changes

In previous releases the EVALUATE element included the checksum attribute and the content was text, like this:

 

<EVALUATEchecksum="3982342715fb297713b21d2baee13649e36f8f42cde75a2dbaf521b2ce584674">&lt;CTRL&gt;&lt;DP&gt;&lt;K&gt;ap00.system.cgi.scriptalias&lt;/K&gt;&lt;CD&gt;matches&lt;/CD&gt;&lt;OP&gt;xre&lt;/OP&gt;&lt;V&gt;&lt;![CDATA[.*]]&gt;&lt;/V&gt;&lt;FVset=&quot;1&quot;&gt;161803399999999&lt;/FV&gt;&lt;FVset=&quot;1&quot;&gt;314159265358979&lt;/FV&gt;&lt;/DP&gt;&lt;/CTRL&gt;</EVALUATE>

 

With this release the EVALUATE element does not include the checksum and the content isXML (not text), like this:

 

<EVALUATE>
    <CTRL><DP><K>ap00.system.cgi.scriptalias</K><CD>matches</CD><OP>xre</OP><V><![CDATA[.*]]></V><FVset="1">161803399999999</FV><FV set="1">314159265358979</FV></DP></CTRL>
</EVALUATE>

 

Can I still import policy XML with the checksum?

Yes, you can still do this - no problem.  Remember if you export your policy we’ll use the new XML output and the checksum attribute will be removed.

 

 

Posture Info API improvements

We’ve made improvements to the XML output of the Compliance Posture Info API v2 (resource/api/2.0/fo/compliance/posture/info/ with action=list). This gives you more details about the controls evaluated on your hosts and their posture. A new summary section tells you more about the control instances (posture info records) like the number of assets, controls and control instances evaluated.  We also report the percentage of controls that passed for each host.

 

Want to see the new details?  Be sure to specify the parameter details=All.  We’ve added more content to the XML output and the posture_info_list_output.dtd has been updated.

 

API request

curl -u"USERNAME:PASSWORD" -H "X-Requested-With: Curl" -d "action=list&policy_ids=10649&details=All&asset_group_ids=423117,423147""https://qualysapi.qualys.com/api/2.0/fo/compliance/posture/info/"

 

XML output

<?xmlversion="1.0" encoding="UTF-8" ?>
<!DOCTYPEPOSTURE_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>2014-04-09T05:00:46Z</DATETIME>
    <POLICY>
    <ID>10649</ID>
   <DATETIME>2014-04-09T05:00:46Z</DATETIME>
    <INFO_LIST>
      <INFO>
        <ID>1794005</ID>
        <HOST_ID>2154769</HOST_ID>
       <CONTROL_ID>1061</CONTROL_ID>
       <TECHNOLOGY_ID>6</TECHNOLOGY_ID>
        <INSTANCE></INSTANCE>
        <STATUS>Passed</STATUS>
        <EVIDENCE>
          <BOOLEAN_EXPR><![CDATA[:dp_1match_all $tp_1]]></BOOLEAN_EXPR>
          <DPV_LIST>
            <DPVlastUpdated="2014-02-09T23:30:35Z">
              <LABEL>:dp_1</LABEL>
             <V><![CDATA[161803399999999]]></V>
              <TM_REF>@tm_1</TM_REF>
            </DPV>
          </DPV_LIST>
        </EVIDENCE>
      </INFO>
      <INFO>
        <ID>1794006</ID>
        <HOST_ID>2154769</HOST_ID>
       <CONTROL_ID>1071</CONTROL_ID>
       <TECHNOLOGY_ID>6</TECHNOLOGY_ID>
        <INSTANCE></INSTANCE>
        <STATUS>Passed</STATUS>
        <EVIDENCE>
         <BOOLEAN_EXPR><![CDATA[(:dp_2 in #fv_1 or :dp_2 >= $tp_2)]]></BOOLEAN_EXPR>
          <DPV_LIST>
            <DPVlastUpdated="2014-02-09T23:30:35Z">
              <LABEL>:dp_2</LABEL>
             <V><![CDATA[0]]></V>
            </DPV>
          </DPV_LIST>
        </EVIDENCE>
      </INFO>
...
    </INFO_LIST>
    <SUMMARY>
     <TOTAL_ASSETS>1</TOTAL_ASSETS>
     <TOTAL_CONTROLS>199</TOTAL_CONTROLS>
      <CONTROL_INSTANCES>
       <TOTAL>98</TOTAL>
       <TOTAL_PASSED>84</TOTAL_PASSED>
       <TOTAL_FAILED>14</TOTAL_FAILED>
       <TOTAL_ERROR>0</TOTAL_ERROR>
       <TOTAL_EXCEPTIONS>0</TOTAL_EXCEPTIONS>
      </CONTROL_INSTANCES>
    </SUMMARY>
    <GLOSSARY>
      <HOST_LIST>
        <HOST>
          <ID>2154769</ID>
          <IP>10.10.10.34</IP>
         <TRACKING_METHOD>IP</TRACKING_METHOD>
         <DNS><![CDATA[aix-53-10-34.vuln.qa.qualys.com]]></DNS>
          <OS><![CDATA[AIX5.3]]></OS>
          <LAST_VULN_SCAN_DATETIME>2014-01-19T17:49:27Z</LAST_VULN_SCAN_DATETIME>
         <LAST_COMPLIANCE_SCAN_DATETIME>2014-02-09T23:30:35Z</LAST_COMPLIANCE_SCAN_DATETIME>
          <PERCENTAGE><![CDATA[85.71% (84 of98)]]></PERCENTAGE>
        </HOST>
      </HOST_LIST>
      <CONTROL_LIST>
        <CONTROL>
          <ID>1061</ID>
          <STATEMENT><![CDATA[Statusof the existence of plus sign or '+' entries in the host's password-relatedfiles]]></STATEMENT>
...
    </GLOSSARY>
  </POLICY>
  </RESPONSE>
</POSTURE_INFO_LIST_OUTPUT>

 

DTD updates

1) The new SUMMARY subelement gives details for the request (in RESPONSE) and per policy (in POLICY). The summary tells you statistics about the control instances (posture info records) returned in the XML output including the total number of: assets, controls and control instances.  For control instances you’ll find the total number of: instances, instances having the status passed, failed and error, plus the instance defined as exceptions.

 

2) The new PERCENTAGE subelement (in HOST) tells you you the percentage of controls having the status passed. For example “85.71% (84 of 98)” mean 85.71% of the controls passed, 84 controls passed and 98 controls were evaluated.

 

...
<!ELEMENT RESPONSE(DATETIME, ((INFO_LIST?, SUMMARY?, WARNING_LIST?, GLOSSARY?) | POLICY+))>

<!ELEMENT POLICY(ID, DATETIME, INFO_LIST?, SUMMARY?, WARNING_LIST?, GLOSSARY?)>
...
<!ELEMENT HOST_LIST(HOST+)>
<!ELEMENT HOST (ID,IP, TRACKING_METHOD, DNS?, NETBIOS?, OS?, OS_CPE?,
                  LAST_VULN_SCAN_DATETIME?,LAST_COMPLIANCE_SCAN_DATETIME?, 
                PERCENTAGE?)>
...
<!ELEMENTPERCENTAGE (#PCDATA)>
...
<!ELEMENT SUMMARY(TOTAL_ASSETS, TOTAL_CONTROLS, CONTROL_INSTANCES)>
<!ELEMENT TOTAL_ASSETS(#PCDATA)>
<!ELEMENTTOTAL_CONTROLS (#PCDATA)>
<!ELEMENTCONTROL_INSTANCES (TOTAL, TOTAL_PASSED, TOTAL_FAILED,
                             TOTAL_ERROR,TOTAL_EXCEPTIONS)>
<!ELEMENT TOTAL(#PCDATA)>
<!ELEMENTTOTAL_PASSED (#PCDATA)>
<!ELEMENTTOTAL_FAILED (#PCDATA)>
<!ELEMENTTOTAL_ERROR (#PCDATA)>
<!ELEMENTTOTAL_EXCEPTIONS (#PCDATA)>

 

 

 


Vulnerability Management (VM) and Policy Compliance (PC)

 

Select Multiple Scanner Appliances for Scans

With this release you can select multiple scanner appliances for your internal vulnerability and compliance scans. This is especially useful when scanning a large number of hosts because it allows you to distribute the scan task across scanner appliances.

 

How do I launch a scan? For a vulnerability scan, use the VM Scan API v2 (resource/api/2.0/fo/scan/ with action=launch). For a compliance scan use PC Scan API v2 (resource /api/2.0/fo/scan/compliance/ with action=launch).

 

Want to select multiple appliances? Simply tell us the appliance IDs or friendly names when making your launch scan request.

 

Parameter

Description

iscanner_id={value}

 

(Optional)  The IDs of the scanner appliances to be used. Multiple entries are comma  separated.


These  parameters are mutually exclusive and cannot be specified in the same  request: iscanner_id and iscanner_name.

iscanner_name={value}

 

(Optional)  The friendly names of the scanner appliances to be used. Multiple entries are  comma separated.

These  parameters are mutually exclusive and cannot be specified in the same  request: iscanner_id and iscanner_name.

 

 

A few notes...

  • One of these parameters must be specified in a request for an internal scan: iscanner_name, iscanner_id, default_scanner, scanners_in_ag. (Note: The parameters default_scanner and scanners_in_ag have not changed. Refer to the API v2 User Guide for details on these parameters.)
  • For an Express Lite user, Internal Scanning must be enabled in the user’s account.

 

Show me a sample API request  This request will launch a vulnerability scan on the IP address range 10.10.10.2-10.10.10.255 using these scanner appliances:scanner1, scanner2 and scanner3. You’ll notice the XML output uses the simple return DTD (simple_return.dtd).

 

API request

curl -H"X-Requested-With: Curl" -u "USERNAME:PASSWORD" -X"POST" -d 
"action=launch&scan_title=My+Vulnerability+Scan&ip=10.10.10.2-10.10.10.255&option_id=43165&iscanner_name=scanner1,scanner2,scanner3""https://qualysapi.qualys.com/api/2.0/fo/scan/"

 

XML output

<?xmlversion="1.0" encoding="UTF-8" ?>
<!DOCTYPESIMPLE_RETURN SYSTEM "https://qualysapi.qualys.com/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
  <RESPONSE>
   <DATETIME>2014-02-26T21:32:40Z</DATETIME>
    <TEXT>New vm scanlaunched</TEXT>
    <ITEM_LIST>
      <ITEM>
        <KEY>ID</KEY>
        <VALUE>136992</VALUE>
      </ITEM>
      <ITEM>
        <KEY>REFERENCE</KEY>
       <VALUE>scan/1358285558.36992</VALUE>
      </ITEM>
    </ITEM_LIST>
  </RESPONSE>
</SIMPLE_RETURN>

 

 

Launch Reports using Asset Tags

We’ve made it easier for you to launch reports by selecting asset tags for the hosts you want to report on using the Report Share API (/api/2.0/fo/report/ with action=launch). It’s possible to select asset tags for both vulnerability and compliance reports. Use the following tag parameters:

 

Parameter

Description

use_tags={0|1}

 

(Optional)  Specify “1” when your report target will include asset tags. Specify “0” (the  default) when your report target will include IP addreses/ranges and/or asset  groups. When not specified, use_tags=0 is used.

 

tag_include_selector=

{all|any}

 

(Optional)  Specify “any” (the default) to include hosts that match at least one of the  selected tags. Specify “all” to include hosts that match all of the selected  tags.

 

tag_include_selector  is valid only when use_tags=1 is specified.

 

tag_exclude_selector=

{all|any}

 

(Optional)  Specify “any” (the default) to exclude hosts that match at least one of the  selected tags. Specify “all” to exclude hosts that match all of the selected  tags.

 

tag_exclude_selector  is valid only when use_tags=1 is specified.

 

tag_set_by={id|name}

 

(Optional)  Specify “id” (the default) to select a tag set by providing tag IDs. Specify  “name” to select a tag set by providing tag names.

 

tag_set_by  is valid only when use_tags=1 is specified.

 

tag_set_include={value}

 

(Optional)  Specify a tag set to include. Hosts that match these tags will be included.  You identify the tag set by providing tag name or IDs. Multiple entries are  comma separated.

 

tag_set_include  is valid only when use_tags=1 is specified.

 

tag_set_exclude={value}

 

(Optional)  Specify a tag set to exclude. Hosts that match these tags will be excluded.  You identify the tag set by providing tag name or IDs. Multiple entries are  comma separated.

 

tag_set_exclude  is valid only when use_tags=1 is specified.

 

 

API request

This request launches a report on hosts with the asset tag Windows. The XML output uses the simple return DTD (simple_return.dtd).

 

curl -u"USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X"POST" -d"action=launch&template_id=55469&report_title=My+Windows+Report&output_format=pdf&use_tags=1&tag_set_by=name&tag_set_include=Windows"
"https://qualysapi.qualys.com/api/2.0/fo/report/"

 

 

XML output

<?xmlversion="1.0" encoding="UTF-8" ?>
<!DOCTYPE GENERICSYSTEM "https://qualysapi.qualys.com/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
  <RESPONSE>
   <DATETIME>2014-02-20T21:45:23Z</DATETIME>
    <TEXT>New reportlaunched</TEXT>
    <ITEM_LIST>
      <ITEM>
        <KEY>ID</KEY>
        <VALUE>1665</VALUE>
      </ITEM>
    </ITEM_LIST>
  </RESPONSE>
</SIMPLE_RETURN>

 

 


QualysGuard Cloud Platform

 

Manage your Virtual Scanners using the API

The Scanner Appliance API v2 (/api/2.0/fo/appliance) includes multiple updates to help you manage all your scanner appliances - both physical and virtual. We’ve updated the list action to return all appliances in your account and you can filter the list by friendly name and appliance IDs. New actions allow Managers and Unit Managers to create, update and delete virtual scanners.

 

Tell me about Permissions. Managers can perform all actions on all virtual scanners(list, create, update, delete). Unit Managers can perform all actions on virtual scanners in their business unit. Scanners and Readers can list virtual scanners assigned to their accounts.

 

List all your Scanner Appliances - physical and virtual

Use the parameter action=list to return a list of scanner appliances in your account,as in previous releases. Now your virtual scanner appliances will be included.  We’ve added these new parameters:

 

Parameter

 

Description

 

name={string}

 

(Optional)  List only scanner appliances (physical and virtual) that have names matching  the string provided. Tip - Substring match is supported. For example, if you  have 2 appliances named “myscanner” and “anotherscanner” and you supply the  string “name=scan” both appliance both appliances will be returned in the XML  output.

 

ids={id1,id2,..}

 

(Optional)  List only scanner appliances (physical and virtual) that have certain IDs.  Multiple IDs are comma separated.

 

include_license_info={0|1}

 

(Optional)  Set to 1 to return virtual scanner license information in the XML output.  This tells you the number of licenses you have and the number used. This  information is not returned by default. When specified the XML output will  include the LICENSE_INFO element.

 

 

API request

curl -u"USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X"POST" -d "action=list&echo_request=1&ids=777,1127,1131&include_license_info=1" "https://qualysapi.qualys.com/api/2.0/fo/appliance/"


 

XML output

<?xmlversion="1.0" encoding="UTF-8" ?>
<!DOCTYPEAPPLIANCE_LIST_OUTPUT SYSTEM 
"https://qualysapi.qualys.com/api/2.0/fo/appliance/appliance_list_output.dtd">
<APPLIANCE_LIST_OUTPUT>
    <RESPONSE>
       <DATETIME>2014-01-02T09:26:01Z</DATETIME>
        <APPLIANCE_LIST>
            <APPLIANCE>
                <ID>777</ID>
               <NAME>scanner1</NAME>
                <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>
               <RUNNING_SCAN_COUNT>0</RUNNING_SCAN_COUNT>
               <STATUS>Online</STATUS>
            </APPLIANCE>
            <APPLIANCE>
                <ID>1127</ID>
               <NAME>scanner2</NAME>
               <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>
               <RUNNING_SCAN_COUNT>0</RUNNING_SCAN_COUNT>
               <STATUS>Online</STATUS>
            </APPLIANCE>
            <APPLIANCE>
                <ID>1131</ID>
               <NAME>scanner3</NAME>
               <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>
               <RUNNING_SCAN_COUNT>0</RUNNING_SCAN_COUNT>
               <STATUS>Offline</STATUS>
            </APPLIANCE>
        </APPLIANCE_LIST>
        <LICENSE_INFO>
           <QVSA_LICENSES_COUNT>10</QVSA_LICENSES_COUNT>
           <QVSA_LICENSES_USED>3</QVSA_LICENSES_USED>
        </LICENSE_INFO>
    </RESPONSE>
</APPLIANCE_LIST_OUTPUT>

 

DTD update:

<!-- QUALYSAPPLIANCE_LIST_OUTPUT DTD -->
<!ELEMENTAPPLIANCE_LIST_OUTPUT (REQUEST?,RESPONSE)>

<!ELEMENT REQUEST(DATETIME, USER_LOGIN, RESOURCE, PARAM_LIST?,
                   POST_DATA?)>
...
<!ELEMENT RESPONSE(DATETIME, APPLIANCE_LIST?, LICENSE_INFO?)>
...
<!ELEMENT LICENSE_INFO (QVSA_LICENSES_COUNT, QVSA_LICENSES_USED)>
<!ELEMENT QVSA_LICENSES_COUNT (#PCDATA)>
<!ELEMENT QVSA_LICENSES_USED (#PCDATA)>

 

 

Add New Virtual Scanner

Use these parameters:

 

Parameter

Description

action=create

 

(Required)  The POST method must be used.

 

name={string}

 

(Required)  The friendly name. This name can’t already be assigned to an appliance in  your account. It can be a maximum of 15 characters, spaces are not allowed.

 

polling_interval={value}

 

(Optional)  The polling interval, in seconds. A valid value is 60 to 3600 (we recommend  180 which is the default). This is the frequency that the virtual scanner  will attempt to connect to our Cloud Security Platform. The appliance calls  home to provide health updates/heartbeats to the platform, to get software  updates from the platform, to learn if new scan jobs have been requested by  users, and to upload scan results data to the platform, if applicable.

 

 

API request

curl -u"USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X"POST" -d "action=create&echo_request=1&name=scanner1" "https://qualysapi.qualys.com/api/2.0/fo/appliance/"

 

 

XML output

<?xmlversion="1.0" encoding="UTF-8" ?>
<!DOCTYPEAPPLIANCE_LIST_OUTPUT SYSTEM 
"https://qualysapi.qualys.com/api/2.0/fo/appliance/appliance_create_output.dtd">
<APPLIANCE_CREATE_OUTPUT>
    <RESPONSE>
       <DATETIME>2014-01-02T09:26:01Z</DATETIME>
        <ID>777</ID>
        <NAME>scanner1</NAME>
        <ACTIVATION CODE>ACTIVATION-CODE</ACTIVATIONCODE>
       <REMAINING_QVSA_LICENSES>4</REMAINING_QVSA_LICENSES>
    </RESPONSE>
</APPLIANCE_CREATE_OUTPUT>

 

New DTD:

<!-- QUALYSAPPLIANCE_CREATE_OUTPUT DTD -->
<!ELEMENTAPPLIANCE_CREATE_OUTPUT (REQUEST?,RESPONSE)>

<!ELEMENT REQUEST(DATETIME, USER_LOGIN, RESOURCE, PARAM_LIST?,
                   POST_DATA?)>
<!ELEMENT DATETIME(#PCDATA)>
<!ELEMENTUSER_LOGIN (#PCDATA)>
<!ELEMENT RESOURCE(#PCDATA)>
<!ELEMENTPARAM_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, APPLIANCE)>

<!ELEMENT APPLIANCE(ID, FRIENDLY_NAME, ACTIVATION_CODE,
                     REMAINING_QVSA_LICENSES)>
<!ELEMENT ID(#PCDATA)>
<!ELEMENTFRIENDLY_NAME (#PCDATA)>
<!ELEMENTACTIVATION_CODE (#PCDATA)>
<!ELEMENTREMAINING_QVSA_LICENSES (#PCDATA)>

 

 

Update a Virtual Scanner

Use these parameters:

 

Parameter

Description

action=update

 

(Required)  The POST method must be used.

 

id={id}

 

(Required)  A valid ID of a virtual scanner.

 

name={string}

 

(Optional)  The friendly name. This name can’t already be assigned to an appliance in  your account.  It can be a maximum of  15 characters, spaces are not allowed.

 

polling_interval={value}

 

(Optional)  The polling interval, in seconds. A valid value is 60 to 3600 (we recommend  180 which is the default). This is the frequency that the virtual scanner  will attempt to connect to our Cloud Security Platform. The appliance calls  home to provide health updates/heartbeats to the platform, to get software  updates from the platform, to learn if new scan jobs have been requested by  users, and to upload scan results data to the platform, if applicable.

 

comment={value}

 

(Optional)  User-defined comments.

 

 

API request

 

curl -u"USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X"POST" -d "action=update&echo_request=1&id=12345&name=scanner15" "https://qualysapi.qualys.com/api/2.0/fo/appliance/"

 

 

XML output

The XML output uses the simple return (/api/2.0/simple_return.dtd).

 

<?xmlversion="1.0" encoding="UTF-8" ?>
<!DOCTYPESIMPLE_RETURN SYSTEM "https://qualysapi.qualys.com/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
    <RESPONSE>
       <DATETIME>2014-04-03T12:12:45Z</DATETIME>
        <TEXT>Virtual scanner updatedsuccessfully</TEXT>
        <ITEM_LIST>
            <ITEM>
                <KEY>ID</KEY>
               <VALUE>17110</VALUE>
            </ITEM>
        </ITEM_LIST>
    </RESPONSE>
</SIMPLE_RETURN>

 

 

Delete a Virtual Scanner

Deleting a virtual scanner appliance results in these actions: 1) The virtual scanner will be removed from associated Asset Groups, and 2) Scheduled Scans using this virtual scanner will be deactivated.

 

Is your virtual scanner running scans? If yes it’s not possible to delete it. We recommend you check to be sure the virtual scanner you want to delete is not running scans.

 

Use these parameters:

 

Parameter

Description

action=delete

 

(Required)  The POST method must be used.

 

id={id}

 

(Required)  A valid ID of a virtual scanner.

 

 

 

API request

 

curl -u"USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X"POST" -d "action=delete&echo_request=1&id=12345" "https://qualysapi.qualys.com/api/2.0/fo/appliance/"

 

 

XML output

The XML output uses the simple return (/api/2.0/simple_return.dtd). If schedules and/or asset groups were impacted we’ll list them so you can update them as needed.

 

<?xmlversion="1.0" encoding="UTF-8" ?>
<!DOCTYPEAPPLIANCE_LIST_OUTPUT SYSTEM 
"https://qualysapi.qualys.com/api/2.0/fo/simple_return.dtd">
<SIMPLE_RETURN>
    <RESPONSE>
       <DATETIME>2014-01-02T09:26:01Z</DATETIME>
        <TEXT>Virtual scanner deletedsuccessfully</ID>
        <ITEM_LIST>
             <ITEM>
                  <KEY>ID<KEY>
                  <VALUE>115<VALUE>
             </ITEM>
             <ITEM>
                 <KEY>DEACTIVATED_SCHEDULED_SCANS<KEY>
                 <VALUE>None<VALUE>
             </ITEM>
             <ITEM>
                 <KEY>AFFECTED_ASSET_GROUPS<KEY>
                 <VALUE>None<VALUE>
             </ITEM>
        <ITEM_LIST>
    </RESPONSE>
</SIMPLE_RETURN>

 

Network (Overlapping IP) Support

We’ve made several improvements and updates to the Network Support API for customers who have this feature turned on in their accounts. For users who do not have this feature, these changes have no impact - new input parameters are not available, and changes to DTDs and XML output are not visible.

 

Set Up Networks

 

Scanner Appliance List API v2 - filter by network ID

The Scanner Appliance List API v2 (resource /api/2.0/fo/appliance/ with action=list) returns scanner appliances in your account. Now you can use the new input parameter “network_id” (optional) to return a list of scanner appliances for a certain network. Specify 0 for the Global Default Network or a custom network ID.

 

API request

curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" "https://qualysapi.qualys.com/api/2.0/fo/appliance/?action=list&network_id=1002"

 


 

XML output

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE APPLIANCE_LIST_OUTPUT SYSTEM
"https://qualysapi.qualys.com/api/2.0/fo/appliance/appliance_list_output.dtd">
<APPLIANCE_LIST_OUTPUT>
  <RESPONSE>
    <DATETIME>2014-04-01T05:42:29Z</DATETIME>
    <APPLIANCE_LIST>
      <APPLIANCE>
        <ID>15242</ID>
        <NAME>vscanner1</NAME>
        <NETWORK_ID>1002</NETWORK_ID>
        <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>
        <RUNNING_SCAN_COUNT>0</RUNNING_SCAN_COUNT>
        <STATUS>Offline</STATUS>
      </APPLIANCE>
      <APPLIANCE>
        <ID>15235</ID>
        <NAME>vscanner2</NAME>
        <NETWORK_ID>1002</NETWORK_ID>
        <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>
        <RUNNING_SCAN_COUNT>1</RUNNING_SCAN_COUNT>
        <STATUS>Online</STATUS>
      </APPLIANCE>
    </APPLIANCE_LIST>
  </RESPONSE>
</APPLIANCE_LIST_OUTPUT>

 

 

Organize Assets by Network

 

Asset Group List API v1 - network ID added to group’s IPs / domains

The Asset Group List API v1 (/msp/asset_group_list.php) is used to retrieve a list of asset groups in your account. We added a new attribute “network_id” to the subelements /SCANIPS/IP and MAPDOMAINS/DOMAIN in the XML output (asset_group_list.dtd). This appears for an All asset group that is not the same as the subscription’s All asset group.

 

Have multiple All asset groups? Yes you might. There is always 1 All asset group for the subscription - this includes all assets, visible to Managers. If you have business units, there is 1 unique All asset group for each business unit. If you have Scanners and/or Readers, there is 1 unique All asset group for each Scanner/Reader account. (There is no All asset group for a network.)

 

XML output

Sample XML output showing an All asset group that is not the subscription’s All asset group:

 

...
<ASSET_GROUP>
  <ID>5010</ID>
  <TITLE><![CDATA[All]]></TITLE>
  <SCANIPS>
    <IP network_id="0"> 10.0.0.0-10.10.10.11</IP>
    <IP network_id="0"> 10.10.10.13-10.10.10.247</IP>
    <IP network_id="1193"> 10.0.0.0-10.10.10.11</IP>
    <IP network_id="1193"> 10.10.10.13-10.10.10.247</IP>
...
  <MAPDOMAINS>
    <DOMAIN network_id="0">qualys-test.com</DOMAIN>
    <DOMAIN network_id="0" netblock="10.10.10.10, 10.10.10.17">mydomain1.com</DOMAIN>
    <DOMAIN network_id="1193">qualys-test.com</DOMAIN>
  </MAPDOMAINS>
...

 

DTD update

New “network_id” attribute added to the subelements /IP and /DOMAIN.

 

...
<!ELEMENT IP (#PCDATA)>
<!ATTLIST IP network_id CDATA "0">
...
<!ATTLIST DOMAIN
          netblock CDATA #IMPLIED
          network_id CDATA "0"
...

 

 

Asset Inventory

 

Support for IP List API v2

The IP List API v2 (resource /api/2.0/fo/asset/ip/ with action=list) is used to retrieve a list of IP addresses in your account. Use the new input parameter “network_id” (optional) to return a list of IPs for a certain network.

 

The XML output now lists the network ID for each IP address/range when the request is made by a sub-user with access to multiple networks. We added a new attribute “network_id” to the subelements /IP_SET/IP and /IP_SET/IP_RANGE in the XML output (ip_list_output.dtd).

 

Good to know:

 

  • Managers will not see the “network_id” attribute for any IP or IP_RANGE elements in the output since Managers can see all IPs for all networks.
  • Any sub-user with access to only a single network (the Global Default Network or a custom network) will not see the “network_id” attribute either. This is for consistency with the UI, where these users do not see the network workflows.

 

XML output

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE IP_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/asset/ip/ip_list_output.dtd">
<IP_LIST_OUTPUT>
  <RESPONSE>
    <DATETIME>2014-02-14T22:47:32Z</DATETIME>
    <IP_SET>
      <IP_RANGE network_id="0">1.0.0.0-10.10.10.14</IP_RANGE>
      <IP_RANGE network_id="0">10.10.10.17-10.10.10.29</IP_RANGE>
      <IP network_id="0">10.10.10.32</IP>
    </IP_SET>
  </RESPONSE>
</IP_LIST_OUTPUT>

 

 

DTD updates

New “network_id” attribute added to the subelements /IP_SET/IP and /IP_SET/IP_RANGE.

 

...
<!ELEMENT IP_SET ((IP|IP_RANGE)+)>
<!ELEMENT IP (#PCDATA)>
<!ATTLIST IP
  network_id  CDATA  "0"
>
<!ELEMENT IP_RANGE (#PCDATA)>
<!ATTLIST IP_RANGE
  network_id  CDATA  "0"
>
...

 

 

Support for Excluded IP List API v2

The Excluded IP List API v2 (/api/2.0/fo/asset/excluded_ip/ with action=list) returns a list of excluded hosts.

Use the new input parameter “network_id” (optional) to return a list of excluded IPs for a certain network.

The XML output now identifies the network ID for each IP address/range when your subscription has at least 1 network defined. We added a new attribute “network_id” to the subelements /IP_SET/IP and /IP_SET/IP_RANGE in the XML output (ip_list_output.dtd).

 

XML output

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE IP_LIST_OUTPUT SYSTEM "https://qualysapi.qualys.com/api/2.0/fo/asset/excluded_ip/ip_list_output.dtd">
<IP_LIST_OUTPUT>
  <RESPONSE>
    <DATETIME>2014-03-20T20:49:19Z</DATETIME>
    <IP_SET>
      <IP network_id="0">10.10.10.19</IP>
      <IP_RANGE network_id="1275">10.10.50.6-10.10.50.10</IP_RANGE>
    </IP_SET>
  </RESPONSE>
</IP_LIST_OUTPUT>

 

 

DTD updates

New “network_id” attribute added to the subelements /IP_SET/IP and /IP_SET/IP_RANGE.

 

...
<!ELEMENT IP_SET ((IP|IP_RANGE)+)>
<!ELEMENT IP (#PCDATA)>
<!ATTLIST IP
  network_id  CDATA  "0"
>
<!ELEMENT IP_RANGE (#PCDATA)>
<!ATTLIST IP_RANGE
  network_id  CDATA  "0"
>
...

 

Support for Excluded IP Change History API v2

The excluded IP change history V2 API (/api/2.0/fo/asset/excluded_ip/history/ with action=list) returns a change history for excluded hosts.

Use the new input parameter “network_id” (optional) to return a list of change history for excluded hosts for a certain network.

The XML output now identifies the network ID for each IP address/range when your subscription has at least 1 network defined. We added a new attribute “network_id” to the subelements /IP_SET/IP and /IP_SET/IP_RANGE in the XML output (history_list_output.dtd).

 

XML output

...
<HISTORY_LIST>
      <HISTORY>
        <ID>1441</ID>
        <IP_SET>
          <IP_RANGE network_id="0">10.10.10.234-10.10.10.235</IP_RANGE>
        </IP_SET>
        <ACTION>Added</ACTION>
...

 

DTD updates

New “network_id” attribute added to the subelements /IP_SET/IP and /IP_SET/IP_RANGE.

 

...
<!ELEMENT IP_SET ((IP|IP_RANGE)+)>
<!ELEMENT IP (#PCDATA)>
<!ATTLIST IP
    network_id  CDATA  "0"
...
<!ELEMENT IP_RANGE (#PCDATA)>
<!ATTLIST IP_RANGE
    network_id  CDATA  "0"
...

 

 

Scan Configuration

 

Support for IPv6 List API v2

The IPv6 List API v2 (resource /api/2.0/fo/asset/ip/v4_v6/ with action=list) is used to view a list of IPv6 mapping records in your account. The XML output now identifies the network ID for each IPv6 mapping when the user’s account has more than 1 network. We added a new NETWORK_ID element to the XML output (ip_map_list_output.dtd).

 

XML output

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE IP_MAP_LIST_OUTPUT SYSTEM
"https://qualysapi.qualys.com/api/2.0/fo/asset/ip/v4_v6/ip_map_list_output.dtd">
<IP_MAP_LIST_OUTPUT>
<RESPONSE>
   <DATETIME>2014-03-27T19:42:10Z</DATETIME>
   <IP_MAP_LIST>
     <IP_MAP>
       <ID>46947</ID>
       <V4>0.0.0.7</V4>
       <V6>2001:db8:85a3::8a2e:370:84</V6>
       <NETWORK_ID>1234</NETWORK_ID>
     </IP_MAP>
     <IP_MAP>
       <ID>47036</ID>
       <V4>0.0.0.1</V4>
       <V6>2001:db8:85a3::8a2e:370:77</V6>
       <NETWORK_ID>0</NETWORK_ID>
     </IP_MAP>
   </IP_MAP_LIST>
</RESPONSE>
</IP_MAP_LIST_OUTPUT>

 

 

 

DTD update

 

New NETWORK_ID subelement added for the subelement /IP_MAP.

 

...
<!ELEMENT RESPONSE (DATETIME, IP_MAP_LIST?, WARNING?)>


<!ELEMENT IP_MAP_LIST (IP_MAP+)>
<!ELEMENT IP_MAP (ID, V4, V6, NETWORK_ID?)>
<!ELEMENT ID (#PCDATA)>
<!ELEMENT V4 (#PCDATA)>
<!ELEMENT V6 (#PCDATA)>
<!ELEMENT NETWORK (#PCDATA)>
<!ELEMENT NETWORK_ID (#PCDATA)>

 

 

Support for Authentication Record List by Type

The Authentication Record List by Type API v2 (resource /api/2.0/fo/auth/<type>/ with action=list) is used to view a list of authentication records visible to the user for a specific authentication type (Unix, VMware, Windows etc).

 

The XML output now identifies the network ID for each record when the user’s account has more than 1 network. We added a new NETWORK_ID subelement for AUTH_<type> subelements (like AUTH_UNIX, AUTH_WINDOWS, AUTH_VMWARE, etc). 12 DTDs were updated.

 

 

XML output (Unix Record List)

 

<AUTH_UNIX_LIST_OUTPUT>
  <RESPONSE>
    <DATETIME>2014-03-27T13:32:17Z</DATETIME>
    <AUTH_UNIX_LIST>
      <AUTH_UNIX>
        <ID>678</ID>
        <TITLE><![CDATA[My Unix Record]]></TITLE>
        <USERNAME><![CDATA[username]]></USERNAME>
        <ROOT_TOOL>Sudo</ROOT_TOOL>
        <CLEARTEXT_PASSWORD>0</CLEARTEXT_PASSWORD>
        <IP_SET>
          <IP_RANGE>10.10.10.168-10.10.10.195</IP_RANGE>
        </IP_SET>
        <NETWORK_ID>0</NETWORK_ID>
        <CREATED>
            <DATETIME>2014-02-20T01:01:01</DATETIME>
            <BY>username</BY>
        </CREATED>
...

 

DTD update - Unix Record List

<baseurl>/api/2.0/fo/auth/unix/auth_unix_list_output.dtd
...
<!ELEMENT AUTH_UNIX (ID, TITLE, USERNAME, CLEARTEXT_PASSWORD, ROOT_TOOL, RSA_PRIVATE_KEY?, DSA_PRIVATE_KEY?, PORT?, IP_SET, NETWORK_ID?, CREATED, LAST_MODIFIED, COMMENTS?, USE_AGENTLESS_TRACKING?, AGENTLESS_TRACKING_PATH?)>
...
<!ELEMENT NETWORK_ID (#PCDATA)>
...

 

DTD update - Windows Record List

<baseurl>/api/2.0/fo/auth/windows/auth_windows_list_output.dtd
...
<!ELEMENT AUTH_WINDOWS (ID, TITLE, USERNAME, NTLM?, WINDOWS_DOMAIN?, WINDOWS_AD_DOMAIN?, WINDOWS_AD_TRUST?, IP_SET?, NETWORK_ID?, CREATED, LAST_MODIFIED, COMMENTS?, USE_AGENTLESS_TRACKING?)>
...
<!ELEMENT NETWORK_ID (#PCDATA)>
...

 

DTD update - VMware Record List

<baseurl>/api/2.0/fo/auth/vmware/auth_vmware_list_output.dtd
<!ELEMENT AUTH_VMWARE (ID, TITLE, USERNAME, PORT, SSL_VERIFY, HOSTS?, IP_SET, NETWORK_ID?, CREATED, LAST_MODIFIED, COMMENTS?)>
..
<!ELEMENT NETWORK_ID (#PCDATA)>
...

 

DTD update - SNMP Record List

<baseurl>/api/2.0/fo/auth/snmp/auth_snmp_list_output.dtd
...
<!ELEMENT AUTH_SNMP (ID, TITLE, USERNAME?, AUTH_ALG?, PRIV_ALG?, SEC_ENG?, CONTEXT_ENG?, CONTEXT?, COMMUNITY_STRINGS?, VERSION, IP_SET, NETWORK_ID?, CREATED, LAST_MODIFIED, COMMENTS?)>
...
<!ELEMENT NETWORK_ID (#PCDATA)>
...

 

DTD update - Oracle Record List

<baseurl>/api/2.0/fo/auth/oracle/auth_oracle_list_output.dtd
...
<!ELEMENT AUTH_ORACLE (ID, TITLE, USERNAME, (SID|SERVICENAME), PORT, IP_SET, PC_ONLY?, WINDOWS_OS_CHECKS, WINDOWS_OS_OPTIONS?, UNIX_OPATCH_CHECKS, UNIX_OS_CHECKS, UNIX_OS_OPTIONS?, NETWORK_ID?, CREATED, LAST_MODIFIED, COMMENTS?)>
...
<!ELEMENT NETWORK_ID (#PCDATA)>
...

 

Oracle Listener Record List

<baseurl>/api/2.0/fo/auth/oracle_listener/auth_oracle_listener_list_output.dtd
...
<!ELEMENT AUTH_ORACLE_LISTENER (ID, TITLE, IP_SET, NETWORK_ID?, CREATED, LAST_MODIFIED, COMMENTS?)>
...
<!ELEMENT NETWORK_ID (#PCDATA)>
...

 

MS SQL Record List

<baseurl>/api/2.0/fo/auth/ms_sql/auth_ms_sql_list_output.dtd
...
<!ELEMENT AUTH_MS_SQL (ID, TITLE, USERNAME, (INSTANCE | AUTO_DISCOVER_INSTANCES), (DATABASE | AUTO_DISCOVER_DATABASES), (PORT|AUTO_DISCOVER_PORTS), DB_LOCAL, WINDOWS_DOMAIN?, IP_SET, NETWORK_ID?, CREATED, LAST_MODIFIED, COMMENTS?)>
...
<!ELEMENT NETWORK_ID (#PCDATA)>
...

 

MS IIS Server Record List

<baseurl>/api/2.0/fo/auth/ms_iis/auth_ms_iis_list_output.dtd
...
<!ELEMENT AUTH_MS_IIS (ID, TITLE, IP_SET, NETWORK_ID?, CREATED, LAST_MODIFIED, COMMENTS?)>
...
<!ELEMENT NETWORK_ID (#PCDATA)>
...

 

IBM WebSphere Record List

<baseurl>/api/2.0/fo/auth/ibm_websphere/auth_ibm_websphere_list_output.dtd 
...
<!ELEMENT AUTH_IBM_WEBSPHERE (ID, TITLE, IP_SET, UNIX_INSTLLATION_DIRECTORY, NETWORK_ID?, CREATED, LAST_MODIFIED, COMMENTS?)>
...
<!ELEMENT NETWORK_ID (#PCDATA)>
...

 

IBM DB2 Record List

<baseurl>/api/2.0/fo/auth/ibm_db2/auth_ibm_db2_list_output.dtd 
...
<!ELEMENT AUTH_IBM_DB2 (ID, TITLE, USERNAME, DATABASE, PORT, IP_SET, PC_ONLY?, NETWORK_ID?, CREATED, LAST_MODIFIED, COMMENTS?)>
...
<!ELEMENT NETWORK_ID (#PCDATA)>
...

 

HTTP Record List

<baseurl>/api/2.0/fo/auth/http/auth_http_list_output.dtd 
...
<!ELEMENT AUTH_HTTP (ID, TITLE, USERNAME, SSL, (REALM|VHOST), IP_SET?, NETWORK_ID?, CREATED, LAST_MODIFIED, COMMENTS?)>
...
<!ELEMENT NETWORK_ID (#PCDATA)>
...

 

Apache Web Server Record List

<baseurl>/api/2.0/fo/auth/apache/auth_apache_list_output.dtd 
...
<!ELEMENT AUTH_APACHE (ID, TITLE, IP_SET, UNIX_CONFIGURATION_FILE, UNIX_CONTROL_COMMAND, NETWORK_ID?, CREATED, LAST_MODIFIED, COMMENTS?)>
...
<!ELEMENT NETWORK_ID (#PCDATA)>
...

 

 

 

Outcomes