Update Host Asset

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

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

Update fields for a host asset and collections of host assets.

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

Permissions required - Managers with full scope, other users must have the requested assets in their scope and these permissions: Access Permission “API Access” and Asset Management Permission “Update Asset”.

We have restricted our asset update requests to static tags and have excluded dynamic tags. With this release, we will decline a request if the request contains TagSimple list having a dynamic tag for add/remove/set operation. The request is processed if it contains only static tags.

In case of the set operation, if the request includes static tags, then the existing static tags are removed and new static tags (specified in the request) are applied on that particular asset. All the existing system or dynamic tags are retained as is. You cannot add or remove dynamic tags manually.

Sample - Update some fields for host asset IDSample - Update some fields for host asset ID

API request

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

Request POST data

<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
        <data>
            <HostAsset>
              <name>Updated Name</name>
            </HostAsset>
        </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/hostasset.xsd">
    <responseCode>SUCCESS</responseCode>
    <count>1</count>
    <data>
        <HostAsset>
            <id>2020094</id>
            <name>Updated Name</name>
            <os>WINDOWS 95</os>
            <dnsHostName>win95.old.corp.net</dnsHostName>
            <created>2018-09-06T19:16:35Z</created>
            <modified>2018-09-06T19:16:35Z</modified>
            <type>HOST</type>
            <tags>
                <list />
            </tags>
            <sourceInfo>
                <list/>
            </sourceInfo>
            <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>

Sample - Update some fields for host assets that have names containing the word OLDSample - Update some fields for host assets that have names containing the word OLD

API request

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

curl -u "USERNAME:PASSWORD" -H "Content-type: text/xml" -X "POST" --data-binary @- "<qualys_base_url>/qps/rest/2.0/update/am/hostasset" < file.xml

Note: “file.xml” contains the request POST data.

Request POST data

<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
    <filters>
        <Criteria field="name" operator="CONTAINS">OLD</Criteria>
    </filters>
    <data>
        <HostAsset>
            <tags>
                <add>
                    <TagSimple>
                        <id>12345</id>
                    </TagSimple>
                </add>
                <remove>
                    <TagSimple>
                        <id>54321</id>
                        <TagSimple>
                        </remove>
                    </tags>
                    <software>
                        <set>
                            <HostAssetSoftware>
                                <name>Windows</name>
                                <version>95
                                </name>
                            </HostAssetSoftware>
                        </set>
                    </software>
                    <openPort>
                        <add>
                            <HostAssetOpenPort>
                                <port>8080</port>
                                <protocol>TCP</protocol>
                            </HostAssetOpenPort>
                        </add>
                    </openPort>
                </HostAsset>
            </data>
        </ServiceRequest>

XML output

<?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/hostasset.xsd">
    <responseCode>SUCCESS</responseCode>
    <count>1</count>
    <data>
        <HostAsset>
            <id>2020094</id>
            <name>Updated Name</name>
            <os>WINDOWS 95</os>
            <dnsHostName>win95.old.corp.net</dnsHostName>
            <created>2014-02-06T19:16:35Z</created>
            <modified>2014-02-06T19:16:35Z</modified>
            <type>HOST</type>
            <tags>
                <list>
                    <TagSimple>
                        <id>12345</id>
                        <name>Simple Tag 1</name>
                    </TagSimple>
                </list>
            </tags>
            <sourceInfo>
                <list/>
            </sourceInfo>
            <netbiosName>TEST</netbiosName>
            <netbiosNetworkId>10</netbiosNetworkId>
            <networkGuid>66bf43c8-7392-4257-b856-a320fde231eb</networkGuid>
            <address>127.0.0.1</address>
            <trackingMethod>IP</trackingMethod>
            <openPort>
                <list>
                    <HostAssetOpenPort>
                        <port>8080</port>
                        <protocol>TCP</protocol>
                    </HostAssetOpenPort>
                </list>
            </openPort>
            <software>
                <list>
                    <HostAssetSoftware>
                        <name>Windows</name>
                        <version>95</version>
                    </HostAssetSoftware>
                </list>
            </software>
            <vuln>
                <list/>
            </vuln>
        </HostAsset>
    </data>
</ServiceResponse>

Sample - Request to add tags to a host assetSample - Request to add tags to a host asset

API request

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

Request POST data

<ServiceRequest>
    <data>
        <HostAsset>
            <tags>
                <add>
                    <TagSimple>
                        <id>11307825</id>
                    </TagSimple>
                </add>
            </tags>
        </HostAsset>
    </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/a
m/hostasset.xsd">
    <responseCode>SUCCESS</responseCode>
    <count>1</count>
    <data>
        <HostAsset>
            <id>3458268</id>
        </HostAsset>
    </data>
</ServiceResponse>

Sample - Update HostAsset for BMC HelixSample - Update HostAsset for BMC Helix

Request POST data

<?xml version="1.0" encoding="UTF-8"?> <ServiceRequest> 
<filters>
     <Criteria field="id" operator="IN">19059383         
     </Criteria> 
   </filters> 
<data> 
<HostAsset> 
   <tags> 
   <add> 
      <TagSimple> 
        <id>87832867</id> 
      </TagSimple> 
   </add> 
</tags> 
</HostAsset> 
</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/a
m/hostasset.xsd">
    <responseCode>SUCCESS</responseCode>
    <count>1</count>
    <data>
        <HostAsset>
            <id>19059383</id>
        </HostAsset>
    </data>
</ServiceResponse>

XSD Response

<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema" 
 targetNamespace="http://api.portal.qualys.com/v2"
 xmlns:tns="http://api.portal.qualys.com/v2"
 xmlns:common="http://api.portal.qualys.com/common"
 elementFormDefault="qualified">
   <include schemaLocation="asset.xsd" />
    <include schemaLocation="asset_common.xsd" />
    <include schemaLocation="agent_source.xsd" />
    <import namespace="http://api.portal.qualys.com/common" 
     schemaLocation="http://api.portal.qualys.com/common/qualys_common.xsd" />
    <simpleType name="AssetTrackingMethod">
     <restriction base="string">
...
    <enumeration value="PASSIVE_SCANNER" />
     <enumeration value="GCP_INSTANCE_ID" />
     <enumeration value="SHODAN" />
     <enumeration value="PASSIVE_SENSOR" />
     <enumeration value="EASM" />
     <enumeration value="ICS_OCA" />
     <enumeration value="SERVICE_NOW" />
     <enumeration value="ACTIVE_DIRECTORY" />
     <enumeration value="BMC Helix" />
   </restriction>
   </simpleType> 
     <complexType name="HostAssetOpenPort">
   <sequence>
     <element name="port" type="integer" />
     <element name="protocol" minOccurs="0" type="tns:Protocol"/>
   </sequence>
  </complexType>
     <complexType name="HostAssetOpenPortQList">
   <sequence>
     <element name="count" type="int" maxOccurs="1" minOccurs="0"/>
   </sequence>
 </complexType>
     ...
    <complexType name="HostAssetSoftware">
   <sequence>
     <element name="name" type="string" />
     <element name="version" type="string" default="unkown" />
   </sequence>
 </complexType>
 </schema>

XSD

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