Impacket machine_role.py
Back to the Category Index / Back to the Command Index
Overview
Section titled “Overview”Determines whether a Windows host is standalone, a domain member, or a domain controller, and displays domain and forest information.
| Item | Details |
|---|---|
| Implementation | examples/machine_role.py |
| Category | Active Directory / LDAP / Account Management |
| Size | 176 lines |
| Distribution | Installed as a script through scripts=examples/*.py in setup.py |
CLI and Inputs
Section titled “CLI and Inputs”Check python examples/machine_role.py -h for the current option definitions.
| Argument | Description |
|---|---|
target | [[domain/]username[:password]@]<targetName or address> |
-ts | Add timestamps to log output. |
-debug | Enable debug logging. |
-dc-ip | Domain controller IP address. Defaults to the domain (FQDN) in target. |
-target-ip | Target machine IP address. Defaults to target; useful when the target is a NetBIOS name that cannot be resolved. |
-port | Destination SMB server port (choices: 139, 445; default: 445). |
-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 target; fall back to command-line credentials if none are valid. |
-aesKey | 128- or 256-bit AES key for Kerberos authentication. |
Detailed Processing Flow
Section titled “Detailed Processing Flow”The command connects to the MS-DSSP interface over the SMB named pipe \\pipe\\lsarpc and displays the machine role, NetBIOS/DNS domain names, forest name, and domain GUID from the DsRolerGetPrimaryDomainInformation response.
How It Works
Section titled “How It Works”MS-DSSP’s DsRolerGetPrimaryDomainInformation returns the host’s
primary domain and machine role in one structure. The command makes a
DCE/RPC connection to \\pipe\\lsarpc over SMB, binds to the DSSP
interface, and requests the basic domain information level.
The response’s machine-role enum distinguishes standalone workstations and servers, member workstations and servers, and backup and primary DCs. The command also extracts the flat NetBIOS domain name, DNS domain name, forest name, and domain GUID. These describe domain membership and DC role, rather than merely identifying the OS product type.
The remoteName used for name resolution is separate from the actual
connection destination, remoteHost. Kerberos needs a hostname for the SPN,
so supplying an IP with -target-ip must not discard the logical name.
Unknown enum values or NULL domain fields may occur on future versions or
standalone hosts; avoid relying solely on direct dictionary indexing.
Key Implementation Elements
Section titled “Key Implementation Elements”| Symbol | Location | Entry Point for Tracing Behavior |
|---|---|---|
MachineRole | 34 | __init__(), print_info() |
Dependencies
Section titled “Dependencies”Internal Impacket Modules
Section titled “Internal Impacket Modules”| Module | Main Names Used |
|---|---|
impacket.examples | logger |
impacket.examples.utils | parse_target |
impacket | version |
impacket.uuid | bin_to_string |
impacket.dcerpc.v5 | dssp, transport |
Output, Side Effects, and Required Privileges
Section titled “Output, Side Effects, and Required Privileges”- Primarily queries and authentication attempts. Repeated runs can affect audit logs, account lockouts, and target load.
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”This command depends on dcerpc.v5.transport, dcerpc.v5.dssp, and the shared target/authentication parser. MachineRole handles the request and display. When adding enums or flags, ensure unknown values do not break the output.
Verification
Section titled “Verification”- Syntax:
python -m py_compile examples/machine_role.py - CLI:
python examples/machine_role.py -h - Related test:
tests/misc/test_dcerpc_v5_ndr.py