Update IP addresses in the user's subscription.
- Host attributes you can update include 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.
- You can update multiple IPs/ranges in the same request. The host attribute changes will apply to all IPs included in the action.
- When the Network Support feature is enabled, you can update IPs in a custom network or in the Global Default Network. Only one network ID can be specified per update request. When a network ID is not specified in the request, we default to a value of 0 for Global Default Network.
If Cloud (EC2, Azure, or GCP) or QAgent tracked hosts (IPs) are executed along with IP, DNS, or NETBios tracked hosts (IPs) for changing the tracking method, the Cloud or QAgent hosts will remain unchanged (Tracking method for cloud and Qagent hosts will not be changed).
Managers have permission to update any IP, in any network. Sub-users (who have permission to update IPs) can update IPs for networks in their user scope. A Unit Manager can update IPs in asset groups assigned to their business unit. Users with other roles (Scanner, Reader, Auditor) do not have permission to update IP addresses.
|
Parameter |
Required/Optional |
Data Type |
Description |
|---|---|---|---|
|
action=update |
Required | String |
Specify action to update Ips |
|
echo_request={0|1} |
Optional | Integer |
Specify 1 to view (echo) input parameters in the XML output. By default these are not included. |
|
ips={value} -or- {POSTed CSV raw data} |
Required | 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} |
Optional, and 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. |
|
tracking_method={value} |
Optional | String |
To change to another tracking method specify IP for IP address, DNS or NETBIOS. 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. |
|
host_dns={value} |
Optional | 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} |
Optional | Integer |
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. |
|
owner={value} |
Optional | String |
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. |
|
ud1={value} ud2={value} ud3={value} |
Optional | Integer |
Values for user-defined fields 1, 2 and 3. You can specify a maximum of 128 characters (ascii) for each field value. |
|
comment={value} |
Optional | String |
User-defined comments. |
API Request
curl -H "X-Requested-With: demo" -u "USERNAME:PASSWORD" -X "POST"-d "action=update&ips=10.10.10.200,10.10.23.40&tracking_method=DNS" "https://<qualys_base_url>/api/2.0/fo/asset/ip/"XML Output
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SIMPLE_RETURN SYSTEM "https://<qualys_base_url>/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
<RESPONSE>
<DATETIME>2018-04-07T17:27:36Z</DATETIME>
<TEXT>IPs successfully updated</TEXT>
</RESPONSE>
</SIMPLE_RETURN>IP 10.10.26.167 has multiple entries so we’re specifying the NetBIOS hostname in the request to identify which entry to update.
API Request
curl -H "X-Requested-With: demo" -u "USERNAME:PASSWORD" -X "POST"-d "action=update&ips=10.10.26.167&host_netbios=ORA10105-WIN-25&&comment=mycomment" "https://<qualys_base_url>/api/2.0/fo/asset/ip/"XML Output
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SIMPLE_RETURN SYSTEM "<qualys_base_url>/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
<RESPONSE>
<DATETIME>2018-05-02T05:23:15Z</DATETIME>
<TEXT>IPs successfully updated</TEXT>
</RESPONSE>
</SIMPLE_RETURN>(Applicable when the Network Support feature is enabled.) In this sample, network ID 2222 is specified in the request. The tracking method will be changed for the specified IPs in this network only.
API Request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST" -d "action=update&network_id=2222&ips=10.10.10.200,10.10.23.40&tracking_method=DNS" "https://<qualys_base_url>/api/2.0/fo/asset/ip/"XML Output
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SIMPLE_RETURN SYSTEM "<qualys_base_url>/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
<RESPONSE>
<DATETIME>2020-10-14T17:27:36Z</DATETIME>
<TEXT>IPs successfully updated</TEXT>
</RESPONSE>
</SIMPLE_RETURN>(Applicable when the Network Support feature is enabled.) In this sample, the sub-user is trying to update an IP address in a network that is not in their scope.
API Request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With: Curl" -X "POST" -d "action=update&network_id=55555&ips=10.10.10.10&comment=mycomment" "https://<qualys_base_url>/api/2.0/fo/asset/ip/"XML Output
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE SIMPLE_RETURN SYSTEM "<qualys_base_url>/api/2.0/simple_return.dtd">
<SIMPLE_RETURN>
<RESPONSE>
<DATETIME>2020-10-14T17:27:36Z</DATETIME>
<CODE>1905</CODE>
<TEXT>parameter network_id has invalid value: 55555 (No such network ID or not in user scope)</TEXT>
</RESPONSE>
</SIMPLE_RETURN>For the request below we’re updating IP 10.10.25.224. The duplicate host warning is returned because there are 2 asset records for IP 10.10.25.224.
API Request
curl -u "USERNAME:PASSWORD" -H "X-Requested-With: curl" -X POST -d "action=update&ips=10.10.25.224&tracking_method=IP" "https://<qualys_base_url>/api/2.0/fo/asset/ip/"XML Output
<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE DUPLICATE_HOSTS_ERROR_OUTPUT SYSTEM "https://<qualys_base_url>/api/2.0/fo/asset/ip/duplicate_hosts_error.dtd">
<DUPLICATE_HOSTS_ERROR_OUTPUT>
<RESPONSE>
<CODE>1982</CODE>
<DATETIME>2018-03-16T04:54:15Z</DATETIME>
<WARNING>
<TEXT>You cannot change the tracking method for the following host using the API since there are multiple scan data entries. This can happen when the host is resolved to different hostnames in different scan tasks. You'll need to change the tracking method using the UI. Use the URL to log into your account, edit the host and select another tracking method. At the prompt click Apply to save the most recent scan data and purge the other scan data.</TEXT>
<DUPLICATE_HOSTS>
<DUPLICATE_HOST>
<IP>10.10.25.224</IP>
<DNS_HOSTNAME>ora10105-win-25-224.qualys.com</DNS_HOSTNAME>
<NETBIOS_HOSTNAME>ORA10105-WIN-25</NETBIOS_HOSTNAME>
<LAST_SCANDATE>09/09/2016 at 13:35:29 (GMT)</LAST_SCANDATE>
<TRACKING>DNS</TRACKING>
</DUPLICATE_HOST>
</DUPLICATE_HOSTS>
<URL><![CDATA[https://<qualys_base_url>/fo/tools/ip_assets.php]]></URL>
</WARNING>
</RESPONSE>
</DUPLICATE_HOSTS_ERROR_OUTPUT><platform API server>/api/2.0/fo/asset/ip/duplicate_hosts_error.dtd"