Qualys Asset Management and Tagging API
Click to view navigation pane


Update Tag

[POST] /qps/rest/2.0/update/am/tag/<id>

[POST] /qps/rest/2.0/update/am/tag

Update fields for a tag and collections of tags.



Permissions required

Managers with full scope, other users must have these permissions: Access Permission “API Access”, Tag Permission “Create User Tag”, Tag Permission “Modify Dynamic Tag Rules” (to create a dynamic tag)

Input ParametersInput Parameters

Using the NOT EQUALS operator for updating tags could result in accidental update of unknown tags without any warning. To prevent accidental updates of unknown tags, we do not support NOT EQUALS operator for update actions.

Provider name cannot be updated.

Click here for available operators

Parameter

Mandatory

/Optional

Data Type

Description

name

   text

Name of the tag

criticalityScore

  

keyword

Update the asset criticality score for a tag between 1 to 5 with 1 being the lowest and 5 being the highest.

ruleType

  

text

STATIC, GROOVY, OS_REGEX, NETWORK_RANGE, NAME_CONTAINS, INSTALLED_SOFTWARE, OPEN_PORTS, VULN_EXIST, ASSET_SEARCH, CLOUD_ASSET, BUSINESS_INFORMATION, GLOBAL_ASSET_VIEW, NETWORK_RANGE, TAG_SET

ruleText

  

text

Define the criteria for the rule

color

   integer

Text formatted as #FFFFFF where F can be any value between 0-9 and A-F

Sample 1 - Rename parent tag, remove some child tagsSample 1 - Rename parent tag, remove some child tags

API request

curl -u "USERNAME:PASSWORD" -H "Content-type: text/xml" -X "POST" --data-binary @- "<qualys_base_url>/qps/rest/2.0/update/am/tag/12345"
< file.xml
Note: “file.xml” contains the request POST data.

Request POST data

<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
    <data>
        <Tag>
            <name>Parent Tag (Updated)</name>
            <children>
                <remove>
                    <TagSimple>
                        <id>123</id>
                    </TagSimple>
                    <TagSimple>
                        <id>456</id>
                    </TagSimple>
                </remove>
            </children>
        </Tag>
    </data>
</ServiceRequest>

Response

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="<qualys_base_url>/qps/xsd/2.0/am/tag.xsd">
    <responseCode>SUCCESS</responseCode>
    <count>1</count>
    <data>
        <Tag>
            <id>12345</id>
            <name>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>
                    <TagSimple>
                        <id>1</id>
                        <name>Child 1</name>
                    </TagSimple>
                    <TagSimple>
                        <id>2</id>
                        <name>Child 2</name>
                    </TagSimple>
                    <TagSimple>
                        <id>3</id>
                        <name>Child 3</name>
                    </TagSimple>
                    <TagSimple>
                        <id>123</id>
                        <name>Linked Child 1</name>
                    </TagSimple>
                    <TagSimple>
                        <id>456</id>
                        <name>Linked Child 2</name>
                    </TagSimple>
                </list>
            </children>
        </Tag>
    </data>
</ServiceResponse>
<responseCode>SUCCESS</responseCode>

Sample 2 - Update an asset tag with criticality score and tag ID in URLSample 2 - Update an asset tag with criticality score and tag ID in URL

API request

curl -n -u "USERNAME:PASSWORD" -H "content-type: text/xml"-X "POST" --
"<qualys_base_url>/rest/2.0/update/am/tag/11175413" < file.xml
Note: “file.xml” contains the request POST data.

Request POST data

<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
    <data>
        <Tag>
            <name>name change3</name>
            <criticalityScore>5</criticalityScore>
            <children>
                <remove>
                    <TagSimple>
                        <id>123</id>
                    </TagSimple>
                    <TagSimple>
                        <id>456</id>
                    </TagSimple>
                </remove>
            </children>
        </Tag>
    </data>
</ServiceRequest

Response

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="<qualys_base_url>/qps/rest/2.0/update/am/tag">
    <responseCode>SUCCESS</responseCode>
    <count>1</count>
    <hasMoreRecords>false</hasMoreRecords>
    <data>
        <Tag>
            <id>11175413</id>
        </Tag>
    </data>
</ServiceResponse>

Sample 3 - Update the tag color, rule text, rule type, child tagSample 3 - Update the tag color, rule text, rule type, child tag

API request

curl -n -u "USERNAME:PASSWORD" -H "content-type: text/xml"-X "POST" --
"<qualys_base_url>/rest/2.0/update/am/tag/19237412" < file.xml
Note: “file.xml” contains the request POST data

Request POST data

<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
    <data>
        <Tag>
            <color>#FFFFFF</color>
            <ruleType>ASSET_SEARCH</ruleType>
            <ruleText>&lt;?xml version="1.0" encoding="UTF-8"?&gt;&lt;TAG_CRITERIA&gt;&lt;NETBIOS&gt; &lt;SEARCH_TYPE&gt;BEGINNING&lt;/SEARCH_TYPE&gt;&lt;SEARCH_TERM&gt;test&lt;/SEARCH_TERM&gt; &lt;/NETBIOS&gt;&lt;/TAG_CRITERIA&gt;</ruleText>
            <children>
                <set>
                    <TagSimple>
                        <name>Child</name>
                    </TagSimple>
                </set>
            </children>
        </Tag>
    </data>
</ServiceRequest

Response

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="<qualys_base_url>/qps/rest/2.0/update/am/tag">
    <responseCode>SUCCESS</responseCode>
    <count>1</count>
    <hasMoreRecords>false</hasMoreRecords>
    <data>
        <Tag>
            <id>19237412</id>
        </Tag>
    </data>
</ServiceResponse>

Sample 4 - Update dynamic tag using rule engine GLOBAL_ASSET_VIEWSample 4 - Update dynamic tag using rule engine GLOBAL_ASSET_VIEW

API request

curl --location --request "POST"
--header 'Authorization: Basic cXVheXNfY2YyOlFhdGVtcEAxMjM='
--header 'Content-Type: application/xml'
--data-raw
"<qualys_base_url>/rest/2.0/create/am/tag/22446888" < file.xml
Note: “file.xml” contains the request POST data.

Request POST data

<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
    <data>
        <Tag>
            <name>Create_Tag_OperatingSystemLifecycleStageEOL1</name>
            <ruleType>GLOBAL_ASSET_VIEW</ruleType>
            <ruleText>operatingSysteem.name:"Linux"</ruleText>
        </Tag>
    </data>
</ServiceRequest

Response

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="<qualys_base_url>/qps/rest/2.0/update/am/tag.xsd">
    <responseCode>SUCCESS</responseCode>
    <count>1</count>
    <data>
        <Tag>
            <id>22446888</id>
        </Tag>
    </data>
</ServiceResponse>

Sample 5 - Update TagSet with ruleTextSample 5 - Update TagSet with ruleText

API request

curl -u "USERNAME:PASSWORD" -H "Content-type: text/xml" -X "POST" --
data-binary @-
"qualys_base_url/qps/rest/2.0/update/am/tag/25681813"
< file.xml>
Note: “file.xml” contains the request POST data.

Request POST data

<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
    <data>
        <Tag>
            <ruleType>TAG_SET</ruleType>
            <ruleText>
                <![CDATA[
                
                <?xml version="1.0" encoding="UTF-8" standalone="yes"?></ruleText><TAG_SET_TAG><INCLUDE_TAG><TAG_LIST><Tag><PARENT>18890412</PARENT><CHILD></CHILD></Tag><Tag><PARENT>18890012</PARENT><CHILD></CHILD></Tag></TAG_LIST><SCOPE>ANY</SCOPE></INCLUDE_TAG><EXCLUDE_TAG><TAG_LIST/><SCOPE>ANY</SCOPE></EXCLUDE_TAG></TAG_SET_TAG>]]>
            </ruleText>
        </Tag>
    </data>
</ServiceRequest>

Response

<?xml version="1.0" encoding="UTF-8"?>
<ServiceResponse
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="qualys_base_url/qps/xsd/2.0/am/tag.xsd">
    <responseCode>SUCCESS</responseCode>
    <count>1</count>
    <data>
        <Tag>
            <id>25681813</id>
        </Tag>
    </data>
</ServiceResponse>

Updated XSD

<schema
    xmlns="http://www.w3.org/2001/XMLSchema"
    xmlns:tns="http://am.oxm.api.portal.qualys.com/v2"
targetNamespace="http://am.oxm.api.portal.qualys.com/v2"
elementFormDefault="qualified">
    <complexType name="TagSimple">
        <sequence>
            <element name="id" type="long"/>
            <element name="name" type="string"/>
        </sequence>
    </complexType>
    <simpleType name="TagRuleType">
        <restriction base="string">
            <enumeration value="STATIC"/>
            <enumeration value="GROOVY"/>
            <enumeration value="OS_REGEX"/>
            <enumeration value="NETWORK_RANGE"/>
            <enumeration value="NETWORK_RANGE_ENHANCED"/>
            <enumeration value="NAME_CONTAINS"/>
            <enumeration value="INSTALLED_SOFTWARE"/>
            <enumeration value="OPEN_PORTS"/>
            <enumeration value="VULN_EXIST"/>
            <enumeration value="ASSET_SEARCH"/>
            <enumeration value="CLOUD_ASSET"/>
            <enumeration value="BUSINESS_INFORMATION"/>
            <enumeration value="GLOBAL_ASSET_VIEW"/>
            <enumeration value="TAG_SET"/>
        </restriction>
    </simpleType>
...
</complexContent>undefined</complexType>undefined</schema>

XSD

<platform API server>/qps/xsd/2.0/am/tag.xsd