Active Directory Discovery

The Active Directory plugin queries a domain controller over LDAP and records the domain, domain controllers, organizational units, computers, users, groups, Group Policy Object containers, and AD-integrated DNS zones and records.

Where it runs

The plugin is built into the Infracast image and runs directly on air-gapped installs, where the platform itself runs inside your network (offline mode enabled). On the hosted platform the domain controller is not reachable from outside your network, so run it through an on-premises relay: the relay carries the same plugin and runs it inside your network. The relay must be on the same build as the platform; a relay that is out of date is shown as degraded ("update pending") and plugin jobs sent to it fail with that reason until it is updated.

What is collected

Object	What is recorded
Domain	Name, forest and domain functional level
Domain controllers	Name, DNS host name, operating system and version, creation time
Organizational units	Name, DN, description, parent/child hierarchy
Computers	Name, DNS host name, operating system and version, last logon timestamp, containing OU
Users (enabled, person accounts)	sAMAccountName, display name, mail, department, title, last logon timestamp, containing OU
Groups	Name, description, DN, member count, membership edges to user objects
Group Policy Objects	Name, display name, gPCFileSysPath (container metadata only)
DNS zones and records	See DNS

User and group-membership edges are matched by common name of the member DN; members that are not user objects (nested groups, computers) are not linked.

Not collected

The following are not implemented by the plugin today: trust relationships, GPO links to OUs, GPO settings from SYSVOL (no SMB access is made), LAPS metadata, service principal names, delegation settings, fine-grained password policies, AdminSDHolder state, Global Catalog queries, multiple domain controllers per job, and OU exclusion lists. Each domain is one job against one domain controller.

DNS

AD-integrated DNS zones are read from the same LDAP connection and bind account as the rest of discovery — read-only searches only. Nothing is written to the directory.

• Where zones are read from: the domain partition (DC=DomainDnsZones), the forest partition (DC=ForestDnsZones), and the legacy location under CN=System. A deployment without one of them is fine.
• What is decoded: the binary dnsRecord attribute of each dnsNode — A, AAAA, CNAME, NS, PTR, MX, SRV, TXT and SOA. Other record types are kept visible as generic data rather than dropped. Tombstoned (deleted) nodes are skipped.
• Result: one onprem.dns_zone node per zone and one onprem.dns_record node per name and record type, with record_type, values, ttl, zone_name, is_wildcard and dns_source = ad. These appear on the DNS page and feed the Certificates page, which labels them "Active Directory DNS".
• Never a partial zone: a zone is recorded only if every page of the search succeeded and every record decoded. A zone that cannot be read completely is reported as not collected, with the reason, and produces no nodes. The other zones are still recorded. A zone with ranged attribute retrieval (a single name with more than about 1,500 records) is refused for the same reason.

Optional configuration: collect_dns (false turns the DNS step off; default on), dns_zones (comma-separated list of zone names; default all) and dns_only (true collects only the DNS step and skips the directory objects).

Scope of verification

The DNS decoder and collector are verified against Samba 4 AD domain controllers (real captured records, compared with Samba's own rendering of the same records). They have not been verified against Windows Server DNS. The record format is the documented Microsoft one, and encodings that exist only on Windows are handled defensively, but treat Windows Server results as unverified until you have compared a zone you know.

Least-privilege setup

Any authenticated domain user can read the DNS partitions by default. Use a dedicated account that is a member of Domain Users only, and keep its password in your secrets store. Zone contents are your internal namespace: they are stored in your own workspace only.

Configuration

Key	Required	Description
ldap_url	yes	For example ldap://dc01.corp.example.com:389
domain	yes	For example corp.example.com
username	yes	Bind user, UPN form recommended (svc-infracast@corp.example.com)
password	yes	Bind password
use_tls	no	true to upgrade the connection with StartTLS before binding
base_dn	no	Defaults to the domain converted to DC= form (corp.example.com → DC=corp,DC=example,DC=com)
collect_dns	no	false to skip DNS
dns_zones	no	Only these zones
dns_only	no	true to collect only AD-integrated DNS

Certificate verification

With use_tls the plugin does not verify the domain controller's certificate. Use it only on networks you control. If the domain controller uses a certificate your network issued, keep this connection on a network you control.

Windows domain controllers refuse a simple bind over a clear-text connection ("strong auth required"): set use_tls to true.

Finding your Base DN

(Get-ADDomain).DistinguishedName
# DC=corp,DC=example,DC=com

ldapsearch -x -H ldap://dc01.corp.example.com -b "" -s base defaultNamingContext

Troubleshooting

LDAP Result Code 49 "Invalid Credentials"

Try both svc-infracast@corp.example.com and CORP\svc-infracast, check the account is not locked out (Get-ADUser svc-infracast -Properties LockedOut), and test the bind with ldapwhoami.

"Strong Auth Required"

The domain controller requires an encrypted connection for the bind. Set use_tls to true.

A DNS zone is reported as not collected

The error names the zone and the reason: a search that failed part-way, a record that could not be decoded, or a name with ranged values. No partial zone is stored. Narrow the run with dns_zones to isolate it.