Asset Tagging API Examples

Document created by Jeff Leggett Employee on Jun 4, 2015Last modified by Jeff Leggett Employee on Nov 28, 2016
Version 15Show Document
  • View in full screen mode

Was helping a customer tonight with some Tagging API calls.  Sharing back for future reference.

 

Creating Tags with the API

 

Customer wants to tag host assets with a custom set of tags.  To create a custom set of tags with the Tagging API here's an example:

 

using this XML createtags.xml

<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
    <data>
  <Tag>
  <name>Internal Tags</name>
    <children>
  <set>
  <TagSimple><name>PCI DSS Compliance</name></TagSimple>
      <TagSimple><name>DEV-PCI (Project)</name></TagSimple>
      <TagSimple><name>Media Hosts</name></TagSimple>
    <TagSimple><name>Web Presentation Layer</name></TagSimple>
    <TagSimple><name>Internal Network</name></TagSimple>
      <TagSimple><name>IT-Security Operations</name></TagSimple>
    <TagSimple><name>Server Technologies</name></TagSimple>
  </set>
  </children>
    </Tag>
  </data>
</ServiceRequest>
             

 

The following command will create these tags under an "Internal Tags" parent tag.

 

100326MBP15:Code jleggett$ curl -u "USER:PWD" -H "Content-type: text/xml" -X "POST" --data-binary @-  "https://qualysapi.qualys.com/qps/rest/2.0/create/am/tag" < createtags.xml

<?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>10236452</id>
      <name>Internal Tags</name>
      <created>2015-02-25T23:50:03Z</created>
      <modified>2015-02-25T23:50:03Z</modified>
      <children>
        <list>
          <TagSimple>
            <id>10236453</id>
            <name>Web Presentation Layer</name>
          </TagSimple>
          <TagSimple>
            <id>10236454</id>
            <name>DEV-PCI (Project)</name>
          </TagSimple>
          <TagSimple>
            <id>10236455</id>
            <name>Server Technologies</name>
          </TagSimple>
          <TagSimple>
            <id>10236456</id>
            <name>Shaw Media Hosts</name>
          </TagSimple>
          <TagSimple>
            <id>10236457</id>
            <name>Internal Network</name>
          </TagSimple>
          <TagSimple>
            <id>10236458</id>
            <name>PCI DSS Compliance</name>
          </TagSimple>
          <TagSimple>
            <id>10236459</id>
            <name>IT-Security Operations</name>
          </TagSimple>
        </list>
      </children>
    </Tag>
  </data>
             

 

Using these id #'s created you can use the host asset API to tag these host assets with it automatically.

 

Using this XML: taghostasset.xml

<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
    <data>
    <HostAsset>
    <tags>
      <add>
     <TagSimple><id>10236453</id></TagSimple>
   <TagSimple><id>10236454</id></TagSimple>
   <TagSimple><id>10236455</id></TagSimple>
   <TagSimple><id>10236456</id></TagSimple>
   <TagSimple><id>10236457</id></TagSimple>
   <TagSimple><id>10236458</id></TagSimple>
   <TagSimple><id>10236459</id></TagSimple>
   </add>
      </tags>
      </HostAsset>
    </data>
</ServiceRequest>
             

 

The the following command will add these tags to the hostasset id # 60348306

100326MBP15:Code jleggett$ curl -u "USER:PWD" -H "Content-type: text/xml" -X "POST" --data-binary @-  "https://qualysapi.qualys.com/qps/rest/2.0/update/am/hostasset/60348306" < taghostasset.xml

<?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>60348306</id>
    </HostAsset>
  </data>
</ServiceResponse>
           

 

 

The Before screenshot of the HOst Asset

Screen Shot 2015-02-25 at 5.47.45 PM.png

And the After:

Screen Shot 2015-02-25 at 6.57.17 PM.png

Get a List of all my tags

 

Using the following XML pulltags.xml

<ServiceRequest>

<preferences>

<limitResults>100</limitResults>

</preferences>

</ServiceRequest>

 

 

Then the following command will output all of your tags with at least 1 asset assigned to it.

 

jleggett$ curl -u "USERNAME:PASSWORD" -H "content-type: text/xml" -X "POST" --data-binary @- "https://qualysapi.qualys.com/qps/rest/2.0/search/am/tag" < pulltags.xml > taglist.xml

 

I won't include the full taglist.xml output here, as it's very large, but a tag section looks like this:

<?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/1.0/am/tag.xsd
"
>



  <responseCode>SUCCESS</responseCode>

  <count>38</count>

  <hasMoreRecords>false</hasMoreRecords>

  <data>

    <Tag>

      <id>7491397</id>

      <uuid>aefad53f-c8e2-538a-e040-10ac1304744f</uuid>

      <name>Web Application Assets</name>

      <scope>USER</scope>

      <assetTypeOrdinal>3</assetTypeOrdinal>

      <reservedType>WEB_ASSET_TYPE_ROOT</reservedType>

      <reindex>false</reindex>

      <display/>

      <children>

        <count>0</count>

      </children>

      <created>2014-02-14T22:00:11Z</created>

      <updated>2014-03-24T18:56:43Z</updated

           

 

NOTE: if you have more than 100 tags (or gave a number below 100) you will get a slightly different response at the start:

 

<?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>50</count>
    <hasMoreRecords>true</hasMoreRecords>
    <lastId>10233306</lastId>
    <data>...

 

If <hasMoreRecords> is true you need to call the API again with the Criteria field using <lastId>, for example:

 

<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
    <filters>
        <Criteria field="id" operator="GREATER">10233306</Criteria>
    </filters>
</ServiceRequest>

 

Updating tags on an asset

 

So you wanted to replace and add some tags on a given asset (for example to move from a UAT build environment in a PROD environment to go live with).  You can do that with the following XML:

<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
<data>
  <HostAsset>
  <tags>
    <add>
       <TagSimple><id>10389062</id></TagSimple>
    </add>
    <remove>
       <TagSimple><id>10389061</id></TagSimple>
  </remove>
  </tags>
   </HostAsset>
</data>
</ServiceRequest>
    

 

The following command will add these tags to the hostasset id # 60348306

100326MBP15:Code jleggett$ curl -u "USER:PWD" -H "Content-type: text/xml" -X "POST" --data-binary @-  "https://qualysapi.qualys.com/qps/rest/2.0/update/am/hostasset/60348306" < updatetags.xml

 

The before screenshot of the host asset:

Screen Shot 2015-09-15 at 10.08.37 AM.png

And then after I have run the command above: (NOTE the change in TAG from UAT (yellow) to PROD (green)

 

Screen Shot 2015-09-15 at 10.11.13 AM.png

 

Get a list of hosts with a Given Tag

 

If you want to pull all the hosts with a given tag use the hostesset API.

 

Using this XML searchbytags.xml

<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
    <filters>
        <Criteria field="tagName" operator="EQUALS">Cloud Agent</Criteria>
    </filters>
</ServiceRequest>
 

 

Then this curl will pull  all hosts tagged with "Cloud Agent"

100326MBP15:Code jleggett$ curl -u USERNAME:PASSWORD -H "content-type: text/xml" -X "POST" --data-binary @- "https://qualysapi.qualys.com/qps/rest/2.0/search/am/hostasset" < searchbytag.xml > cloudagents.xml

 

We get 14 hosts back with all related asset data.  I have just included the beginning of the file for size reason s here.

<?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>14</count>
  <hasMoreRecords>false</hasMoreRecords>
  <data>
    <HostAsset>
      <id>71507763</id>
      <name>QLYSJPAE01</name>
      <created>2015-08-06T04:19:04Z</created>
      <modified>2016-01-15T08:43:19Z</modified>
      <type>HOST</type>
      <tags>
        <list>
          <TagSimple>
            <id>7630770</id>
            <name>192.168.X</name>
          </TagSimple>
 

 

Applying a tag or tags to multiple host assets

 

First, you will need to query hostasset (as in previous example), to get a list of all id's you care about (\\data\HostAsset\id in XMLPATH) then pass those id's to the hostasset API again with the tags you want applied.  The XML will look like the following:

 

<ServiceRequest>
   <filters>
       <Criteria field="id" operator="IN">2496953,2523656,2615056,2615457,2616056</Criteria>
</filters>
   <data>
       <HostAsset>
         
          <tags>
               <add>
                   <TagSimple>
                       <id>2178016</id>
                   </TagSimple>                   
               </add>
           </tags>
       </HostAsset>
   </data>
</ServiceRequest>

Hope this helps you use the Asset Management & Tagging API!

 

This document was generated from the following discussion: Asset Tagging API Example

 

Additional information regarding Groovy code can be found on this DOC Creating Asset Tags using Groovy

5 people found this helpful

Attachments

    Outcomes