POST /asset_model/configuration

Update asset configuration fields.

Warning: Tuning these configuration settings can be dangerous; modifying the wrong variable or executing the wrong query can lead to erratic system behavior and/or destabilization, errors in the log and ultimately data loss. PLEASE BE CAREFUL when reconfiguring these values and make sure you are confident with what you are doing BEFORE making changes.

Sets asset configuration settings to the values provided if they are within the valid range for each configuration setting.

Table 1. POST /asset_model/configuration resource details
MIME Type

application/json

Table 2. POST /asset_model/configuration request parameter details
Parameter Type Optionality Data Type MIME Type Description

fields

header

Optional

String

text/plain

Optional - Use this parameter to specify which fields you would like to get back in the response. Fields that are not named are excluded. Specify subfields in brackets and multiple fields in the same object are separated by commas.

Table 3. POST /asset_model/configuration request body details
Parameter Data Type MIME Type Description Sample

AssetConfiguration

Object

application/json

null

{ "asset_identity_coalescing": 42, "cleanup_policy": "String <one of: COMPONENT, ENTIRE_ASSET>", "client_application_profiling_enabled": true, "coalesce_ownership_changes": true, "dns_lookups_for_host_identity_enabled": true, "identity_profiling_enabled": true, "ip_reconciliation_blacklist_enabled": true, "maximum_asset_cleanup_batch_size": 42, "maximum_grey_list_port_per_asset": 42, "maximum_ip_address_per_asset": 42, "maximum_mac_address_per_asset": 42, "netbios_lookups_for_host_identity_enabled": true, "open_port_profiling_enabled": true, "profiler_audit_event_maximum": 42, "realtime_dns_enabled": true, "retain_assets_with_vulnerabilties": true, "system_retention": { "client_application": 42, "hostname": 42, "interfaces": 42, "ip": 42, "netbios": 42, "port": 42, "product": 42, "property": 42, "users": 42 }, "unified_name_preference": "String <one of: NETBIOS, DNS>", "user_retention": { "hostname": 42, "interfaces": 42, "ip": 42, "product": 42, "property": 42 } }

Table 4. POST /asset_model/configuration response codes
HTTP Response Code Unique Code Description

200

Asset configuration was updated.

422

2007

An invalid value is attempting to assign to profiler_audit_event_maximum field. The value should be positive integer and less than 1000000000000.

422

2008

An invalid value is attempting to assign to maximum_ip_address_per_asset field. The value should be positive integer and less than 1000000000000.

422

2009

An invalid value is attempting to assign to maximum_mac_address_per_asset field. The value should be positive integer and less than 1000000000000.

422

2010

An invalid value is attempting to assign to maximum_grey_list_port_per_asset field. The value should be positive integer and less than 1000000000000.

422

2011

An invalid value is attempting to assign to asset_identity_coalescing field. The value should be positive integer and less than 1000000000000 or null to retain data forever.

422

2012

An invalid value is attempting to assign to retention.system.interfaces field. The value should be positive integer and less than 1000000000000 or null to retain data forever.

422

2013

An invalid value is attempting to assign to retention.system.hostname field. The value should be positive integer and less than 1000000000000 or null to retain data forever.

422

2014

An invalid value is attempting to assign to retention.system.ip field. The value should be positive integer and less than 1000000000000 or null to retain data forever.

422

2015

An invalid value is attempting to assign to retention.system.property field. The value should be positive integer and less than 1000000000000 or null to retain data forever.

422

2016

An invalid value is attempting to assign to retention.system.product field. The value should be positive integer and less than 1000000000000 or null to retain data forever.

422

2017

An invalid value is attempting to assign to retention.system.port field. The value should be positive integer and less than 1000000000000 or null to retain data forever.

422

2018

An invalid value is attempting to assign to retention.system.netbios field. The value should be positive integer and less than 1000000000000 or null to retain data forever.

422

2019

An invalid value is attempting to assign to retention.system.client_application field. The value should be positive integer and less than 1000000000000 or null to retain data forever.

422

2020

An invalid value is attempting to assign to retention.system.users field. The value should be positive integer and less than 1000000000000 or null to retain data forever.

422

2021

An invalid value is attempting to assign to retention.user.interfaces field. The value should be positive integer and less than 1000000000000 or null to retain data forever.

422

2022

An invalid value is attempting to assign to retention.user.hostname field. The value should be positive integer and less than 1000000000000 or null to retain data forever.

422

2023

An invalid value is attempting to assign to retention.user.ip field. The value should be positive integer and less than 1000000000000 or null to retain data forever.

422

2024

An invalid value is attempting to assign to retention.user.property field. The value should be positive integer and less than 1000000000000 or null to retain data forever.

422

2025

An invalid value is attempting to assign to retention.user.product field. The value should be positive integer and less than 1000000000000 or null to retain data forever.

422

2026

An invalid value is attempting to assign to maximum_asset_cleanup_batch_size. The value should be positive integer and less than 1000000000000.

500

2001

An error occurred while attempting to assign a value to a variable.

500

2002

An error occurred while attempting to assign a value. The value was found to be outside the allowable range.

500

2003

An error occurred while interacting with the database.

500

2004

An error occurred while attempting to assign a value to a variable. The expected data type did not match the received type.

500

2005

An error occurred while attempting to retrieve a configuration setting. Invalid setting provided.

500

2006

An error occurred while attempting to assign a value to a variable. The provided value of null cannot be assigned to this configuration option.

Response Description

An updated AssetConfigDTO object. An AssetConfigDTO object contains the following fields:
  • realtime_dns_enabled - Boolean - Enables/disables Real-Time DNS Lookups for Asset Profiles.
  • profiler_audit_event_maximum - Long - Specifies the number of audit events per minute that are allowed to be generated by the asset profiler. Increasing the threshold increases audit throughput, but negatively impacts the system events per minute limit.
  • maximum_ip_address_per_asset - Long - Specifies the number of IPs allowed in a single asset profile before the asset profiler treats the asset as a 'vortex asset'.
  • maximum_mac_address_per_asset - Long - Specifies the number of MACs and empty interfaces allowed in a single asset profile before the asset profiler treats an asset as a 'vortex asset'.
  • unified_name_preference - Enum - When determining the unified name, whether the NetBIOS Name or DNS Name is preferred. There are 2 possible values for this configuration variable: If NetBIOS is selected, NetBIOS is preferred over DNS . The order is [ Given Name, NetBIOS Name, DNS Name, IP Address ]. If DNS is selected, DNS is preferred over NetBIOS . The order is [ Given Name, DNS Name, NetBIOS Name, IP Address ].
  • ip_reconciliation_blacklist_enabled - Boolean - Specifies whether the asset profiler should leverage the 'reconciliation blacklists'. When true, this setting compares incoming updates to the blacklists and excludes those that match. A 'blacklist' is a Reference Set that is populated by a suite of CRE rules which track asset data over time for identity information found to be associated with 3 or more other pieces of specific asset properties in a 2 hour (or less) time window.
  • maximum_grey_list_port_per_asset - Long - Specifies the maximum number of 'grey list' ports that a single asset can have. When an asset has hit the limit, no more new grey list ports are created for that asset, although new white list ports will still be created. Generally, a grey list port is a port that appears to be an open port but does not fall within the range of well-known service ports, also known as the 'white list'.
  • dns_lookups_for_host_identity_enabled - Boolean - Enables/disables DNS Lookups for host identity.
  • netbios_lookups_for_host_identity_enabled - Boolean - Enables/disables NetBIOS lookups for host identity.
  • identity_profiling_enabled - Boolean - Enables/disables identity profiling in the host profiler. Identity profiling is the act of gleaning identity from flows, where said flows are suspected of containing DNS or DHCP identity information.
  • client_application_profiling_enabled - Boolean - Enables/disables client application profiling in the host profiler. This setting should be turned off, in the case the client applications in the asset model are becoming too heavy.
  • open_port_profiling_enabled - Boolean - Enables/disables profiling open ports for a particular asset IP in the host profiler. This variable specifies whether the host profiler should perform the traditional job of profiling open ports for a particular IP.
  • asset_identity_coalescing - Long - Specifies the duration, in milliseconds, of an asset update coalescing window. This setting duplicate updates to asset identity received within the selected time interval will be merged.
  • coalesce_ownership_changes - Boolean - Enables/disables asset update coalescing when asset ownership is modified. Disable if there are custom rules that utilize asset data to ensure that duplicate updates reporting identity data transitioning from one asset to another are processed.
  • cleanup_policy - Enum - This setting retains all expired asset data until everything belonging to that asset has exceeded its threshold. To clean up asset data only when all of that asset's components have expired, set to "ENTIRE_ASSET". To clean up asset data individually as each component expires, set to "COMPONENT".
  • maximum_asset_cleanup_batch_size - Long - Specifies the size (in assets) of a logical transaction in which a batch of assets are 'cleaned'. This value is configurable as a safeguard against transactions that might otherwise exceed the maximum time allowed by DB connection pool. Generally, if the asset cleanup agent is not suffering connection pool problems, you do not need to change this config value.
  • retain_assets_with_vulnerabilties - Boolean - Allows/disallows the cleanup agent to permanently delete expired assets that still have vulnerabilities.
  • system_retention - Object - Specifies the retention period, in milliseconds, for an asset discovered by identity (events), the host profiler (flows) or a scanner.
    • interfaces - Long - Specifies the retention period, in milliseconds,for asset interfaces (MAC Addresses). This will be truncated from milliseconds into the number of days. To retain data forever, set to null.
    • hostname - Long - Specifies the retention period, in milliseconds, for asset DNS and NetBIOS hostnames . This will be truncated from milliseconds into the number of days. To retain data forever, set to null.
    • property - Long - Specifies the retention period, in milliseconds, for: Unified Name, Detection Confidence (legacy), Wireless AP, Wireless SSID, Switch ID, Switch Port ID, Extended, Old Cvss Risk (legacy), VLAN, Asset Type. This will be truncated from milliseconds into the number of days. To retain data forever, set to null.
    • product - Long - Represents the retention period, in milliseconds, for scanned asset products, including operating systems, windows applications and 3rd party products bound to open ports. This will be truncated from milliseconds into the number of days. To retain data forever, set to null.
    • ip - Long - Specifies the retention period, in milliseconds, for asset IP Addresses (IPv4 and IPv6). This will be truncated from milliseconds into the number of days. To retain data forever, set to null.
    • port - Long - Specifies the retention period, in milliseconds, for asset ports. This will be truncated from milliseconds into the number of days. To retain data forever, set to null.
    • netbios - Long - Specifies the retention period, in milliseconds, for NetBIOS groups associated with the asset. This will be truncated from milliseconds into the number of days. To retain data forever, set to null.
    • client_application - Long - Specifies the retention period, in milliseconds, of asset client applications. This will be truncated from milliseconds into the number of days. To retain data forever, set to null.
    • users - Long - Specifies the retention period, in milliseconds, for asset users. This will be truncated from milliseconds into the number of days. To retain data forever, set to null.
  • user_retention - Object - Specifies the retention period, in milliseconds, for an asset added manually by users.
    • interfaces - Long - Specifies the retention period, in milliseconds,for asset interfaces (MAC Addresses). This will be truncated from milliseconds into the number of days. To retain data forever, set to null.
    • hostname - Long - Specifies the retention period, in milliseconds, for asset DNS and NetBIOS hostnames . This will be truncated from milliseconds into the number of days. To retain data forever, set to null.
    • property - Long - Specifies the retention period, in milliseconds, for: Unified Name, Detection Confidence (legacy), Wireless AP, Wireless SSID, Switch ID, Switch Port ID, Extended, Old Cvss Risk (legacy), VLAN, Asset Type. This will be truncated from milliseconds into the number of days. To retain data forever, set to null.
    • product - Long - Represents the retention period, in milliseconds, for scanned asset products, including operating systems, windows applications and 3rd party products bound to open ports. This will be truncated from milliseconds into the number of days. To retain data forever, set to null.
    • ip - Long - Specifies the retention period, in milliseconds, for asset IP Addresses (IPv4 and IPv6). This will be truncated from milliseconds into the number of days. To retain data forever, set to null.

Response Sample


{
    "asset_identity_coalescing": 42,
    "cleanup_policy": "String <one of: COMPONENT, ENTIRE_ASSET>",
    "client_application_profiling_enabled": true,
    "coalesce_ownership_changes": true,
    "dns_lookups_for_host_identity_enabled": true,
    "identity_profiling_enabled": true,
    "ip_reconciliation_blacklist_enabled": true,
    "maximum_asset_cleanup_batch_size": 42,
    "maximum_grey_list_port_per_asset": 42,
    "maximum_ip_address_per_asset": 42,
    "maximum_mac_address_per_asset": 42,
    "netbios_lookups_for_host_identity_enabled": true,
    "open_port_profiling_enabled": true,
    "profiler_audit_event_maximum": 42,
    "realtime_dns_enabled": true,
    "retain_assets_with_vulnerabilties": true,
    "system_retention": {
        "client_application": 42,
        "hostname": 42,
        "interfaces": 42,
        "ip": 42,
        "netbios": 42,
        "port": 42,
        "product": 42,
        "property": 42,
        "users": 42
    },
    "unified_name_preference": "String <one of: NETBIOS, DNS>",
    "user_retention": {
        "hostname": 42,
        "interfaces": 42,
        "ip": 42,
        "product": 42,
        "property": 42
    }
}