Documentation Index
Fetch the complete documentation index at: https://mintlify.com/fortra/impacket/llms.txt
Use this file to discover all available pages before exploring further.
Overview
The smb module provides a complete implementation of the SMB (Server Message Block) protocol version 1. This module handles low-level SMB packet construction, authentication, file operations, and named pipe communication.
Key Classes
SMB
Main class for SMB protocol implementation.
from impacket import smb
conn = smb.SMB(remote_name, remote_host)
conn.login(user, password, domain)
The NetBIOS name of the remote host. Use '*SMBSERVER' for auto-detection.
IP address or hostname of the remote server
Local NetBIOS name. Defaults to local hostname if not specified.
Port number for NetBIOS session service
Connection timeout in seconds
Methods
login()
Authenticate to the SMB server using NTLM.
conn.login(user, password, domain='', lmhash='', nthash='')
Username for authentication
Password for authentication (not used if hashes provided)
Domain name for authentication
LM hash for pass-the-hash authentication
NT hash for pass-the-hash authentication
Raises SessionError if authentication fails
connect_tree()
Connect to a shared resource on the server.
tid = conn.connect_tree(share)
UNC path to the share (e.g., '\\\\server\\share')
Tree ID (TID) used for subsequent file operations
list_path()
List files and directories in a share.
files = conn.list_path(shareName, path, password=None)
Name of the share to list
Path relative to the share root (e.g., '*' for all files)
Password for password-protected shares
List of SharedFile objects containing file information
open()
Open or create a file on the share.
fid = conn.open(tid, path, desired_access, share_mode,
creation_options, creation_disposition,
file_attributes)
Tree ID from connect_tree()
Path to the file relative to share root
Access mask specifying desired operations (e.g., FILE_READ_DATA, FILE_WRITE_DATA)
Share mode flags (e.g., FILE_SHARE_READ, FILE_SHARE_WRITE)
Creation options (e.g., FILE_NON_DIRECTORY_FILE)
Creation disposition (e.g., FILE_OPEN, FILE_CREATE, FILE_OVERWRITE_IF)
File attributes (e.g., ATTR_NORMAL, ATTR_READONLY)
File ID (FID) used for read/write operations
read_andx()
Read data from an open file.
data = conn.read_andx(tid, fid, offset=0, max_size=None)
Byte offset to start reading from
Maximum bytes to read. Defaults to server’s max buffer size.
write_andx()
Write data to an open file.
bytes_written = conn.write_andx(tid, fid, data, offset=0)
Data to write to the file
Byte offset to start writing at
close()
Close an open file.
logoff()
Log off from the SMB server.
Constants
File Attributes
ATTR_READONLY = 0x001 # Read-only file
ATTR_HIDDEN = 0x002 # Hidden file
ATTR_SYSTEM = 0x004 # System file
ATTR_DIRECTORY = 0x010 # Directory
ATTR_ARCHIVE = 0x020 # Archive flag
ATTR_NORMAL = 0x080 # Normal file
ATTR_TEMPORARY = 0x100 # Temporary file
ATTR_COMPRESSED = 0x800 # Compressed file
Access Masks
FILE_READ_DATA = 0x00000001 # Read file data
FILE_WRITE_DATA = 0x00000002 # Write file data
FILE_APPEND_DATA = 0x00000004 # Append to file
FILE_READ_EA = 0x00000008 # Read extended attributes
FILE_WRITE_EA = 0x00000010 # Write extended attributes
FILE_EXECUTE = 0x00000020 # Execute file
FILE_READ_ATTRIBUTES = 0x00000080 # Read file attributes
FILE_WRITE_ATTRIBUTES = 0x00000100 # Write file attributes
DELETE = 0x00010000 # Delete file
GENERIC_READ = 0x80000000 # Generic read access
GENERIC_WRITE = 0x40000000 # Generic write access
GENERIC_ALL = 0x10000000 # All access rights
Share Access Modes
FILE_SHARE_READ = 0x00000001 # Allow concurrent read access
FILE_SHARE_WRITE = 0x00000002 # Allow concurrent write access
FILE_SHARE_DELETE = 0x00000004 # Allow concurrent delete access
Creation Disposition
FILE_SUPERSEDE = 0x00000000 # Replace file if exists, create if not
FILE_OPEN = 0x00000001 # Open existing file only
FILE_CREATE = 0x00000002 # Create new file only
FILE_OPEN_IF = 0x00000003 # Open if exists, create if not
FILE_OVERWRITE = 0x00000004 # Overwrite existing file only
FILE_OVERWRITE_IF = 0x00000005 # Overwrite if exists, create if not
Supporting Classes
SharedFile
Represents file information returned by list_path().
Returns the full filename
Returns the 8.3 short filename
Returns file size in bytes
Returns True if item is a directory
Returns True if file is read-only
Returns True if file is hidden
Returns creation time as Unix timestamp
Returns modification time as Unix timestamp
Returns access time as Unix timestamp
SessionError
Exception raised when SMB operations fail.
try:
conn.login(user, password)
except smb.SessionError as e:
print(f"Error: {e}")
error_code = e.get_error_code()
Returns the SMB error code
Usage Examples
Basic File Operations
from impacket import smb
from impacket.smb import FILE_OPEN, FILE_SHARE_READ
# Connect to server
conn = smb.SMB('*SMBSERVER', '192.168.1.100')
conn.login('user', 'password', 'DOMAIN')
# Connect to share
tid = conn.connect_tree('\\\\192.168.1.100\\share')
# List files
files = conn.list_path('share', '*')
for f in files:
print(f"{f.get_longname()} - {f.get_filesize()} bytes")
# Read a file
fid = conn.open(tid, 'example.txt', smb.FILE_READ_DATA,
FILE_SHARE_READ, smb.FILE_NON_DIRECTORY_FILE,
FILE_OPEN, smb.ATTR_NORMAL)
data = conn.read_andx(tid, fid)
conn.close(tid, fid)
print(data.decode('utf-8'))
# Clean up
conn.logoff()
Writing Files
from impacket import smb
conn = smb.SMB('*SMBSERVER', '192.168.1.100')
conn.login('user', 'password')
tid = conn.connect_tree('\\\\192.168.1.100\\share')
# Create and write to file
fid = conn.open(tid, 'output.txt',
smb.FILE_WRITE_DATA | smb.FILE_READ_DATA,
smb.FILE_SHARE_READ, smb.FILE_NON_DIRECTORY_FILE,
smb.FILE_OVERWRITE_IF, smb.ATTR_NORMAL)
data = b"Hello, SMB World!"
conn.write_andx(tid, fid, data)
conn.close(tid, fid)
conn.logoff()
Pass-the-Hash Authentication
from impacket import smb
import hashlib
conn = smb.SMB('*SMBSERVER', '192.168.1.100')
# Authenticate using NTLM hash
lmhash = 'aad3b435b51404eeaad3b435b51404ee'
nthash = '8846f7eaee8fb117ad06bdd830b7586c'
conn.login('admin', '', domain='CORP', lmhash=lmhash, nthash=nthash)
tid = conn.connect_tree('\\\\192.168.1.100\\C$')
# Now you can perform operations
files = conn.list_path('C$', '*')
conn.logoff()
Error Handling
from impacket import smb
from impacket.nt_errors import STATUS_ACCESS_DENIED, STATUS_OBJECT_NAME_NOT_FOUND
try:
conn = smb.SMB('*SMBSERVER', '192.168.1.100')
conn.login('user', 'wrongpassword')
except smb.SessionError as e:
if e.get_error_code() == STATUS_ACCESS_DENIED:
print("Access denied - check credentials")
else:
print(f"SMB Error: {e}")
Helper Functions
Time Conversion
from impacket import smb
import time
# Convert POSIX timestamp to Windows FILETIME
posix_time = int(time.time())
filetime = smb.POSIXtoFT(posix_time)
# Convert FILETIME to POSIX timestamp
posix_time = smb.FTtoPOSIX(filetime)
See Also
- SMBConnection - High-level SMB client wrapper
- SMB3 - SMB2/SMB3 protocol implementation
- NTLM - NTLM authentication helpers
