Create Pipeline Rules with Assets

A set of pipeline rules can be used to set the associated assets field on a message, update existing assets, and retrieve asset information to further enrich messages. Asset-related pipeline functions allow you to do more with assets via processing pipelines.

`set_associated_assets`

This pipeline rule populates the associated_assets and associated_asset_categories fields on the message using GIM schema fields. The associated assets field will be an array with the ID of each asset that matches a field on the message to an asset field of the same type. The associated_assets field will determine which assets are displayed on the expanded log message on the search page. The associated_asset_categories field will be an array that includes all associated asset categories.

Machine Asset Message Fields

The following fields are used to associate machine assets:

IP Address Message Fields	MAC Address Message Fields	Hostname Message Fields
`source_ip`	`source_mac`	`source_hostname`
`source_ipv6`	`destination_mac`	`destination_hostname`
`source_nat_ip`		`host_hostname`
`destination_ip`
`destination_nat_ip`
`host_ip`
`vendor_private_ip`
`vendor_private_ipv6`
`vendor_public_ip`
`vendor_public_ipv6`
`event_observer_ip`

User Asset Message Fields

The following fields are used to associate user assets:

Username Message Fields	User ID Message Fields	Email Message Fields
`user_name`	`user_id`	`user_email`
`target_user_name`	`target_user_id`	`target_user_email`
`user_name_mapped`

Warning: This function uses an in-memory cache to limit the amount of DB calls required to associate an asset with a message.

`machine_asset_lookup`

This pipeline rule takes a lookup_type and value parameter. lookup_type can be either name, ip, mac, or hostname. The value field is the value used to look up the specified type. The rule assumes that the lookup will be unique, so if multiple assets happen to match the lookup, only one will be returned. If the lookup has a match, it will return a map with the following structure:

Copy

{
  "id": "string"
  "name": "string",
  "priority": number,
  "category": ["string", "array"],
  "details": {
    "type": "machine",
    "description": "string",
    "owner": "string",
    "ip_addresses": ["string", "array"],
    "mac_addresses": ["string", "array"],
    "hostnames": ["string", "array"],
    "custom_fields": Map
  }
}

The custom_fields map structure will depend on the custom fields defined for a given asset. Each entry will have a string key and an array of values that are either strings, dates, or numbers.

These fields can then be used to enrich the message in a more targeted way than the set_associated_assets rule. For example, to look up an asset by the source_ip field and then set fields on the message based on the asset returned would look similar to:

Copy

rule "machine_asset_lookup"
when
    has_field("source_ip")
then
    let asset = machine_asset_lookup(lookup_type:"ip", value:to_string($message.source_ip));
    let details = asset.details;
    set_field("asset_id", asset.id);
    set_field("asset_name", asset.name);
    set_field("asset_description", details.description);
    set_field("asset_ips", details.ip_addresses);
    set_field("asset_macs", details.mac_addresses);
    set_field("asset_hostnames", details.hostnames);
end

`machine_asset_update`

This rule will update IP addresses and hostnames of existing machine assets. The parameters are:

lookup_type: Either name, ip, mac, or hostname.
lookup_value: The value for the lookup_type.
ip_addresses: String or array of IP addresses to update the asset with [optional].
hostnames: String or array of hostnames to update the asset with [optional].

Copy

rule "machine_asset_update"
when
    true
then
    machine_asset_update(lookup_type:"mac", lookup_value:"AA:BB", ip_addresses:"10.0.0.0");
end

Using this rule on DHCP logs, for example, can keep existing assets up to date based on incoming logs.

Copy

rule "machine_asset_update"
when
    true
then
    machine_asset_update(lookup_type:"mac", lookup_value:$message.mac, ip_addresses:to_string($message.new_ip));
end

`user_asset_lookup`

This pipeline rule is used to look up a user asset and enrich log messages with user asset data. The rule takes a lookup_type and value parameter. lookup_type can be either name, username, user_id, or email. The value field is the value to be used in looking up the specified type. The rule assumes that the lookup will be unique, so if multiple assets happen to match the lookup, only one will be returned. If the lookup has a match, it will return a map with the following structure:

Copy

{
  "id": "string"
  "name": "string",
  "priority": number,
  "category": ["string", "array"],
  "details": {
    "type": "user",
    "description": "string",
    "username": "string",
    "user_ids": ["string", "array"],
    "email_addresses": ["string", "array"],
    "first_name": "string",
    "last_name": "string"
  }
}

These fields can then be used to enrich the message in a more targeted way than the set_associated_assets rule. For example, looking up an asset by the username field and then set fields on the message based on the asset returned would look similar to:

Copy

rule "user_asset_lookup"
when
    has_field(“username”)
then
    let asset = user_asset_lookup(lookup_type:"username", value:"username");
    let details = asset.details;
    set_field("asset_id", asset.id);
    set_field("asset_name", asset.name);
    set_field("asset_type", details.type);
    set_field("asset_username", details.username);
    set_field("asset_user_ids", details.user_ids);
    set_field("asset_emails", details.email_addresses);
end