Design: Domain controller discovery support in windowseventlogreceiver for centralized Security event collection

[pankaj101A]

Component(s)

receiver/windowseventlog

Issue

Proposed Solution

Implement an automated discovery mechanism with two sequential steps:

Step 1: LDAP Domain Path Discovery

Determine the root domain path of the Active Directory service on the collector's host machine.

Primary Method: Query Active Directory Root DSE

• Connect to ldap:// (DEFAULT_ROOT_DSE)
• Query for the defaultNamingContext attribute
• Format result as LDAP path (e.g., LDAP://DC=example,DC=com)
• Return immediately on success

Fallback Method: Windows API GetComputerNameEx()

• If LDAP query fails, retrieve the computer's DNS domain name
• Convert DNS format to LDAP distinguished name format
• Example: example.com → LDAP://DC=example,DC=com

Step 2: Domain Controller Discovery

Query the discovered domain for all Domain Controllers using LDAP filter criteria.

Implementation Details:

• Use LDAP filter: (&(objectClass=computer)(primaryGroupID=516))
  • objectClass=computer: Targets computer objects
  • primaryGroupID=516: Filters for Domain Controllers
• Extract DC attributes: cn, dNSHostName, name
• Create operator.windows.Input object for each discovered DC with:
  • Server: DC DNS hostname
  • Username: From configuration
  • Password: From configuration

Technical Details

Configuration Flag

• Flag Name: discoverDomainControllers
• Location: windowseventlog config
• Type: Boolean
• Usage: Enable/disable domain discovery during build phase

Integration Point

• Build Function: operator.windows.config_windows.Build()
• Trigger: On collector startup/restart
• Action: If flag enabled, invoke discovery process

Error Handling Strategy

Scenario	Action
Step 1 - Primary failure	Fallback to Windows API
Step 1 - Secondary failure	Log error and fail discovery
Step 2 - LDAP query failure	Log error, continue with existing config
Step 2 - No DCs found	Log warning, continue with existing config
Step 2 - Partial failures	Log failed DCs, process successful ones

Acceptance Criteria

• LDAP Root DSE query implementation with fallback to GetComputerNameEx()
• DC discovery via LDAP filter (&(objectClass=computer)(primaryGroupID=516))
• Configuration flag to enable/disable discovery
• operator.windows.Input objects created for each discovered DC
• Comprehensive error handling with appropriate logging
• Discovery process executes on collector startup
• Unit tests for both discovery steps
• Integration tests with sample AD environment
• Documentation updated with usage examples

Future Enhancements

These items are out of scope for the initial implementation but should be considered:

• Implement periodic discovery (currently startup-only)
• Add retry logic with exponential backoff
• Support custom LDAP filters for specialized deployments
• Cache discovery results to minimize LDAP queries
• Add discovery metrics and detailed logging
• Support for multiple forests/domains
• Discovery performance optimization for large environments

Code References

Step 1 - LDAP Query:

conn, _ := ldap.DialURL("ldap://")
req := ldap.NewSearchRequest("", ldap.ScopeBaseObject, ...)
res, _ := conn.Search(req)
domainPath := res.Entries[0].GetAttributeValue("defaultNamingContext")

Step 1 - Windows API Fallback:

ret, err := windows.GetComputerNameEx(
    windows.ComputerNameDnsDomain,
    &domainNameBuf[0],
    &size,
)
// Convert example.com to LDAP://DC=example,DC=com format

Step 2 - DC Discovery:

searchReq := ldap.NewSearchRequest(
    "DC=yourdomain,DC=com",              // Domain from Step 1
    ldap.ScopeWholeSubtree,              // Search entire subtree
    ldap.NeverDerefAliases,              // Don't dereference aliases
    1000,                                 // Size limit
    0,                                    // No time limit
    false,                                // Attributes only = false
    "(&(objectClass=computer)(primaryGroupID=516))", // DC filter
    []string{"cn", "dNSHostName", "name"}, // Attributes to retrieve
    nil,
)

Related Issues

[Original Issue](https://github.com//issues/44156)

Labels

• enhancement
• windows
• active-directory
• discovery

Tip

_{React with 👍 to help prioritize this issue. Please use comments to provide useful context, avoiding +1 or me too, to help us triage it. Learn more here.}

[github-actions]

Pinging code owners:

• receiver/windowseventlog: @armstrmi @pjanotti

See Adding Labels via Comments if you do not have permissions to add labels yourself.