Impacket tstool.py

Back to the category index / Back to the command index

Overview

Uses Terminal Services RPC to list sessions and processes and to disconnect, log off, or terminate them.

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

CLI and input

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

Subcommands: qwinsta, tasklist, taskkill, tscon, tsdiscon, logoff, shutdown, msg, shadow

Argument	Description
target	[[domain/]username[:password]@]
-debug	Enable debug output
-ts	Add a timestamp to each log message
-v	Enable verbose output
-pid	Process ID (PID)
-name	Process image name; internally runs tasklist to obtain its PID
-source	Source session ID; required
-dest	Destination session ID; required
-password	Password for the destination session
-session	Session ID to disconnect; required
-logoff	Force sessions to log off
-shutdown	Shut down the system
-reboot	Reboot after shutdown
-poweroff	Power off after shutdown
-title	Optional MessageBox title
-message	MessageBox contents; required
-control	Request control of the session (view-only by default)
-prompt	Request user permission (silent by default)
-file	Save invitation to this file (default: invite.msrcIncident)
-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
-target-ip	Target machine IP address; if omitted, use the target value. Useful when a NetBIOS target name cannot be resolved
-port	Destination SMB server port (choices: 139, 445; default: 445)

Detailed processing flow

The tool connects to an SMB session and the Terminal Services endpoint. TSHandler.run() dispatches qwinsta, tasklist, taskkill, tscon, tsdiscon, logoff, shutdown, msg, and shadow. When needed, LSA resolves SIDs to usernames.

How it works

Terminal Services exposes sessions and processes through its own RPC interface. This command establishes an SMB/RPC transport and dispatches session enumeration, process enumeration, session control, and system actions to different TSTS requests according to the subcommand. TSHandler.run() maps CLI actions to protocol helpers.

qwinsta collects session IDs, states, and station or user information. tasklist uses LSA lookups to add names to SIDs in process records. taskkill, tscon, tsdiscon, and logoff resolve existing IDs or names before changing state. msg and shadow also handle variable-length text, permission or control flags, and response codes.

Sessions can change during enumeration, so an ID may no longer exist when used for an action. Distinguish RPC transport errors, missing target sessions, access denials, and user rejections. Shutdown and power-off affect every session, so validate arguments and prepare auditable logs before making protocol calls.

Key implementation elements

Symbol	Location	Where to trace its responsibility
TSHandler	59	__init__(), connect(), run(), get_session_list(), enumerate_sessions_config(), enumerate_sessions_info(), do_qwinsta(), lookupSids(), sidToUser(), do_tasklist(), do_taskkill(), do_tscon(), and others

Dependencies

Within Impacket

Module	Main names used
impacket	LOG, version
impacket.examples	logger
impacket.examples.utils	parse_target
impacket.smbconnection	SMBConnection
impacket.dcerpc.v5	lsad, lsat, transport, tsts
impacket.dcerpc.v5.rpcrt	DCERPCException, RPC_C_AUTHN_GSS_NEGOTIATE, RPC_C_AUTHN_LEVEL_PKT_PRIVACY
impacket.dcerpc.v5.dtypes	MAXIMUM_ALLOWED
impacket.dcerpc.v5.tsts	SHADOW_CONTROL_REQUEST, SHADOW_PERMISSION_REQUEST, SHADOW_REQUEST_RESPONSE

Output, side effects, and required privileges

• Some operations change the target’s state. Check the target name, SID, and path before making changes.

Failure paths and cleanup

• On failure, use protocol status codes to determine whether name resolution, connection, authentication, service state, or permissions caused the stop.

When changing the implementation

The code depends on dcerpc.v5.tsts, transport, lsad, lsat, and SMBConnection. Validate arguments specific to each subcommand before the RPC call, and close session handles after each action.

Verification

• Syntax: python -m py_compile examples/tstool.py
• CLI: python examples/tstool.py -h
• Related test: tests/SMB_RPC/test_rpcrt.py
• Related test: tests/misc/test_dcerpc_v5_ndr.py
• Related test: tests/misc/test_tsts.py