SMB Protocol Library

Warnings

• breaking SMBv1 (Server Message Block version 1) support was completely removed starting from smbprotocol version 1.0.0. This library now exclusively supports SMBv2 and SMBv3.
  Fix: Ensure your SMB server supports SMBv2 or SMBv3. If you are connecting to older systems (e.g., Windows XP, Windows Server 2003 without updates), you will need to upgrade the server or use a different library.
• gotcha All `smbprotocol` objects representing server resources (e.g., `Connection`, `Session`, `TreeConnect`, `Open`) require explicit disconnection or closing. Failing to call `.disconnect()` or `.close()` will lead to resource leaks on both the client and server.
  Fix: Always wrap your `smbprotocol` operations in `try...finally` blocks to ensure that `.disconnect()` or `.close()` methods are called for all instantiated resource objects. For file-like objects, consider using a `with` statement if available (e.g., `smbprotocol.file.File` does support `with`).
• gotcha Authentication can be complex, especially with Active Directory domains or specific security policies. Incorrectly providing the username (e.g., missing domain prefix for domain accounts, using UPN instead of samAccountName) or incorrect password hashing can lead to failed connections.
  Fix: Verify the exact username format required by your SMB server (e.g., `DOMAIN\username`, `username@domain.com`, or just `username` for local accounts). Ensure the password is correct. For Active Directory, you might need to ensure proper DNS resolution and Kerberos setup if using Kerberos authentication.
• gotcha The `smbprotocol` library provides a synchronous API. While it can be used within an `asyncio` application, it does not directly support `await` and will block the event loop if not run in a separate thread or process.
  Fix: If integrating into an `asyncio` application, use `loop.run_in_executor()` to run `smbprotocol` calls in a separate thread pool to prevent blocking the main event loop.

Install

• pip install smbprotocol Install stable version

Imports

• Connection

  from smbprotocol.connection import Connection

• Session

  from smbprotocol.session import Session

• TreeConnect

  from smbprotocol.tree import TreeConnect

• Open

  from smbprotocol.open import Open

• FilePipe

  from smbprotocol.file import FilePipe

• CreateDisposition

  from smbprotocol.file import CreateDisposition

Quickstart

This quickstart demonstrates how to establish a connection to an SMB server, authenticate a user, connect to a shared folder, and list its contents. It emphasizes the critical need to explicitly close all resources (Connection, Session, TreeConnect, Open objects) in a `finally` block to prevent resource leaks.

import os
from smbprotocol.connection import Connection
from smbprotocol.session import Session
from smbprotocol.tree import TreeConnect
from smbprotocol.open import Open, CreateDisposition

# Replace with your SMB server details
SERVER_IP = os.environ.get('SMB_SERVER_IP', '127.0.0.1')
USERNAME = os.environ.get('SMB_USERNAME', 'guest')
PASSWORD = os.environ.get('SMB_PASSWORD', '')
SHARE_NAME = os.environ.get('SMB_SHARE_NAME', 'share') # e.g., 'myshare'

def list_share_contents():
    connection = None
    session = None
    tree_connect = None
    try:
        print(f"Connecting to {SERVER_IP}...")
        connection = Connection(SERVER_IP, port=445)
        connection.connect()
        print("Connection established.")

        print(f"Authenticating as {USERNAME}...")
        session = Session(connection, USERNAME, PASSWORD)
        session.connect()
        print("Authentication successful.")

        print(f"Connecting to share \\{SERVER_IP}\{SHARE_NAME}...")
        # SMB paths use backslashes, but smbprotocol handles forward slashes too
        tree_connect = TreeConnect(connection, session, f'\\\\{SERVER_IP}\\{SHARE_NAME}')
        tree_connect.connect()
        print(f"Connected to share '{SHARE_NAME}'.")

        print(f"Listing contents of '{SHARE_NAME}':")
        # Open the directory itself to enumerate its contents
        dir_open = Open(tree_connect, '/*', CreateDisposition.FILE_OPEN, access_mask=0x80000000) # FILE_LIST_DIRECTORY
        dir_open.create()

        for entry in dir_open.query_directory():
            print(f"  - {entry.file_name}")
        dir_open.close()
        
    except Exception as e:
        print(f"An error occurred: {e}")
    finally:
        if tree_connect:
            print("Disconnecting from tree connect...")
            tree_connect.disconnect()
        if session:
            print("Logging off session...")
            session.logoff()
        if connection:
            print("Disconnecting connection...")
            connection.disconnect()
        print("Cleanup complete.")

if __name__ == '__main__':
    list_share_contents()