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.

To import an asset, you first need to establish a connection to an asset source. Configuration parameters can differ based on the source you choose. In this article we walk you through how to create and configure the connection between Graylog and an external source.

Import Assets

To import your assets from external sources, you first need to:

Create or configure an asset source.
Create a connection to the server.
Create an asset import mapping.
Initiate the import.

Create or Configure an Asset Source

To import your assets, you need to create a new asset source or configure an existing one. If you use an existing source, you can edit it by clicking the ellipsis on a selected asset source, then clicking the Edit option.

To create a new asset source:

Navigate to Assets > Sources.
Click the New Source button.
Select the desired source in the drop-down menu. Supported source types are: LDAP, Active Directory and Microsoft 365.

When adding or editing an asset source, follow the configuration wizard and fill out the required attributes for connection and mapping configurations.

Keep reading to learn more about these configuration options.

Configure Microsoft 365 Sources

Configuration parameters for Microsoft 365 differ from those required for LDAP and Active Directory sources.

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.
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, and select either an Intune or Defender filter (or both for machine assets) to target specific Microsoft machines when scheduling an asset sync.

Create a Connection to the Server

Enter the following information under Connection Configuration. The fields can differ based on the asset source type you choose.

Title: A unique title for your source connection.
Server Address: The IP address or hostname of the server. IPv4 and IPv6 are supported.
Port: The port on the server to connect to. Active Directory and LDAP use 389 and 636 by default.
Transport Security: When connecting to the source server, you should choose either TLS or Start TLS. It is highly advisable to use either form of 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 option controls whether to verify the certificates used with a Certificate Authority.
System User DN: The username for the initial connection to the server, e.g. cn=admin,dc=example,dc=com. This value might be optional depending on your server configuration.
System Password: The password for the initial connection to the server.
Description: An optional description of the asset source.

You can then test the server connection by clicking the Test Server Connection button to the right of the configuration wizard. Save the asset connection configurations, then proceed to configure asset mapping(s). If there is an error, you are presented with a warning box that states the problem. In this case, reconfigure the connection.

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 they lack the required permissions.

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.

Once 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 clicking on an asset source to reveal carousel cards that represent each mapping.

Mapping Configuration Parameters

The parameters below can differ according to the asset source type.

Asset Type: The type of asset created in Graylog upon import.
Mapping Title: A user-defined title for this import mapping configuration.
Search Base Distinguished Name: The base tree to limit the search for which entries to query from the asset source.
Search Pattern: The search pattern that determines 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.
User Asset Mapping: In this section, you define what source entry attribute field should map to each Graylog asset field. The configurable fields vary based on the asset type selected. In the screenshot above, we see a User Asset Mapping, which contains options for the fields corresponding to a Graylog User Asset.

Hint: If a user asset type is selected, one configurable field is User ID Attribute. The value entered should contain the name of the asset source attribute field that will be mapped to the created Graylog asset, e.g.(uid). In this case, when assets are imported, if a source entry has user123 in the User IDs field, then the created Graylog asset will also have user123 in its User IDs field. The configuration for mapping the Unique ID Attribute during Active Directory user asset import is hard-coded to use objectGUID as the Unique ID mapping value.

After you enter the values, you can test the mapping configuration by clicking the Test Mapping button. A dry run import is run and a sample of what imported assets will look like is presented. You can make changes and re-test before the configuration is saved and an actual import is initiated. If there is an error, you are presented with a warning box that states the problem. In this case, reconfigure the connection.

Initiate the Import

Once both connection and mapping configurations are saved, you can initiate an asset import by clicking the Actions button and selecting the Import option from the drop-down menu. 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.

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

When importing or syncing 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. Click on a source to view the available mappings.

To enable asset source sync:

Navigate to Assets > Sources.
Locate the asset.
Click on Edit found at the end of the corresponding row.
Click the Mappings configuration tab.
Scroll down and toggle to the Enable Sync option.
Click Save & Complete.

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

Roles and Permissions

The following user permissions are required for the management of asset sources and mappings:

asset:read: Viewing and listing asset sources.
asset:edit: Creating, editing, and deleting sources.
asset:read: Viewing and listing asset source mappings.
asset:create: Creating, editing, and deleting source mappings.
asset:manage_vulnerability_scanners: Creating, editing and deleting vulnerability scanners.

Create a New Asset

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

Select Assets from the top-level menu.
Toggle to the desired asset type (user/machine) in the tab header.
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.

Once a category has been created through either method, it becomes available in the Category drop-down list to be assigned to future assets. To assign a category to multiple assets:

Select your assets on the Assets page.
Click on the Bulk Actions button.
Click Add Category.
Select the desired category.
Click Confirm.