Translate LDAP Attribute

Stack

The translate_ldap_attribute processor translates LDAP attributes into friendlier values. The typical use case is converting an Active Directory Global Unique Identifier (GUID) into a human-readable name (for example the object's cn).

Every object on an Active Directory or an LDAP server is issued a GUID. Internal processes refer to their GUID’s rather than the object's name and these values sometimes appear in logs.

If the search attribute is invalid (malformed) or does not map to any object on the domain the processor returns an error unless ignore_failure is set.

The result of this operation is an array of values, given that a single attribute can hold multiple values.

The search attribute is expected to map to a single object. If multiple entries match, only the first entry's mapped attribute values are returned.

processors:
  - translate_ldap_attribute:
      field: winlog.event_data.ObjectGuid
      ignore_missing: true
      ignore_failure: true
      # ldap_domain: "example.com"  # Optional - override the OS-discovered domain used for SRV/LOGONSERVER hints
      # ldap_address: "ldap://ds.example.com:389"
      # ldap_base_dn: "dc=example,dc=com"
		

1. Optional - Beats discovers controllers when omitted
2. Optional - otherwise rootDSE and hostname inference are used

The translate_ldap_attribute processor has the following configuration settings:

Beats attempts LDAP authentication in the following order:

1. Simple bind using ldap_bind_user and ldap_bind_password when both are supplied.
2. Automatic bind when both values are empty. On Windows Beats creates an SSPI (Kerberos/NTLM) client for the SPN ldap/<hostname derived from ldap_address>, which works for Local System, domain-joined services, and gMSA accounts. Other platforms do not yet implement automatic authentication.
3. If automatic authentication is unavailable or fails, Beats issues an unauthenticated bind. When ldap_bind_user is set without a password that identity is used; otherwise Beats binds anonymously.

Always prefer specifying ldap_address as an FQDN (for example ldap://dc1.example.com:389) so the SPN built for SSPI matches the controller's service principal and TLS certificates.

When ldap_address is omitted Beats resolves controllers dynamically:

1. Domain discovery. Beats determines the DNS domain from ldap_domain (if set) or OS metadata. Windows checks USERDNSDOMAIN, GetComputerNameEx, the TCP/IP and Kerberos registry keys, and the machine's FQDN. Linux/macOS read /etc/resolv.conf, /etc/krb5.conf, and the hostname suffix. If no domain is available SRV lookups are skipped.
2. DNS SRV queries. When a domain is known Beats queries _ldaps._tcp.<domain> first and _ldap._tcp.<domain> second using the system resolver. Results are sorted by priority/weight per RFC 2782 and converted to ldaps://host:port or ldap://host:port URLs.
3. Windows LOGONSERVER fallback. If SRV queries return no controllers or no domain was discovered, Beats reads the LOGONSERVER environment variable. When a domain is known the NetBIOS name is combined with it to build an FQDN so TLS validation and SSPI SPNs remain valid.

Each candidate address is attempted in order (LDAPS before LDAP) until a connection and bind succeed.

When ldap_base_dn is empty the client queries the controller's rootDSE for defaultNamingContext or the first non-system namingContexts entry. If neither is present Beats cannot continue and you must provide ldap_base_dn explicitly.

If the searches are slow or you expect a high amount of different key attributes to be found, consider using a cache processor to speed processing:

processors:
  - cache:
      backend:
        memory:
          id: ldapguids
      get:
        key_field: winlog.event_data.ObjectGuid
        target_field: winlog.common_name
      ignore_missing: true
  - if:
      not:
        - has_fields: winlog.common_name
    then:
      - translate_ldap_attribute:
          field: winlog.event_data.ObjectGuid
          target_field: winlog.common_name
          ldap_address: "ldap://"
          ldap_base_dn: "dc=example,dc=com"
      - cache:
          backend:
            memory:
              id: ldapguids
            capacity: 10000
          put:
            key_field: winlog.event_data.ObjectGuid
            value_field: winlog.common_name