msad - a cli for microsoft active directory
2025-04-20
msAD
msad is a library and command line tool for working with an Active Directory / LDAP server from Unix, Linux and macOS systems.
It supports authentication with user/password and Kerberos (the gssapi dependency is an optional extra, msad[kerberos], so installing the plain CLI never requires the system Kerberos dev headers).
It supports pagination: it can retrieve more than 2000 objects, a limit of AD.
msad is also the foundation of three sibling, read-only front ends: mcpAD (an MCP server), restAD (a REST API) and graphqlAD (a GraphQL API) — same typed library, different protocol.
Features
- search objects (users, groups, computers, contacts, OUs, …) with a raw LDAP filter
- search users by field (name, surname, mail, sAMAccountName, department)
- search groups by name / cn / sAMAccountName / displayName, optionally restricted to security groups by scope (global/domain local/universal)
- search computers by name / dNSHostName / operatingSystem, optionally excluding domain controllers
- search contacts and organizational units (OUs), and list OU contents
- find inactive users / stale computers (last logon older than N days)
- find risky accounts: password not required, Kerberos pre-auth not required, “sensitive and not delegated”, never-expiring or expired accounts
- audit reads: domain info, default password policy, privileged groups, FSMO role owners, domain trusts, AD sites, GPOs, fine-grained password policies
- list domain controllers, empty groups, and computers grouped by OS
- get a single user, group, computer, contact or OU; fetch any entry directly by its DN
- list group members (direct or recursive/nested) and a user’s groups (direct or recursive/nested)
- check whether a user is a (nested) member of a group
- add/remove members to/from AD groups using DN or sAMAccountName
- change AD passwords, unlock a locked-out user account
- check if a user is disabled, locked, or has an expired/never-expiring password
- decode raw AD attributes (userAccountControl, groupType, FILETIME, SID, GUID) into human-readable companion fields
- LDAP filter escaping to prevent injection
By default, user lookups return a useful attribute set — identity fields plus manager, memberOf, userAccountControl, accountExpires, lastLogonTimestamp, whenCreated and all extensionAttribute1 through extensionAttribute15 (commonly used by organizations for custom/HR data such as company code, employee type or division).
Usage
msad search "(samaccountname=matteo)" --out-format=json # show all attributes
msad search "(cn=redaelli*)" --attributes mail --attributes samaccountname --out-format=json
msad user-search --surname "Rossi" --department "IT"
msad group-search "qlik_*"
msad security-groups --scope global
msad computer-search --name "PC0*" --exclude-domain-controllers
msad contact-search "anna*"
msad group-members qlik_analyzer_users --nested
msad group-add-member qlik_analyzer_users matteo
msad group-remove-member qlik_analyzer_users matteo
msad user-groups matteo --nested
msad inactive-users --days 90
msad password-not-required
msad kerberos-preauth-not-required
msad never-expiring-accounts
Installation
uv tool install msad
# with Kerberos (SASL/GSSAPI) support — needs the system Kerberos dev
# headers (e.g. libkrb5-dev on Debian/Ubuntu, krb5-devel on RHEL/Fedora,
# krb5 via Homebrew on macOS) to build the gssapi extension:
uv tool install 'msad[kerberos]'
The code is available on GitHub and the package is published on PyPI.