ADSearch is a lightweight, single‑binary command‑line utility that performs advanced LDAP queries against Microsoft Active Directory (AD) and Azure AD. The cheat sheet below covers installation, options, common queries, output formats, security best practices, integration use‑cases, and alternatives.
Quick Start
# Basic query – all users
adsearch -q "(objectClass=user)" -o csv
# Query a specific DC (useful in multi‑site setups)
adsearch -q "(objectClass=computer)" -o csv -d dc01
# Export to JSON (integrate with APIs)
adsearch -q "(servicePrincipalName=*)" -o json
All commands print to STDOUT by default; redirect output to files
with shell redirection (> or >>).
Command‑Line Options
| Option | Alias | Purpose | Example |
|---|---|---|---|
-q | --query | LDAP filter string | -q "(objectClass=user)" |
-f | --fields | Comma‑separated attribute list | -f sAMAccountName,department,mail |
-o | --output | Output format (csv,json,xml,txt) | -o csv |
-d | --dc | Target domain controller | -d dc01 |
-p | --page-size | LDAP paging size (default 1000) | -p 5000 |
-l | --log-level | Verbosity (error,info,debug) | -l info |
-c | --cache | Path to local JSON cache (optional) | -c cache.json |
-x | --plain-auth | NTLM simple bind (requires -w) | -x |
-w | --password | NTLM password (for -x) | -w <pwd> |
--ssl | - | Use LDAPS (port 636 by default) | --ssl |
--ssl-port | -t | Custom LDAPS port | --ssl-port 3268 |
-V | --version | Print version and exit | -V |
-h | --help | Show help | -h |
Environment overrides:
ADSEARCH_DC,ADSEARCH_OUTPUT,ADSEARCH_LOG(eg.export ADSEARCH_OUTPUT=csvto default to CSV)
Output Formats & Customization
| Format | Description | Key Settings |
|---|---|---|
| CSV | Comma separated values, RFC‑4180 compliant | -o csv -f attr1,attr2 |
| JSON | Array of objects; useful for PowerShell ConvertFrom-Json or REST APIs | -o json |
| XML | Root <items> with <item> nodes; preserves nested attributes | -o xml |
| TXT | Pipe‑delimited text (useful for awk or cut) | -o txt |
For CSV you can change the delimiter with -o csv:sep=;.
For JSON you can enable pretty‑printing with -o json:pretty.
Common LDAP Filters
- All enabled users
-q "(userAccountControl:1.2.840.113556.1.4.803:=512)" - All disabled users
-q "(userAccountControl:1.2.840.113556.1.4.803:=(512|2))" - Users in a specific security group
-q "(memberOf=CN=Domain Admins,OU=Groups,DC=example,DC=com)" - Service Principals with a particular SPN
-q "(servicePrincipalName=spn:service/host::)" -f sAMAccountName,servicePrincipalName - Computers joined to a particular OU
-q "(distinguishedName=OU=Workstations,DC=example,DC=com)" - Domain controllers (server objects)
-q "(objectCategory=serverObject)" -f dnsHostName,ipv4Address
Tip: Use the bitwise AND OID
1.2.840.113556.1.4.803 to filter by enabled/disabled
status, password‑age, etc.
:1.2.840.113556.1.4.803:=512 checks the ENABLE bit (512).
Timestamp Helpers
AD stores lastLogonTimestamp as a 64‑bit Windows filetime.
PowerShell conversion example:
# Convert lastLogonTimestamp to readable UTC
$ts = [DateTime]::FromFileTimeUtc( $user.lastLogonTimestamp )
# To local time
$tsLocal = $ts.ToLocalTime()
Use this when you need to determine account inactivity for cleanup scripts.
Security & Authentication
- Prefer Kerberos (default) – no password on command line.
- For environments without Kerberos, use simple NTLM with
-x -w <pwd>. - Always run ADSearch on a host that can reach the target DCs securely (LDAPS on port 636 or 3268 for global catalog).
- Log actions with
-l debugto capture the filter and target DC. - Use environment variables (e.g.
ADSEARCH_SSL=1) to enforce LDAPS instead of clear‑text LDAP. - When scripting, avoid embedding passwords in plain files;
store them in
credman.exeor a Windows Credential Manager entry and reference via--cred=WindowsCredStore. - Rotate service‑principal passwords regularly; use
adsearchto list all SPNs before rotating.
Typical Use‑Cases
- Account Cleanup – Find users inactive > 90 days and export to CSV for audit.
- Privileged Access Review – List members of
Domain Admins,Enterprise Admins,Account Operators. - Service‑Principal Management – Identify all SPNs for a given application, then audit or rotate.
- OU‑Based Policies – Enumerate all OUs to verify group‑nested delegation.
- Cross‑domain – Use the
-doption to point at a DC in a different forest; supply-u <user> -w <pwd>for remote binding. - Automation – PowerShell wrapper that pulls user data, converts timestamps, and writes to a CSV used by other scripts.
Other Tools to Consider
- PowerShell AD Cmdlets – Great for one‑off tasks; heavier than ADSearch.
- OpenLDAP
ldapsearch– Portable, but lacks AD‑specific extensions (e.g.,userAccountControlbitwise filters). - Softerra LDAP Administrator – GUI, expensive license.
- ADFind – Classic CLI, no paging support, fewer output formats.
- AzCopy + Azure AD Graph / MS Graph – For cloud‑only environments; requires separate Graph SDK.
Community & Resources
- GitHub Repo – Source, releases, and issue tracker.
- Microsoft Docs – AD PowerShell Cmdlets
- PowerShell AD Module Docs
- PowerShell GitHub – For advanced scripting.
- Ask questions on Stack Overflow (tag: active-directory).
- Monthly IRC/Discord channel
#adsearch(invite link on repo).
Roadmap (FY24)
- v1.5 – Docker images for Windows & Linux.
- v2.0 – Native Graph API support for Azure AD.
- v1.6 –
--filter-templatesfile with predefined OID extractions. - v1.7 – Built‑in LDAP query builder UI (Electron).
Stay tuned by watching the repository or subscribing to the release RSS feed.
No comments yet. Be the first to comment!