Eric Perraudeau

QualysGuard 7.3 API Early Notification

Blog Post created by Eric Perraudeau Employee on Jun 18, 2012

A new release of QualysGuard®, Version 7.3, will be available in production the second half of July 2012. More information specific to this release will be communicating via the Release Notification page here:

 

This notification provides an early preview of the API enhancements for QualysGuard 7.3, allowing you to make any changes to automated scripts or code that utilize the following APIs:

  • https://[QUALYSAPISERVER]/api/2.0/fo/appliance/

 

Table of content:

Enhancements to "appliance" API v2

The “appliance” API v2 (/api/2.0/fo/appliance/), which returns configuration information about the virtual and physical scanner appliances associated with a QualysGuard subscription, has been updated to return the same set of information already available from within the QualysGuard User Interface. In QualysGuard 7.3, when the parameter "output_mode=full" is provided, the output of the “appliance” API will return the following new information:

 

 

 

XML ElementStatusComments and references to screenshots
/IDNOT CHANGEDNot displayed in the UI, this is the ID of the QualysGuard object in the database
/NAMENOT CHANGEDG1
/SOFTWARE_VERSIONNOT CHANGEDV10
/RUNNING_SCAN_COUNTNOT CHANGED
/STATUSNOT CHANGEDG6
/MODEL_NUMBERNOT CHANGEDG2
/SERIAL_NUMBERNOT CHANGEDG3
/LAN_IP_ADDRESSREPLACED by /INTERFACE_SETTINGS/
INTERFACE=lan/IP_ADDRESS

/LAN_IPV6_ADDRESSREPLACED by /INTERFACE_SETTINGS/
INTERFACE=lan/IPV6_ADDRESS

/WAN_IP_ADDRESSREPLACED by /INTERFACE_SETTINGS/
INTERFACE=wan/IP_ADDRESS

/ML_LATESTNEWV5
/ML_VERSIONUPDATED: new "updated" attribute V4 and V6
/VULNSIGS_LATESTNEWV2
/VULNSIGS_VERSIONUPDATED: new "updated" attribute V1 and V3
/ASSET_GROUP_COUNTNOT CHANGED
/LAST_UPDATED_DATENOT CHANGEDV9
/POLLING_INTERVALNOT CHANGEDG4
/VLAN_ENABLEDREPLACED by /VLANS/SETTING=Enabled
/FDCC_ENABLEDNOT CHANGEDSO1
/UPDATEDNOT CHANGED
/RUNNING_SCANSNOT CHANGED
/ACTIVATION_CODENEW
/INTERFACE_SETTINGSNEW
/INTERFACE_SETTINGS/SETTINGNEWvalue is "disabled" (W1) or not displayed if "enabled"
/INTERFACE_SETTINGS/INTERFACENEWvalue is "lan" or "wan"
/INTERFACE_SETTINGS/IP_ADDRESSNEWL4 or W5
/INTERFACE_SETTINGS/NETMASKNEWL5 or W6
/INTERFACE_SETTINGS/GATEWAYNEWL6 or W7
/INTERFACE_SETTINGS/LEASENEWL1 (Static) or W2 (Dynamic for DHCP)
/INTERFACE_SETTINGS/IPV6_ADDRESSNEWL7
/INTERFACE_SETTINGS/SPEEDNEWL3 or W4
/INTERFACE_SETTINGS/DUPLEXNEWL2 or W3
/INTERFACE_SETTINGS/DNSNEW
/INTERFACE_SETTINGS/DNS/DOMAINNEWL8
/INTERFACE_SETTINGS/DNS/PRIMARYNEWL9 or W8
/INTERFACE_SETTINGS/DNS/SECONDARYNEWL10 or W9
/PROXY_SETTINGSNEW
/PROXY_SETTINGS/SETTINGNEWP1
/PROXY_SETTINGS/PROXYNEW
/PROXY_SETTINGS/PROXY/TYPENEWvalue is "primary" or "secondary"
/PROXY_SETTINGS/PROXY/IP_ADDRESSNEWP2 or P3
/PROXY_SETTINGS/PROXY/PORTNEWP4 or P5
/PROXY_SETTINGS/PROXY/USERNEWP6 or P7
/VLANSNEW
/VLANS/SETTINGNEWvalue is "enabled" or "disabled"
/VLANS/VLANNEW
/VLANS/VLAN/IDNEWV3
/VLANS/VLAN/NAMENEWV4
/VLANS/VLAN/IP_ADDRESSNEWV1
/VLANS/VLAN/NETMASKNEWV2
/STATIC_ROUTESNEW
/STATIC_ROUTES/ROUTENEW
/STATIC_ROUTES/ROUTE/NAMENEWSR3
/STATIC_ROUTES/ROUTE/IP_ADDRESSNEWSR2
/STATIC_ROUTES/ROUTE/NETMASKNEWSR2
/STATIC_ROUTES/ROUTE/GATEWAYNEWSR1
/ASSET_GROUP_LISTNEW
/ASSET_GROUP_LIST/ASSET_GROUPNEW
/ASSET_GROUP_LIST/ASSET_GROUP/IDNEW
/ASSET_GROUP_LIST/ASSET_GROUP/NAMENEWAG1
/USER_LOGINNEWG5
/HEARTBEATS_MISSEDNEWG7
/SS_CONNECTIONNEWV11
/SS_LAST_CONNECTEDNEWV12
/USER_LISTNEW
/USER_LIST/USER_ACCOUNTNEW
/USER_LIST/USER_ACCOUNT/IDNEWU1
/USER_LIST/USER_ACCOUNT/NAMENEWU1
/COMMENTSNEWC1

 

The following screenshots of Scanner Appliance UI page contain the references to the XML elements presented above. This is provided to help to understand the signification of the XML elements returned in the appliance API output.

Screen Shot 2012-06-14 at 18.46.34 .pngScreen Shot 2012-06-14 at 18.46.39 .png

Screen Shot 2012-06-14 at 18.46.45 .pngScreen Shot 2012-06-14 at 18.46.53 .png

Screen Shot 2012-06-14 at 18.46.59 .pngScreen Shot 2012-06-14 at 18.47.05 .png

Screen Shot 2012-06-14 at 18.47.13 .pngScreen Shot 2012-06-14 at 18.47.18 .png

Screen Shot 2012-06-14 at 18.47.24 .pngScreen Shot 2012-06-14 at 18.47.32 .png

Screen Shot 2012-06-14 at 18.47.41 .png

 

Preview of the new DTD

 

<!-- QUALYS APPLIANCE_LIST_OUTPUT DTD -->
<!-- $Revision$ -->
<!ELEMENT APPLIANCE_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, APPLIANCE_LIST?)>
<!ELEMENT APPLIANCE_LIST (APPLIANCE+)>
<!ELEMENT APPLIANCE (ID, NAME, SOFTWARE_VERSION, RUNNING_SCAN_COUNT, STATUS, MODEL_NUMBER?, SERIAL_NUMBER?, ACTIVATION_CODE?, INTERFACE_SETTINGS*, PROXY_SETTINGS?, VLANS?, STATIC_ROUTES?, ML_LATEST?, ML_VERSION?, VULNSIGS_LATEST?, VULNSIGS_VERSION?, ASSET_GROUP_COUNT?, ASSET_GROUP_LIST?, LAST_UPDATED_DATE?, POLLING_INTERVAL?, USER_LOGIN?, HEARTBEATS_MISSED?, SS_CONNECTION?, SS_LAST_CONNECTED?, FDCC_ENABLED?, USER_LIST?, UPDATED?, COMMENTS?, RUNNING_SCANS?)>
<!ELEMENT ID (#PCDATA)>
<!ELEMENT NAME  (#PCDATA)>
<!ELEMENT SOFTWARE_VERSION (#PCDATA)>
<!ELEMENT RUNNING_SCAN_COUNT (#PCDATA)>
<!ELEMENT STATUS (#PCDATA)>
<!ELEMENT MODEL_NUMBER (#PCDATA)>
<!ELEMENT SERIAL_NUMBER (#PCDATA)>
<!ELEMENT ACTIVATION_CODE (#PCDATA)>
<!ELEMENT INTERFACE_SETTINGS (SETTING?, INTERFACE, IP_ADDRESS, NETMASK, GATEWAY, LEASE, IPV6_ADDRESS?, SPEED, DUPLEX, DNS)>
<!ELEMENT SETTING (#PCDATA)>
<!ELEMENT INTERFACE (#PCDATA)>
<!ELEMENT IP_ADDRESS (#PCDATA)>
<!ELEMENT NETMASK (#PCDATA)>
<!ELEMENT GATEWAY (#PCDATA)>
<!ELEMENT LEASE (#PCDATA)>
<!ELEMENT IPV6_ADDRESS (#PCDATA)>
<!ELEMENT SPEED (#PCDATA)>
<!ELEMENT DUPLEX (#PCDATA)>
<!ELEMENT DNS (DOMAIN?, PRIMARY, SECONDARY)>
<!ELEMENT DOMAIN (#PCDATA)>
<!ELEMENT PRIMARY (#PCDATA)>
<!ELEMENT SECONDARY (#PCDATA)>
<!ELEMENT PROXY_SETTINGS (SETTING, PROXY*)>
<!ELEMENT PROXY (TYPE, IP_ADDRESS, PORT, USER)>
<!ELEMENT TYPE (#PCDATA)>
<!ELEMENT PORT (#PCDATA)>
<!ELEMENT USER (#PCDATA)>
<!ELEMENT VLANS (SETTING, VLAN*)>
<!ELEMENT STATIC_ROUTES (ROUTE*)>
<!ELEMENT ROUTE (NAME, IP_ADDRESS, NETMASK, GATEWAY)>
<!ELEMENT VLAN (ID, NAME, IP_ADDRESS, NETMASK)>
<!ELEMENT ML_LATEST (#PCDATA)>
<!ELEMENT ML_VERSION (#PCDATA)>
<!ATTLIST ML_VERSION updated CDATA #IMPLIED>
<!ELEMENT VULNSIGS_LATEST (#PCDATA)>
<!ELEMENT VULNSIGS_VERSION (#PCDATA)>
<!ATTLIST VULNSIGS_VERSION updated CDATA #IMPLIED>
<!ELEMENT ASSET_GROUP_COUNT (#PCDATA)>
<!ELEMENT ASSET_GROUP_LIST (ASSET_GROUP*)>
<!ELEMENT ASSET_GROUP (ID, NAME)>
<!ELEMENT LAST_UPDATED_DATE (#PCDATA)>
<!ELEMENT POLLING_INTERVAL (#PCDATA)>
<!ELEMENT HEARTBEATS_MISSED (#PCDATA)>
<!ELEMENT SS_CONNECTION (#PCDATA)>
<!ELEMENT SS_LAST_CONNECTED (#PCDATA)>
<!ELEMENT FDCC_ENABLED (#PCDATA)>
<!ELEMENT RUNNING_SCANS (SCAN+)>
<!ELEMENT SCAN (ID, TITLE, REF, TYPE, SCAN_DATE)>
<!ELEMENT TITLE (#PCDATA)>
<!ELEMENT REF (#PCDATA)>
<!ELEMENT SCAN_DATE (#PCDATA)>
<!ELEMENT USER_LIST (USER_ACCOUNT*)>
<!ELEMENT USER_ACCOUNT (ID, NAME)>
<!ELEMENT UPDATED (#PCDATA)>
<!ELEMENT COMMENTS (#PCDATA)>

<!-- EOF -->

 

Example of the XML output

 

$ curl -u "PASS:PASSWORD" -H "X-Requested-With: curl" "https://qualysapi.qualys.com/api/2.0/fo/appliance/?action=list&output-mode=full"

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE APPLIANCE_LIST_OUTPUT SYSTEM "https://web4.dev.qualys.com:23443/api/2.0/fo/appliance/appliance_list_output.dtd">
<APPLIANCE_LIST_OUTPUT>
  <RESPONSE>
    <DATETIME>2012-06-13T07:23:49Z</DATETIME>
    <APPLIANCE_LIST>
      <APPLIANCE>
        <ID>248</ID>
        <NAME>is_quays_ra2</NAME>
        <SOFTWARE_VERSION>2.6</SOFTWARE_VERSION>
        <RUNNING_SCAN_COUNT>0</RUNNING_SCAN_COUNT>
        <STATUS>Online</STATUS>
        <MODEL_NUMBER>QGSA-0000-A1</MODEL_NUMBER>
        <SERIAL_NUMBER>0</SERIAL_NUMBER>
        <ACTIVATION_CODE>10148009490167</ACTIVATION_CODE>
        <INTERFACE_SETTINGS>
          <INTERFACE>lan</INTERFACE>
          <IP_ADDRESS>10.40.1.86</IP_ADDRESS>
          <NETMASK>255.255.255.0</NETMASK>
          <GATEWAY>10.40.1.1</GATEWAY>
          <LEASE>Static</LEASE>
          <IPV6_ADDRESS></IPV6_ADDRESS>
          <SPEED>100</SPEED>
          <DUPLEX>Full</DUPLEX>
          <DNS>
            <DOMAIN>ina.hole</DOMAIN>
            <PRIMARY>10.100.1.21</PRIMARY>
            <SECONDARY>10.100.1.22</SECONDARY>
          </DNS>
        </INTERFACE_SETTINGS>
        <INTERFACE_SETTINGS>
          <SETTING>Disabled</SETTING>
          <INTERFACE>wan</INTERFACE>
          <IP_ADDRESS></IP_ADDRESS>
          <NETMASK>255.255.255.0</NETMASK>
          <GATEWAY>127.0.0.1</GATEWAY>
          <LEASE>Dynamic</LEASE>
          <SPEED>10</SPEED>
          <DUPLEX>Half</DUPLEX>
          <DNS>
            <PRIMARY>0.0.0.0</PRIMARY>
            <SECONDARY>0.0.0.0</SECONDARY>
          </DNS>
        </INTERFACE_SETTINGS>
        <PROXY_SETTINGS>
          <SETTING>Disabled</SETTING>
          <PROXY>
            <TYPE>primary</TYPE>
            <IP_ADDRESS>0.0.0.0</IP_ADDRESS>
            <PORT>0</PORT>
            <USER></USER>
          </PROXY>
          <PROXY>
            <TYPE>secondary</TYPE>
            <IP_ADDRESS>0.0.0.0</IP_ADDRESS>
            <PORT>0</PORT>
            <USER></USER>
          </PROXY>
        </PROXY_SETTINGS>
        <VLANS>
          <SETTING>Enabled</SETTING>
          <VLAN>
            <ID>123</ID>
            <NAME>Mine</NAME>
            <IP_ADDRESS>172.168.1.1</IP_ADDRESS>
            <NETMASK>255.255.0.0</NETMASK>
          </VLAN>
        </VLANS>
        <STATIC_ROUTES>
          <ROUTE>
            <NAME>OneRoute</NAME>
            <IP_ADDRESS>192.168.1.0</IP_ADDRESS>
            <NETMASK>255.255.255.0</NETMASK>
            <GATEWAY>192.168.254.1</GATEWAY>
          </ROUTE>
          <ROUTE>
            <NAME>TwoRoute</NAME>
            <IP_ADDRESS>192.168.2.0</IP_ADDRESS>
            <NETMASK>255.255.255.0</NETMASK>
            <GATEWAY>192.168.254.2</GATEWAY>
          </ROUTE>
        </STATIC_ROUTES>
        <ML_LATEST>5.19.41-1</ML_LATEST>
        <ML_VERSION updated="yes">5.19.41-1</ML_VERSION>
        <VULNSIGS_LATEST>1.28.277-2</VULNSIGS_LATEST>
        <VULNSIGS_VERSION updated="yes">1.28.277-2</VULNSIGS_VERSION>
        <ASSET_GROUP_COUNT>10</ASSET_GROUP_COUNT>
        <ASSET_GROUP_LIST>
          <ASSET_GROUP>
            <ID>30560</ID>
            <NAME>112411</NAME>
          </ASSET_GROUP>
          <ASSET_GROUP>
            <ID>33979</ID>
            <NAME>1to100</NAME>
          </ASSET_GROUP>
          <ASSET_GROUP>
            <ID>33980</ID>
            <NAME>1to50</NAME>
          </ASSET_GROUP>
          <ASSET_GROUP>
            <ID>33439</ID>
            <NAME>bad_nb</NAME>
          </ASSET_GROUP>
          <ASSET_GROUP>
            <ID>35014</ID>
            <NAME>cvss</NAME>
          </ASSET_GROUP>
          <ASSET_GROUP>
            <ID>35015</ID>
            <NAME>deadhost</NAME>
          </ASSET_GROUP>
          <ASSET_GROUP>
            <ID>33739</ID>
            <NAME>LotsODNS</NAME>
          </ASSET_GROUP>
          <ASSET_GROUP>
            <ID>20181</ID>
            <NAME>New</NAME>
          </ASSET_GROUP>
          <ASSET_GROUP>
            <ID>21779</ID>
            <NAME>SingleDNS2</NAME>
          </ASSET_GROUP>
          <ASSET_GROUP>
            <ID>33619</ID>
            <NAME>SingleDNS3</NAME>
          </ASSET_GROUP>
        </ASSET_GROUP_LIST>
        <LAST_UPDATED_DATE>2012-06-13T05:53:21Z</LAST_UPDATED_DATE>
        <POLLING_INTERVAL>60 seconds</POLLING_INTERVAL>
        <USER_LOGIN>quays_ra2</USER_LOGIN>
        <HEARTBEATS_MISSED>0</HEARTBEATS_MISSED>
        <SS_CONNECTION>Active</SS_CONNECTION>
        <SS_LAST_CONNECTED>2011-10-25T17:16:51Z</SS_LAST_CONNECTED>
        <FDCC_ENABLED>Yes</FDCC_ENABLED>
        <USER_LIST>
          <USER_ACCOUNT>
            <ID>8453</ID>
            <NAME>quays_ra10</NAME>
          </USER_ACCOUNT>
          <USER_ACCOUNT>
            <ID>15475</ID>
            <NAME>quays_ra21</NAME>
          </USER_ACCOUNT>
        </USER_LIST>
        <UPDATED>Yes</UPDATED>
        <COMMENTS><![CDATA[This is a comment.  OK?
<script>alert('foo');</script>]]></COMMENTS>
      </APPLIANCE>
    </APPLIANCE_LIST>
  </RESPONSE>
</APPLIANCE_LIST_OUTPUT>
<!-- CONFIDENTIAL AND PROPRIETARY INFORMATION. Qualys provides the QualysGuard Service "As Is," without any warranty of any kind. Qualys makes no warranty that the information contained in this report is complete or error-free. Copyright 2012, Qualys, Inc. //--> 

Outcomes