SMBConnection

Overview

The SMBConnection class provides a unified, high-level interface for SMB communication that automatically handles protocol negotiation between SMB1, SMB2, and SMB3. It abstracts away protocol-specific details and provides a consistent API regardless of the underlying SMB version.

Class Definition

Main class for SMB client operations with automatic protocol negotiation.

from impacket.smbconnection import SMBConnection

conn = SMBConnection(remoteName, remoteHost, myName=None, 
                      sess_port=445, timeout=60, 
                      preferredDialect=None)

remoteName

str

required

NetBIOS name of the remote host. Use '*SMBSERVER' for automatic detection, or provide the actual hostname.

remoteHost

str

required

IP address or hostname of the target server

myName

str

Local NetBIOS name. If None, uses the local hostname.

sess_port

int

default:"445"

SMB session port. Use 445 for direct TCP or 139 for NetBIOS

timeout

int

default:"60"

Connection timeout in seconds

preferredDialect

str | int

Preferred SMB dialect. Options:

SMB_DIALECT - SMB1 (NT LM 0.12)
SMB2_DIALECT_002 - SMB 2.0.2
SMB2_DIALECT_21 - SMB 2.1
SMB2_DIALECT_30 - SMB 3.0
SMB2_DIALECT_311 - SMB 3.1.1

If None, negotiates the highest supported version.

Authentication Methods

Authenticate using NTLM.

conn.login(user, password, domain='', lmhash='', nthash='', 
           ntlmFallback=True)

user

str

required

Username for authentication

password

str

required

User password (not used if hashes are provided)

domain

str

default:"''"

Domain name for the account

lmhash

str

default:"''"

LM hash for pass-the-hash authentication (hex string)

nthash

str

default:"''"

NT hash for pass-the-hash authentication (hex string)

ntlmFallback

bool

default:"True"

Allow fallback to NTLMv1 if NTLMv2 fails (SMB1 only)

raises

SessionError

Raised if authentication fails

kerberosLogin()

Authenticate using Kerberos.

conn.kerberosLogin(user, password, domain='', lmhash='', nthash='',
                   aesKey='', kdcHost=None, TGT=None, TGS=None,
                   useCache=True)

user

str

required

Username for authentication

password

str

required

User password

domain

str

required

Domain name (required for Kerberos)

lmhash

str

default:"''"

LM hash for RC4-HMAC if AES not supported

nthash

str

default:"''"

NT hash for RC4-HMAC if AES not supported

aesKey

str

default:"''"

AES key (aes256-cts-hmac-sha1-96 or aes128-cts-hmac-sha1-96)

kdcHost

str

Hostname or IP of the KDC. If None, uses DNS to resolve the domain.

TGT

dict

Pre-obtained Ticket Granting Ticket

TGS

dict

Pre-obtained Ticket Granting Service ticket

useCache

bool

default:"True"

Use credential cache for ticket lookup

File and Directory Operations

connectTree()

Connect to a network share.

tid = conn.connectTree(share)

Share name (e.g., 'ADMIN$', 'C$', 'IPC$')

return

int

Tree ID for use in subsequent operations

listPath()

List files and directories in a share.

files = conn.listPath(shareName, path, password=None)

Name of the share to list

path

str

required

Path pattern (e.g., '*' for all files, '*.txt' for text files)

password

str

Password for password-protected shares

return

list[SharedFile]

List of SharedFile objects

createFile()

Create or open a file.

fid = conn.createFile(treeId, pathName, desiredAccess=GENERIC_ALL,
                       shareMode=FILE_SHARE_READ | FILE_SHARE_WRITE,
                       creationOption=FILE_NON_DIRECTORY_FILE,
                       creationDisposition=FILE_OVERWRITE_IF,
                       fileAttributes=FILE_ATTRIBUTE_NORMAL)

treeId

int

required

Tree ID from connectTree()

pathName

str

required

Path to the file relative to share root

desiredAccess

int

default:"GENERIC_ALL"

Access mask (e.g., FILE_READ_DATA, FILE_WRITE_DATA, GENERIC_ALL)

Share access mode

creationOption

int

default:"FILE_NON_DIRECTORY_FILE"

File creation options

creationDisposition

int

default:"FILE_OVERWRITE_IF"

Action to take if file exists

fileAttributes

int

default:"FILE_ATTRIBUTE_NORMAL"

File attributes to set

return

int

File ID (FID) for subsequent operations

openFile()

Open an existing file.

fid = conn.openFile(treeId, pathName, desiredAccess=FILE_READ_DATA,
                     shareMode=FILE_SHARE_READ)

treeId

int

required

Tree ID

pathName

str

required

Path to the file

desiredAccess

int

default:"FILE_READ_DATA"

Access rights requested

Sharing mode

return

int

File ID for the opened file

readFile()

Read data from a file.

data = conn.readFile(treeId, fileId, offset=0, bytesToRead=None,
                      singleCall=True)

treeId

int

required

Tree ID

fileId

int

required

File ID from openFile() or createFile()

offset

int

default:"0"

Byte offset to start reading from

bytesToRead

int

Number of bytes to read. If None, reads maximum buffer size.

singleCall

bool

default:"True"

If True, reads only once. If False, continues reading until bytesToRead is satisfied.

return

bytes

Data read from the file

writeFile()

Write data to a file.

bytes_written = conn.writeFile(treeId, fileId, data, offset=0)

treeId

int

required

Tree ID

fileId

int

required

File ID

data

bytes

required

Data to write

offset

int

default:"0"

Byte offset to write at

return

int

Number of bytes written

closeFile()

Close an open file.

conn.closeFile(treeId, fileId)

treeId

int

required

Tree ID

fileId

int

required

File ID to close

deleteFile()

Delete a file from the share.

conn.deleteFile(shareName, pathName)

Share name

pathName

str

required

Path to the file to delete

getFile()

Download a file using a callback.

with open('local_file.txt', 'wb') as f:
    conn.getFile(shareName, pathName, f.write)

Share name

pathName

str

required

Remote file path

callback

callable

required

Function to call with file data chunks (receives bytes)

Share access mode

putFile()

Upload a file using a callback.

with open('local_file.txt', 'rb') as f:
    conn.putFile(shareName, pathName, f.read)

Share name

pathName

str

required

Remote file path

callback

callable

required

Function to call to get file data (receives int size, returns bytes)

createDirectory()

Create a directory.

conn.createDirectory(shareName, pathName)

Share name

pathName

str

required

Directory path to create

deleteDirectory()

Delete a directory.

conn.deleteDirectory(shareName, pathName)

Share name

pathName

str

required

Directory path to delete

rename()

Rename a file or directory.

conn.rename(shareName, oldPath, newPath)

Share name

oldPath

str

required

Current path

newPath

str

required

New path

Information Retrieval

listShares()

List available shares on the server.

shares = conn.listShares()

return

list[dict]

List of share dictionaries with keys like 'shi1_netname', 'shi1_type', 'shi1_remark'

getDialect()

Get the negotiated SMB dialect.

dialect = conn.getDialect()

return

str | int

The negotiated dialect (e.g., SMB2_DIALECT_311)

getServerName()

Get the server’s NetBIOS name.

server_name = conn.getServerName()

return

str

Server NetBIOS name

getServerDomain()

Get the server’s domain.

domain = conn.getServerDomain()

return

str

Server domain name

getServerOS()

Get the server’s operating system.

os_info = conn.getServerOS()

return

str

Operating system string (e.g., "Windows 10 Build 19041")

isGuestSession()

Check if logged in as guest.

is_guest = conn.isGuestSession()

return

bool

True if guest session, False otherwise

Named Pipe Operations

waitNamedPipe()

Wait for a named pipe to become available.

conn.waitNamedPipe(treeId, pipeName, timeout=5)

treeId

int

required

Tree ID (usually for IPC$ share)

pipeName

str

required

Name of the pipe (e.g., '\\PIPE\\srvsvc')

timeout

int

default:"5"

Timeout in seconds

transactNamedPipe()

Perform a transaction on a named pipe.

conn.transactNamedPipe(treeId, fileId, data, waitAnswer=True)

treeId

int

required

Tree ID

fileId

int

required

File ID of the opened pipe

data

bytes

required

Data to send

waitAnswer

bool

default:"True"

Wait for response

Connection Management

close()

Close the connection and log off.

conn.close()

logoff()

Log off from the server.

conn.logoff()

reconnect()

Reconnect using the same credentials.

conn.reconnect()

Usage Examples

Basic Connection and File Operations

from impacket.smbconnection import SMBConnection

# Connect to server (automatically negotiates SMB version)
conn = SMBConnection('WORKSTATION', '192.168.1.100')

# Authenticate
conn.login('admin', 'password', 'DOMAIN')

# List shares
shares = conn.listShares()
for share in shares:
    print(f"Share: {share['shi1_netname']} - {share['shi1_remark']}")

# List files
files = conn.listPath('C$', '/*')
for f in files:
    print(f"{f.get_longname()} ({f.get_filesize()} bytes)")

# Read a file
tid = conn.connectTree('C$')
fid = conn.openFile(tid, '/Windows/System32/drivers/etc/hosts',
                     FILE_READ_DATA, FILE_SHARE_READ)
data = conn.readFile(tid, fid)
conn.closeFile(tid, fid)

print(data.decode('utf-8'))

# Clean up
conn.close()

Upload and Download Files

from impacket.smbconnection import SMBConnection

conn = SMBConnection('*SMBSERVER', '192.168.1.100')
conn.login('user', 'pass')

# Upload a file
with open('local.txt', 'rb') as f:
    conn.putFile('share', '/remote.txt', f.read)

# Download a file
with open('downloaded.txt', 'wb') as f:
    conn.getFile('share', '/remote.txt', f.write)

conn.close()

Kerberos Authentication

from impacket.smbconnection import SMBConnection

conn = SMBConnection('DC01', '192.168.1.10')

# Authenticate with Kerberos
conn.kerberosLogin('admin', 'password', 'CORP.LOCAL',
                    kdcHost='dc01.corp.local')

# Perform operations
shares = conn.listShares()
for share in shares:
    print(share['shi1_netname'])

conn.close()

Pass-the-Hash

from impacket.smbconnection import SMBConnection

conn = SMBConnection('*SMBSERVER', '192.168.1.100')

# Authenticate using NTLM hash
conn.login('administrator', '', 'WORKGROUP',
           lmhash='aad3b435b51404eeaad3b435b51404ee',
           nthash='8846f7eaee8fb117ad06bdd830b7586c')

tid = conn.connectTree('ADMIN$')
files = conn.listPath('ADMIN$', '/*')
conn.close()

Working with Named Pipes (RPC)

from impacket.smbconnection import SMBConnection
from impacket.dcerpc.v5 import transport

conn = SMBConnection('*SMBSERVER', '192.168.1.100')
conn.login('admin', 'password')

# Use SMBConnection for RPC transport
rpctransport = transport.SMBTransport('192.168.1.100',
                                       filename=r'\pipe\samr',
                                       smb_connection=conn)

dce = rpctransport.get_dce_rpc()
dce.connect()
# ... perform RPC operations ...

conn.close()

Error Handling

from impacket.smbconnection import SMBConnection, SessionError
from impacket.nt_errors import STATUS_LOGON_FAILURE, STATUS_OBJECT_NAME_NOT_FOUND

try:
    conn = SMBConnection('*SMBSERVER', '192.168.1.100')
    conn.login('user', 'wrongpass')
except SessionError as e:
    error_code = e.getErrorCode()
    
    if error_code == STATUS_LOGON_FAILURE:
        print("Invalid credentials")
    else:
        print(f"SMB Error: {e.getErrorString()}")

Core Modules

DCE/RPC

Kerberos

LDAP

Utilities

​Overview

​Class Definition

​SMBConnection

​Authentication Methods

​login()

​kerberosLogin()

​File and Directory Operations

​connectTree()

​listPath()

​createFile()

​openFile()

​readFile()

​writeFile()

​closeFile()

​deleteFile()

​getFile()

​putFile()

​createDirectory()

​deleteDirectory()

​rename()

​Information Retrieval

​listShares()

​getDialect()

​getServerName()

​getServerDomain()

​getServerOS()

​isGuestSession()

​Named Pipe Operations

​waitNamedPipe()

​transactNamedPipe()

​Connection Management

​close()

​logoff()

​reconnect()

​Usage Examples

​Basic Connection and File Operations

​Upload and Download Files

​Kerberos Authentication

​Pass-the-Hash

​Working with Named Pipes (RPC)

​Error Handling

​See Also

Build docs developers (and LLMs) love

Overview

Class Definition

SMBConnection

Authentication Methods

login()

kerberosLogin()

File and Directory Operations

connectTree()

listPath()

createFile()

openFile()

readFile()

writeFile()

closeFile()

deleteFile()

getFile()

putFile()

createDirectory()

deleteDirectory()

rename()

Information Retrieval

listShares()

getDialect()

getServerName()

getServerDomain()

getServerOS()

isGuestSession()

Named Pipe Operations

waitNamedPipe()

transactNamedPipe()

Connection Management

close()

logoff()

reconnect()

Usage Examples

Basic Connection and File Operations

Upload and Download Files

Kerberos Authentication

Pass-the-Hash

Working with Named Pipes (RPC)

Error Handling

See Also