Impacket sambaPipe.py

Back to the category index / Back to the command index

Overview

Places a .so file on a share and opens a named pipe to test whether Samba loads external pipe modules.

Item	Details
Implementation	examples/sambaPipe.py
Category	SMB / MSRPC / NTLM
Size	281 lines
Distribution	Installed as a script through scripts=examples/*.py in setup.py

CLI and input

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

Argument	Description
target	[[domain/]username[:password]@]
-so	Shared object (.so) filename to upload and load (required)
-debug	Enable debug output.
-ts	Add a timestamp to each log message.
-hashes	NTLM hashes in LMHASH:NTHASH format.
-no-pass	Do not prompt for a password (useful with -k).
-k	Use Kerberos authentication. Read credentials from the ccache file named by KRB5CCNAME, based on the target parameters; if no valid credentials are found, use those supplied 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 portion (FQDN) of the target.
-target-ip	Target IP address; if omitted, use the target value. Useful when the target is a NetBIOS name that cannot be resolved.
-port	Destination SMB server port (choices: 139, 445; default: 445)

Detailed processing flow

After connecting over SMB, the tool finds or selects a writable share and uploads the specified shared object. It opens the pipe module name with an SMB1 or SMB2 create request and checks the response status. Afterward, it removes the uploaded file where possible.

How it works

In some Samba configurations, named pipe names affect how external RPC module libraries are resolved. This creates a path through which a shared object placed on a writable share can be loaded. The command first establishes an SMB session, enumerates shares, checks for a writable location, and transfers the specified .so file to a remote path.

It then constructs a low-level SMB1 or SMB2 packet for the pipe create/open request. Opening a regular file and opening a named pipe differ in path namespace, create options, and impersonation level, so it sets the structure for each dialect explicitly. The server status code shows how far module lookup or opening proceeded.

Successful upload and successful pipe opening are separate stages; the placed file can remain after a failure in between. The writable-share check includes creating and deleting a temporary file, without overwriting an existing file. Behavior depends on the target Samba version and configuration, so a rejection may indicate mitigation or an inapplicable target, not just failed credentials.

Key implementation elements

Symbol	Location	Where to trace its responsibility
PIPEDREAM	50	__init__(), isShareWritable(), findSuitableShare(), uploadSoFile(), create(), openPipe(), run()

Dependencies

Within Impacket

Module	Main names used
impacket	version
impacket.examples	logger
impacket.examples.utils	parse_target
impacket.nt_errors	STATUS_SUCCESS
impacket.smb	FILE_DIRECTORY_FILE, FILE_NON_DIRECTORY_FILE, FILE_OPEN, FILE_READ_DATA, FILE_SHARE_READ, FILE_WRITE_DATA, SMB, SMBCommand, SMBNtCreateAndX_Data, SMBNtCreateAndX_Parameters, SMB_DIALECT
impacket.smb3structs	SMB2Create, SMB2Create_Response, SMB2Packet, SMB2_CREATE, SMB2_FLAGS_DFS_OPERATIONS, SMB2_IL_IMPERSONATION, SMB2_OPLOCK_LEVEL_NONE, SMB2_SESSION_FLAG_ENCRYPT_DATA
impacket.smbconnection	SMBConnection
impacket.dcerpc.v5	srvs, transport

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, or WMI/RPC resources. Recovery 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 explicitly named cleanup function, check for a finally-equivalent path and closure or deletion of protocol handles.

When changing the implementation

The code depends on low-level smb and smb3structs as well as SMBConnection. PIPEDREAM handles share probing, upload, and create/open requests. Check dialect and path semantics and cleanup on failure.

Verification

• Syntax: python -m py_compile examples/sambaPipe.py
• CLI: python examples/sambaPipe.py -h
• Related test: tests/SMB_RPC/test_smb.py
• Related test: tests/SMB_RPC/test_smbserver.py
• Related test: tests/misc/test_dcerpc_v5_ndr.py