Impacket karmaSMB.py

Back to the category index / Back to the command index

Overview

Starts a test SMB server that returns payloads based on the share and filename requested by a client.

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

CLI and input

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

Argument	Description
--help	Show the help message and exit
fileName	Path to the file whose contents are sent to SMB clients
-config	File mapping extensions to files to serve; use fileName for unmapped extensions
-smb2support	Enable experimental SMB2 support
-ts	Add a timestamp to each log message
-debug	Enable debug output

Detailed processing flow

The tool reads its configuration, default file, and extension mappings, then replaces SimpleSMBServer SMB1 and SMB2 handlers for individual commands. It observes tree-connect, create, query, and read requests and serves a local file matching the requested path through a virtual share. The server waits until stopped.

How it works

A normal SMB server exposes only configured shares and paths. KarmaSMB instead observes the share and filename requested by the client and substitutes content based on an extension mapping or default file. To test automatic retrieval by SMB clients, it replaces server command handlers for both SMB1 and SMB2.

On tree connect, it creates a virtual mapping that accepts any share. On create or open, it normalizes the requested path and chooses the local file to return. Reads return bytes from the file associated with a handle, using the offset and length; directory and basic-information queries build metadata that lets the client continue. The size, attributes, and end-of-file must agree with the substituted content for the client to read it correctly.

Server state maps sessions, tree IDs, and file IDs to local file handles. Keep handles separate across clients; do not resolve paths containing .. or separators to arbitrary local files; preserve response IDs for SMB2 compound requests. Keep the priority between default files and extension mappings consistent across protocol handlers.

Key implementation elements

Symbol	Location	Where to trace its responsibility
KarmaSMBServer	77	__init__(), findFirst2(), smbComNtCreateAndX(), queryPathInformation(), smb2Read(), smb2Close(), smb2Create(), smb2QueryDirectory(), smb2TreeConnect(), smbComTreeConnectAndX(), run(), setDefaultFile(), and others

Dependencies

Within Impacket

Module	Main names used
impacket.examples	logger
impacket	smb, smbserver, version
impacket.smb3structs	*
impacket.smb	FILE_APPEND_DATA, FILE_OVERWRITE, FILE_OVERWRITE_IF, FILE_WRITE_DATA, GENERIC_WRITE
impacket.nt_errors	STATUS_ACCESS_DENIED, STATUS_NO_MORE_FILES, STATUS_OBJECT_PATH_NOT_FOUND, STATUS_SUCCESS, STATUS_USER_SESSION_DELETED
impacket.smbserver	SRVSServer, STATUS_SMB_BAD_TID, decodeSMBString, encodeSMBString, findFirst2, queryPathInformation

Output, side effects, and required privileges

• The tool primarily makes queries and authentication attempts. Frequent runs can affect audit logs, account lockouts, and target load.
• Starts a listening socket or long-running loop. Check the bind address, port, stop method, and shared state across concurrent connections.

Failure paths and cleanup

• On failure, use protocol status codes to determine whether name resolution, connection, authentication, service state, or permissions caused the stop.
• Cleanup-related methods include smb2Close(). Check that new early returns and exception paths reach it too.
• Ensure stop requests, client disconnections, partial reads or writes, and worker exceptions do not leave the listener in an inconsistent state.

When changing the implementation

The code depends on impacket.smbserver and SMB1/SMB2 structures. KarmaSMBServer protocol handlers are central; keep path normalization, file sizes and offsets, and handle lifecycles consistent across both dialects.

Verification

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