Impacket badsuccessor.py
Back to the Category Index / Back to the Command Index
Overview
Section titled “Overview”Creates, modifies, and deletes delegated Managed Service Accounts (dMSAs), and examines related AD attributes.
| Item | Details |
|---|---|
| Implementation | examples/badsuccessor.py |
| Category | Active Directory / LDAP / Account Management |
| Size | 747 lines |
| Distribution | Installed as a script through scripts=examples/*.py in setup.py |
CLI and Inputs
Section titled “CLI and Inputs”Check python examples/badsuccessor.py -h for the current option definitions.
| Argument | Description |
|---|---|
account | Account used to authenticate to the DC. |
-dmsa-name | Name of the dMSA to add. Defaults to a random dMSA-[A-Z0-9]{8} name. |
-action | Action to perform: add (requires -target-ou), delete (requires -dmsa-name and -target-ou), modify (requires -dmsa-name, -target-ou, and -target-account), or search a dMSA. Choices: add, delete, modify, search. Default: search. |
-target-ou | OU to check for dMSA creation permissions, such as OU=weakOU,DC=domain,DC=local. |
-principals-allowed | User allowed to retrieve the managed password. Defaults to the current user. |
-target-account | Target user or computer account DN for msDS-ManagedAccountPrecededByLink (can target Domain Controllers, Domain Admins, Protected Users, etc.). Default: Administrator. |
-dns-hostname | DNS hostname for the dMSA. Defaults to dmsaname.domain. |
-ts | Add timestamps to log output. |
-debug | Enable debug logging. |
-method | Method of adding the computer. LDAPS has certificate requirements and is not always available. Choices: LDAP, LDAPS. Default: LDAPS. |
-port | Destination port. LDAP defaults to 389; LDAPS to 636. Choices: 389, 636. |
-baseDN | LDAP base DN. Defaults to the domain (FQDN) in the account parameter. |
-hashes | NTLM hashes in LMHASH:NTHASH format. |
-no-pass | Skip the password prompt (useful with -k). |
-k | Use Kerberos authentication. Read credentials from the ccache (KRB5CCNAME) based on the account; fall back to command-line credentials if none are valid. |
-aesKey | 128- or 256-bit AES key for Kerberos authentication. |
-dc-host | Hostname of the domain controller. Defaults to the domain (FQDN) in the account parameter. |
-dc-ip | IP address of the domain controller. Useful when the FQDN cannot be resolved. |
Detailed Processing Flow
Section titled “Detailed Processing Flow”After creating an LDAP session, the command searches OUs, checks account existence, builds a security descriptor, and adds or changes a dMSA object according to the action. It resolves SIDs to names and validates allowed principals and the target account before writing.
How It Works
Section titled “How It Works”Rather than adding a dMSA object in the same way as a normal user or computer,
the command sets dMSA-specific schema attributes and links to the account being migrated.
search_ous() and check_account_exists() first validate the destination and referenced account.
build_security_descriptor() converts the SIDs of principals permitted to use
the dMSA into an access control structure.
add_dmsa() creates the object with its objectClass, account name, DNS hostname,
and attributes required for a managed account. modify_dmsa() updates the target
account or allowed principals on an existing object. Add and modify are separate
because LDAP add and modify have different failure units and to avoid removing unexpected attributes from an existing object.
SID exclusions, OU selection, and generated names are safeguards, not merely display
aids: they prevent targeting the wrong privileged principal or a protected container.
Because behavior depends on the Windows Server schema and functional level, do not
treat noSuchAttribute or objectClassViolation as a generic authentication error.
Determine whether the target DC understands dMSAs.
Key Implementation Elements
Section titled “Key Implementation Elements”| Symbol | Location | Entry Point for Tracing Behavior |
|---|---|---|
BADSUCCESSOR | 34 | __init__(), run(), delete_dmsa(), check_account_exists(), search_ous(), is_excluded_sid(), resolve_sid_to_name(), generate_dmsa_name(), convert_sid_to_string(), build_security_descriptor(), add_dmsa(), modify_dmsa() |
Dependencies
Section titled “Dependencies”Internal Impacket Modules
Section titled “Internal Impacket Modules”| Module | Main Names Used |
|---|---|
impacket | version |
impacket.examples | logger |
impacket.examples.utils | init_ldap_session, parse_identity, parse_target |
impacket.ldap | ldaptypes |
External Packages (Direct Use)
Section titled “External Packages (Direct Use)”| Import Name | Distribution Package | Usage / Declaration Status |
|---|---|---|
ldap3 | ldap3 | Imported directly; declared dependency |
Output, Side Effects, and Required Privileges
Section titled “Output, Side Effects, and Required Privileges”- Some operations change the target’s state. Confirm the target name, SID, and path before making changes.
Failure Paths and Cleanup
Section titled “Failure Paths and Cleanup”- On failure, use protocol status to determine whether name resolution, connection, authentication, service state, or permissions stopped the operation.
When Changing the Implementation
Section titled “When Changing the Implementation”The command uses ldap3, impacket.ldap.ldaptypes, and init_ldap_session; BADSUCCESSOR owns the processing. Because it depends heavily on schema and functional level, check changes to attribute names, objectClass, and SID exclusion rules against the corresponding Windows Server generation.
Verification
Section titled “Verification”- Syntax:
python -m py_compile examples/badsuccessor.py - CLI:
python examples/badsuccessor.py -h - Related test:
tests/SMB_RPC/test_ldap.py