Qualys Asset Management and Tagging API
Click to view navigation pane


Create Host Asset

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

Create one or more host assets using writable fields and collections. It is a good idea to attach tags that will make new assets visible to the current user if that user does not have permission to see all assets. Otherwise users will not be able to see or modify the new assets until an administrator or process attaches the appropriate tags to them.

What's next? After you've created host assets you need to activate them to make them available for scanning and reporting. Learn more on Activating Host Assets



Permissions required - Managers with full scope. Other users must have these permissions: Access Permission “API Access” and Asset Management Permission “Create Asset”.

We have restricted our asset create 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 - Create new host asset with tagsSample - Create new host asset with tags

API request

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

Request POST data

<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
    <data>
        <HostAsset>
            <name>My Windows Asset</name>
            <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>
            <tags>
                <set>
                    <TagSimple>
                        <id>12345</id>
                    </TagSimple>
                    <TagSimple>
                        <id>54321</id>
                    </TagSimple>
                </set>
            </tags>
            <software>
                <set>
                    <HostAssetSoftware>
                        <name>Photoshop</name>
                        <version>9</version>
                    </HostAssetSoftware>
                </set>
            </software>
        </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>My Windows Asset</name>
            <created>2018-09-06T19:16:35Z</created>
            <modified>2018-09-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>

Sample - Bulk creation of assetsSample - Bulk creation of assets

API request

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

Request POST data

<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
    <data>
        <HostAsset>
            <name>My Windows Asset</name>
            <os>Windows 8</os>
            <dnsHostName>localhost13</dnsHostName>
            <netbiosName>TEST</netbiosName>
            <netbiosNetworkId>10</netbiosNetworkId>
            <networkGuid>66bf43c8-7392-4257-b856-a320fde231eb</networkGuid>
            <address>13.0.0.1</address>
            <trackingMethod>IP</trackingMethod>
            <software>
                <set>
                    <HostAssetSoftware>
                        <name>Photoshop</name>
                        <version>9</version>
                    </HostAssetSoftware>
                </set>
            </software>
        </HostAsset>
        <HostAsset>
            <name>My Windows Asset</name>
            <os>Windows 8</os>
            <dnsHostName>localhost14</dnsHostName>
            <netbiosName>TEST</netbiosName>
            <netbiosNetworkId>10</netbiosNetworkId>
            <networkGuid>66bf43c8-7392-4257-b856-a320fde231eb</networkGuid>
            <address>14.0.0.1</address>
            <trackingMethod>IP</trackingMethod>
            <software>
                <set>
                    <HostAssetSoftware>
                        <name>Photoshop</name>
                        <version>9</version>
                    </HostAssetSoftware>
                </set>
            </software>
        </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>2</count>
    <data>
        <HostAsset>
            <id>2899060</id>
            <name>My Windows Asset</name>
            <created>2016-04-01T16:57:50Z</created>
            <modified>2016-04-01T16:57:50Z</modified>
            <type>HOST</type>
            <tags>
                <list/>
            </tags>
            <sourceInfo>
                <list/>
            </sourceInfo>
            <os>Windows 8</os>
            <dnsHostName>localhost13</dnsHostName>
            <netbiosName>TEST</netbiosName>
            <netbiosNetworkId>10</netbiosNetworkId>
            <networkGuid>66bf43c8-7392-4257-b856-a320fde231eb</networkGuid>
            <address>13.0.0.1</address>
            <trackingMethod>IP</trackingMethod>
            <openPort>
                <list/>
            </openPort>
            <software>
                <list>
                    <HostAssetSoftware>
                        <name>Photoshop</name>
                        <version>9</version>
                    </HostAssetSoftware>
                </list>
            </software>
            <vuln>
                <list/>
            </vuln>
            <processor>
                <list/>
            </processor>
            <volume>
                <list/>
            </volume>
            <account>
                <list/>
            </account>
            <networkInterface>
                <list>
                    <HostAssetInterface>
                        <hostname>localhost13</hostname>
                        <type>LOCAL</type>
                        <address>13.0.0.1</address>
                    </HostAssetInterface>
                </list>
            </networkInterface>
        </HostAsset>
        <HostAsset>
            <id>2899061</id>
            <name>My Windows Asset</name>
            <created>2016-04-01T16:57:51Z</created>
            <modified>2016-04-01T16:57:51Z</modified>
            <type>HOST</type>
            <tags>
                <list/>
            </tags>
            <sourceInfo>
                <list/>
            </sourceInfo>
            <os>Windows 8</os>
            <dnsHostName>localhost14</dnsHostName>
            <netbiosName>TEST</netbiosName>
            <netbiosNetworkId>10</netbiosNetworkId>
            <networkGuid>66bf43c8-7392-4257-b856-a320fde231eb</networkGuid>
            <address>14.0.0.1</address>
            <trackingMethod>IP</trackingMethod>
            <openPort>
                <list/>
            </openPort>
            <software>
                <list>
                    <HostAssetSoftware>
                        <name>Photoshop</name>
                        <version>9</version>
                    </HostAssetSoftware>
                </list>
            </software>
            <vuln>
                <list/>
            </vuln>
            <processor>
                <list/>
            </processor>
            <volume>
                <list/>
            </volume>
            <account>
                <list/>
            </account>
            <networkInterface>
                <list>
                    <HostAssetInterface>
                        <hostname>localhost14</hostname>
                        <type>LOCAL</type>
                        <address>14.0.0.1</address>
                    </HostAssetInterface>
                </list>
            </networkInterface>
        </HostAsset>
    </data>
</ServiceResponse>

Sample - Create host asset with tagsSample - Create host asset with tags

API request

curl -u "USERNAME:PASSWORD" -H "content-type: text/xml" -X "POST" -- "<qualys_base_url>/qps/rest/2.0/create/am/hostasset"< file.xml

Request POST data

<?xml version="1.0" encoding="UTF-8" ?>
<ServiceRequest>
    <data>
        <HostAsset>
            <name>Windows 95</name>
            <tags>
                <add>
                    <TagSimple>
                        <id>11175413</id>
                    </TagSimple>
                </add>
            </tags>
            <os>Windows 7</os>
            <dnsHostName>localhost</dnsHostName>
            <netbiosName>TEST</netbiosName>
            <netbiosNetworkId>10</netbiosNetworkId>
            <networkGuid>66bf43c8-7392-4257-b856-a320fde231eb</networkGuid>
            <address>255.255.255.0</address>
            <trackingMethod>IP</trackingMethod>
            <software>
                <set>
                    <HostAssetSoftware>
                        <name>Photoshop</name>
                        <version>9</version>
                    </HostAssetSoftware>
                </set>
            </software>
        </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/a
m/hostasset.xsd">
    <responseCode>SUCCESS</responseCode>
    <count>1</count>
    <data>
        <HostAsset>
            <id>7992387</id>
            <name>Windows 95</name>
            <created>2021-03-08T13:00:29Z</created>
            <modified>2021-03-08T13:00:29Z</modified>
            <type>HOST</type>
            <tags>
                <list>
                    <TagSimple>
                        <id>11175413</id>
                        <name>Static</name>
                    </TagSimple>
                </list>
            </tags>
            <os>Windows 7</os>
            <dnsHostName>localhost13</dnsHostName>
            <netbiosName>TEST</netbiosName>
            <netbiosNetworkId>10</netbiosNetworkId>
            <networkGuid>66bf43c8-7392-4257-b856-a320fde231eb</networkGuid>
            <address>255.255.255.0</address>
            <trackingMethod>IP</trackingMethod>
            <software>
                <list>
                    <HostAssetSoftware>
                        <name>Photoshop</name>
                        <version>9</version>
                    </HostAssetSoftware>
                </list>
            </software>
            <networkInterface>
                <list>
                    <HostAssetInterface>
                        <hostname>localhost13</hostname>
                        <type>LOCAL</type>
                        <address>255.255.255.0</address>
                    </HostAssetInterface>
                </list>
            </networkInterface>
        </HostAsset>
    </data>
</ServiceResponse>

XSD

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