Graylog Security’s asset management module allows you to track different types of assets across your environment and enrich messages with their information. Asset information can be manually added through the Graylog UI or synced through LDAP or Active Directory. Once asset information is added to Graylog, assets can be associated with specific log messages by enabling the Illuminate:Assets processing pack or a set of pipeline rules. Those associated assets can then be queried in the search UI and used in alerts.

Prerequisites

• A valid Graylog Security license is required. Contact the Graylog Sales team for more information on purchasing and downloading this license.

Asset Types

The following asset types are applicable to all assets managed by this feature:

Machine Assets

Machine assets represent different types of machines across your network: servers, personal computers, firewalls, etc.

User Assets

User assets represent the various system and human user accounts across your environment: usernames, user_ids, email_addresses, first_name, last_name, etc.

Create an Asset

1. To create assets in Graylog, navigate to the Security/Assets drop-down menu and choose Assets.

2. On the Assets page you will find two types of assets: machine and user. Select the desired asset type from the tab header.

3. Finally, click on the New Asset button; this will initiate the process for creating your specific asset.

Create a Machine Asset

To create machine assets, click on the New Asset button in the Machine Assets tab and a multi-tabbed editor comprising:General Info, Location and Custom Fields will be displayed. Fill out the necessary attributes. At a minimum, machine assets must have a Name and at least one IP Address, Hostname, or MAC Address.

General Info

• Name: The unique display name for the asset. This must be unique across all asset types.

• Owner: Person/Group who owns this machine.

• IP Addresses: IP addresses associated with the asset.

• Hostnames: Hostnames associated with the asset.

• MAC Addresses: MAC addresses of the asset.

• Category: Tags for the asset. A list of categories can be configured in the Assets > Config menu.

• Priority: Asset priority. A list of priorities can be configured in the Assets > Config menu.

Location

The physical location of the asset. These fields are not required.

Custom Fields

The custom fields section can be used to track any other necessary information about a machine asset as it allows for the inclusion of additional information required for machine assets beyond what is provided in the user interface. Each custom field has a name, type (string, date, or number), and a set of values.

Create a User Asset

User assets are created in a similar, single-page editor where you can fill out the attributes on the form. At a minimum user assets will need to have an Asset Name and at least one Username.

• Asset Name: The unique display name for the asset. This must be unique across all asset types.

• Category: Tags for the asset. A list of categories can be configured in the Assets > Config menu.

• Priority: Asset priority. A list of priorities can be configured in the Assets > Config menu.

• Usernames: Usernames associated to the user.

• User IDs: Unique identifiers for the user other than username. For example, a Windows SID or UUID.

• Email Addresses: Any email addresses associated with the user.

• First Name: User's first name.

• Last Name: User's last name.

Assign Asset Priorities and Categories

Each asset can be assigned a priority and multiple categories.

Priorities are used to classify importance of machine and user assets. For example, a user asset with a common account would likely warrant a lower priority than that of an admin user account with more privileged access to the network. There is a default list of priorities including Low, Medium, High, and Critical, which can be customized in the tab.

Categories are used as tags to group and sort assets. There are no default categories; users can either add from the tab or when creating or editing an asset. Once a category has been created through either method, it will become available in the Category drop-down list to be assigned to future assets.

Import Assets from AD/LDAP

In addition to creating assets manually, assets can be imported from external Active Directory or LDAP sources. Users have the capability to configure a connection to an Active Directory/LDAP server, configure filter options to target which user(s) or machine(s) to import from the AD/LDAP server, and control how the external entities are mapped to the Graylog asset schema.

A new Asset Sources tab has been added to the Assets tab header. This is where all asset sources are listed.

Create a New Asset Source

From the Asset Sources tab on the Assets page, new sources can be created by clicking on the New Source button and selecting which asset type to create from the drop-down options.

Existing sources can be edited by clicking on the ellipsis on a selected asset source and clicking on the Edit option.

When adding or editing an asset source, the following configuration form is presented where users fill out the required attributes for connection and mapping configurations.

• Title: A unique title for your source connection.

• Server Address: The IP or hostname of the AD or LDAP server.

• Port: The port on the AD or LDAP server to connect to. AD and LDAP use 389 and 636 by default.

• Transport Security: When connecting to the source server, you have the choice to use either TLS or Start TLS. It is highly advisable to utilize TLS for communication with your asset sources, as it guarantees encryption of asset details, ensuring their confidentiality.

• Verify Certificates: If TLS or Start TLS is selected, this controls whether or not to verify the certificates used with a Certificate Authority.

• System User DN: This is the username for the initial connection to the server, e.g. cn=admin,dc=example,dc=com. This might be optional depending on your server configuration

• System Password: The password for the initial connection to the server

• Description: An optional description of this asset source.

Users can then test the server connection by clicking on the Test Server Connection button to the right of the form, before proceeding to save the asset source.

Create an Asset Import Mapping

After setting up an asset source, users can create multiple queries to import specific subsets of data. For example, users can import "just the admin users" or "just the laptops." This is achieved by defining one or more import mapping configuration that determine which assets are imported from the parent source and how entries in LDAP or AD map to imported assets in the Graylog asset schema.

Once an established asset source is selected, users have access to all existing mapping configurations. Additionally, users can define a new mapping configuration by simply clicking the New Mapping button.

Clicking on the New Mapping button will bring up a form where users can configure their import options.

• Asset Type: The type of asset created in Graylog upon import.

• Mapping Title: A user-defined title for this import mapping configuration.

• Search Base DN: The base tree to limit the search for which entries to query from the asset source.

• Search Pattern: The search pattern to target which entries to import from the asset source.

• Categories/Priority: What asset categories and priority to assign to all assets imported with this mapping configuration.

• Description: A more detailed description of the mapping configuration.

• Asset Type Field Mappings: In this section, users define what source entry attribute field should map to each Graylog asset field. The configurable fields will vary based on the asset type selected. In the screenshot above, we see a User Asset Mapping form, which contains options for the fields corresponding to a Graylog User Asset.

Once values have been entered, a mapping configuration can be tested by clicking the Test Mapping button. This will perform a dry run import and present a sample of what imported assets will look like. Any needed changes can be made and re-tested before the configuration is saved and an actual import is initiated.

Import Assets

Once both connection and mapping configurations are saved, an asset import can be initiated by clicking on the Actions button and selecting the import option from the drop-down menu. This action will pull the targeted entries from the asset source, map them based on the mapping configuration, and create assets in Graylog that can be viewed from the Assets page.

Create Pipeline Rules with Assets

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

set_associated_assets

This pipeline rule populates the associated_assets field on the message using GIM schema fields. The field will set 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.

Machine Asset Message Fields

The following fields are used to associate machine assets:

User Asset Message Fields

The following fields are used to associate user assets:

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:

{
  "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:

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

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.

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:

{
  "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:

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

Associate Assets in Search Results

With the release of Graylog 5.2, an Illuminate version with a new assets processing pack for Illuminate was also introduced.

When the Illuminate bundle is activated, the pack will automatically run the set_associated_assets pipeline rule for all messages.

However, users have the option to specifically apply the set_associated_assets pipeline rule for a subset of logs. In this case, the user would not enable the Illuminate assets processing pack but rather would implement the set_associated_assets pipeline function themselves by putting the set_associated_assets in a pipeline rule, adding it to a pipeline, setting filters, and/or assigning it to a selected stream(s).

This functionality is customizable to the extent that users can either apply it to all logs by enabling the Illuminate processing pack or to a subset of their logs by manually configuring and applying the rule. Refer to our documentation on pipelines for more information on creating pipeline rules.

Once a message has been enriched with the associated_assets fields, those fields can be displayed in the expanded log view of an individual message. The details of each associated asset can then be expanded as well.

In addition to viewing the asset in search results, users now also have the capability to add an asset to the search query and to pivot into any log message associated with that asset.

Pivot to an Asset Search

This capability allows users to view an asset in search results and transition to exploring additional logs related to that specific asset for further investigation. For instance, if a log message identifies a finance department's computer as an asset, users can pivot and access all logs associated with that machine, allowing for a deeper delve into its activities. To pivot to an asset search, click the Add to query button for a particular asset to view all log messages for that asset.

Note that the asset ID is then added to the search query for the associated_assets field.

Search for Assets

On the Assets page, users have the capability to search for assets. This functionality allows users to create a search query based on asset information. Users can search for assets individually or in bulk.

To search for an individual asset, click on the ellipsis for the selected asset and choose the Search for asset option.

To perform bulk searches, choose the assets you want to search, then click on the Bulk Actions button and search for the selected assets.

Asset Management Use Cases

Scenario 1: Searching for Users/Machines

Let's say a user has two different user accounts (bill.murray and bmurray) as well as two different emails (bmurray@gmail.com and big.ern@kingpin.com). If we want to search across all logs for that user:

1. Navigate to the Security/Assets menu header and click on the User Assets tab. Then select the ellipsis next to the selected user asset.

2. Then select Search for Asset from the menu options.

3. The user will receive results for any message that contains any of the various user names or email addresses.

This same scenario applies to machine assets with multiple IP addresses, hostnames, etc.

Scenario 2: Searching for Additional Logs about a Machine after Spotting Suspicious Activity

While sifting through logs in Graylog, you see an unusual message and wants to see other logs from that specific machine or user. As an example, in the screenshot below, you see failed logins heading to a particular machine and want to see other messages from that machine. To do this, you could select the asset on the left and then Add to Query:

This will add the asset to the query, so now we are looking at logins just for that asset.