Terry McCorkle

QualysGuard API Notification

Blog Post created by Terry McCorkle on Mar 14, 2014

This API notification provides an early preview into the coming API changes in QualysGuard, allowing you to proactively identify any changes that might be required for your automated scripts or programs that utilize the API methods described below.  There is one primary API change in this release:

 

New API: Asset Management and Tagging API v2

 

This release will apply to the following platforms:

 

 

Full release notes will be available to customers on the day of the release.

 

API Enhancements

 

Tag API

          The Tags API provides a suite of API functions for managing tags. The supported Tag operations are get, create, update, search, count, delete and evaluate.

 

          Tag operations

                    Get Tag

                    Create Tag

                    Update Tag

                    Search Tags

                    Count Tags

                    Delete Tag

                    Evaluate Tag

 

 

Example:

          Fetch tag ID 12345.

 

Request:

          curl -n -u "USERNAME:PASSWORD" "https://qualysapi.qualys.com/rest/2.0/get/am/tag/12345"

 

 

Response:

 

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://qualysapi.qualys.com/qps/xsd/2.0/am/tag.xsd">
  <responseCode>SUCCESS</responseCode>
  <count>1</count>
  <data>
    <Tag>
      <id>12345</id>
      <name>Test Tag</name>
      <created>2014-02-06T19:14:50Z</created>
      <modified>2014-02-06T19:14:50Z</modified>
      <color>#FFFFFF</color>
      <ruleText>asset.installedSoftwares.contains { it.name == "Windows" }</ruleText>
      <ruleType>GROOVY</ruleType>
      <children>
        <list/>
      </children>
    </Tag>
  </data>
</ServiceResponse>

 

Host Asset API

          The Host Asset API provides a suite of API functions for managing host assets. In many cases these are hosts detected by our cloud scanners. Host assets can also be added manually by the QualysGuard API or user interface. The HostAsset members identify operating system, NetBIOS, tags, open ports, NICs, installed software, EC2 source information and current vulnerabilities (all instances).

 

          Host Asset operations

                    Get Host Asset

                    Create Host Asset

                    Update Host Asset

                    Search Hosts Assets

                    Count Host Assets

                    Delete Host Asset

                    Activate Host Asset

 

Example:

          Fetch the host asset ID 12345 and list host asset details.

 

Request:

          curl -n -u "USERNAME:PASSWORD" "https://qualysapi.qualys.com/rest/2.0/get/am/hostasset/12345"

 

Response:

 

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://qualysapi.qualys.com/qps/xsd/2.0/am/hostasset.xsd">
  <responseCode>SUCCESS</responseCode>
  <count>1</count>
  <data>
    <HostAsset>
      <id>2020094</id>
      <name>My Windows Asset</name>
      <created>2014-02-06T19:16:35Z</created>
      <modified>2014-02-06T19:16:35Z</modified>
      <type>HOST</type>
      <tags>
        <list>
            <TagSimple>
                <id>12345</id>
                <name>Tag 1</name>
            </TagSimple>
            <TagSimple>
                <id>54321</id>
                <name>Tag 2</name>
            </TagSimple>
        </list>
      </tags>
      <sourceInfo>
        <list/>
      </sourceInfo>
      <os>Windows 7</os>
      <dnsHostName>localhost</dnsHostName>
      <netbiosName>TEST</netbiosName>
      <netbiosNetworkId>10</netbiosNetworkId>
      <networkGuid>66bf43c8-7392-4257-b856-a320fde231eb</networkGuid>
      <address>127.0.0.1</address>
      <trackingMethod>IP</trackingMethod>
      <openPort>
        <list/>
      </openPort>
      <software>
        <list/>
      </software>
      <vuln>
        <list/>
      </vuln>
    </HostAsset>
  </data>
</ServiceResponse>

 

Asset API

          The Asset API is a subset of the Host Asset API. The Asset members identify name, tags, and EC2 source information.

 

          Asset operations

                    Get Asset

                    Update Asset

                    Search Assets

                    Count Assets

                    Delete Asset

                    Activate Asset

 

Example:

          This example fetches the asset ID 12345 and lists asset details.

 

Request:

          curl -n -u “USERNAME:PASSWORD” "https://qualysapi.qualys.com/rest/2.0/get/am/asset/12345"

 

Response:

 

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://qualysapi.qualys.com/qps/xsd/2.0/am/asset.xsd">
  <responseCode>SUCCESS</responseCode>
  <count>1</count>
  <data>
    <Asset>
      <id>12345</id>
      <name>My Windows Asset</name>
      <created>2014-02-06T19:16:35Z</created>
      <modified>2014-02-06T19:16:35Z</modified>
      <type>HOST</type>
      <tags>
        <list>
            <TagSimple>
                <id>12345</id>
                <name>Tag 1</name>
            </TagSimple>
            <TagSimple>
                <id>54321</id>
                <name>Tag 2</name>
            </TagSimple>
        </list>
      </tags>
    </Asset>
  </data>
</ServiceResponse>

 

Host Instance Vulnerability API

          The Host Instance Vulnerability API provides a suite of API functions for managing vulnerability instances found on host assets. The supported Host Instance Vulnerability operations are get, count and search.

 

    Host Instance Vulnerability operations

                    Get Host Instance Vulnerability

                    Search Host Instance Vulnerabilities

                    Count Host Instance Vulnerabilities

 

Example:

          Fetch the host instance vulnerability with the ID 12345.

 

Request:

          curl -n -u "USERNAME:PASSWORD" "https://qualysapi.qualys.com/rest/2.0/get/am/hostinstancevuln/12345"

 

Response:

 

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://qualysapi.qualys.com/qps/xsd/2.0/am/hostinstancevuln.xsd">
  <responseCode>SUCCESS</responseCode>
  <count>1</count>
  <data>
    <HostInstanceVuln>
      <id>9534081</id>
      <hostAssetId>1543621</hostAssetId>
      <qid>38167</qid>
      <port>25</port>
      <ssl>true</ssl>
      <found>true</found>
      <ignored>false</ignored>
      <disabled>false</disabled>
      <updated>2012-10-19T21:56:23Z</updated>
      <protocol>TCP</protocol>
      <source>HOST</source>
    </HostInstanceVuln>
  </data>
</ServiceResponse>

Outcomes