Shared Command Architecture and Dependencies

Distribution and Entry Points

Impacket’s CLI commands are not console entry points. Instead, setup.py installs examples/*.py as scripts. Each file therefore owns its command name, executable permissions, shebang, and top-level argparse handling. Renaming a file changes the name of the distributed command.

Many commands follow this common flow:

flowchart LR
    A["Validate input with argparse"] --> B["Parse identity / target"]
    B --> C["Select credentials"]
    C --> D["Connect to SMB, LDAP, RPC, Kerberos, etc."]
    D --> E["Command-specific queries or changes"]
    E --> F["Format output or write files"]
    E --> G["Log exceptions"]
    F --> H["Disconnect and clean up temporary resources"]
    G --> H

impacket.examples.logger standardizes log formatting, impacket.version provides the banner, and impacket.examples.utils shares parsing of the domain/user[:password]@target form and LDAP connections. Authentication options vary by command, so check each CLI’s supported protocols before changing arguments that appear to be shared across commands.

Protocol Implementation Details

Cross-command wire specifications and module responsibilities are covered in Protocols and Library Modules.

Topic	Page
Structure field DSL	structure.md
SMB dialects, signing, named pipes	smb.md
NTLM Type1/2/3, AV pairs, MIC, SPNEGO	ntlm-spnego.md
AS/TGS, PAC, S4U, ccache	kerberos.md
String binding, NDR, RPC interfaces	dcerpc.md
LDAP bind, CBT, security descriptors	ldap.md
Boot key, SAM/LSA/NTDS, DPAPI	dpapi-secrets.md
TDS / MQTT / NSPI	tds-messaging.md
ImpactPacket, hives, ESE, NTFS	packets-storage.md

Dependency Layers

Layer	Main Modules	Responsibility
CLI	examples/*.py	Arguments, operation selection, results, exit codes
Shared CLI	impacket.examples.*	Target parsing, shells, secretsdump, relay, service deployment
High-level protocols	smbconnection, ldap.ldap, tds, dcerpc.v5.transport	Sessions, authentication, transport
Protocol structures	smb*, ntlm, krb5.*, dcerpc.v5.*, dpapi, ese	Wire structures, cryptography, RPC interfaces
External packages	Table below	ASN.1, cryptography, LDAP, Web UI, text encodings, etc.
OS / network	Sockets, raw sockets, pcap, target services	Actual I/O

Python Package Dependencies

The runtime dependencies declared by setup.py and requirements.txt are:

Package	Main Uses
six	Python compatibility helpers, byte/string conversion
charset_normalizer	Detecting GPP XML encodings
pyasn1, pyasn1_modules	Kerberos, CMS, LDAP ASN.1
pycryptodomex (Cryptodome)	AES, RC4/MD4, HMAC, RSA
pyOpenSSL (OpenSSL)	TLS, LDAP/MSSQL connection checks
ldap3	LDAP modifications and security descriptor controls
ldapdomaindump	Formatting LDAP attributes and SIDs
flask	Supporting the ntlmrelayx SOCKS/HTTP API
pyreadline3	Interactive shells on Windows

In addition, sniff.py and split.py import pcapy directly, but it is not declared in setup.py or requirements.txt. CheckLDAPStatus.py and GetADComputers.py also use dns.resolver, but dnspython is not declared as a direct dependency. These packages may need to be installed separately in development or runtime environments. When reorganizing dependencies, check backward compatibility and whether they build on each OS.

kintercept.py directly uses the standard-library module asyncore. Since asyncore was removed in Python 3.12, the project cannot import it as-is on its advertised Python 3.12/3.13 versions. Maintaining it requires replacing the event loop or explicitly adopting a compatibility package, plus regression tests for partial I/O.

Authentication and Target Selection

A typical input format is [domain/]user[:password]@target. Some commands prompt for a password when it is omitted and -no-pass is not set. Support for NTLM LMHASH:NTHASH, Kerberos -k, AES keys, and keytabs varies by command.

• target is the logical name used for name resolution and SPN construction.
• -target-ip overrides the connection IP, separating name resolution from the endpoint.
• -dc-ip is the connection address for the KDC or domain controller.
• In Kerberos, SPN and DNS name consistency matters. Replacing the name with an IP address alone may prevent authentication.
• RPC commands build string bindings with DCERPCTransportFactory and choose among SMB named pipes, TCP, RPC over HTTP, and other transports.
• dce.set_credentials() raises the authentication level to CONNECT. Explicitly request PKT_PRIVACY for interfaces such as DRSUAPI that require it.
• LDAP modification commands (dacledit / rbcd / owneredit) use ldap3, while enumeration commands use impacket.ldap.LDAPConnection. impacket.acl handles file ACLs.

Error Handling and Cleanup

Many CLIs catch protocol-specific exceptions and write them to the log. When changing this behavior, do not indiscriminately collapse SessionError, DCERPCException, LDAPSessionError, and KerberosError into generic exceptions. Preserve the status codes needed for diagnosis.

Commands that create remote services, temporary files, shares, WMI objects, or local temporary files must call cleanup(), finish(), or disconnect() on exceptions as well as on success. When adding a return or exception path, ensure it still passes through cleanup.

Changing or Adding a Command

1. Preserve the existing CLI’s positional arguments and authentication options.
2. Keep input handling and flow control in the CLI; put reusable communication code under impacket/.
3. Use the target protocol’s existing transport/session classes; reserve custom sockets for cases such as protocol experiments where they are necessary.
4. Clearly separate reads from changes, and log the target and action for changes.
5. Before changing output formats, check compatibility with pipelines and tool integrations.
6. Use tests under tests/ for structures, conversions, and branches; follow TESTING.md for remote tests that depend on a real environment.
7. New examples/*.py files are distributed automatically. Do not place unintended helper scripts directly under that directory.

When extracting values from responses or files, allow for missing fields and unknown values. Do not add passwords, hashes, tickets, keys, or decrypted secrets to debug logs. These checks apply to every command.

Verification Guide

• Syntax: python -m compileall examples impacket
• CLI: -h for the changed command and exit behavior on invalid input
• Unit tests: tests under tests/ near the changed protocol/module
• Remote tests: an isolated environment with fixed credentials, target OS, and service state
• Packaging: build a wheel and confirm that it contains only the intended scripts

Integration tests over the network may change target state. In particular, for tests involving services, the registry, LDAP security descriptors, or WMI persistence, define the created artifacts and rollback steps first.