Estructura inicial funcional con documentación en el README.md de la FastAPI
This commit is contained in:
1
env/lib/python3.12/site-packages/smbprotocol-1.17.0.dist-info/INSTALLER
vendored
Normal file
1
env/lib/python3.12/site-packages/smbprotocol-1.17.0.dist-info/INSTALLER
vendored
Normal file
@@ -0,0 +1 @@
|
||||
pip
|
||||
305
env/lib/python3.12/site-packages/smbprotocol-1.17.0.dist-info/METADATA
vendored
Normal file
305
env/lib/python3.12/site-packages/smbprotocol-1.17.0.dist-info/METADATA
vendored
Normal file
@@ -0,0 +1,305 @@
|
||||
Metadata-Version: 2.4
|
||||
Name: smbprotocol
|
||||
Version: 1.17.0
|
||||
Summary: Interact with a server using the SMB 2/3 Protocol
|
||||
Author-email: Jordan Borean <jborean93@gmail.com>
|
||||
License-Expression: MIT
|
||||
Project-URL: homepage, https://github.com/jborean93/smbprotocol
|
||||
Keywords: smb,smb2,smb3,cifs,python
|
||||
Classifier: Development Status :: 4 - Beta
|
||||
Classifier: Programming Language :: Python :: 3
|
||||
Classifier: Programming Language :: Python :: 3.10
|
||||
Classifier: Programming Language :: Python :: 3.11
|
||||
Classifier: Programming Language :: Python :: 3.12
|
||||
Classifier: Programming Language :: Python :: 3.13
|
||||
Classifier: Programming Language :: Python :: 3.14
|
||||
Requires-Python: >=3.10
|
||||
Description-Content-Type: text/markdown
|
||||
License-File: LICENSE
|
||||
Requires-Dist: cryptography>=2.0
|
||||
Requires-Dist: pyspnego
|
||||
Provides-Extra: kerberos
|
||||
Requires-Dist: pyspnego[kerberos]; extra == "kerberos"
|
||||
Dynamic: license-file
|
||||
|
||||
# smbprotocol
|
||||
SMBv2 and v3 Client for Python.
|
||||
|
||||
|
||||
[](https://github.com/jborean93/smbprotocol/actions/workflows/ci.yml)
|
||||
[](https://codecov.io/gh/jborean93/smbprotocol)
|
||||
[](https://badge.fury.io/py/smbprotocol)
|
||||
[](https://github.com/jborean93/smbprotocol/blob/master/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](https://msdn.microsoft.com/en-us/library/cc246482.aspx) document.
|
||||
|
||||
|
||||
## Features
|
||||
|
||||
* Negotiation of the SMB 2.0.2 protocol to SMB 3.1.1 (Windows 10/Server 2016)
|
||||
* Authentication with both NTLM and Kerberos
|
||||
* Message signing
|
||||
* Message encryption (SMB 3.x.x+)
|
||||
* Connect to a Tree/Share
|
||||
* Opening of files, pipes and directories
|
||||
* Set create contexts when opening files
|
||||
* Read and writing of files and pipes
|
||||
* Sending IOCTL commands
|
||||
* Sending of multiple messages in one packet (compounding)
|
||||
* Experimental support for both standalone and DFS server shares
|
||||
|
||||
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
|
||||
|
||||
* Python 3.10+
|
||||
* For Kerberos auth on Linux
|
||||
* [python-gssapi](https://github.com/pythongssapi/python-gssapi)
|
||||
* [pykrb5](https://github.com/jborean93/pykrb5)
|
||||
|
||||
To use Kerberos authentication on Linux, further dependencies are required, to install these dependencies run
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```python
|
||||
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
|
||||
|
||||
```bash
|
||||
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;
|
||||
|
||||
* `2.0.0`: Added with Server 2008/Windows Vista
|
||||
* `2.1.0`: Added with Server 2008 R2/Windows 7
|
||||
* `3.0.0`: Added with Server 2012/Windows 8
|
||||
* `3.0.2`: Added with Server 2012 R2/Windows 8.1
|
||||
* `3.1.1`: Added with Server 2016/Windows10
|
||||
|
||||
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
|
||||
|
||||
```python
|
||||
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.
|
||||
|
||||
* `smbprotocol`: Low level interface that can do whatever you want but quite verbose
|
||||
* `smbclient`: Higher level interface that implements the builtin `os` and `os.path` file system functions but for SMB support
|
||||
|
||||
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:
|
||||
|
||||
```python
|
||||
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`:
|
||||
|
||||
* `client_guid`: The client GUID to identify the client to the server on a new connection
|
||||
* `username`: The default username to use when creating a new SMB session if explicit credentials weren't set
|
||||
* `password`: The default password to use for authentication
|
||||
* `domain_controller`: The domain controller hostname. This is useful for environments with DFS servers as it is used to identify the DFS domain information automatically
|
||||
* `skip_dfs`: Whether to skip doing any DFS resolution, useful if there is a bug or you don't want to waste any roundtrip requesting referrals
|
||||
* `auth_protocol`: The authentication protocol to use; `negotiate` (default), `kerberos`, or `ntlm`
|
||||
* `require_secure_negotiate`: Control whether the client validates the negotiation info when connecting to a share (default: `True`).
|
||||
* More information can be found on [SMB3 Secure Dialect Negotiation](https://docs.microsoft.com/en-us/archive/blogs/openspecification/smb3-secure-dialect-negotiation)
|
||||
|
||||
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:
|
||||
|
||||
* `username`: The username used to connect to the share
|
||||
* `password`: The password used to connect to the share
|
||||
* `port`: Override the default port (`445`) to connect to
|
||||
* `encrypt`: Whether to force encryption on the connection, requires SMBv3 or newer on the remote server (default: `False`)
|
||||
* `connection_timeout`: Override the connection timeout in seconds (default: `60`)
|
||||
|
||||
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.
|
||||
|
||||
```python
|
||||
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;
|
||||
|
||||
```bash
|
||||
# Install in current environment.
|
||||
# Recommend to have virtual environment installed at .venv path.
|
||||
# Dependency groups need pip 25.1+.
|
||||
python -m pip install "pip>=25.1"
|
||||
pip install -e . --group dev
|
||||
```
|
||||
|
||||
From there to run the basic tests run;
|
||||
|
||||
```bash
|
||||
python -m pytest -v --cov smbprotocol --cov-report term-missing
|
||||
```
|
||||
|
||||
Before sending the code for review, besides making sure all the test pass,
|
||||
check that the code complies with the coding standards:
|
||||
|
||||
```bash
|
||||
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;
|
||||
|
||||
* `SMB_USER`: The username to authenticate with
|
||||
* `SMB_PASSWORD`: The password to authenticate with
|
||||
* `SMB_SERVER`: The IP or hostname of the server to authenticate with
|
||||
* `SMB_PORT`: The port the SMB server is listening on, default is `445`
|
||||
* `SMB_SHARE`: The name of the share to connect to, a share with this name must exist as well as a share with the name`$SMB_SHARE-encrypted` must also exist that forces encryption
|
||||
|
||||
From here running `pytest` 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;
|
||||
|
||||
```bash
|
||||
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;
|
||||
|
||||
* Multiple channel support to speed up large data transfers
|
||||
* Lots and lots more...
|
||||
55
env/lib/python3.12/site-packages/smbprotocol-1.17.0.dist-info/RECORD
vendored
Normal file
55
env/lib/python3.12/site-packages/smbprotocol-1.17.0.dist-info/RECORD
vendored
Normal file
@@ -0,0 +1,55 @@
|
||||
smbclient/__init__.py,sha256=TEagfJq_z-Ga1R4kRAoIv84sePDTBpqZf4iaFEfmzfk,873
|
||||
smbclient/__pycache__/__init__.cpython-312.pyc,,
|
||||
smbclient/__pycache__/_io.cpython-312.pyc,,
|
||||
smbclient/__pycache__/_os.cpython-312.pyc,,
|
||||
smbclient/__pycache__/_pool.cpython-312.pyc,,
|
||||
smbclient/__pycache__/path.cpython-312.pyc,,
|
||||
smbclient/__pycache__/shutil.cpython-312.pyc,,
|
||||
smbclient/_io.py,sha256=DX--j5Qalgu6LuGZbhIbULUfrqvRVDok6BL14UArUkU,25386
|
||||
smbclient/_os.py,sha256=JZ1De3qVC8eYoNjdkyG1Uo5XkWeTgbjtsatatv10xq0,64872
|
||||
smbclient/_pool.py,sha256=Ktt4lzcOycetrKc1tKxGREnqM-gKhrZjKNG65zHLn74,20003
|
||||
smbclient/path.py,sha256=dDrPTeOl9RiOYgBWTxSqqr1YW50Kxj7MrxEDsRcq1LI,5372
|
||||
smbclient/shutil.py,sha256=6eX5XSPSwu7MKKTj79W_LOxw1Kk1e9SkmyG2gfJSTZo,22669
|
||||
smbprotocol-1.17.0.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4
|
||||
smbprotocol-1.17.0.dist-info/METADATA,sha256=afDyu5l9jgf73ttwjNgHYiAI_I96wwwCh3d0dicaI_g,12234
|
||||
smbprotocol-1.17.0.dist-info/RECORD,,
|
||||
smbprotocol-1.17.0.dist-info/REQUESTED,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
||||
smbprotocol-1.17.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
|
||||
smbprotocol-1.17.0.dist-info/licenses/LICENSE,sha256=TDxVCrwrBMUH7Q1kHdflJOr_W9BseGKvlXMBg21JbRU,1079
|
||||
smbprotocol-1.17.0.dist-info/top_level.txt,sha256=FKBCscFI5BKUeJcqiEtAMZn7LXm9x6RV5JVr43H89Ns,22
|
||||
smbprotocol/__init__.py,sha256=KgH_63k6QJ2nBudMpUON8hG8E7Xmh1NqOZ-o4Tkkoto,592
|
||||
smbprotocol/__pycache__/__init__.cpython-312.pyc,,
|
||||
smbprotocol/__pycache__/_text.cpython-312.pyc,,
|
||||
smbprotocol/__pycache__/change_notify.cpython-312.pyc,,
|
||||
smbprotocol/__pycache__/connection.cpython-312.pyc,,
|
||||
smbprotocol/__pycache__/create_contexts.cpython-312.pyc,,
|
||||
smbprotocol/__pycache__/dfs.cpython-312.pyc,,
|
||||
smbprotocol/__pycache__/exceptions.cpython-312.pyc,,
|
||||
smbprotocol/__pycache__/file_info.cpython-312.pyc,,
|
||||
smbprotocol/__pycache__/header.cpython-312.pyc,,
|
||||
smbprotocol/__pycache__/ioctl.cpython-312.pyc,,
|
||||
smbprotocol/__pycache__/open.cpython-312.pyc,,
|
||||
smbprotocol/__pycache__/query_info.cpython-312.pyc,,
|
||||
smbprotocol/__pycache__/reparse_point.cpython-312.pyc,,
|
||||
smbprotocol/__pycache__/security_descriptor.cpython-312.pyc,,
|
||||
smbprotocol/__pycache__/session.cpython-312.pyc,,
|
||||
smbprotocol/__pycache__/structure.cpython-312.pyc,,
|
||||
smbprotocol/__pycache__/transport.cpython-312.pyc,,
|
||||
smbprotocol/__pycache__/tree.cpython-312.pyc,,
|
||||
smbprotocol/_text.py,sha256=tLJK8NhOCjkpLsX1GY2QrLNzjtdjomKKwOG6vWCjALs,833
|
||||
smbprotocol/change_notify.py,sha256=G40VmHCm4qEnyLoQHlboywZyDQYHXHvmAfe9EYixPus,11691
|
||||
smbprotocol/connection.py,sha256=wvTfuUVNyssyr3sfC2HUqgmk4i0Pi5huecTD68SuL3w,71515
|
||||
smbprotocol/create_contexts.py,sha256=h-eW5H-SjZlbgwT67pOMyDteY10L_S2pvtkSvs8adwU,27160
|
||||
smbprotocol/dfs.py,sha256=EiJTZZWNzzMLKDPG5aeYX0GwvL8lh6wZJsE-1ObufRw,15223
|
||||
smbprotocol/exceptions.py,sha256=S18z5UQJhcKYNhHYrRs4elb3i4Vds4xS_EpZCthM3pw,35938
|
||||
smbprotocol/file_info.py,sha256=9GA34QJO9h-AfjrDN6baR7YIAMVg9fC0ggY4LgLnAXg,34157
|
||||
smbprotocol/header.py,sha256=4CGaBc6HySKWuiHozjPN1lycSlZKBIDuNCIjWosHSyU,9926
|
||||
smbprotocol/ioctl.py,sha256=hlVLPMKvvpqsNu5TYeARV_RkLqZiSgltanQUG-oLlBY,18749
|
||||
smbprotocol/open.py,sha256=0_tswZzczUHnIfnH8Wnko-u3gMqyTpkDZIAf7nD8fcM,59707
|
||||
smbprotocol/query_info.py,sha256=PCciijEVw8YbNaO9hrKnT4mM1vQX9fnsjXJGOF8duho,370
|
||||
smbprotocol/reparse_point.py,sha256=bXMoHNhUVTAu7Fz0TYdvUtdB21N7OxJMeNItcC7mNyY,7589
|
||||
smbprotocol/security_descriptor.py,sha256=Pf0UzELN5_1ZtIYO-6i8zD__duHna5yP_Jb3BUCnIsY,12912
|
||||
smbprotocol/session.py,sha256=SBXLqwJQMsUe4pHfljb1dEkUpXF9qmD3bKBTmFv1-V4,17713
|
||||
smbprotocol/structure.py,sha256=7-CvoLy-A48dThRaUMY5R-9wJyg1IdTzXqJkANO0jMw,33078
|
||||
smbprotocol/transport.py,sha256=YnbAcyw47OJAfPI4UpO0wNPmdv07N_1Vo7uhE30Jelk,6190
|
||||
smbprotocol/tree.py,sha256=j5RgaW_CIat4FcEAROTQgiG4jpuAT_K3ASOvckLADjI,13386
|
||||
0
env/lib/python3.12/site-packages/smbprotocol-1.17.0.dist-info/REQUESTED
vendored
Normal file
0
env/lib/python3.12/site-packages/smbprotocol-1.17.0.dist-info/REQUESTED
vendored
Normal file
5
env/lib/python3.12/site-packages/smbprotocol-1.17.0.dist-info/WHEEL
vendored
Normal file
5
env/lib/python3.12/site-packages/smbprotocol-1.17.0.dist-info/WHEEL
vendored
Normal file
@@ -0,0 +1,5 @@
|
||||
Wheel-Version: 1.0
|
||||
Generator: setuptools (83.0.0)
|
||||
Root-Is-Purelib: true
|
||||
Tag: py3-none-any
|
||||
|
||||
21
env/lib/python3.12/site-packages/smbprotocol-1.17.0.dist-info/licenses/LICENSE
vendored
Normal file
21
env/lib/python3.12/site-packages/smbprotocol-1.17.0.dist-info/licenses/LICENSE
vendored
Normal file
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2017 Jordan Borean, Red Hat
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
2
env/lib/python3.12/site-packages/smbprotocol-1.17.0.dist-info/top_level.txt
vendored
Normal file
2
env/lib/python3.12/site-packages/smbprotocol-1.17.0.dist-info/top_level.txt
vendored
Normal file
@@ -0,0 +1,2 @@
|
||||
smbclient
|
||||
smbprotocol
|
||||
Reference in New Issue
Block a user