Impacket dcomexec.py

Back to the category index / Back to the command index

Overview

Uses DCOM objects to run a command or a semi-interactive shell on the target host.

Item	Details
Implementation	examples/dcomexec.py
Category	Remote execution / WMI / services
Size	656 lines
Distribution	Installed as a script through scripts=examples/*.py in setup.py

CLI and input

Run python examples/dcomexec.py -h for the current option definitions.

Argument	Description
target	[[domain/]username[:password]@]
-share	Share from which to retrieve output (default: ADMIN$)
-nooutput	Do not print output (no SMB connection is created)
-ts	Add a timestamp to each log message
-debug	Enable debug output
-codec	Help text generated dynamically from the runtime value
-object	DCOM object used to run the shell command (default: ShellWindows; choices: ShellWindows, ShellBrowserWindow, MMC20)
-com-version	DCOM version in MAJOR_VERSION:MINOR_VERSION format, for example 5.7
-shell-type	Command processor for the semi-interactive shell (choices: cmd, powershell; default: cmd)
command	Command to run on the target; if empty, launch a semi-interactive shell
-silentcommand	Run the given command without cmd.exe (no output; shell built-ins such as dir and cd cannot run)
-hashes	NTLM hashes in LMHASH:NTHASH format
-no-pass	Do not prompt for a password (useful with -k)
-k	Use Kerberos authentication. Look for matching credentials in the ccache file named by KRB5CCNAME; if none are valid, use those specified on the command line
-aesKey	AES key for Kerberos authentication (128 or 256 bits)
-dc-ip	Domain controller IP address; if omitted, use the domain name (FQDN) from the target parameter
-A	smbclient/mount.cifs-style authentication file; see smbclient manual page option -A
-keytab	Read SPN keys from a keytab file

Detailed processing flow

The tool establishes a DCOM connection and obtains the selected object’s COM interface. It passes commands to a dispatch method. With output enabled, it redirects output to a temporary file on a share and retrieves it over a separate SMB connection. For the interactive shell, cmd.Cmd dispatches local and remote commands, uploads, and downloads.

How it works

DCOM activates a remote COM object and calls its interface methods through RPC. This command creates a ShellWindows, ShellBrowserWindow, or MMC20.Application object and reaches shell execution through IDispatch. Each object has a different property and method chain, so getInterface() and RemoteShellMMC20 handle the differences.

A command’s return value alone does not provide stdout. Normally, the remote shell writes output to a temporary file on a share, and a separate SMBConnection reads it. The interactive shell keeps the current directory as a command prefix. Only lget/lput use SMB file transfer; other input goes to DCOM process execution. With -nooutput, no SMB connection is needed, and the meaning of execution confirmation changes.

COM objects have interface references and a DCOM connection lifecycle. Release interfaces and disconnect even when a method call fails, and prevent polling for the temporary file from continuing indefinitely. Distinguish differences caused by COM versions, object availability, or desktop/session isolation from credential errors.

Key implementation elements

Symbol	Location	Where to trace its responsibility
DCOMEXEC	65	__init__(), getInterface(), run()
RemoteShell	206	__init__(), do_shell(), do_help(), do_lcd(), do_lget(), do_lput(), do_exit(), do_EOF(), emptyline(), do_cd(), default(), get_output(), and others
RemoteShellMMC20	444	execute_remote()
AuthFileSyntaxError	497	__init__()
load_smbclient_auth_file()	511	Module function

Dependencies

Within Impacket

Module	Main names used
impacket	version
impacket.dcerpc.v5.dcom.oaut	DISPATCH_METHOD, DISPATCH_PROPERTYGET, DISPPARAMS, IDispatch, IID_IDispatch, VARENUM, VARIANT, string_to_bin
impacket.dcerpc.v5.dcomrt	COMVERSION, DCOMConnection, FLAGS_OBJREF_CUSTOM, FLAGS_OBJREF_EXTENDED, FLAGS_OBJREF_HANDLER, FLAGS_OBJREF_STANDARD, INTERFACE, IRemUnknown2, OBJREF, OBJREF_CUSTOM, OBJREF_EXTENDED, OBJREF_HANDLER, OBJREF_STANDARD
impacket.dcerpc.v5.dtypes	NULL
impacket.examples	logger
impacket.examples.utils	parse_target
impacket.smbconnection	SMB2_DIALECT_002, SMB2_DIALECT_21, SMBConnection, SMB_DIALECT
impacket.krb5.keytab	Keytab

External packages (used directly)

Import name	Distribution package	Import path and declaration status
six	six	Imported directly; declared

Output, side effects, and required privileges

• Some operations change the target’s state. Check the target name, SID, and path before making changes.
• Some paths use temporary resources such as remote services, tasks, files, shares, and WMI/RPC resources. Cleaning them up after an abnormal exit is part of the behavior contract.

Failure paths and cleanup

• On failure, use protocol status codes to determine whether name resolution, connection, authentication, service state, or permissions caused the stop.
• Even without an explicit cleanup function, check for finally-equivalent paths and closure or deletion of protocol handles.

When changing the implementation

The code depends on dcerpc.v5.dcomrt, DCOM OAUT structures, SMBConnection, and keytabs. DCOMEXEC handles object activation; RemoteShell and its related classes handle commands and output. Always release COM interfaces and disconnect.

Verification

• Syntax: python -m py_compile examples/dcomexec.py
• CLI: python examples/dcomexec.py -h
• Related test: tests/dcerpc/test_dcomrt.py