Here you can filter host assets based on input parameters and then you can update host attributes using new update parameters (new_tracking_method, new_owner, new_ud1, new_ud2, new_ud3, and new_comment).
- With host update API, you can update host attributes like tracking method (IP, DNS, NETBIOS), owner, user defined fields (ud1, ud2, ud3), and comments.
- You cannot update an IP to use tracking method EC2 or AGENT. Also, if an IP is already tracked by EC2 or AGENT, you cannot change the tracking method to something else. We will skip the tracking method update in these cases.
As part of the update request you’ll need to tell us which hosts you want to update. You can do this in a number of ways. You can simply specify the host IDs, or you can specify IP addresses, asset group IDs or asset group titles. When specifying IP addresses or asset groups, there are additional optional input parameters available.
Specify hosts using one of these combinations of input parameters:
- ids (required) only
- ips (required) with any of these optional parameters: host_dns, host_netbios, network_id, network_name, tracking_method
- ag_ids (required) with or without tracking_method
- ag_titles (required) with or without tracking_method
These input parameters are described in more detail below.
Use new input parameters to tell us the host attributes you want to change. New input parameters include new_tracking_method, new_owner, new_ud1, new_ud2, new_ud3, and new_comment. The new values you specify will overwrite the existing values, and your changes will apply to all hosts included in the API request.
|
Parameter |
Required/Optional |
Data Type |
Description |
|---|---|---|---|
|
General |
|
||
|
action=update |
Required | String |
Specify action=update to update the host list. |
|
echo_request={0|1} |
Optional | Integer |
Specify 1 to view input parameters in the XML output. When unspecified, parameters are not included in the XML output. |
|
Host Filters |
|
||
|
ids={value} |
Optional | Integer |
Show only certain host IDs/ranges. One or more host IDs/ranges may be specified. Multiple entries are comma separated. A host ID range is specified with a hyphen (for example, 190-400).Valid host IDs are required. |
|
ips={value} -or- {POSTed CSV raw data} |
Integer/ File |
The hosts within the subscription you want to update. IPs must be specified by using the “ips” parameter (using the POST method) or by uploading CSV raw data (using the POST method). To upload CSV raw data, specify --data-binary <data>. One or more IPs/ranges may be specified. Multiple entries are comma separated. An IP range is specified with a hyphen (for example, 10.10.30.1-10.10.30.50). CIDR notation is supported. |
|
|
network_id={value} |
Valid only when the Network Support feature is enabled for the user’s account | Integer |
Restrict the request to a certain custom network by specifying the network ID. When unspecified, we default to “0” for Global Default Network. |
|
ag_ids={value} |
Optional | Integer |
Show only hosts belonging to asset groups with certain IDs. One or more asset group IDs and/or ranges may be specified. Multiple entries are comma separated. A range is specified with a dash (for example, 386941-386945). Valid asset group IDs are required. |
|
ag_titles={value} |
Optional | String |
Show only hosts belonging to asset groups with certain strings in the asset group title. One or more asset group titles may be specified. Multiple entries are comma separated (for example, My+First+Asset+Group,Another+Asset+Group). |
|
network_name={value} |
Valid only when the Network Support feature is enabled for the user’s account | String |
Restrict the request to a certain custom network by specifying the network name. |
|
tracking_method={value} |
Integer |
Show only IP addresses/ranges which have a certain tracking method. |
|
|
host_dns={value} |
String |
The DNS hostname for the IP you want to update. A single IP must be specified in the same request and the IP will only be updated if it matches the hostname specified. |
|
|
host_netbios={value} |
String |
The NetBIOS hostname for the IP you want to update. A single IP must be specified in the same request and the IP will only be updated if it matches the hostname specified. |
|
|
Host Changes |
|
||
|
new_tracking_method={value} |
Optional | String |
Change the tracking method. Specify IP for IP address, DNS or NETBIOS. Note - You cannot change the tracking method to EC2 or AGENT. If an IP is already tracked by EC2 or AGENT, you cannot change the tracking method to something else. |
|
new_owner={value} |
Optional | String |
Change the owner of the host asset(s). The owner must be a Manager. Another user (Unit Manager, Scanner, Reader) can be the owner if the IP address is in the user’s account. |
|
new_ud1={value} new_ud2={value} new_ud3={value} |
Optional | Boolean |
Change values for user-defined fields 1, 2 and 3. You can specify a maximum of 128 characters (ascii) for each field value. |
|
new_comment={value} |
Optional | String |
Change the user-defined comments. Specify new comments for the host asset(s). |
API Request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With:curl demo2" "POST" -d "action=update&ids=2332017&new_tracking_method=DNS&new_ud1=Loc&new_ud2=Fun&new_ud3=AT&new_comment=API_Comment&new_owner=user@123" "https://<qualys_base_url>/api/2.0/fo/asset/host/"XML Output
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE HOST_LIST_OUTPUT SYSTEM "https://<qualys_base_url>/api/2.0/fo/asset/host/dtd/update/output.dtd">
<HOST_UPDATE_OUTPUT>
<RESPONSE>
<DATETIME>2021-03-09T10:38:17Z</DATETIME>
<TEXT>Assets successfully updated</TEXT>
</RESPONSE>
</HOST_UPDATE_OUTPUT>API Request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With:curl demo2" "POST" -d "action=update&ips=10.10.32.31&new_tracking_method=DNS&new_ud1=Loc&new_ud2=Fun&new_ud3=AT&new_comment=API_Comment&new_owner=user@123" "https://<qualys_base_url>/api/2.0/fo/asset/host/"XML Output
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE HOST_LIST_OUTPUT SYSTEM "https://<qualys_base_url>/api/2.0/fo/asset/host/dtd/update/output.dtd">
<HOST_UPDATE_OUTPUT>
<RESPONSE>
<DATETIME>2021-03-09T06:03:42Z</DATETIME>
<TEXT>Assets successfully updated</TEXT>
</RESPONSE>
</HOST_UPDATE_OUTPUT>API Request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With:curl demo2" "POST" -d "action=update&ag_ids=4580719&new_tracking_method=IP&new_ud1=Loc&new_ud2=Fun&new_ud3=AT&new_comment=API_Comment&new_owner=user@123" "https://<qualys_base_url>/api/2.0/fo/asset/host/"XML Output
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE HOST_LIST_OUTPUT SYSTEM "https://<qualys_base_url>/api/2.0/fo/asset/host/dtd/update/output.dtd">
<HOST_UPDATE_OUTPUT>
<RESPONSE>
<DATETIME>2021-03-09T10:39:11Z</DATETIME>
<TEXT>Assets successfully updated</TEXT>
</RESPONSE>
</HOST_UPDATE_OUTPUT>API Request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With:curl demo2" "POST" -d "action=update&ag_titles=AG_Update&new_tracking_method=IP&new_ud1=Loc&new_ud2=Fun&new_ud3=AT&new_comment=API_Comment&new_owner=user@123" "https://<qualys_base_url>/api/2.0/fo/asset/host/"XML Output
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE HOST_LIST_OUTPUT SYSTEM "https://<qualys_base_url>/api/2.0/fo/asset/host/dtd/update/output.dtd">
<HOST_UPDATE_OUTPUT>
<RESPONSE>
<DATETIME>2021-03-09T10:39:43Z</DATETIME>
<TEXT>Assets successfully updated</TEXT>
</RESPONSE>
</HOST_UPDATE_OUTPUT><platform API server>/api/2.0/fo/asset/host/dtd/update/output.dtd