sonar-set-ip-address

Batch-inserts or updates IP addresses and specified field values from input records in the asset IP database. Existing IP addresses are updated with values from input records; IP addresses that are not yet registered are created.

Command properties

Item	Description
Command type	Transforming
Required permission	Administrator
License usage	N/A
Parallel execution	Not supported
Distributed execution	Runs on Control Node (reducer)

Syntax

sonar-set-ip-address fields=STR [batchsize=INT] [company=STR]

Options

fields=STR

Comma-separated list of field names to synchronize. The available field names are: priority, confidentiality, integrity, availability, category_name, hostname, workgroup, emp_key, emp_key2, description, os_name, os_ver, mac, location, installed, ext0, ext1, ext2, ext3, ext4, ext5, ext6, ext7, ext8, ext9, site_guid

⚠️ Priority (priority) and the confidentiality, integrity, and availability (confidentiality, integrity, availability; CIA) scores cannot be used together.

When you specify priority alone, the three CIA scores are set to the same value as priority.
To use CIA, you must specify all three fields. Specifying only one or two raises an error. In that case, priority is calculated automatically from the sum of the three scores (High if the sum is greater than 7, Medium if greater than 4, otherwise Low).
When creating a new asset, if you specify neither priority nor CIA, the asset's priority and CIA scores are not set.

batchsize=INT

Batch unit size for inserting IP addresses. Specify a value in the range 1–5,000. For large-scale IP synchronization, increasing the batch size reduces the number of transactions and improves performance. However, if an error occurs, the entire batch fails to synchronize. (Default: 1)

company=STR

GUID of the target company to insert asset IPs into. If not specified, the current session's company is used.

Note

The system account does not belong to any company. Queries that run with system account privileges must explicitly specify the target company using this option.

Input fields

Field	Type	Required	Description
ip	string, ipaddr	Required	IP address. Both string and IP address types are accepted.
priority	string	Optional	Priority. `low`, `medium`, `high`. Cannot be used together with the CIA fields.
confidentiality	string	Optional	Confidentiality. `low`, `medium`, `high`. Specify together with `integrity` and `availability`.
integrity	string	Optional	Integrity. `low`, `medium`, `high`. Specify together with `confidentiality` and `availability`.
availability	string	Optional	Availability. `low`, `medium`, `high`. Specify together with `confidentiality` and `integrity`.
category_name	string	Optional	Device category name. Treated as uncategorized if not found in the internal category list.
hostname	string	Optional	Host name (max 255 characters)
workgroup	string	Optional	NT domain or workgroup (max 255 characters)
emp_key	string	Optional	Primary contact employee ID (max 255 characters). Ignored if not found in the employee table.
emp_key2	string	Optional	Secondary contact employee ID (max 255 characters). Ignored if not found in the employee table.
description	string	Optional	Notes (max 2,000 characters)
os_name	string	Optional	Operating system name (max 50 characters)
os_ver	string	Optional	Operating system version (max 20 characters)
mac	string	Optional	MAC address (max 20 characters)
location	string	Optional	Installation location (max 255 characters)
installed	timestamp	Optional	Installation date and time
site_guid	string	Optional	Site GUID
ext0 ~ ext9	string	Optional	Extended fields (max 255 characters each)

Output fields

Field	Type	Description
_error	string	Error detail. `ip is null` if the `ip` field is null; `invalid ip` if the IP format is invalid.

All fields from the input record are output unchanged. The _error field is added only for records where an error occurred.

Error codes

Parse errors

Error code	Message	Description
300501	No permission to update IP address objects.	The user does not have administrator permission.
300502	sonar-set-ip-address's company option is illegal GUID format.	The `company` option value is not a valid GUID.
300503	Can't find a company by the GUID for sonar-set-ip-address.	No company exists for the specified `company` GUID.
300504	sonar-set-ip-address's batchsize option should be specified in the range 1 to 5000.	The `batchsize` value is outside the range 1–5,000 or is not an integer.
300505	Specify fields option to the sonar-set-ip-address command. Use priority, confidentiality, integrity, availability, category_name, hostname, workgroup, emp_key, emp_key2, description, os_name, os_ver, mac, location, installed, ext0, ext1, ext2, ext3, ext4, ext5, ext6, ext7, ext8, ext9, site_guid fields.	The `fields` option is not specified.
300506	[field] field is not supported.	The `fields` option contains an unsupported field name.
300507	[company] option is needed.	The command was run under a system account without the `company` option.
300508	Invalid field combination. Use either 'priority' alone or all three 'confidentiality', 'integrity', 'availability' together.	`priority` and the CIA fields were specified together, or only some of the CIA fields were specified.

Runtime errors

N/A

Description

The sonar-set-ip-address command looks up the asset IP database using the ip field value in each input record. If the IP address is already registered, it updates the field values specified in the fields option. If the IP address is not yet registered, it creates a new entry.

The ip field is always required and is automatically included even if not specified separately in the fields option. If the ip field value is null or not a valid IP address, synchronization for that record is skipped and the error detail is recorded in the _error field.

If a field specified in the fields option does not exist in the input record, that field's value is updated to null. Conversely, fields that exist in the input record but are not specified in the fields option are not synchronized.

When the batchsize option is used, records are collected in batches of the specified size and processed together. If an error occurs during batch processing, the _error field of all records in the same batch is populated with the error detail.

Tip

You can customize the extended fields (ext0–ext9) for asset IPs using the following Logpresso shell command under global Sonar settings:
logpresso> sonar.setGlobalOption ip_custom_fields "0=Manufacturer,1=Model"

Examples

Synchronize asset IPs

json "[{'ip': '192.0.2.1', 'hostname': 'web-01', 'os_name': 'Linux', 'priority': 'medium'}, {'ip': '192.0.2.2', 'hostname': 'db-01', 'os_name': 'Linux', 'priority': 'high'}]"
| sonar-set-ip-address fields="hostname, os_name, priority"

Synchronizes the values of the hostname, os_name, and priority fields to the asset IP database.

Synchronize in bulk with a batch size

json "[{'ip': '192.0.2.1', 'hostname': 'web-01', 'os_name': 'Linux', 'mac': '00:11:22:33:44:55', 'priority': 'medium'}, {'ip': '192.0.2.2', 'hostname': 'db-01', 'os_name': 'Linux', 'mac': 'aa:bb:cc:dd:ee:ff', 'priority': 'high'}]"
| sonar-set-ip-address batchsize=100 fields="hostname, os_name, mac, description, priority"

Processes the asset IP information in batches of 100 records. When creating a new asset, specify priority (or the CIA fields) so that the priority score is set.

Specify the company GUID explicitly

json "[{'ip': '198.51.100.1', 'hostname': 'fw-01', 'category_name': 'Firewall', 'priority': 'high'}]"
| sonar-set-ip-address company=550e8400-e29b-41d4-a716-446655440000 fields="hostname, category_name, priority"

Synchronizes to the asset IP database of a specific company.

Synchronize using CIA scores
```
json "[{'ip': '198.51.100.1', 'hostname': 'fw-01', 'confidentiality': 'high', 'integrity': 'medium', 'availability': 'high'}]"
| sonar-set-ip-address fields="hostname, confidentiality, integrity, availability"
```
Synchronizes by specifying confidentiality, integrity, and availability (CIA) scores. When the CIA fields are used, priority is calculated automatically from the sum of the three scores.

Compatibility

The sonar-set-ip-address command has been available since before Sonar 4.0.