Update IPs
Click here to see this page in full context

Update IPs

GET POST/api/2.0/fo/asset/ip/?action=update

Update IP addresses in the user's subscription.

Good to Know

- 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.

Permissions

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.

Input ParametersInput Parameters

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.

Sample - Add IPs and Assign Tracking MethodSample - Add IPs and Assign Tracking Method

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>

Sample - Update IP with Matching NetBIOS NameSample - Update IP with Matching NetBIOS Name

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>

Sample - Update IPs in Custom NetworkSample - Update IPs in Custom Network

(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>

Sample - Network ID is not in User's ScopeSample - Network ID is not in User's Scope

(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>

Sample - Duplicate Host ErrorSample - Duplicate Host Error

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>

DTD

<platform API server>/api/2.0/fo/asset/ip/duplicate_hosts_error.dtd"