Import and Configure Assets

The following article exclusively pertains to a Graylog Security feature or functionality. Graylog Security is a part of the Graylog centralized log management platform and requires a separate license. Contact the Graylog Sales team for more information on this product.

Before assets can be used to enrich your log data, you must first import and configure assets in Graylog. Assets can be any of a variety of machine or user entities in your environment, as defined in Asset Enrichment.

In this article we walk you through how to configure the connection between Graylog and an external asset source and how to import assets into Graylog.

Prerequisites

Before proceeding, ensure that the following prerequisites are met:

  • A valid Graylog Security license.

  • You need access credentials and configuration information for any asset sources you want to connect.

Import Assets

The basic steps to import an asset are as follows:

  1. Create or configure an asset source, which requires two parts:

    1. Create a connection to the asset (server configuration).

    2. Create an asset import mapping.

  2. Initiate the import.

These steps are described in detail below.

Create or Configure an Asset Source

You need to create a new asset source or configure an existing source before you can import assets. If you use an existing source, you can edit it by clicking the ellipsis on the source, then selecting Edit from the dropdown.

To create a new asset source:

  1. In the Security layout, navigate to Assets, then select the Sources tab.

  2. Click New Source.

  3. Select the source type from the dropdown. Supported source types are LDAP, Active Directory, and Microsoft 365.

Configuration options are different based on the source type. Configuration for LDAP and Active Directory follow the same options, while Microsoft 365 configuration is a different set of options. Skip to the section below for the type of source you are configuring.

Configure LDAP and Active Directory Sources

Server configuration information is the same for both LDAP and Active directory. You need to provide credentials from your Microsoft account. Check Microsoft documentation for details. Follow these steps under Connection Configuration:

  1. Enter the following information.

    Title

    Enter a unique name for the source connection.

    Server Address

    Enter the server address to connect to the source. IPv4 and IPv6 are supported. You can enter this value as an IP address or a fully qualified domain name (FQDN).

    Port

    Enter the port number for the server.

    Transport Security

    Select security options for communication between Graylog and the asset source.

    Choose an encryption method:

    • None: No encryption is used.

    • TLS: Communication is secured by TLS.

    • StartTLS: Uses a secure connection if available but allows for an insecure connection.

    Verify Certificates: If you select either TLS or Start TLS, this option controls whether to verify the certificates used with a Certificate Authority.

    System User DN

    Enter the username for initial connectionto the server, for example: cn=admin,dc=example,dc=com. This value might be optional depending on your server configuration.

    System Password

    Enter the password for the initial connection to the server.

    Description (optional)

    Add a meaningful description.

  2. Click Test Server Connection to validate the connection with the entered credentials. Resolve any errors before proceeding.

    Warning: Asset import can fail even if the initial connection test succeeds. This failure could happen if the system user is incorrectly configured or if the user lacks the required permissions.

  3. Click Save Connection to save the asset connection configurations.

You can now proceed to configure asset mappings for this source.

Configure Microsoft 365 Sources

Configuration parameters for Microsoft 365 differ from those required for LDAP and Active Directory sources. However, Microsoft 356 connections also offer additional benefits:

  • A Microsoft 365 source allows vulnerabilities to be imported along with assets if the Include Vulnerabilities check box is enabled on the Mapping Configuration page. See Vulnerability Scanning for more information.

  • You can choose to add Entra ID filters for user assets, and Entra ID, Intune, or Defender filters to target specific Microsoft machines when importing.

You are required to enter credentials on the Connection Configuration page that identify the tenant and client application. These credentials can be found in your Microsoft 365 client application. Refer to Microsoft 365 Setup for details on how to establish a connection between the Microsoft 365 API and the Graylog server.

Follow these steps under Connection Configuration:

  1. Enter the following information.

    Title

    Enter a unique name for the source connection.

    Directory (tenant) ID

    Enter the Globaly Unique Identifier (GUID) of the tenant to which the content belongs.

    Client ID

    Enter the GUID of your application that created the subscription.

    Client Secret

    Enter a secret string that the application uses to prove its identity when requesting a token

    Subscription Type

    Select your organization's Microsoft 365 subscription plan from the dropdown.

    Description (optional)

    Add a meaningful description.

  2. Click Test Server Connection to validate the connection with the entered credentials. Resolve any errors before proceeding.

    Warning: Asset import can fail even if the initial connection test succeeds. This failure could happen if the system user is incorrectly configured or if the user lacks the required permissions.

  3. Click Save Connection to save the asset connection configurations.

You can now proceed to configure asset mappings for this source.

Create an Asset Import Mapping

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

After an asset connection is established, you have access to all existing mapping configurations. You can then continue with the configuration wizard to define mapping configurations.

A mapping configuration allows you to define the specific assets that you want to import from a source. It also gives you the option to determine what default values are applied.

For example, you can have an LDAP server with two different mappings. One mapping is configured to select only admin users and has an admin category as well as a high priority category. When you import admin users via this mapping, all of the assets have the same priority and category.

You can set up another mapping that selects general users and uses a medium or low priority. You can set up a high priority mapping for accounting machines and a low priority mapping for user laptops. Configuration parameters can be applied to machine assets and user assets.

You can also configure an asset source sync interval on the mapping configuration page.

Hint: If you have a Microsoft 365 source, you can choose to add Entra ID, Intune, and Defender filters to target specific Microsoft machines.

Mappings can also be edited or deleted on the Sources page by selecting an asset source to reveal carousel cards that represent each mapping.

Mapping Configuration Parameters

Enter the following general information for asset mappings on the Mappings Configuration form:

Asset Type

Select either machine asset or user asset for the source type of the mapping you are creating.

Mapping Title

Enter a unique title for this configuration.

Search Base DN

(AD/LDAP assets only) Enter the base tree to limit the search for which entries to query from the asset source. This entry is written in the form: ou=people,dc=example,dc=com

Search Pattern

(AD/LDAP assets only) Enter the search pattern that determines which entries to import from the asset source.

Categories

(optional) Assign a category by selecting from the dropdown. You can create or update the category list on the Config tab.

Priority

(optional) Select a priority level from the dropdown. This value affects the risk score of the asset. You can update the category list on the Config tab.

Description

(optional) Enter a detailed description of the mapping configuration.

Enable Sync

Slide this toggle to enable or disable automatic synchronization of assets. To learn about using this feature, see Schedule an Asset Source Sync.

Sync Interval in Hours

Set the interval between syncs if you enable automatic synchronization.

The additional information required depends on the asset source type and whether it is a user asset or machine asset. Skip to the section below for the type of asset you are configuring.

Active Directory and LDAP User Asset Mapping

In the User Asset Mapping section, you define what source entry attribute field should map to each Graylog user asset field. Include the following information:

User ID Attribute

Enter the name of the asset source attribute field that maps to the created Graylog asset, for example uid.

  • For Active Directory, this value is set automatically to objectGUID and cannot be changed. This value is what Active Directory uses as its unique User ID.

  • For LDAP, enter a globally unique identifier for a user, which might be in the form of a GUID or numeric ID.

When assets are imported, if a source entry has, for example, user123 in the User IDs field, then the created Graylog asset also has user123 in its User IDs field.

Username Attribute

Enter the logon username for the account:

  • For Active Directory, this value is typically mapped to sAMAccountName or userPrincipalName.

  • For LDAP, this value is typically mapped to uid.

This value cannot be modified after the first import.

User First Name Attribute

Enter the first or given name for users, if available. This value is typically the givenName attribute.

User Last Name Attribute

Enter the last name or surname for users, if available. This value is typically the sn attribute.

User Full Name Attribute

Enter the full display name of the user, generally stored in the displayName attribute.

Hint: If either User First Name Attribute or User Full Name Attribute include values, those values take precedence over this one.

Email Attributes

Enter email attributes for users:

  • For Active Directory, typically mail (primary) and proxyAddresses (alias/secondary).

  • For LDAP, typically mail (primary) and mailAlternateAddress (alias/secondary).

Note that you can include multiple attributes in this field by pressing Enter or Tab.

Active Directory and LDAP Machine Asset Mapping

In the Machine Asset Mapping section, you define what source entry attribute field should map to each Graylog machine asset field. Include the following information:

Asset Name

Enter a unique identifier for the machine.

Host Name Attributes

Enter the name of a computer or machine object. This value is typically stored in dNSHostName (Active Directory) or cn (LDAP).

Note that you can include multiple values in this field by pressing Enter or Tab.

IP Address Attributes

Enter the IP address for the machine. Note that you can include multiple values in this field by pressing Enter or Tab.

MAC Address Attributes

Enter the MAC address for the machine. Note that you can include multiple values in this field by pressing Enter or Tab.

Owner

(Optional) Enter the attribute that maps to the asset owner:

For Active Directory, this value is typically managedBy.

For LDAP, this value is typically owner or manager.

Microsoft 365 User and Machine Mapping

In the mapping section for Microsoft 365, you define filters to apply to the imported source:

  • For user assets, you can apply only Entra ID filters.

  • For machine assets, you can apply Entra ID, Intune, and Defender filters.

For each category, you enter the filter as a search query that limits the data returned. If you want to return all data, enter the wildcard character (*). See the Microsoft documentation for how to construct filter queries.

Test Your Mapping Configuration

After you enter the values, you can test the mapping configuration by clicking the Test Mapping button. A test import is run and you receive a sample of what imported assets will look like. You can make changes and re-test before you save the configuration and initiate an actual import.

If there is an error, you are presented with a warning box that states the problem. In this case, you need to troubleshoot and reconfigure the connection before you can import assets.

Initiate the Import

When both connection and mapping configurations are saved, you can initiate an asset import. Click the Actions button, then select Import from the dropdown. This action pulls the targeted entries from the asset source, maps them based on the mapping configuration, and creates assets in Graylog that can be viewed from the Assets page.

Hint: For LDAP and Active Directory assets, Graylog uses internal paging for imports. These sources are often limited to imports of 1000 assets at a time. By default, the page size in Graylog is set to 500, which should avoid issues in most environments. However, if you need to adjust page size, you can set the ad_ldap_page_size property in your server.conf file to a value that works for your system.

Click a source on the Sources page to view or edit its configuration.

When you import or sync an asset, it's name remains the same as in the source. Any subsequent imports or syncs match existing assets by name and update all of the details from the backend. This way, the asset remains constant and searching is unaffected.

Warning: Assets that are imported through a mapping are deleted if the corresponding asset in the source is deleted.

Schedule an Asset Source Sync

The asset source sync functionality performs the same actions as asset import. An update in the source is automatically reflected in Graylog via the asset sync. This can be either an update in the source or removal of an asset or assets. All changes made in the source are reflected in Graylog.

You can schedule the import of assets by defining an interval. Asset source sync is available for all mappings listed under a source. Select a source to view the available mappings.

To enable asset source sync:

  1. Navigate to Assets > Sources.

  2. Locate the asset.

  3. Click Edit found at the end of the corresponding row.

  4. Click the Mappings configuration tab.

  5. Scroll down and toggle to the Enable Sync option.

  6. Click Save & Complete.

The default sync interval is in hours and can be modified.

Roles and Permissions

Graylog includes two roles specific to managing or working with assets:

  • Asset Manager: Grants read/write access to all assets. This role is required to create asset sources, import assets, and all other management functions for assets. Note that this role's permissions are included for all Admin users but you can assign the role to any non-Admin users you want to have elevated permissions for assets.

  • Asset Reader: Grants read-only access to assets. This role is sufficient for users who do not need to manage assets.

The following permissions are included in the above roles and are required for the management of asset sources and mappings as follows:

  • asset:read: Viewing and listing asset sources and asset source mappings.

  • asset:edit: Creating, editing, and deleting sources.

  • asset:create: Creating, editing, and deleting source mappings.

  • asset:manage_vulnerability_scanners: Creating, editing, and deleting vulnerability scanners.

The Asset Reader role includes only the asset: read permission, while Asset Manager includes all of these permissions.

Create a New Asset

You can create a new asset through the Graylog Security user interface manually. To do so:

  1. Select Assets from the top-level menu.

  2. Toggle to the desired asset type (user/machine) in the tab header.

  3. Click the New Asset button.

Create a New Machine Asset

To create machine assets, navigate to Assets > Machines then click the New Asset button. Follow the configuration wizard to configure a new machine asset. At a minimum, machine assets must have a name and at least one IP address, hostname, or MAC address.

Configuration Parameters

General Info

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

  • Owner: Person or group who owns this machine.

  • IP Addresses: IP addresses associated with the asset. Both IPv4 and IPv6 are supported.

  • Hostnames: Hostnames associated with the asset.

  • MAC Addresses: MAC addresses of the asset.

  • Categories: 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.

  • Description: Provide a description of the asset.

Location

This section includes fields related to the physical location of the asset. These fields are optional.

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.

Hint: Tracking historical changes made to an asset over time can be performed in audit logs by searching for the asset ID. Changes can also be tracked using the Custom Fields section. For example, if a machine asset is passed from one owner to the next, a list of previous owners can be tracked in a custom string field. You can create a custom field under Custom Fields when creating or editing an asset.

Create a New User Asset

To create user assets, navigate to Assets > Users then click the New Asset button. Follow the configuration wizard to configure a new user asset. At a minimum, user assets need to have an asset name and at least one username.

Configuration Parameters

  • Asset Name: The unique display name for the asset. This name 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.

Manage Asset Configurations

The Config menu found on the Assets page gives you the ability to manage asset priorities and categories. Each asset can be assigned a priority and multiple categories.

Manage Asset Priority

Priorities are used to classify the importance of machine and user assets. For example, a user asset with a basic account would likely have 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.

Hint: The asset priority that is set here directly affects the asset risk score. If it is set low, the asset risk score will also be low.

Manage Asset Category

Categories are used as tags to group and sort assets. There are no default categories. You can add a category in two places:

  • Config tab: Edit or create a new category in the Config tab.

  • New asset configuration modal: Directly type in a new category in the Categories field when creating or editing an asset.

When a category is created through either method, it becomes available in the Category dropdown to be assigned to future assets. To assign a category to multiple assets:

  1. Select your assets on the Assets page.

  2. Click the Bulk Actions button.

  3. Click Add Category.

  4. Select the desired category.

  5. Click Confirm.