search

jborean93 / smbprotocol

Python SMBv2 and v3 Client
MIT License
309 stars 72 forks source link

readme

smbprotocol

SMBv2 and v3 Client for Python.

Test workflow codecov PyPI version License

SMB is a network file sharing protocol and has numerous iterations over the years. This library implements the SMBv2 and SMBv3 protocol based on the MS-SMB2 document.

Features

This is definitely not feature complete as SMB is quite a complex protocol, see backlog for features that would be nice to have in this library.

Requirements

To use Kerberos authentication on Linux, further dependencies are required, to install these dependencies run

# for Debian/Ubuntu/etc:
sudo apt-get install gcc python-dev libkrb5-dev
pip install smbprotocol[kerberos]

# for RHEL/CentOS/etc:
sudo yum install gcc python-devel krb5-devel krb5-workstation python-devel
pip install smbprotocol[kerberos]

Kerberos auth with Windows should just work out of the box with the pyspnego library but on Linux, the python-gssapi library must be installed and smbprotocol requires a particular GSSAPI extension to be available to work. This extension should be installed on the majority of MIT or Heimdal Kerberos installs but that is not a guarantee. To verify that Kerberos is available on Linux you can run the following check in a Python console:

try:
    from gssapi.raw import inquire_sec_context_by_oid
    print("python-gssapi extension is available")
except ImportError as exc:
    print(f"python-gssapi extension is not available: {exc}")

If it isn't available, then either a newer version of the system's gssapi implementation needs to be setup and python-gssapi compiled against that newer version. In the absence of this extension, only NTLM auth is used.

Installation

To install smbprotocol, simply run

pip install smbprotocol

# To install with Kerberos support
pip install smbprotocol[kerberos]

This will download the required packages that are used in this package and get your Python environment ready to go.

Additional Info

One of the first steps as part of the SMB protocol is to negotiate the dialect used and other features that are available. Currently smbprotocol supports the following dialects;

Each dialect adds in more features to the protocol where some are minor but some are major. One major changes is in Dialect 3.x where it added message encryption. Message encryption is set to True by default and needs to be overridden when creating a Session object for the older dialects.

By default, the negotiation process will use the latest dialect that is supported by the server but this can be overridden if required. When this is done by the following code

import uuid

from smbprotocol.connection import Connection, Dialects

connection = Connection(uuid.uuid4(), "server", 445)
connection.connect(Dialects.SMB_3_0_2)

While you shouldn't want to downgrade to an earlier version, this does allow you to set a minimum dialect version if required.

Examples

There are 2 different APIs you can use with this library.

The examples folder contains some examples of both the high and low level interface but for everyday user's it is recommended to use smbclient as it is a lot simpler.

smbclient Interface

The higher level interface smbclient is designed to make this library easier for people to use for simple and common use cases. It is designed to replicate the builtin os and os.path filesystem functions like os.open(), os.stat(), and os.path.exists(). It is also designed to handle connections to a DFS target unlike smbprotocol.

A connection made by smbclient is kept in a pool and re-used for future requests to the same server until the Python process exists. This makes authentication simple and only required for the first call to the server. Any DFS referrals are also cached in that Python process. This optimises any future requests to that same DFS namespace.

The functions in smbclient have a global config object that can be used to set any connection defaults to use for any future connections. It can also be used to specify any domain based DFS settings for more advanced setups. It is recommended to use ClientConfig() to set any global credentials like so:

import smbclient

smbclient.ClientConfig(username='user', password='password')

The ClientConfig is a singleton and any future instanciations of that object will just update the keys being set. You can set the following keys on the ClientConfig:

As well as setting the default credentials on the ClientConfig you can also specify the credentials and other connection parameters on each smbclient function or when registering a new server. These functions accept the following kwargs:

If using Kerberos authentication and a Kerberos ticket has already set by kinit then smbclient will automatically use those credentials without having to be explicitly set. If no ticket has been retrieved or you wish to use different credentials then set the default credentials on the ClientConfig or specify username and password on the first request to the server.

For example I only need to set the credentials on the first request to create the directory and not for the subsequent file creation in that dir.

import smbclient

# Optional - specify the default credentials to use on the global config object
smbclient.ClientConfig(username='user', password='pass')

# Optional - register the credentials with a server (overrides ClientConfig for that server)
smbclient.register_session("server", username="user", password="pass")

smbclient.mkdir(r"\\server\share\directory", username="user", password="pass")

with smbclient.open_file(r"\\server\share\directory\file.txt", mode="w") as fd:
    fd.write(u"file contents")

If you wish to reset the cache you can either start a new Python process or call smbclient.reset_connection_cache() to close all the connections that have been cached by the client.

Logging

This library makes use of the builtin Python logging facilities. Log messages are logged to the smbprotocol named logger as well as smbprotocol.* where * is each python script in the smbprotocol directory.

These logs are really useful when debugging issues as they give you a more step by step snapshot of what it is doing and what may be going wrong. The debug side will also print out a human readable string of each SMB packet that is sent out from the client so it can get very verbose.

Testing

To this module, you need to install some pre-requisites first. This can be done by running;

# Install in current environment.
# Recommend to have virtual environment installed at .venv path.
pip install -r requirements-dev.txt
pip install -e .

# you can also run tox by installing tox
pip install tox

From there to run the basic tests run;

py.test -v --cov smbprotocol --cov-report term-missing

# or with tox for dedicated virtual environments and multiple Python versions.
tox

Before sending the code for review, besides making sure all the test pass, check that the code complies with the coding standards:

source ./build_helpers/lib.sh

lib::sanity::run

There are extra tests that only run when certain environment variables are set. To run these tests set the following variables;

From here running tox or py.test with these environment variables set will activate the integration tests.

This requires either Windows 10 or Server 2016 as they support Dialect 3.1.1 which is required by the tests.

If you don't have access to a Windows host, you can use Docker to setup a Samba container and use that as part of the tests. To do so run the following bash commands;

source ./build_helpers/lib.sh

lib::setup::smb_server

This command will also set the required SMB_* env vars used in testing.

Backlog

Here is a list of features that I would like to incorporate, PRs are welcome if you want to implement them yourself;