Estructura inicial funcional con documentación en el README.md de la FastAPI

This commit is contained in:
2026-09-25 11:20:50 -03:00
parent edc71742fa
commit 774e227642
2710 changed files with 1012769 additions and 0 deletions

View File

@@ -0,0 +1,22 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
MAX_PAYLOAD_SIZE = 65536
class Dialects:
"""
[MS-SMB2] v53.0 2017-09-15
2.2.3 SMB2 NEGOTIATE Request Dialects
16-bit integeres specifying an SMB2 dialect that is supported. 0x02FF is
used in the SMBv1 negotiate request to say that dialects greater than
2.0.2 is supported.
"""
SMB_2_0_2 = 0x0202
SMB_2_1_0 = 0x0210
SMB_3_0_0 = 0x0300
SMB_3_0_2 = 0x0302
SMB_3_1_1 = 0x0311
SMB_2_WILDCARD = 0x02FF

View File

@@ -0,0 +1,28 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
def to_bytes(value, encoding="utf-8"):
"""
Makes sure the value is encoded as a byte string.
:param value: The Python string value to encode.
:param encoding: The encoding to use.
:return: The byte string that was encoded.
"""
if isinstance(value, bytes):
return value
return value.encode(encoding)
def to_text(value, encoding="utf-8"):
"""
Makes sure the value is decoded as a text string.
:param value: The Python byte string value to decode.
:param encoding: The encoding to use.
:return: The text/unicode string that was decoded.
"""
if isinstance(value, str):
return value
return value.decode(encoding)

View File

@@ -0,0 +1,331 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
import logging
import threading
from collections import OrderedDict
from smbprotocol.exceptions import Cancelled, NotifyEnumDir
from smbprotocol.header import Commands, NtStatus
from smbprotocol.structure import (
BytesField,
EnumField,
FlagField,
IntField,
Structure,
TextField,
)
log = logging.getLogger(__name__)
class ChangeNotifyFlags:
"""
[MS-SMB2] 2.2.35 SMB2 CHANGE_NOTIFY Request - Flags
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-smb2/598f395a-e7a2-4cc8-afb3-ccb30dd2df7c
"""
NONE = 0
SMB2_WATCH_TREE = 0x0001
class CompletionFilter:
"""
[MS-SMB2] 2.2.35 SMB2 CHANGE_NOTIFY Request - CompletionFilter
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-smb2/598f395a-e7a2-4cc8-afb3-ccb30dd2df7c
"""
FILE_NOTIFY_CHANGE_FILE_NAME = 0x00000001
FILE_NOTIFY_CHANGE_DIR_NAME = 0x00000002
FILE_NOTIFY_CHANGE_ATTRIBUTES = 0x00000004
FILE_NOTIFY_CHANGE_SIZE = 0x00000008
FILE_NOTIFY_CHANGE_LAST_WRITE = 0x00000010
FILE_NOTIFY_CHANGE_LAST_ACCESS = 0x00000020
FILE_NOTIFY_CHANGE_CREATION = 0x00000040
FILE_NOTIFY_CHANGE_EA = 0x00000080
FILE_NOTIFY_CHANGE_SECURITY = 0x00000100
FILE_NOTIFY_CHANGE_STREAM_NAME = 0x00000200
FILE_NOTIFY_CHANGE_STREAM_SIZE = 0x00000400
FILE_NOTIFY_CHANGE_STREAM_WRITE = 0x00000800
class FileAction:
"""
[MS-FSCC] 2.7.1 FILE_NOTIFY_INFORMATION - Action
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/634043d7-7b39-47e9-9e26-bda64685e4c9
"""
FILE_ACTION_ADDED = 0x00000001
FILE_ACTION_REMOVED = 0x00000002
FILE_ACTION_MODIFIED = 0x00000003
FILE_ACTION_RENAMED_OLD_NAME = 0x00000004
FILE_ACTION_RENAMED_NEW_NAME = 0x00000005
FILE_ACTION_ADDED_STREAM = 0x00000006
FILE_ACTION_REMOVED_STREAM = 0x00000007
FILE_ACTION_MODIFIED_STREAM = 0x00000008
FILE_ACTION_REMOVED_BY_DELETE = 0x00000009
FILE_ACTION_ID_NOT_TUNNELLED = 0x0000000A
FILE_ACTION_TUNNELLED_ID_COLLISION = 0x0000000B
class FileNotifyInformation(Structure):
"""
[Ms-FSCC] 2.7.1 FILE_NOTIFY_INFORMATION
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/634043d7-7b39-47e9-9e26-bda64685e4c9
"""
def __init__(self):
self.fields = OrderedDict(
[
("next_entry_offset", IntField(size=4)),
(
"action",
EnumField(
size=4,
enum_type=FileAction,
),
),
(
"file_name_length",
IntField(
size=4,
default=lambda s: len(s["file_name"]),
),
),
(
"file_name",
TextField(
encoding="utf-16-le",
size=lambda s: s["file_name_length"].get_value(),
),
),
]
)
super().__init__()
class SMB2ChangeNotifyRequest(Structure):
"""
[MS-SMB2] 2.2.35 SMB2 CHANGE_NOTIFY Request
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-smb2/598f395a-e7a2-4cc8-afb3-ccb30dd2df7c
Sent by the client to request change notifications on a directory.
"""
COMMAND = Commands.SMB2_CHANGE_NOTIFY
def __init__(self):
self.fields = OrderedDict(
[
(
"structure_size",
IntField(
size=2,
default=32,
),
),
(
"flags",
FlagField(
size=2,
flag_type=ChangeNotifyFlags,
),
),
("output_buffer_length", IntField(size=4)),
("file_id", BytesField(size=16)),
(
"completion_filter",
FlagField(
size=4,
flag_type=CompletionFilter,
),
),
("reserved", IntField(size=4)),
]
)
super().__init__()
class SMB2ChangeNotifyResponse(Structure):
"""
[MS-SMB2] 2.2.36 SMB2 CHANGE_NOTIFY Response
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-smb2/14f9d050-27b2-49df-b009-54e08e8bf7b5
Sent by the server to transmit the results of a client's change notify request.
"""
COMMAND = Commands.SMB2_CHANGE_NOTIFY
def __init__(self):
self.fields = OrderedDict(
[
(
"structure_size",
IntField(
size=2,
default=9,
),
),
(
"output_buffer_offset",
IntField(
size=2,
default=72,
),
),
(
"output_buffer_length",
IntField(
size=4,
default=lambda s: len(s["buffer"]),
),
),
(
"buffer",
BytesField(
size=lambda s: s["output_buffer_length"].get_value(),
),
),
]
)
super().__init__()
class FileSystemWatcher:
def __init__(self, open):
"""
A class that encapsulates a FileSystemWatcher over SMB. It is designed to make it easy to run the watcher in
the background and provide an event that is fired when the server notifies that a change has occurred. It is
up to the caller to action on that event through their own sync or asynchronous implementation.
:param open: The Open() class of a directory to watch for change notifications.
"""
self.open = open
self.response_event = threading.Event()
self._t_on_response = threading.Thread(target=self._on_response)
self._t_on_response.daemon = True
self._t_exc = None
self._request = None
self._file_actions = None
self._result_lock = threading.Lock() # Used to ensure the result is only processed once
@property
def result(self):
"""
The result of the FileSystemWatcher request after it has been completed. Returns None if it still running
or has been cancelled, raises the underlying exception if one was returned by the server or a list of
FileNotifyInformation() structures that contain all the changed details. The list is empty if the watcher's
output buffer length was set to 0 which indicates a change has occured but no details were returned by the
server.
"""
if self.cancelled:
return None
if self._request is None or self._request.response is None:
return None
elif self._request.response["status"].get_value() == NtStatus.STATUS_PENDING:
return None
elif self._t_exc:
raise self._t_exc
with self._result_lock:
if self._file_actions is not None:
return self._file_actions
response = self._request.response["data"].get_value()
change_response = SMB2ChangeNotifyResponse()
change_response.unpack(response)
response_buffer = change_response["buffer"].get_value()
self._file_actions = []
current_offset = 0
is_next = True
while is_next:
notify_info = FileNotifyInformation()
notify_info.unpack(response_buffer[current_offset:])
self._file_actions.append(notify_info)
current_offset += notify_info["next_entry_offset"].get_value()
is_next = notify_info["next_entry_offset"].get_value() != 0
return self._file_actions
@property
def cancelled(self):
"""States whether the change notify request was cancelled or not."""
return self._request is not None and self._request.cancelled is True
def start(self, completion_filter, flags=0, output_buffer_length=65536, send=True):
"""
Starts a change notify request against the server with the options specified.
Note: cannot send as a compound request as the resulting async reply session cannot be determined. See the
following URL for more details.
https://social.msdn.microsoft.com/Forums/en-US/a580f7bc-6746-4876-83db-6ac209b202c4/mssmb2-change-notify-response-sessionid?forum=os_fileservices
:param completion_filter: Specify one or more filters to request a notification on.
:param flags: Specify custom flags, only ChangeNotifyFlags.SMB2_WATCH_TREE is defined which watches for change
events in the sub directories of the Open() dir specified.
:param output_buffer_length: The output buffer length to defined the max size of data the server can return.
Set to 0 to only receive a notification of changes without the details of the change.
:param send: Whether to send the request in the same call or return the message to the caller and the
unpack function. Note the compound request must not close the dir the watcher is started on.
"""
change_notify = SMB2ChangeNotifyRequest()
change_notify["flags"] = flags
change_notify["output_buffer_length"] = output_buffer_length
change_notify["file_id"] = self.open.file_id
change_notify["completion_filter"] = completion_filter
log.info(
"Session: %s, Tree Connect: %s , Open: %s - sending SMB2 Change Notify request",
self.open.tree_connect.session.username,
self.open.tree_connect.share_name,
self.open.file_name,
)
log.debug(change_notify)
if send:
request = self.open.connection.send(
change_notify, self.open.tree_connect.session.session_id, self.open.tree_connect.tree_connect_id
)
self._start_response(request)
return
else:
return change_notify, self._start_response
def _start_response(self, request):
self._request = request
self._t_on_response.start()
def cancel(self):
"""
Cancels the change notify request on the server.
"""
self._request.cancel()
def wait(self):
"""
Waits until a change response has been returned from the server.
:return: The file action result
"""
self._t_on_response.join()
return self.result
def _on_response(self):
try:
self.open.connection.receive(self._request)
except Cancelled:
self.is_cancelled = True
except NotifyEnumDir:
# output_buffer_length was 0 so we only need to notify the caller that a change occurred, set an empty
# action list.
self._file_actions = []
except Exception as exc:
self._t_exc = exc
finally:
log.debug("Firing response event for %s change notify", self.open.file_name)
self.response_event.set()

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,775 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
from collections import OrderedDict
from smbprotocol.header import NtStatus
from smbprotocol.structure import (
BoolField,
BytesField,
DateTimeField,
EnumField,
FlagField,
IntField,
Structure,
UuidField,
)
class CreateContextName:
"""
[MS-SMB2] v53.0 2017-09-15
2.2.13.2 SMB2_CREATE_CONTEXT Request Values
Valid names for the name to set on a SMB2_CREATE_CONTEXT Request entry
"""
SMB2_CREATE_EA_BUFFER = b"\x45\x78\x74\x41"
# note: the structures for this are located in security_descriptor.py
SMB2_CREATE_SD_BUFFER = b"\x53\x65\x63\x44"
SMB2_CREATE_DURABLE_HANDLE_REQUEST = b"\x44\x48\x6e\x51"
SMB2_CREATE_DURABLE_HANDLE_RECONNECT = b"\x44\x48\x6e\x43"
SMB2_CREATE_ALLOCATION_SIZE = b"\x41\x6c\x53\x69"
SMB2_CREATE_QUERY_MAXIMAL_ACCESS_REQUEST = b"\x4d\x78\x41\x63"
SMB2_CREATE_TIMEWARP_TOKEN = b"\x54\x57\x72\x70"
SMB2_CREATE_QUERY_ON_DISK_ID = b"\x51\x46\x69\x64"
SMB2_CREATE_REQUEST_LEASE = b"\x52\x71\x4c\x73"
SMB2_CREATE_REQUEST_LEASE_V2 = b"\x52\x71\x4c\x73"
SMB2_CREATE_DURABLE_HANDLE_REQUEST_V2 = b"\x44\x48\x32\x51"
SMB2_CREATE_DURABLE_HANDLE_RECONNECT_V2 = b"\x44\x48\x32\x43"
SMB2_CREATE_APP_INSTANCE_ID = b"\x45\xbc\xa6\x6a\xef\xa7\xf7\x4a" b"\x90\x08\xfa\x46\x2e\x14\x4d\x74"
SMB2_CREATE_APP_INSTANCE_VERSION = b"\xb9\x82\xd0\xb7\x3b\x56\x07\x4f" b"\xa0\x7b\x52\x4a\x81\x16\xa0\x10"
SVHDX_OPEN_DEVICE_CONTEXT = b"\x9c\xcb\xcf\x9e\x04\xc1\xe6\x43" b"\x98\x0e\x15\x8d\xa1\xf6\xec\x83"
@staticmethod
def get_response_structure(name, size=None):
"""
Returns the response structure for a know list of create context
responses.
:param name: The constant value above
:param size: Specify the size of the context buffer, used to differenciate between REQUEST_LEASE and
REQUEST_LEASE_V2.
:return: The response structure or None if unknown
"""
# Special handling for request lease here the header name has the same value, use the size to differenciate.
if name == CreateContextName.SMB2_CREATE_REQUEST_LEASE:
return {
32: SMB2CreateResponseLease(),
52: SMB2CreateResponseLeaseV2(),
}.get(size, None)
return {
CreateContextName.SMB2_CREATE_DURABLE_HANDLE_REQUEST: SMB2CreateDurableHandleResponse(),
CreateContextName.SMB2_CREATE_DURABLE_HANDLE_RECONNECT: SMB2CreateDurableHandleReconnect(),
CreateContextName.SMB2_CREATE_QUERY_MAXIMAL_ACCESS_REQUEST: SMB2CreateQueryMaximalAccessResponse(),
CreateContextName.SMB2_CREATE_QUERY_ON_DISK_ID: SMB2CreateQueryOnDiskIDResponse(),
CreateContextName.SMB2_CREATE_DURABLE_HANDLE_REQUEST_V2: SMB2CreateDurableHandleResponseV2(),
CreateContextName.SMB2_CREATE_DURABLE_HANDLE_RECONNECT_V2: SMB2CreateDurableHandleReconnectV2,
CreateContextName.SMB2_CREATE_APP_INSTANCE_ID: SMB2CreateAppInstanceId(),
CreateContextName.SMB2_CREATE_APP_INSTANCE_VERSION: SMB2CreateAppInstanceVersion(),
}.get(name, None)
class EAFlags:
"""
[MS-FSCC]
2.4.15 FileFullEaInformation Flags
Specifies the flag used when setting extended attributes.
"""
NONE = 0x0000000
FILE_NEED_EA = 0x00000080
class LeaseState:
"""
[MS-SMB2]
2.2.13.2.8 SMB2_CREATE_REQUEST_LEASE LeaseState
The requested lease state, field is constructed with a combination of the
following values.
"""
SMB2_LEASE_NONE = 0x00
SMB2_LEASE_READ_CACHING = 0x01
SMB2_LEASE_HANDLE_CACHING = 0x02
SMB2_LEASE_WRITE_CACHING = 0x04
class LeaseRequestFlags:
"""
[MS-SMB2]
2.2.13.2.10 SMB2_CREATE_REQUEST_LEASE_V2
The flags to use on an SMB2CreateRequestLeaseV2 packet.
"""
SMB2_LEASE_FLAG_PARENT_LEASE_KEY_SET = 0x00000004
class LeaseResponseFlags:
"""
[MS-SMB2]
2.2.14.2.10 SMB2_CREATE_RESPONSE_LEASE
"""
SMB2_LEASE_FLAG_BREAK_IN_PROGRESS = 0x00000002
SMB2_LEASE_FLAG_PARENT_LEASE_KEY_SET = 0x00000004 # V2 Response
class DurableHandleFlags:
"""
[MS-SMB2]
2.2.13.2.11 SMB2_CREATE_DURABLE_HANDLE_REQUEST_V2
Flags used on an SMB2CreateDurableHandleRequestV2 packet.
"""
SMB2_DHANDLE_FLAG_PERSISTENT = 0x00000002
class SVHDXOriginatorFlags:
"""
[MS-RSVD] 2.2.4.12 SVHDX_OPEN_DEVICE_CONTEXT OriginatorFlags
Used to indicate which component has originated or issued the operations.
"""
SVHDX_ORIGINATOR_PVHDPARSER = 0x00000001
SVHDX_ORIGINATOR_VHDMP = 0x00000004
class SMB2CreateContextRequest(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.13.2 SMB2_CREATE_CONTEXT Request Values
Structure used in the SMB2 CREATE Request and SMB2 CREATE Response to
encode additional flags and attributes
"""
def __init__(self):
self.fields = OrderedDict(
[
("next", IntField(size=4)),
("name_offset", IntField(size=2, default=16)),
("name_length", IntField(size=2, default=lambda s: len(s["buffer_name"]))),
("reserved", IntField(size=2)),
("data_offset", IntField(size=2, default=SMB2CreateContextRequest._buffer_data_offset)),
("data_length", IntField(size=4, default=lambda s: len(s["buffer_data"]))),
("buffer_name", BytesField(size=lambda s: s["name_length"].get_value())),
(
"padding",
BytesField(
size=SMB2CreateContextRequest._padding_size,
default=SMB2CreateContextRequest._default_padding_size,
),
),
("buffer_data", BytesField(size=lambda s: s["data_length"].get_value())),
# not actually a field but each list entry must start at the 8 byte
# alignment
(
"padding2",
BytesField(
size=SMB2CreateContextRequest._padding2_size,
default=SMB2CreateContextRequest._default_padding2_size,
),
),
]
)
super().__init__()
@staticmethod
def _buffer_data_offset(structure):
if structure["data_length"].get_value() == 0:
return 0
else:
return structure["name_offset"].get_value() + len(structure["buffer_name"]) + len(structure["padding"])
@staticmethod
def _padding_size(structure):
if structure["data_length"].get_value() == 0:
return 0
buffer_name_len = structure["name_length"].get_value()
mod = buffer_name_len % 8
return mod if mod == 0 else 8 - mod
@staticmethod
def _default_padding_size(structure):
return b"\x00" * SMB2CreateContextRequest._padding_size(structure)
@staticmethod
def _padding2_size(structure):
data_length = len(structure["buffer_name"]) + len(structure["padding"]) + len(structure["buffer_data"])
mod = data_length % 8
return mod if mod == 0 else 8 - mod
@staticmethod
def _default_padding2_size(structure):
return b"\x00" * SMB2CreateContextRequest._padding2_size(structure)
def get_context_data(self):
"""
Get the buffer_data value of a context response and try to convert it
to the relevant structure based on the buffer_name used. If it is an
unknown structure then the raw bytes are returned.
:return: relevant Structure of buffer_data or bytes if unknown name
"""
buffer_name = self["buffer_name"].get_value()
structure = CreateContextName.get_response_structure(buffer_name, size=self["data_length"].get_value())
if structure:
structure.unpack(self["buffer_data"].get_value())
return structure
else:
# unknown structure, just return the raw bytes
return self["buffer_data"].get_value()
@staticmethod
def pack_multiple(messages):
"""
Converts a list of SMB2CreateContextRequest structures and packs them
as a bytes object used when setting to the SMB2CreateRequest
buffer_contexts field. This should be used as it would calculate the
correct next field value for each context entry.
:param messages: List of SMB2CreateContextRequest structures
:return: bytes object that is set on the SMB2CreateRequest
buffer_contexts field.
"""
data = b""
msg_count = len(messages)
for i, msg in enumerate(messages):
if not isinstance(msg, SMB2CreateContextRequest):
buffer = msg
buffer_name = getattr(msg, "NAME", None)
if buffer_name is None:
raise ValueError(
"Invalid context message, must be either a SMB2CreateContextRequest or a "
"predefined structure object with NAME defined."
)
msg = SMB2CreateContextRequest()
msg["buffer_name"] = buffer_name
msg["buffer_data"] = buffer
if i == msg_count - 1:
msg["next"] = 0
else:
# because the end padding2 val won't be populated if the entry
# offset is 0, we set to 1 so the len calc is correct
msg["next"] = 1
msg["next"] = len(msg)
data += msg.pack()
return data
class SMB2CreateEABuffer(Structure):
"""
[MS-SMB2] 2.2.13.2.1 SMB2_CREATE_EA_BUFFER
[MS-FSCC] 2.4.15 FileFullEaInformation
Used to apply extended attributes as part of creating a new file.
"""
NAME = CreateContextName.SMB2_CREATE_EA_BUFFER
def __init__(self):
self.fields = OrderedDict(
[
# 0 if no more entries, otherwise offset after ea_value
("next_entry_offset", IntField(size=4)),
("flags", FlagField(size=1, flag_type=EAFlags)),
("ea_name_length", IntField(size=1, default=lambda s: len(s["ea_name"]) - 1)), # minus \x00
("ea_value_length", IntField(size=2, default=lambda s: len(s["ea_value"]))),
# ea_name is ASCII byte encoded and needs a null terminator '\x00'
("ea_name", BytesField(size=lambda s: s["ea_name_length"].get_value() + 1)),
("ea_value", BytesField(size=lambda s: s["ea_value_length"].get_value())),
# not actually a field but each list entry must start at the 4 byte
# alignment
(
"padding",
BytesField(size=SMB2CreateEABuffer._padding_size, default=SMB2CreateEABuffer._default_padding_size),
),
]
)
super().__init__()
@staticmethod
def _padding_size(structure):
if structure["next_entry_offset"].get_value() == 0:
return 0
data_length = len(structure["ea_name"]) + len(structure["ea_value"])
mod = data_length % 4
return mod if mod == 0 else 4 - mod
@staticmethod
def _default_padding_size(structure):
return b"\x00" * SMB2CreateEABuffer._padding_size(structure)
@staticmethod
def pack_multiple(messages):
"""
Converts a list of SMB2CreateEABuffer structures and packs them as a
bytes object used when setting to the SMB2CreateContextRequest
buffer_data field. This should be used as it would calculate the
correct next_entry_offset field value for each buffer entry.
:param messages: List of SMB2CreateEABuffer structures
:return: bytes object that is set on the SMB2CreateContextRequest
buffer_data field.
"""
data = b""
msg_count = len(messages)
for i, msg in enumerate(messages):
if i == msg_count - 1:
msg["next_entry_offset"] = 0
else:
# because the end padding val won't be populated if the entry
# offset is 0, we set to 1 so the len calc is correct
msg["next_entry_offset"] = 1
msg["next_entry_offset"] = len(msg)
data += msg.pack()
return data
class SMB2CreateDurableHandleRequest(Structure):
"""
[MS-SMB2] 2.2.13.2.3 SMB2_CREATE_DURABLE_HANDLE_REQUEST
Used by the client to mark the open as a durable open.
"""
NAME = CreateContextName.SMB2_CREATE_DURABLE_HANDLE_REQUEST
def __init__(self):
self.fields = OrderedDict([("durable_request", BytesField(size=16, default=b"\x00" * 16))])
super().__init__()
class SMB2CreateDurableHandleResponse(Structure):
"""
[MS-SMB2] 2.2.14.2.3 SMB2_CREATE_DURABLE_HANDLE_RESPONSE
Sent by the server in response to an SMB2CreateDurableHandleRequest packet.
"""
def __init__(self):
self.fields = OrderedDict([("reserved", IntField(size=8))])
super().__init__()
class SMB2CreateDurableHandleReconnect(Structure):
"""
[MS-SMB2] 2.2.13.2.4 SMB2_CREATE_DURABLE_HANDLE_RECONNECT
Used by the client when attempting to reestablish a durable open
"""
NAME = CreateContextName.SMB2_CREATE_DURABLE_HANDLE_RECONNECT
def __init__(self):
self.fields = OrderedDict([("data", BytesField(size=16))])
super().__init__()
class SMB2CreateQueryMaximalAccessRequest(Structure):
"""
[MS-SMB2] 2.2.13.2.5 SMB2_CREATE_QUERY_MAXIMAL_ACCESS_REQUEST
Used by the client to retrieve maximal access information as part of
processing the open.
"""
NAME = CreateContextName.SMB2_CREATE_QUERY_MAXIMAL_ACCESS_REQUEST
def __init__(self):
self.fields = OrderedDict([("timestamp", DateTimeField())])
super().__init__()
class SMB2CreateQueryMaximalAccessResponse(Structure):
"""
[MS-SMB2] 2.2.14.2.5 SMB2_CREATE_QUERY_MAXIMAL_ACCESS_RESPONSE
Used by the server in response to an SMB2CreateQueryMaximalAccessRequest
packet.
"""
def __init__(self):
self.fields = OrderedDict(
[
("query_status", EnumField(size=4, enum_type=NtStatus, enum_strict=False)),
# either FilePipePrinterAccessMask or DirectoryAccessMask
("maximal_access", IntField(size=4)),
]
)
super().__init__()
class SMB2CreateAllocationSize(Structure):
"""
[MS-SMB2] 2.2.13.2.6 SMB2_CREATE_ALLOCATION_SIZE
Used by the client to set the allocation size of a file that is being
newly created or overwritten.
"""
NAME = CreateContextName.SMB2_CREATE_ALLOCATION_SIZE
def __init__(self):
self.fields = OrderedDict([("allocation_size", IntField(size=8))])
super().__init__()
class SMB2CreateTimewarpToken(Structure):
"""
[MS-SMB2] 2.2.13.2.7 SMB2_CREATE_TIMEWARP_TOKEN
Used by the client when requesting the server to open a version of the file
at a previous point in time.
"""
NAME = CreateContextName.SMB2_CREATE_TIMEWARP_TOKEN
def __init__(self):
self.fields = OrderedDict([("timestamp", DateTimeField())])
super().__init__()
class SMB2CreateRequestLease(Structure):
"""
[MS-SMB2] 2.2.13.2.8 SMB2_CREATE_REQUEST_LEASE
Used by the cliet when requesting the server to return a lease.
"""
NAME = CreateContextName.SMB2_CREATE_REQUEST_LEASE
def __init__(self):
self.fields = OrderedDict(
[
("lease_key", BytesField(size=16)),
("lease_state", FlagField(size=4, flag_type=LeaseState)),
("lease_flags", IntField(size=4)),
("lease_duration", IntField(size=8)),
]
)
super().__init__()
class SMB2CreateResponseLease(Structure):
"""
[MS-SMB2] 2.2.14.2.10 SMB2_CREATE_RESPONSE_LEASE
Sent by the server in response to an SMB2CreateRequestLease
"""
def __init__(self):
self.fields = OrderedDict(
[
("lease_key", BytesField(size=16)),
("lease_state", FlagField(size=4, flag_type=LeaseState)),
("lease_flags", FlagField(size=4, flag_type=LeaseResponseFlags)),
("lease_duration", IntField(size=8)),
]
)
super().__init__()
class SMB2CreateQueryOnDiskIDResponse(Structure):
"""
[MS-SMB2] 2.2.14.2.9 SMB2_CREATE_QUERY_ON_DISK_ID
Sent by the server in response to an SMB2CreateQueryOnDiskIDRequest packet.
"""
NAME = CreateContextName.SMB2_CREATE_QUERY_ON_DISK_ID
def __init__(self):
self.fields = OrderedDict(
[
("disk_file_id", IntField(size=8)),
("volume_id", IntField(size=8)),
("reserved", BytesField(size=16, default=b"\x00" * 16)),
]
)
super().__init__()
class SMB2CreateRequestLeaseV2(Structure):
"""
[MS-SMB2] 2.2.13.2.10 SMB2_CREATE_REQUEST_LEASE_V2
Used when the client is requesting the server to return a lease on a file
or directory.
Valid for the SMB 3.x family only
"""
NAME = CreateContextName.SMB2_CREATE_REQUEST_LEASE_V2
def __init__(self):
self.fields = OrderedDict(
[
("lease_key", BytesField(size=16)),
("lease_state", FlagField(size=4, flag_type=LeaseState)),
("lease_flags", FlagField(size=4, flag_type=LeaseRequestFlags)),
("lease_duration", IntField(size=8)),
("parent_lease_key", BytesField(size=16)),
("epoch", BytesField(size=2)),
("reserved", IntField(size=2)),
]
)
super().__init__()
class SMB2CreateResponseLeaseV2(Structure):
"""
[MS-SMB2] 2.2.14.2.11 SMB2_CREATE_RESPONSE_LEASE_V2
Sent by the server in response to an SMB2CreateRequestLeaseV2 packet.
"""
def __init__(self):
self.fields = OrderedDict(
[
("lease_key", BytesField(size=16)),
("lease_state", FlagField(size=4, flag_type=LeaseState)),
("flags", FlagField(size=4, flag_type=LeaseResponseFlags)),
("lease_duration", IntField(size=8)),
("parent_lease_key", BytesField(size=16)),
("epoch", IntField(size=2)),
("reserved", IntField(size=2)),
]
)
super().__init__()
class SMB2CreateDurableHandleRequestV2(Structure):
"""
[MS-SMB2] 2.2.13.2.11 SMB2_CREATE_DURABLE_HANDLE_REQUEST_V2
Used by the client to request the server mark the open as durable or
persistent.
Valid for the SMB 3.x family only
"""
NAME = CreateContextName.SMB2_CREATE_DURABLE_HANDLE_REQUEST_V2
def __init__(self):
self.fields = OrderedDict(
[
# timeout in milliseconds
("timeout", IntField(size=4)),
("flags", FlagField(size=4, flag_type=DurableHandleFlags)),
("reserved", IntField(size=8)),
("create_guid", UuidField(size=16)),
]
)
super().__init__()
class SMB2CreateDurableHandleReconnectV2(Structure):
"""
[MS-SMB2] 2.2.13.2.12 SMB2_CREATE_DURABLE_HANDLE_RECONNECT_V2
Used by the client when reestablishing a durable open.
Valid for the SMB 3.x family only
"""
NAME = CreateContextName.SMB2_CREATE_DURABLE_HANDLE_RECONNECT_V2
def __init__(self):
self.fields = OrderedDict(
[
("file_id", BytesField(size=16)),
("create_guid", UuidField(size=16)),
("flags", FlagField(size=4, flag_type=DurableHandleFlags)),
]
)
super().__init__()
class SMB2CreateDurableHandleResponseV2(Structure):
"""
[MS-SMB2] 2.2.14.2.12 SMB2_CREATE_DURABLE_HANDLE_RESPONSE_V2
Sent by the server in response to an SMB2CreateDurableHandleRequestV2
packet.
"""
def __init__(self):
self.fields = OrderedDict(
[("timeout", IntField(size=4)), ("flags", FlagField(size=4, flag_type=DurableHandleFlags))]
)
super().__init__()
class SMB2CreateAppInstanceId(Structure):
"""
[MS-SMB2] 2.2.13.2.13 SMB2_CREATE_APP_INSTANCE_ID
Used by the client when supplying an identifier provided by an application.
Valid for the SMB 3.x family and should also have an durable handle on the
create request.
"""
NAME = CreateContextName.SMB2_CREATE_APP_INSTANCE_ID
def __init__(self):
self.fields = OrderedDict(
[
("structure_size", IntField(size=2, default=20)),
("reserved", IntField(size=2)),
("app_instance_id", BytesField(size=16)),
]
)
super().__init__()
class SMB2SVHDXOpenDeviceContextRequest(Structure):
"""
[MS-SMB2] 2.2.13.2.14 SVHDX_OPEN_DEVICE_CONTEXT
[MS-RSVD] 2.2.4.12 SVHDX_OPEN_DEVICE_CONTEXT
Used to open the shared virtual disk file.
"""
NAME = CreateContextName.SVHDX_OPEN_DEVICE_CONTEXT
def __init__(self):
self.fields = OrderedDict(
[
("version", IntField(size=4, default=1)),
("has_initiator_id", BoolField(size=1, default=lambda s: len(s["initiator_host_name"]) > 0)),
("reserved", BytesField(size=3, default=b"\x00\x00\x00")),
("initiator_id", UuidField(size=16)),
("originator_flags", EnumField(size=4, enum_type=SVHDXOriginatorFlags)),
("open_request_id", IntField(size=8)),
("initiator_host_name_length", IntField(size=2, default=lambda s: len(s["initiator_host_name"]))),
# utf-16-le encoded string
("initiator_host_name", BytesField(size=lambda s: s["initiator_host_name_length"].get_value())),
]
)
super().__init__()
class SMB2SVHDXOpenDeviceContextResponse(Structure):
"""
[MS-SMB2] 2.2.14.2.14 SVHDX_OPEN_DEVICE_CONTEXT_RESPONSE
[MS-RSVD] 2.2.4.31 SVHDX_OPEN_DEVICE_CONTEXT_RESPONSE
The response packet sent by the server in response to an
SMB2VHDXOpenDeviceContextRequest
"""
def __init__(self):
self.fields = OrderedDict(
[
("version", IntField(size=4, default=1)),
("has_initiator_id", BoolField(size=1, default=lambda s: len(s["initiator_host_name"]) > 0)),
("reserved", BytesField(size=3, default=b"\x00\x00\x00")),
("initiator_id", UuidField(size=16)),
("flags", IntField(size=4)),
("originator_flags", EnumField(size=4, enum_type=SVHDXOriginatorFlags)),
("open_request_id", IntField(size=8)),
("initiator_host_name_length", IntField(size=2, default=lambda s: len(s["initiator_host_name"]))),
# utf-16-le encoded string
("initiator_host_name", BytesField(size=lambda s: s["initiator_host_name_length"].get_value())),
]
)
super().__init__()
class SMB2SVHDXOpenDeviceContextV2Request(Structure):
"""
[MS-SMB2] 2.2.13.2.14 SVHDX_OPEN_DEVICE_CONTEXT
[MS-RSVD] 2.2.4.32 SVHDX_OPEN_DEVICE_CONTEXT_V2
Used to open the shared virtual disk file on the RSVD Protocol version 2
"""
NAME = CreateContextName.SVHDX_OPEN_DEVICE_CONTEXT
def __init__(self):
self.fields = OrderedDict(
[
("version", IntField(size=4, default=2)),
("has_initiator_id", BoolField(size=1, default=lambda s: len(s["initiator_host_name"]) > 0)),
("reserved", BytesField(size=3, default=b"\x00\x00\x00")),
("initiator_id", UuidField(size=16)),
("originator_flags", EnumField(size=4, enum_type=SVHDXOriginatorFlags)),
("open_request_id", IntField(size=8)),
("initiator_host_name_length", IntField(size=2, default=lambda s: len(s["initiator_host_name"]))),
# utf-16-le encoded string
("initiator_host_name", BytesField(size=lambda s: s["initiator_host_name_length"].get_value())),
("virtual_disk_properties_initialized", IntField(size=4)),
("server_service_version", IntField(size=4)),
("virtual_sector_size", IntField(size=4)),
("physical_sector_size", IntField(size=4)),
("virtual_size", IntField(size=8)),
]
)
super().__init__()
class SMB2SVHDXOpenDeviceContextV2Response(Structure):
"""
[MS-SMB2] 2.2.14.2.14 SVHDX_OPEN_DEVICE_CONTEXT_RESPONSE
[MS-RSVD] 2.2.4.32 SVHDX_OPEN_DEVICE_CONTEXT_V2_RESPONSE
The response packet sent by the server in response to an
SMB2VHDXOpenDeviceContextV2Request
"""
def __init__(self):
self.fields = OrderedDict(
[
("version", IntField(size=4, default=2)),
("has_initiator_id", BoolField(size=1, default=lambda s: len(s["initiator_host_name"]) > 0)),
("reserved", BytesField(size=3, default=b"\x00\x00\x00")),
("initiator_id", UuidField(size=16)),
("flags", IntField(size=4)),
("originator_flags", EnumField(size=4, enum_type=SVHDXOriginatorFlags)),
("open_request_id", IntField(size=8)),
("initiator_host_name_length", IntField(size=2, default=lambda s: len(s["initiator_host_name"]))),
# utf-16-le encoded string
("initiator_host_name", BytesField(size=lambda s: s["initiator_host_name_length"].get_value())),
("virtual_disk_properties_initialized", IntField(size=4)),
("server_service_version", IntField(size=4)),
("virtual_sector_size", IntField(size=4)),
("physical_sector_size", IntField(size=4)),
("virtual_size", IntField(size=8)),
]
)
super().__init__()
class SMB2CreateAppInstanceVersion(Structure):
"""
[MS-SMB2] 2.2.13.2.15 SMB2_CREATE_APP_INSTANCE_VERSION
Used when the client is supplying a version for the app instance identifier
provided by an application.
Valid for the SMB 3.1.1+ family
"""
NAME = CreateContextName.SMB2_CREATE_APP_INSTANCE_VERSION
def __init__(self):
self.fields = OrderedDict(
[
("structure_size", IntField(size=2, default=24)),
("reserved", IntField(size=2)),
("padding", IntField(size=4)),
("app_instance_version_high", IntField(size=8)),
("app_instance_version_low", IntField(size=8)),
]
)
super().__init__()

View File

@@ -0,0 +1,456 @@
# Copyright: (c) 2020, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
from __future__ import annotations
import time
from collections import OrderedDict, namedtuple
from typing import Iterator
from smbprotocol.structure import (
BytesField,
EnumField,
FlagField,
IntField,
ListField,
Structure,
TextField,
)
DFSTarget = namedtuple("DFSTarget", ["target_path", "set_boundary"])
"""A TargetEntry element in the TargetList ReferralCache.
Contains the DFS target details for a referral request. This object is defined in [MS-DFSC] under
`ReferralCache TargetList`_.
Attributes:
target_path (str): The NetworkPath value in the referral entry.
set_boundary (bool): Whether the TARGET_SET_BOUNDARY flag was set in the referral entry.
.. _ReferralCache TargetList:
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-dfsc/0f9ef683-b497-47d0-8c2c-e56e34fde2e3
"""
class DomainEntry:
"""A DomainCache entry.
A processed domain and DC referral request.
Args:
referral: The DFSReferralResponse entry for a domain referral request to cache.
Attributes:
domain_list (List[str]): A list of known domain controller hostnames for the domain.
"""
def __init__(self, referral: DFSReferralEntryV3):
self.domain_list = []
self._referral = referral
self._start_time: float = time.time()
self._domain_hint_idx: int | None = None
@property
def domain_name(self) -> str:
"""The domain DFS path."""
return self._referral.dfs_path
@property
def dc_hint(self) -> str:
"""The last known good domain hostname in domain_list."""
return self.domain_list[self._domain_hint_idx]
@dc_hint.setter
def dc_hint(self, value: str) -> None:
for idx, target in enumerate(self.domain_list):
if target == value:
self._domain_hint_idx = idx
break
else:
raise ValueError("The specific domain hint does not exist in this domain cache entry")
@property
def is_expired(self) -> bool:
"""Whether the hint has expired or not."""
return ((time.time() - self._start_time) - self._referral["time_to_live"].get_value()) >= 0
@property
def is_valid(self) -> bool:
"""Whether the domain entry has had a DC referral response or not."""
return self._domain_hint_idx is not None and not self.is_expired
def process_dc_referral(self, referral: DFSReferralResponse) -> None:
if self._domain_hint_idx is None:
self._domain_hint_idx = 0
for dc_entry in referral["referral_entries"].get_value():
for dc_hostname in dc_entry.network_address:
if dc_hostname not in self.domain_list:
self.domain_list.append(dc_hostname)
class ReferralEntry:
"""A ReferralCache entry.
A parsed referral response that is cached by the client for future connection requests.
Args:
referral: The DFSReferralResponse to cache.
"""
def __init__(self, referral: DFSReferralResponse):
referrals = referral["referral_entries"].get_value()
self._referral_header_flags = referral["referral_header_flags"]
self._referrals: list[DFSReferralEntryV1 | DFSReferralEntryV2 | DFSReferralEntryV3] = referrals
self._start_time: float = time.time()
self._target_hint_idx: int = 0
@property
def dfs_path(self) -> str:
return self._referrals[self._target_hint_idx].dfs_path
@property
def is_root(self) -> bool:
return self._referrals[self._target_hint_idx]["server_type"].has_flag(DFSServerTypes.ROOT_TARGETS)
@property
def is_link(self) -> bool:
return not self.is_root
# @property
# def is_interlink(self) -> bool:
# return False
@property
def is_expired(self) -> bool:
referral = self._referrals[self._target_hint_idx]
return ((time.time() - self._start_time) - referral["time_to_live"].get_value()) >= 0
@property
def target_failback(self) -> bool:
return self._referral_header_flags.has_flag(DFSReferralHeaderFlags.TARGET_FAIL_BACK)
@property
def target_hint(self) -> DFSTarget:
return self.target_list[self._target_hint_idx]
@target_hint.setter
def target_hint(self, value: DFSTarget) -> None:
for idx, target in enumerate(self.target_list):
if target == value:
self._target_hint_idx = idx
break
else:
raise ValueError("The specific target hint does not exist in this referral entry")
@property
def target_list(self) -> list[DFSTarget]:
return [
DFSTarget(
target_path=e.network_address,
set_boundary=e["referral_entry_flags"].has_flag(DFSReferralEntryFlags.TARGET_SET_BOUNDARY),
)
for e in self._referrals
]
def __iter__(self) -> Iterator[DFSTarget]:
"""Iterates through the target_list with a priority being the hinted value."""
yield self.target_list[self._target_hint_idx]
for idx, target in enumerate(self.target_list):
if idx == self._target_hint_idx:
continue
yield target
class DFSReferralRequestFlags:
"""
[MS-DFSC] 2.2.3 REQ_GET_DFS_REFERRAL_EX
RequestFlags
"""
SITE_NAME = 0x00000001
class DFSReferralHeaderFlags:
"""
[MS-DFSC] 2.2.4 RESP_GET_DFS_REFERRAL
ReferralHeaderFlags
"""
REFERRAL_SERVERS = 0x00000001
STORAGE_SERVERS = 0x00000002
TARGET_FAIL_BACK = 0x00000004
class DFSServerTypes:
"""
[MS-DFSC] 2.2.5.1 DFS_REFERRAL_V1
ServerType
"""
NON_ROOT_TARGETS = 0x0000
ROOT_TARGETS = 0x0001
class DFSReferralEntryFlags:
"""
[MS-DFSC] 2.2.5.3 DFS_REFERRAL_V3 & 2.2.5.4 DFS_REFERRAL_V4
ReferralEntryFlags
"""
NAME_LIST_REFERRAL = 0x0002
TARGET_SET_BOUNDARY = 0x0004
class DFSReferralRequest(Structure):
"""
[MS-DFSC] 2.2.2 REQ_GET_DFS_REFERRAL
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-dfsc/663c9b38-41b8-4faa-b6f6-a4576b4cea62
"""
def __init__(self):
self.fields = OrderedDict(
[
("max_referral_level", IntField(size=2, default=4)),
("request_file_name", TextField(null_terminated=True)),
]
)
super().__init__()
class DFSReferralRequestEx(Structure):
"""
[MS-DFSC] 2.2.3 REQ_GET_DFS_REFERRAL_EX
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-dfsc/575ad372-46a7-4ed6-80e5-f87768fad9a0
"""
def __init__(self):
self.fields = OrderedDict(
[
("max_referral_level", IntField(size=2, default=4)),
("request_flags", FlagField(size=2, flag_type=DFSReferralRequestFlags)),
(
"request_data_length",
IntField(
size=4,
default=lambda s: 4
+ s["request_file_name_length"].get_value()
+ s["site_name_length"].get_value(),
),
),
(
"request_file_name_length",
IntField(
size=2,
default=lambda s: len(s["request_file_name"]),
),
),
(
"request_file_name",
TextField(
null_terminated=True,
size=lambda s: s["request_file_name_length"].get_value(),
),
),
(
"site_name_length",
IntField(
size=2,
default=lambda s: len(s["site_name"]),
),
),
(
"site_name",
TextField(
null_terminated=True,
size=lambda s: s["site_name_length"].get_value(),
),
),
]
)
super().__init__()
class DFSReferralResponse(Structure):
"""
[MS-DFSC] 2.2.4 RESP_GET_DFS_REFERRAL
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-dfsc/bd1a7a9d-dfee-4dc6-ba37-bfeb329a7bfa
"""
def __init__(self):
self.fields = OrderedDict(
[
("path_consumed", IntField(size=2)),
("number_of_referrals", IntField(size=2)),
("referral_header_flags", FlagField(size=4, flag_type=DFSReferralHeaderFlags)),
(
"referral_entries",
ListField(
list_count=lambda s: s["number_of_referrals"].get_value(),
unpack_func=lambda s, b: self._create_dfs_referral_entry(b),
),
),
("string_buffer", BytesField()),
]
)
super().__init__()
def _create_dfs_referral_entry(self, data):
results = []
for _ in range(self.fields["number_of_referrals"].get_value()):
b_version = data[:1]
if b_version == b"\x01":
referral_entry = DFSReferralEntryV1()
elif b_version == b"\x02":
referral_entry = DFSReferralEntryV2()
else:
referral_entry = DFSReferralEntryV3()
data = referral_entry.unpack(data)
results.append(referral_entry)
# Now process the string_buffer values. Do it in reverse order as the offset value needs to be calculated based
# on the entry size(s) that come after that entry.
entry_offset = 0
for referral_entry in reversed(results):
entry_offset += referral_entry["size"].get_value()
referral_entry.process_string_buffer(data, entry_offset)
return results
class DFSReferralEntryV1(Structure):
"""
[MS-DFSC] 2.2.5.1 DFS_REFERRAL_V1
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-dfsc/2f7570f9-cafe-442b-ae9e-3ff119cae7d8
"""
def __init__(self):
self.fields = OrderedDict(
[
("version_number", IntField(size=2, default=1)),
("size", IntField(size=2)),
("server_type", EnumField(size=2, enum_type=DFSServerTypes)),
("referral_entry_flags", FlagField(size=2, flag_type=DFSReferralEntryFlags)),
("share_name", TextField(null_terminated=True)),
]
)
super().__init__()
@property
def network_address(self):
return self["share_name"].get_value()
def process_string_buffer(self, buffer, entry_offset):
# The V1 entry does not use a string buffer so this is a no-op.
pass
class DFSReferralEntryV2(Structure):
"""
[MS-DFSC] 2.2.5.2 DFS_REFERRAL_V2
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-dfsc/3b6ed482-0ca4-4af1-9fd0-254d137c7af4
"""
def __init__(self):
self.fields = OrderedDict(
[
("version_number", IntField(size=2, default=2)),
("size", IntField(size=2)),
("server_type", FlagField(size=2, flag_type=DFSServerTypes)),
("referral_entry_flags", FlagField(size=2, flag_type=DFSReferralEntryFlags)),
("proximity", IntField(size=4)),
("time_to_live", IntField(size=4)),
("dfs_path_offset", IntField(size=2)),
("dfs_alternate_path_offset", IntField(size=2)),
("network_address_offset", IntField(size=2)),
]
)
self.dfs_path = None
self.dfs_alternate_path = None
self.network_address = None
super().__init__()
def process_string_buffer(self, buffer, entry_offset):
buffer_fields = ["dfs_path", "dfs_alternate_path", "network_address"]
for field_name in buffer_fields:
field_offset = self[f"{field_name}_offset"].get_value()
if field_offset == 0:
continue
field = TextField(null_terminated=True, encoding="utf-16-le")
field.unpack(buffer[field_offset - entry_offset :])
setattr(self, field_name, field.get_value())
class DFSReferralEntryV3(Structure):
"""
[MS-DFSC] 2.2.5.3 DFS_REFERRAL_V3
This is also the same as V4 just with the addition of more referral_entry_flags and version_number being 4.
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-dfsc/50a739cf-8211-4b17-9990-63696d37028d
"""
def __init__(self):
self.fields = OrderedDict(
[
("version_number", IntField(size=2, default=3)),
("size", IntField(size=2)),
("server_type", FlagField(size=2, flag_type=DFSServerTypes, flag_strict=False)),
("referral_entry_flags", FlagField(size=2, flag_type=DFSReferralEntryFlags, flag_strict=False)),
("time_to_live", IntField(size=4)),
# The follow fields depend on the ReferralEntryFlags, the actual field names are when the entry is not a
# NameListReferral.
("dfs_path_offset", IntField(size=2)), # SpecialNameOffset
("dfs_alternate_path_offset", IntField(size=2)), # NumberOfExpandedNames
("network_address_offset", IntField(size=2)), # ExpandedNameOffset
("service_site_guid", BytesField(size=lambda s: s["size"].get_value() - 18)), # Padding
]
)
self.dfs_path = None
self.dfs_alternate_path = None
self.network_address = None
super().__init__()
def process_string_buffer(self, buffer, entry_offset):
is_name_list = self["referral_entry_flags"].has_flag(DFSReferralEntryFlags.NAME_LIST_REFERRAL)
buffer_fields = ["dfs_path", "network_address"]
if not is_name_list:
buffer_fields.insert(1, "dfs_alternate_path")
for field_name in buffer_fields:
field_offset = self[f"{field_name}_offset"].get_value()
if field_offset == 0:
continue
string_offset = field_offset - entry_offset
if is_name_list and field_name == "network_address":
value = []
for _ in range(self["dfs_alternate_path_offset"].get_value()):
field = TextField(null_terminated=True, encoding="utf-16-le")
field.unpack(buffer[string_offset:])
value.append(field.get_value())
string_offset += len(field)
else:
field = TextField(null_terminated=True, encoding="utf-16-le")
field.unpack(buffer[string_offset:])
value = field.get_value()
setattr(self, field_name, value)

View File

@@ -0,0 +1,989 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
from __future__ import annotations
import binascii
import errno
import ntpath
import os
import socket
from collections import OrderedDict
from typing import Any
from smbprotocol import Dialects
from smbprotocol._text import to_bytes, to_text
from smbprotocol.header import NtStatus, SMB2HeaderResponse
from smbprotocol.reparse_point import SymbolicLinkReparseDataBuffer
from smbprotocol.structure import (
BytesField,
EnumField,
IntField,
ListField,
Structure,
StructureField,
)
class SMBException(Exception):
# Generic SMB Exception with a message
pass
class SMBAuthenticationError(SMBException):
# Used for authentication specific errors
pass
class SMBConnectionClosed(SMBException):
# Used to denote the underlying TCP transport has been closed.
pass
class SMBOSError(OSError, SMBException):
"""Wrapper for OSError with smbprotocol specific details.
This is a wrapper for OSError for use in smbclient. It is designed to translate the raw SMBResponseException that
smbprotocol raises into an error that is compatible with OSError.
"""
def __init__(self, ntstatus, filename, filename2=None):
self.ntstatus = ntstatus
self.filename2 = os.fspath(filename2) if filename2 else None
ntstatus_name = "STATUS_UNKNOWN"
for name, val in vars(NtStatus).items():
if ntstatus == val:
ntstatus_name = name
break
error_details = {
NtStatus.STATUS_OBJECT_NAME_NOT_FOUND: errno.ENOENT,
NtStatus.STATUS_OBJECT_PATH_NOT_FOUND: errno.ENOENT,
NtStatus.STATUS_NOT_FOUND: errno.ENOENT,
NtStatus.STATUS_OBJECT_NAME_COLLISION: errno.EEXIST,
NtStatus.STATUS_PRIVILEGE_NOT_HELD: (errno.EACCES, "Required privilege not held"),
NtStatus.STATUS_SHARING_VIOLATION: (
errno.EPERM,
"The process cannot access the file because it is being used by another process",
),
NtStatus.STATUS_NOT_A_REPARSE_POINT: (errno.EINVAL, "The file or directory is not a reparse point"),
NtStatus.STATUS_FILE_IS_A_DIRECTORY: errno.EISDIR,
NtStatus.STATUS_NOT_A_DIRECTORY: errno.ENOTDIR,
NtStatus.STATUS_DIRECTORY_NOT_EMPTY: errno.ENOTEMPTY,
NtStatus.STATUS_END_OF_FILE: getattr(errno, "ENODATA", 120), # Not present on py2 for Windows.
}.get(ntstatus, (0, f"Unknown NtStatus error returned '{ntstatus_name}'"))
if not isinstance(error_details, tuple):
error_details = (error_details, os.strerror(error_details))
super().__init__(error_details[0], error_details[1], os.fspath(filename))
def __str__(self):
status = format(self.ntstatus, "x").zfill(8)
msg = f"[Error {self.errno}] [NtStatus 0x{status}] {self.strerror}: '{self.filename}'"
if self.filename2:
msg += f" -> '{self.filename2}'"
return msg
class SMBLinkRedirectionError(SMBException):
@property
def message(self):
msg = (
f"Encountered symlink at '{self.path}' that points to "
f"'{self.target}' which cannot be redirected: {self.args[0]}"
)
return msg
@property
def path(self):
return self.args[1]
@property
def target(self):
return self.args[2]
def __str__(self):
return self.message
class SMBUnsupportedFeature(SMBException):
@property
def negotiated_dialect(self):
return self.args[0]
@property
def required_dialect(self):
return self.args[1]
@property
def feature_name(self):
return self.args[2]
@property
def requires_newer(self):
if len(self.args) > 3:
return self.args[3]
else:
return None
@property
def message(self):
if self.requires_newer is None:
msg_suffix = ""
elif self.requires_newer:
msg_suffix = " or newer"
else:
msg_suffix = " or older"
required_dialect = self._get_dialect_name(self.required_dialect)
negotiated_dialect = self._get_dialect_name(self.negotiated_dialect)
msg = (
f"{self.feature_name} is not available on the negotiated dialect {negotiated_dialect}, "
f"requires dialect {required_dialect}{msg_suffix}"
)
return msg
def __str__(self):
return self.message
def _get_dialect_name(self, dialect):
dialect_field = EnumField(enum_type=Dialects, enum_strict=False, size=2)
dialect_field.set_value(dialect)
return str(dialect_field)
class _SMBErrorRegistry(type):
__registry = {}
def __init__(cls, name, bases, attributes):
super().__init__(name, bases, attributes)
# Special case for the base SMBResponseException doesn't need to have _STATUS_CODE
if cls.__module__ == _SMBErrorRegistry.__module__ and cls.__name__ == "SMBResponseException":
return
if not hasattr(cls, "_STATUS_CODE"):
raise ValueError(f"{cls.__module__}.{cls.__name__} does not have the _STATUS_CODE class attribute set")
cls.__registry[cls._STATUS_CODE] = cls
def __call__(cls, header=None):
# intercept construction of new SMBResponseException (and derived) instances
if header:
new_cls = cls.__registry.get(header["status"].get_value(), cls)
else:
header = SMB2HeaderResponse()
header["status"] = cls._STATUS_CODE
header["data"] = SMB2ErrorResponse()
new_cls = cls
# now use type.__call__ directly to actually construct instance
return type.__call__(new_cls, header)
class SMBResponseException(SMBException, metaclass=_SMBErrorRegistry):
"""Base SMB response status exception.
This is the base exception that is used when processing the status of an SMB response received from the server.
When being called it may create one of the inherited types depending on whether the status is known or not. Each
inherited class must implement _STATUS_CODE representing the NtStatus error it is for and may implement
_BASE_MESSAGE to provide a better explanation of the error.
"""
_BASE_MESSAGE = "Unknown error."
def __init__(self, header: SMB2HeaderResponse):
self.header = header
@property
def error_details(self) -> list[Any]:
# list of error_details returned by the server, currently used in
# the SMB 3.1.1 error response for certain situations
error = SMB2ErrorResponse()
error.unpack(self.header["data"].get_value())
error_details = []
for raw_error_data in error["error_data"].get_value():
error_id = raw_error_data["error_id"].get_value()
raw_data = raw_error_data["error_context_data"].get_value()
if self.status == NtStatus.STATUS_STOPPED_ON_SYMLINK:
error_data = SMB2SymbolicLinkErrorResponse()
error_data.unpack(raw_data)
elif (
self.status == NtStatus.STATUS_BAD_NETWORK_NAME
and error_id == ErrorContextId.SMB2_ERROR_ID_SHARE_REDIRECT
):
error_data = SMB2ShareRedirectErrorContext()
error_data.unpack(raw_data)
else:
# unknown context data so we just set it the raw bytes
error_data = raw_data
error_details.append(error_data)
return error_details
@property
def message(self) -> str:
error_details = []
for detail in self.error_details:
if isinstance(detail, SMB2SymbolicLinkErrorResponse):
flag = str(detail["flags"])
print_name = detail.get_print_name()
sub_name = detail.get_substitute_name()
error_details.append(f"Flag: {flag}, Print Name: {print_name}, Substitute Name: {sub_name}")
elif isinstance(detail, SMB2ShareRedirectErrorContext):
ip_addresses = []
for ip_addr in detail["ip_addr_move_list"].get_value():
ip_addresses.append(ip_addr.get_ipaddress())
resource_name = to_text(detail["resource_name"].get_value(), encoding="utf-16-le")
addresses = "', '".join(ip_addresses)
error_details.append(f"IP Addresses: '{addresses}', Resource Name: {resource_name}")
else:
# unknown error details in response, output raw bytes
error_details.append("Raw: " + to_text(binascii.hexlify(detail)))
status = format(self.status, "x").zfill(8)
error_msg = f"{self._BASE_MESSAGE} {self.header['status']}: 0x{status}"
if error_details:
error_msg += " - " + (", ".join(error_details))
return f"Received unexpected status from the server: {error_msg}"
@property
def status(self):
return self.header["status"].get_value()
def __str__(self):
return self.message
class Unsuccessful(SMBResponseException):
_BASE_MESSAGE = "The requested operation was unsuccessful."
_STATUS_CODE = NtStatus.STATUS_UNSUCCESSFUL
class NetworkNameDelegated(SMBResponseException):
_BASE_MESSAGE = "The network name was deleted."
_STATUS_CODE = NtStatus.STATUS_NETWORK_NAME_DELETED
class StatusPending(SMBResponseException):
_BASE_MESSAGE = "The operation that was requested is pending completion."
_STATUS_CODE = NtStatus.STATUS_PENDING
class NotifyCleanup(SMBResponseException):
_BASE_MESSAGE = (
"Indicates that a notify change request has been completed due to closing the handle that made "
"the notify change request."
)
_STATUS_CODE = NtStatus.STATUS_NOTIFY_CLEANUP
class NotifyEnumDir(SMBResponseException):
_BASE_MESSAGE = (
"Indicates that a notify change request is being completed and that the information is not "
"being returned in the caller's buffer. The caller now needs to enumerate the files to find "
"the changes."
)
_STATUS_CODE = NtStatus.STATUS_NOTIFY_ENUM_DIR
class BufferOverflow(SMBResponseException):
_BASE_MESSAGE = "The data was too large to fit into the specified buffer."
_STATUS_CODE = NtStatus.STATUS_BUFFER_OVERFLOW
class NoMoreFiles(SMBResponseException):
_BASE_MESSAGE = "No more files were found which match the file specification."
_STATUS_CODE = NtStatus.STATUS_NO_MORE_FILES
class EndOfFile(SMBResponseException):
_BASE_MESSAGE = "The end-of-file marker has been reached. There is no valid data in the file beyond this marker."
_STATUS_CODE = NtStatus.STATUS_END_OF_FILE
class InvalidEAName(SMBResponseException):
_BASE_MESSAGE = "The specified extended attribute (EA) name contains at least one illegal character."
_STATUS_CODE = NtStatus.STATUS_INVALID_EA_NAME
class EAListInconsistent(SMBResponseException):
_BASE_MESSAGE = "The extended attribute (EA) list is inconsistent."
_STATUS_CODE = NtStatus.STATUS_EA_LIST_INCONSISTENT
class StoppedOnSymlink(SMBResponseException):
_BASE_MESSAGE = "The create operation stopped after reaching a symbolic link."
_STATUS_CODE = NtStatus.STATUS_STOPPED_ON_SYMLINK
class InvalidInfoClass(SMBResponseException):
_BASE_MESSAGE = "The specified information class is not a valid information class for the specified object."
_STATUS_CODE = NtStatus.STATUS_INVALID_INFO_CLASS
class InfoLengthMismatch(SMBResponseException):
_BASE_MESSAGE = (
"The specified information record length does not match the length that is required for the "
"specified information class."
)
_STATUS_CODE = NtStatus.STATUS_INFO_LENGTH_MISMATCH
class InvalidParameter(SMBResponseException):
_BASE_MESSAGE = "An invalid parameter was passed to a service or function."
_STATUS_CODE = NtStatus.STATUS_INVALID_PARAMETER
class NoSuchFile(SMBResponseException):
_BASE_MESSAGE = "The file does not exist."
_STATUS_CODE = NtStatus.STATUS_NO_SUCH_FILE
class InvalidDeviceRequest(SMBResponseException):
_BASE_MESSAGE = "The specified request is not a valid operation for the target device."
_STATUS_CODE = NtStatus.STATUS_INVALID_DEVICE_REQUEST
class MoreProcessingRequired(SMBResponseException):
_BASE_MESSAGE = (
"The specified I/O request packet (IRP) cannot be disposed of because the I/O operation is not complete."
)
_STATUS_CODE = NtStatus.STATUS_MORE_PROCESSING_REQUIRED
class AccessDenied(SMBResponseException):
_BASE_MESSAGE = "A process has requested access to an object but has not been granted those access rights."
_STATUS_CODE = NtStatus.STATUS_ACCESS_DENIED
class BufferTooSmall(SMBResponseException):
_BASE_MESSAGE = "The buffer is too small to contain the entry. No information has been written to the buffer."
_STATUS_CODE = NtStatus.STATUS_BUFFER_TOO_SMALL
class ObjectNameInvalid(SMBResponseException):
_BASE_MESSAGE = "The object name is invalid."
_STATUS_CODE = NtStatus.STATUS_OBJECT_NAME_INVALID
class ObjectNameNotFound(SMBResponseException):
_BASE_MESSAGE = "The object name is not found."
_STATUS_CODE = NtStatus.STATUS_OBJECT_NAME_NOT_FOUND
class ObjectNameCollision(SMBResponseException):
_BASE_MESSAGE = "The object name already exists."
_STATUS_CODE = NtStatus.STATUS_OBJECT_NAME_COLLISION
class ObjectPathInvalid(SMBResponseException):
_BASE_MESSAGE = "The object path component was not a directory object."
_STATUS_CODE = NtStatus.STATUS_OBJECT_PATH_INVALID
class ObjectPathNotFound(SMBResponseException):
_BASE_MESSAGE = "The path does not exist."
_STATUS_CODE = NtStatus.STATUS_OBJECT_PATH_NOT_FOUND
class ObjectPathSyntaxBad(SMBResponseException):
_BASE_MESSAGE = "The object path component was not a directory object."
_STATUS_CODE = NtStatus.STATUS_OBJECT_PATH_SYNTAX_BAD
class SharingViolation(SMBResponseException):
_BASE_MESSAGE = "A file cannot be opened because the share access flags are incompatible."
_STATUS_CODE = NtStatus.STATUS_SHARING_VIOLATION
class EASNotSupported(SMBResponseException):
_BASE_MESSAGE = "An operation involving EAs failed because the file system does not support EAs."
_STATUS_CODE = NtStatus.STATUS_EAS_NOT_SUPPORTED
class EATooLarge(SMBResponseException):
_BASE_MESSAGE = "An EA operation failed because the EA set is too large."
_STATUS_CODE = NtStatus.STATUS_EA_TOO_LARGE
class NonExistentEAEntry(SMBResponseException):
_BASE_MESSAGE = "An EA operation failed because the name or EA index is invalid."
_STATUS_CODE = NtStatus.STATUS_NONEXISTENT_EA_ENTRY
class NoEASOnFile(SMBResponseException):
_BASE_MESSAGE = "The file for which EAs were requested has no EAs."
_STATUS_CODE = NtStatus.STATUS_NO_EAS_ON_FILE
class EACorruptError(SMBResponseException):
_BASE_MESSAGE = "The EA is corrupt and cannot be read."
_STATUS_CODE = NtStatus.STATUS_EA_CORRUPT_ERROR
class DeletePending(SMBResponseException):
_BASE_MESSAGE = "A non-close operation has been requested of a file object that has a delete pending."
_STATUS_CODE = NtStatus.STATUS_DELETE_PENDING
class PrivilegeNotHeld(SMBResponseException):
_BASE_MESSAGE = "A required privilege is not held by the client."
_STATUS_CODE = NtStatus.STATUS_PRIVILEGE_NOT_HELD
class WrongPassword(SMBResponseException):
_BASE_MESSAGE = "The specified password is not correct or the user is locked out."
_STATUS_CODE = NtStatus.STATUS_WRONG_PASSWORD
class LogonFailure(SMBResponseException):
_BASE_MESSAGE = (
"The attempted logon is invalid. This is either due to a bad username or authentication information."
)
_STATUS_CODE = NtStatus.STATUS_LOGON_FAILURE
class PasswordExpired(SMBResponseException):
_BASE_MESSAGE = "The user account password has expired."
_STATUS_CODE = NtStatus.STATUS_PASSWORD_EXPIRED
class NoneMapped(SMBResponseException):
_BASE_MESSAGE = "None of the information to be translated has been translated."
_STATUS_CODE = NtStatus.STATUS_NONE_MAPPED
class InsufficientResources(SMBResponseException):
_BASE_MESSAGE = "Insufficient system resources exist to complete the API."
_STATUS_CODE = NtStatus.STATUS_INSUFFICIENT_RESOURCES
class PipeNotAvailable(SMBResponseException):
_BASE_MESSAGE = "An instance of a named pipe cannot be found in the listening state."
_STATUS_CODE = NtStatus.STATUS_PIPE_NOT_AVAILABLE
class PipeBusy(SMBResponseException):
_BASE_MESSAGE = (
"The specified pipe is set to complete operations and there are current I/O operations queued "
"so that it cannot be changed to queue operations."
)
_STATUS_CODE = NtStatus.STATUS_PIPE_BUSY
class PipeClosing(SMBResponseException):
_BASE_MESSAGE = "The specified named pipe is in the closing state."
_STATUS_CODE = NtStatus.STATUS_PIPE_CLOSING
class IOTimeout(SMBResponseException):
_BASE_MESSAGE = "The specified I/O operation was not completed before the time-out period expired."
_STATUS_CODE = NtStatus.STATUS_IO_TIMEOUT
class PipeDisconnected(SMBResponseException):
_BASE_MESSAGE = "The specified named pipe is in the disconnected state."
_STATUS_CODE = NtStatus.STATUS_PIPE_DISCONNECTED
class FileIsADirectory(SMBResponseException):
_BASE_MESSAGE = (
"The file that was specified as a target is a directory, and the caller specified that it could "
"be anything but a directory."
)
_STATUS_CODE = NtStatus.STATUS_FILE_IS_A_DIRECTORY
class NotSupported(SMBResponseException):
_BASE_MESSAGE = "The request is not supported."
_STATUS_CODE = NtStatus.STATUS_NOT_SUPPORTED
class BadNetworkName(SMBResponseException):
_BASE_MESSAGE = "The specified share name cannot be found on the remote server."
_STATUS_CODE = NtStatus.STATUS_BAD_NETWORK_NAME
class RequestNotAccepted(SMBResponseException):
_BASE_MESSAGE = (
"No more connections can be made to this remote computer at this time because the computer has "
"already accepted the maximum number of connections."
)
_STATUS_CODE = NtStatus.STATUS_REQUEST_NOT_ACCEPTED
class PipeEmpty(SMBResponseException):
_BASE_MESSAGE = "Used to indicate that a read operation was done on an empty pipe."
_STATUS_CODE = NtStatus.STATUS_PIPE_EMPTY
class InternalError(SMBResponseException):
_BASE_MESSAGE = "An internal error occurred."
_STATUS_CODE = NtStatus.STATUS_INTERNAL_ERROR
class DirectoryNotEmpty(SMBResponseException):
_BASE_MESSAGE = "Indicates that the directory trying to be deleted is not empty."
_STATUS_CODE = NtStatus.STATUS_DIRECTORY_NOT_EMPTY
class StatusNotADirectory(SMBResponseException):
_BASE_MESSAGE = "A requested opened file is not a directory."
_STATUS_CODE = NtStatus.STATUS_NOT_A_DIRECTORY
class Cancelled(SMBResponseException):
_BASE_MESSAGE = "The I/O request was canceled."
_STATUS_CODE = NtStatus.STATUS_CANCELLED
class CannotDelete(SMBResponseException):
_BASE_MESSAGE = "An attempt has been made to remove a file or directory that cannot be deleted."
_STATUS_CODE = NtStatus.STATUS_CANNOT_DELETE
class FileClosed(SMBResponseException):
_BASE_MESSAGE = (
"An I/O request other than close and several other special case operations was attempted using "
"a file object that had already been closed."
)
_STATUS_CODE = NtStatus.STATUS_FILE_CLOSED
class PipeBroken(SMBResponseException):
_BASE_MESSAGE = "The pipe operation has failed because the other end of the pipe has been closed."
_STATUS_CODE = NtStatus.STATUS_PIPE_BROKEN
class FSDriverRequired(SMBResponseException):
_BASE_MESSAGE = (
"A volume has been accessed for which a file system driver is required that has not yet been loaded."
)
_STATUS_CODE = NtStatus.STATUS_FS_DRIVER_REQUIRED
class UserSessionDeleted(SMBResponseException):
_BASE_MESSAGE = "The remote user session has been deleted."
_STATUS_CODE = NtStatus.STATUS_USER_SESSION_DELETED
class InsuffServerResources(SMBResponseException):
_BASE_MESSAGE = "Insufficient server resources exist to complete the request."
_STATUS_CODE = NtStatus.STATUS_INSUFF_SERVER_RESOURCES
class NotFound(SMBResponseException):
_BASE_MESSAGE = "The object was not found."
_STATUS_CODE = NtStatus.STATUS_NOT_FOUND
class PathNotCovered(SMBResponseException):
_BASE_MESSAGE = "The contacted server does not support the indicated part of the DFS namespace."
_STATUS_CODE = NtStatus.STATUS_PATH_NOT_COVERED
class DfsUnavailable(SMBResponseException):
_BASE_MESSAGE = "DFS is unavailable on the contacted server."
_STATUS_CODE = NtStatus.STATUS_DFS_UNAVAILABLE
class NotAReparsePoint(SMBResponseException):
_BASE_MESSAGE = "The NTFS file or directory is not a reparse point."
_STATUS_CODE = NtStatus.STATUS_NOT_A_REPARSE_POINT
class ServerUnavailable(SMBResponseException):
_BASE_MESSAGE = "The file server is temporarily unavailable."
_STATUS_CODE = NtStatus.STATUS_SERVER_UNAVAILABLE
class DiskFull(SMBResponseException):
_BASE_MESSAGE = "There is not enough space on the disk."
_STATUS_CODE = NtStatus.STATUS_DISK_FULL
class ErrorContextId:
"""
[MS-SMB2] v53.0 2017-09-15
2.2.2.1 SMB2 Error Context Response ErrorId
An identifier for the error context, it MUST be set to one of the following
values.
"""
SMB2_ERROR_ID_DEFAULT = 0x00000000
SMB2_ERROR_ID_SHARE_REDIRECT = 0x53526472
class SymbolicLinkErrorFlags:
"""
[MS-SMB2] v53.0 2017-09-15
2.2.2.2.1 Symbolic Link Error Response Flags
Specifies whether the substitute name is an absolute target path or a path
name relative to the directory containing the symbolic link
"""
SYMLINK_FLAG_ABSOLUTE = 0x00000000
SYMLINK_FLAG_RELATIVE = 0x00000001
class IpAddrType:
"""
[MS-SM2] v53.0 2017-09-15
2.2.2.2.2.1 MOVE_DST_IPADDR structure Type
Indicates the type of the destionation IP address.
"""
MOVE_DST_IPADDR_V4 = 0x00000001
MOVE_DST_IPADDR_V6 = 0x00000002
class SMB2ErrorResponse(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.2 SMB2 Error Response
The SMB2 Error Response packet is sent by the server to respond to a
request that has failed or encountered an error. This is only used in the
SMB 3.1.1 dialect and this code won't decode values based on older versions
"""
def __init__(self):
self.fields = OrderedDict(
[
(
"structure_size",
IntField(
size=2,
default=9,
),
),
(
"error_context_count",
IntField(
size=1,
default=lambda s: len(s["error_data"].get_value()),
),
),
("reserved", IntField(size=1)),
(
"byte_count",
IntField(
size=4,
default=lambda s: len(s["error_data"]),
),
),
(
"error_data",
ListField(
size=lambda s: s["byte_count"].get_value(),
list_count=lambda s: s["error_context_count"].get_value(),
list_type=StructureField(structure_type=SMB2ErrorContextResponse),
unpack_func=SMB2ErrorResponse._error_data_value,
),
),
]
)
super().__init__()
@staticmethod
def _error_data_value(structure, data):
context_responses = []
while len(data) > 0:
response = SMB2ErrorContextResponse()
if structure["error_context_count"].get_value() > 0:
# Working with SMB 3.1.1+ where the errors are already in an SMB2ErrorContextReponse packet, unpack the
# data as usual
data = response.unpack(data)
else:
# Working with an older SMB dialect where the response is set directly in the error_data field, need to
# manually craft the SMB2ErrorContextResponse with the data returned.
response["error_context_data"] = data
data = b""
context_responses.append(response)
return context_responses
class SMB2ErrorContextResponse(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.2.1 SMB2 ERROR Context Response
For the SMB dialect 3.1.1, the server formats the error data as an array of
SMB2 Error Context structures in the SMB2ErrorResponse message.
"""
def __init__(self):
self.fields = OrderedDict(
[
(
"error_data_length",
IntField(
size=4,
default=lambda s: len(s["error_context_data"]),
),
),
(
"error_id",
EnumField(
size=4,
default=ErrorContextId.SMB2_ERROR_ID_DEFAULT,
enum_type=ErrorContextId,
),
),
(
"error_context_data",
BytesField(
size=lambda s: s["error_data_length"].get_value(),
),
),
]
)
super().__init__()
class SMB2SymbolicLinkErrorResponse(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.2.2.1 Symbolic Link Error Response
The Symbolic Link Error Response is used to indicate that a symbolic link
was encountered on the create. It describes the target path that the client
MUST use if it requires to follow the symbolic link.
"""
def __init__(self):
self.fields = OrderedDict(
[
("symlink_length", IntField(size=4, default=lambda s: len(s) - 4)),
("symlink_error_tag", BytesField(size=4, default=b"\x53\x59\x4d\x4c")),
("reparse_tag", BytesField(size=4, default=b"\x0c\x00\x00\xa0")),
("reparse_data_length", IntField(size=2, default=lambda s: len(s["path_buffer"]) + 12)),
# the len in utf-16-le bytes of the path beyond the substitute name
# of the original target, e.g. \\server\share\symlink\file.txt
# would be length of \file.txt in utf-16-le form, this is used by
# the client to find out what part of the original path to append
# to the substitute name returned by the server.
("unparsed_path_length", IntField(size=2)),
("substitute_name_offset", IntField(size=2)),
("substitute_name_length", IntField(size=2)),
("print_name_offset", IntField(size=2)),
("print_name_length", IntField(size=2)),
(
"flags",
EnumField(
size=2,
enum_type=SymbolicLinkErrorFlags,
),
),
# Not in the spec but Windows seems to add \x00\x80 to the end of flags which breaks our parsing. Cannot
# seem to figure out why but this just ignored that field.
("reserved", IntField(size=2)),
# use the get/set_name functions to get/set these values as they
# also (d)encode the text and set the length and offset accordingly
("path_buffer", BytesField(size=SMB2SymbolicLinkErrorResponse._get_name_length)),
]
)
super().__init__()
@staticmethod
def _get_name_length(structure, first=True):
print_name_len = structure["print_name_length"].get_value()
sub_name_len = structure["substitute_name_length"].get_value()
return print_name_len + sub_name_len
def set_name(self, print_name, substitute_name):
"""
Set's the path_buffer and print/substitute name length of the message
with the values passed in. These values should be a string and not a
byte string as it is encoded in this function.
:param print_name: The print name string to set
:param substitute_name: The substitute name string to set
"""
# Ensure that the to_bytes input is an actual text string for py2 compat with native strings.
print_bytes = to_bytes(to_text(print_name), encoding="utf-16-le")
sub_bytes = to_bytes(to_text(substitute_name), encoding="utf-16-le")
path_buffer = print_bytes + sub_bytes
self["print_name_offset"].set_value(0)
self["print_name_length"].set_value(len(print_bytes))
self["substitute_name_offset"].set_value(len(print_bytes))
self["substitute_name_length"].set_value(len(sub_bytes))
self["path_buffer"].set_value(path_buffer)
def get_print_name(self):
offset = self["print_name_offset"].get_value()
length = self["print_name_length"].get_value()
name_bytes = self["path_buffer"].get_value()[offset : offset + length]
return to_text(name_bytes, encoding="utf-16-le")
def get_substitute_name(self):
offset = self["substitute_name_offset"].get_value()
length = self["substitute_name_length"].get_value()
name_bytes = self["path_buffer"].get_value()[offset : offset + length]
return to_text(name_bytes, encoding="utf-16-le")
def resolve_path(self, link_path):
"""
[MS-SMB2] 2.2.2.2.1.1 Handling the Symbolic Link Error Response
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-smb2/a8da655c-8b0b-415a-b726-16dc33fa5827
Attempts to resolve the link target path. Will fail if the link is pointing to a local path or a UNC path
on another host or share.
:param link_path: The original path to the symbolic link to resolve relative paths from.
:return: The resolved link target path.
"""
substitute_name = self.get_substitute_name()
print_name = self.get_print_name()
unparsed_path_length = self["unparsed_path_length"].get_value()
b_link_path = to_bytes(to_text(link_path), encoding="utf-16-le")
unparsed_idx = len(b_link_path) - unparsed_path_length
base_link_path = to_text(b_link_path[:unparsed_idx], encoding="utf-16-le")
unparsed_path = to_text(b_link_path[unparsed_idx:], encoding="utf-16-le")
# Use the common code in SymbolicLinkReparseDataBuffer() to resolve the link target.
symlink_buffer = SymbolicLinkReparseDataBuffer()
symlink_buffer["flags"] = self["flags"].get_value()
symlink_buffer.set_name(substitute_name, print_name)
target_path = symlink_buffer.resolve_link(base_link_path) + unparsed_path
if not target_path.startswith("\\\\"):
raise SMBLinkRedirectionError(
"Cannot resolve link targets that point to a local path", link_path, print_name
)
link_share = ntpath.splitdrive(link_path)[0]
target_share = ntpath.splitdrive(target_path)[0]
if link_share != target_share:
raise SMBLinkRedirectionError(
"Cannot resolve link targets that point to a different host/share", link_path, print_name
)
return target_path
class SMB2ShareRedirectErrorContext(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.2.2.2 Share Redirect Error Context Response
Response to a Tree Connect with the
SMB2_TREE_CONNECT_FLAG_REDIRECT_TO_OWNER flag set.
"""
def __init__(self):
self.fields = OrderedDict(
[
("structure_size", IntField(size=4, default=lambda s: len(s))),
("notification_type", IntField(size=4, default=3)),
("resource_name_offset", IntField(size=4, default=SMB2ShareRedirectErrorContext._resource_name_offset)),
("resource_name_length", IntField(size=4, default=lambda s: len(s["resource_name"]))),
("flags", IntField(size=2, default=0)),
("target_type", IntField(size=2, default=0)),
("ip_addr_count", IntField(size=4, default=lambda s: len(s["ip_addr_move_list"].get_value()))),
(
"ip_addr_move_list",
ListField(
size=lambda s: s["ip_addr_count"].get_value() * 24,
list_count=lambda s: s["ip_addr_count"].get_value(),
list_type=StructureField(size=24, structure_type=SMB2MoveDstIpAddrStructure),
),
),
("resource_name", BytesField(size=lambda s: s["resource_name_length"].get_value())),
]
)
super().__init__()
@staticmethod
def _resource_name_offset(structure):
min_structure_size = 24
addr_list_size = len(structure["ip_addr_move_list"])
return min_structure_size + addr_list_size
class SMB2MoveDstIpAddrStructure(Structure):
"""
[MS-SMB2] c53.0 2017-09-15
2.2.2.2.2.1 MOVE_DST_IPADDR structure
Used to indicate the destination IP address.
"""
def __init__(self):
self.fields = OrderedDict(
[
("type", EnumField(size=4, enum_type=IpAddrType)),
("reserved", IntField(size=4)),
("ip_address", BytesField(size=SMB2MoveDstIpAddrStructure._ip_address_size)),
(
"reserved2",
BytesField(
size=SMB2MoveDstIpAddrStructure._reserved2_size,
default=SMB2MoveDstIpAddrStructure._default_reserved2_size,
),
),
]
)
super().__init__()
@staticmethod
def _ip_address_size(structure):
if structure["type"].get_value() == IpAddrType.MOVE_DST_IPADDR_V4:
return 4
else:
return 16
@staticmethod
def _reserved2_size(structure):
if structure["type"].get_value() == IpAddrType.MOVE_DST_IPADDR_V4:
return 12
else:
return 0
@staticmethod
def _default_reserved2_size(structure):
return b"\x00" * SMB2MoveDstIpAddrStructure._reserved2_size(structure)
def get_ipaddress(self):
# get's the IP address in a human readable format
ip_address = self["ip_address"].get_value()
if self["type"].get_value() == IpAddrType.MOVE_DST_IPADDR_V4:
return socket.inet_ntoa(ip_address)
else:
addr = binascii.hexlify(ip_address).decode("utf-8")
return ":".join([addr[i : i + 4] for i in range(0, len(addr), 4)])
def set_ipaddress(self, address):
# set's the IP address from a human readable format, for IPv6, this
# needs to be the full IPv6 address
if self["type"].get_value() == IpAddrType.MOVE_DST_IPADDR_V4:
self["ip_address"].set_value(socket.inet_aton(address))
else:
addr = address.replace(":", "")
if len(addr) != 32:
raise ValueError("When setting an IPv6 address, it must be in the full form without concatenation")
self["ip_address"].set_value(binascii.unhexlify(addr))

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,307 @@
# Copyright: (c) 2020, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
from collections import OrderedDict
from smbprotocol.structure import BytesField, EnumField, FlagField, IntField, Structure
class Commands:
"""
[MS-SMB2] v53.0 2017-09-15
2.2.1.2 SMB2 Packet Header - SYNC Command
The command code of an SMB2 packet, it is used in the packet header.
"""
SMB2_NEGOTIATE = 0x0000
SMB2_SESSION_SETUP = 0x0001
SMB2_LOGOFF = 0x0002
SMB2_TREE_CONNECT = 0x0003
SMB2_TREE_DISCONNECT = 0x0004
SMB2_CREATE = 0x0005
SMB2_CLOSE = 0x0006
SMB2_FLUSH = 0x0007
SMB2_READ = 0x0008
SMB2_WRITE = 0x0009
SMB2_LOCK = 0x000A
SMB2_IOCTL = 0x000B
SMB2_CANCEL = 0x000C
SMB2_ECHO = 0x000D
SMB2_QUERY_DIRECTORY = 0x000E
SMB2_CHANGE_NOTIFY = 0x000F
SMB2_QUERY_INFO = 0x0010
SMB2_SET_INFO = 0x0011
SMB2_OPLOCK_BREAK = 0x0012
class NtStatus:
"""
[MS-ERREF] https://msdn.microsoft.com/en-au/library/cc704588.aspx
2.3.1 NTSTATUS Values
These values are set in the status field of an SMB2Header response. This is
not an exhaustive list but common values that are returned.
"""
STATUS_SUCCESS = 0x00000000
STATUS_UNSUCCESSFUL = 0xC0000001
STATUS_NETWORK_NAME_DELETED = 0xC00000C9
STATUS_PENDING = 0x00000103
STATUS_NOTIFY_CLEANUP = 0x0000010B
STATUS_NOTIFY_ENUM_DIR = 0x0000010C
STATUS_BUFFER_OVERFLOW = 0x80000005
STATUS_NO_MORE_FILES = 0x80000006
STATUS_END_OF_FILE = 0xC0000011
STATUS_INVALID_EA_NAME = 0x80000013
STATUS_EA_LIST_INCONSISTENT = 0x80000014
STATUS_STOPPED_ON_SYMLINK = 0x8000002D
STATUS_INVALID_INFO_CLASS = 0xC0000003
STATUS_INFO_LENGTH_MISMATCH = 0xC0000004
STATUS_INVALID_HANDLE = 0xC0000008
STATUS_INVALID_PARAMETER = 0xC000000D
STATUS_NO_SUCH_FILE = 0xC000000F
STATUS_INVALID_DEVICE_REQUEST = 0xC0000010
STATUS_MORE_PROCESSING_REQUIRED = 0xC0000016
STATUS_ACCESS_DENIED = 0xC0000022
STATUS_BUFFER_TOO_SMALL = 0xC0000023
STATUS_OBJECT_NAME_INVALID = 0xC0000033
STATUS_OBJECT_NAME_NOT_FOUND = 0xC0000034
STATUS_OBJECT_NAME_COLLISION = 0xC0000035
STATUS_OBJECT_PATH_INVALID = 0xC0000039
STATUS_OBJECT_PATH_NOT_FOUND = 0xC000003A
STATUS_OBJECT_PATH_SYNTAX_BAD = 0xC000003B
STATUS_SHARING_VIOLATION = 0xC0000043
STATUS_EAS_NOT_SUPPORTED = 0xC000004F
STATUS_EA_TOO_LARGE = 0xC0000050
STATUS_NONEXISTENT_EA_ENTRY = 0xC0000051
STATUS_NO_EAS_ON_FILE = 0xC0000052
STATUS_EA_CORRUPT_ERROR = 0xC0000053
STATUS_DELETE_PENDING = 0xC0000056
STATUS_PRIVILEGE_NOT_HELD = 0xC0000061
STATUS_WRONG_PASSWORD = 0xC000006A
STATUS_LOGON_FAILURE = 0xC000006D
STATUS_PASSWORD_EXPIRED = 0xC0000071
STATUS_NONE_MAPPED = 0xC0000073
STATUS_INSUFFICIENT_RESOURCES = 0xC000009A
STATUS_PIPE_NOT_AVAILABLE = 0xC00000AC
STATUS_PIPE_BUSY = 0xC00000AE
STATUS_PIPE_DISCONNECTED = 0xC00000B0
STATUS_PIPE_CLOSING = 0xC00000B1
STATUS_IO_TIMEOUT = 0xC00000B5
STATUS_FILE_IS_A_DIRECTORY = 0xC00000BA
STATUS_NOT_SUPPORTED = 0xC00000BB
STATUS_BAD_NETWORK_NAME = 0xC00000CC
STATUS_REQUEST_NOT_ACCEPTED = 0xC00000D0
STATUS_PIPE_EMPTY = 0xC00000D9
STATUS_INTERNAL_ERROR = 0xC00000E5
STATUS_DIRECTORY_NOT_EMPTY = 0xC0000101
STATUS_NOT_A_DIRECTORY = 0xC0000103
STATUS_CANCELLED = 0xC0000120
STATUS_CANNOT_DELETE = 0xC0000121
STATUS_FILE_CLOSED = 0xC0000128
STATUS_PIPE_BROKEN = 0xC000014B
STATUS_FS_DRIVER_REQUIRED = 0xC000019C
STATUS_USER_SESSION_DELETED = 0xC0000203
STATUS_INSUFF_SERVER_RESOURCES = 0xC0000205
STATUS_NOT_FOUND = 0xC0000225
STATUS_PATH_NOT_COVERED = 0xC0000257
STATUS_DFS_UNAVAILABLE = 0xC000026D
STATUS_NOT_A_REPARSE_POINT = 0xC0000275
STATUS_SERVER_UNAVAILABLE = 0xC0000466
STATUS_DISK_FULL = 0xC000007F
class Smb2Flags:
"""
[MS-SMB2] v53.0 2017-09-15
2.2.1.2 SMB2 Packet Header - SYNC Flags
Indicates various processing rules that need to be done on the SMB2 packet.
"""
SMB2_FLAGS_SERVER_TO_REDIR = 0x00000001
SMB2_FLAGS_ASYNC_COMMAND = 0x00000002
SMB2_FLAGS_RELATED_OPERATIONS = 0x00000004
SMB2_FLAGS_SIGNED = 0x00000008
SMB2_FLAGS_PRIORITY_MASK = 0x00000070
SMB2_FLAGS_DFS_OPERATIONS = 0x10000000
SMB2_FLAGS_REPLAY_OPERATIONS = 0x20000000
class SMB2HeaderAsync(Structure):
"""
[MS-SMB2] 2.2.1.1 SMB2 Packer Header - ASYNC
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-smb2/ea4560b7-90da-4803-82b5-344754b92a79
The SMB2 Packet header for async commands.
"""
def __init__(self):
self.fields = OrderedDict(
[
(
"protocol_id",
BytesField(
size=4,
default=b"\xfeSMB",
),
),
(
"structure_size",
IntField(
size=2,
default=64,
),
),
("credit_charge", IntField(size=2)),
("channel_sequence", IntField(size=2)),
("reserved", IntField(size=2)),
(
"command",
EnumField(
size=2,
enum_type=Commands,
),
),
("credit_request", IntField(size=2)),
(
"flags",
FlagField(
size=4,
flag_type=Smb2Flags,
),
),
("next_command", IntField(size=4)),
("message_id", IntField(size=8)),
("async_id", IntField(size=8)),
("session_id", IntField(size=8)),
(
"signature",
BytesField(
size=16,
default=b"\x00" * 16,
),
),
("data", BytesField()),
]
)
super().__init__()
class SMB2HeaderRequest(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.1.2 SMB2 Packet Header - SYNC
This is the header definition that contains the ChannelSequence/Reserved
instead of the Status field used for a Packet request.
"""
def __init__(self):
self.fields = OrderedDict(
[
(
"protocol_id",
BytesField(
size=4,
default=b"\xfeSMB",
),
),
(
"structure_size",
IntField(
size=2,
default=64,
),
),
("credit_charge", IntField(size=2)),
("channel_sequence", IntField(size=2)),
("reserved", IntField(size=2)),
("command", EnumField(size=2, enum_type=Commands)),
("credit_request", IntField(size=2)),
(
"flags",
FlagField(
size=4,
flag_type=Smb2Flags,
),
),
("next_command", IntField(size=4)),
("message_id", IntField(size=8)),
("process_id", IntField(size=4)),
("tree_id", IntField(size=4)),
("session_id", IntField(size=8)),
(
"signature",
BytesField(
size=16,
default=b"\x00" * 16,
),
),
("data", BytesField()),
]
)
super().__init__()
class SMB2HeaderResponse(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.1.2 SMB2 Packet Header - SYNC
The header definition for an SMB Response that contains the Status field
instead of the ChannelSequence/Reserved used for a Packet response.
"""
def __init__(self):
self.fields = OrderedDict(
[
(
"protocol_id",
BytesField(
size=4,
default=b"\xfeSMB",
),
),
(
"structure_size",
IntField(
size=2,
default=64,
),
),
("credit_charge", IntField(size=2)),
("status", EnumField(size=4, enum_type=NtStatus, enum_strict=False)),
(
"command",
EnumField(
size=2,
enum_type=Commands,
enum_strict=False,
),
),
("credit_response", IntField(size=2)),
(
"flags",
FlagField(
size=4,
flag_type=Smb2Flags,
),
),
("next_command", IntField(size=4)),
("message_id", IntField(size=8)),
("reserved", IntField(size=4)),
("tree_id", IntField(size=4)),
("session_id", IntField(size=8)),
(
"signature",
BytesField(
size=16,
default=b"\x00" * 16,
),
),
("data", BytesField()),
]
)
super().__init__()

View File

@@ -0,0 +1,628 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
import binascii
import socket
from collections import OrderedDict
from smbprotocol import Dialects
from smbprotocol.connection import Capabilities, SecurityMode
from smbprotocol.header import Commands
from smbprotocol.structure import (
BytesField,
EnumField,
FlagField,
IntField,
ListField,
Structure,
StructureField,
UuidField,
)
class CtlCode:
"""
[MS-SMB2] v53.0 2017-09-15
2.2.31 SMB2 IOCTL Request CtlCode
The control code of the FSCTL_IOCTL method.
"""
FSCTL_DFS_GET_REFERRALS = 0x00060194
FSCTL_PIPE_PEEK = 0x0011400C
FSCTL_PIPE_WAIT = 0x00110018
FSCTL_PIPE_TRANSCEIVE = 0x0011C017
FSCTL_SRV_COPYCHUNK = 0x001440F2
FSCTL_SRV_ENUMERATE_SNAPSHOTS = 0x00144064
FSCTL_SRV_REQUEST_RESUME_KEY = 0x00140078
FSCTL_SRV_READ_HASH = 0x001441BB
FSCTL_SRV_COPYCHUNK_WRITE = 0x001480F2
FSCTL_LMR_REQUEST_RESILIENCY = 0x001401D4
FSCTL_QUERY_NETWORK_INTERFACE_INFO = 0x001401FC
FSCTL_SET_REPARSE_POINT = 0x000900A4
FSCTL_GET_REPARSE_POINT = 0x000900A8
FSCTL_DELETE_REPARSE_POINT = 0x000900AC
FSCTL_CREATE_OR_GET_OBJECT_ID = 0x000900C0
FSCTL_SET_SPARSE = 0x000900C4
FSCTL_QUERY_ALLOCATED_RANGES = 0x000940CF
FSCTL_DFS_GET_REFERRALS_EX = 0x000601B0
FSCTL_SET_ZERO_DATA = 0x000980C8
FSCTL_FILE_LEVEL_TRIM = 0x00098208
FSCTL_VALIDATE_NEGOTIATE_INFO = 0x00140204
class IOCTLFlags:
"""
[MS-SMB2] v53.0 2017-09-15
2.2.31 SMB2 IOCTL Request Flags
A flag that indicates how to process the operation
"""
SMB2_0_IOCTL_IS_IOCTL = 0x00000000
SMB2_0_IOCTL_IS_FSCTL = 0x00000001
class HashVersion:
"""
[MS-SMB2] v53.0 2017-09-15
2.2.31.2 SRV_READ_HASH Request HashVersion
The version number of the algorithm used to create the Content Information.
"""
SRV_HASH_VER_1 = 0x00000001
SRV_HASH_VER_2 = 0x00000002
class HashRetrievalType:
"""
[MS-SMB2] v53.0 2017-09-15
2.2.31.2 SRV_READ_HASH Request HashRetrievalType
Indicates the nature of the Offset field in am SMB2SrvReadHashRequest
packet.
"""
SRV_HASH_RETRIEVE_HASH_BASED = 0x00000001
SRV_HASH_RETRIEVE_FILE_BASED = 0x00000002
class IfCapability:
"""
[MS-SMB2] v53.0 2017-09-15
2.2.32.5 NETWORK_INTERFACE_INFO Response Capability
The capabilities of the network interface
"""
RSS_CAPABLE = 0x00000001
RDMA_CAPABLE = 0x00000002
class SockAddrFamily:
"""
[MS-SMB2] v53.0 2017-09-15
2.2.32.5.1 SOCKADDR_STORAGE Family
The address family of the socket.
"""
INTER_NETWORK = 0x0002
INTER_NETWORK_V6 = 0x0017
class SMB2IOCTLRequest(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.31 SMB2 IOCTL Request
Send by the client to issue an implementation-specific file system control
or device control command across the network.
"""
COMMAND = Commands.SMB2_IOCTL
def __init__(self):
self.fields = OrderedDict(
[
("structure_size", IntField(size=2, default=57)),
("reserved", IntField(size=2, default=0)),
(
"ctl_code",
EnumField(
size=4,
enum_type=CtlCode,
),
),
("file_id", BytesField(size=16)),
("input_offset", IntField(size=4, default=SMB2IOCTLRequest._buffer_offset_value)),
(
"input_count",
IntField(
size=4,
default=lambda s: len(s["buffer"]),
),
),
("max_input_response", IntField(size=4)),
("output_offset", IntField(size=4, default=SMB2IOCTLRequest._buffer_offset_value)),
("output_count", IntField(size=4, default=0)),
("max_output_response", IntField(size=4)),
(
"flags",
EnumField(
size=4,
enum_type=IOCTLFlags,
),
),
("reserved2", IntField(size=4, default=0)),
("buffer", BytesField(size=lambda s: s["input_count"].get_value())),
]
)
super().__init__()
@staticmethod
def _buffer_offset_value(structure):
# The offset from the beginning of the SMB2 header to the value of the
# buffer, 0 if no buffer is set
if len(structure["buffer"]) > 0:
header_size = 64
request_size = structure["structure_size"].get_value()
return header_size + request_size - 1
else:
return 0
class SMB2SrvCopyChunkCopy(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.31.1 SRV_COPYCHUNK_COPY
Sent in an SMB2 IOCTL Request by the client to initiate a server-side copy
of data.
"""
def __init__(self):
self.fields = OrderedDict(
[
("source_key", BytesField(size=24)),
("chunk_count", IntField(size=4, default=lambda s: len(s["chunks"].get_value()))),
("reserved", IntField(size=4)),
(
"chunks",
ListField(
size=lambda s: s["chunk_count"].get_value() * 24,
list_count=lambda s: s["chunk_count"].get_value(),
list_type=StructureField(size=24, structure_type=SMB2SrvCopyChunk),
),
),
]
)
super().__init__()
class SMB2SrvCopyChunk(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.31.1.1 SRC_COPYCHUNK
Packet sent in the Chunks array of an SRC_COPY_CHUNK_COPY packet to
describe an individual data range to copy.
"""
def __init__(self):
self.fields = OrderedDict(
[
("source_offset", IntField(size=8)),
("target_offset", IntField(size=8)),
("length", IntField(size=4)),
("reserved", IntField(size=4)),
]
)
super().__init__()
class SMB2SrvReadHashRequest(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.31.2 SRC_READ_HASH Request
Sent by the client in an SMB2 IOCTL Request to retrieve data from the
Content Information File associated with a specified file.
Not valid for the SMB 2.0.2 dialect.
"""
def __init__(self):
self.fields = OrderedDict(
[
("hash_type", IntField(size=4, default=1)), # SRV_HASH_TYPE_PEER_DIST
("hash_version", EnumField(size=4, enum_type=HashVersion)),
("hash_retrieval_type", EnumField(size=4, enum_type=HashRetrievalType)),
("length", IntField(size=4)),
("offset", IntField(size=8)),
]
)
super().__init__()
class SMB2SrvNetworkResiliencyRequest(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.31.3 NETWORK_RESILIENCY_REQUEST Request
Sent by the client to request resiliency for a specified open file.
Not valid for the SMB 2.0.2 dialect.
"""
def __init__(self):
self.fields = OrderedDict(
[
# timeout is in milliseconds
("timeout", IntField(size=4)),
("reserved", IntField(size=4)),
]
)
super().__init__()
class SMB2ValidateNegotiateInfoRequest(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.31.4 VALIDATE_NEGOTIATE_INFO Request
Packet sent to the server to request validation of a previous SMB 2
NEGOTIATE request.
Only valid for the SMB 3.0 and 3.0.2 dialects.
"""
def __init__(self):
self.fields = OrderedDict(
[
(
"capabilities",
FlagField(
size=4,
flag_type=Capabilities,
),
),
("guid", UuidField()),
(
"security_mode",
EnumField(
size=2,
enum_type=SecurityMode,
),
),
("dialect_count", IntField(size=2, default=lambda s: len(s["dialects"].get_value()))),
(
"dialects",
ListField(
size=lambda s: s["dialect_count"].get_value() * 2,
list_count=lambda s: s["dialect_count"].get_value(),
list_type=EnumField(size=2, enum_type=Dialects),
),
),
]
)
super().__init__()
class SMB2IOCTLResponse(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.32 SMB2 IOCTL Response
Sent by the server to transmit the results of a client SMB2 IOCTL Request.
"""
COMMAND = Commands.SMB2_IOCTL
def __init__(self):
self.fields = OrderedDict(
[
("structure_size", IntField(size=2, default=49)),
("reserved", IntField(size=2, default=0)),
(
"ctl_code",
EnumField(
size=4,
enum_type=CtlCode,
),
),
("file_id", BytesField(size=16)),
("input_offset", IntField(size=4)),
("input_count", IntField(size=4)),
("output_offset", IntField(size=4)),
("output_count", IntField(size=4)),
("flags", IntField(size=4, default=0)),
("reserved2", IntField(size=4, default=0)),
(
"buffer",
BytesField(
size=lambda s: s["output_count"].get_value(),
),
),
]
)
super().__init__()
class SMB2SrvCopyChunkResponse(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.32.1 SRV_COPYCHUNK_RESPONSE
"""
def __init__(self):
self.fields = OrderedDict(
[
("chunks_written", IntField(size=4)),
("chunk_bytes_written", IntField(size=4)),
("total_bytes_written", IntField(size=4)),
]
)
super().__init__()
class SMB2SrvSnapshotArray(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.32.2 SRV_SNAPSHOT_ARRAY
Sent by the server in response to an SMB2IOCTLResponse for the
FSCTL_SRV_ENUMERATE_SNAPSHOTS request.
"""
def __init__(self):
# TODO: validate this further when working with actual snapshots
self.fields = OrderedDict(
[
("number_of_snapshots", IntField(size=4)),
("number_of_snapshots_returned", IntField(size=4)),
("snapshot_array_size", IntField(size=4)),
("snapshots", BytesField()),
]
)
super().__init__()
class SMB2SrvRequestResumeKey(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.32.3 SRV_REQUEST_RESUME_KEY Response
Sent by the server in response to an SMB2IOCTLResponse for the
FSCTL_SRV_REQUEST_RESUME_KEY request.
"""
def __init__(self):
self.fields = OrderedDict(
[
("resume_key", BytesField(size=24)),
(
"context_length",
IntField(
size=4,
default=lambda s: len(s["context"]),
),
),
(
"context",
BytesField(
size=lambda s: s["context_length"].get_value(),
),
),
]
)
super().__init__()
class SMB2NetworkInterfaceInfo(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.32.5 NETWORK_INTERFACE_INFO Response
The NETWORK_INTERFACE_INFO returned to the client in an SMB2IOCTLResposne
for the FSCTL_QUERY_NETWORK_INTERFACE_INFO.
Use the pack_multiple and unpack_multiple to handle multiple interfaces
that are returned in the SMB2IOCTLResponse
"""
def __init__(self):
self.fields = OrderedDict(
[
# 0 if no more network interfaces
("next", IntField(size=4)),
("if_index", IntField(size=4)),
("capability", FlagField(size=4, flag_type=IfCapability)),
("reserved", IntField(size=4)),
("link_speed", IntField(size=8)),
("sock_addr_storage", StructureField(size=128, structure_type=SockAddrStorage)),
]
)
super().__init__()
@staticmethod
def pack_multiple(messages):
"""
Packs a list of SMB2NetworkInterfaceInfo messages and set's the next
value accordingly. The byte value returned is then attached to the
SMBIOCTLResponse message.
:param messages: List of SMB2NetworkInterfaceInfo messages
:return: bytes of the packed messages
"""
data = b""
msg_count = len(messages)
for i, msg in enumerate(messages):
if i == msg_count - 1:
msg["next"] = 0
else:
msg["next"] = 152
data += msg.pack()
return data
@staticmethod
def unpack_multiple(data):
"""
Get's a list of SMB2NetworkInterfaceInfo messages from the byte value
passed in. This is the raw buffer value that is set on the
SMB2IOCTLResponse message.
:param data: bytes of the messages
:return: List of SMB2NetworkInterfaceInfo messages
"""
chunks = []
while data:
info = SMB2NetworkInterfaceInfo()
data = info.unpack(data)
chunks.append(info)
return chunks
class SockAddrStorage(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.32.5.1 SOCKADDR_STORAGE
Socket Address information.
"""
def __init__(self):
self.fields = OrderedDict(
[
("family", EnumField(size=2, enum_type=SockAddrFamily)),
(
"buffer",
StructureField(
size=SockAddrStorage._get_buffer_size,
structure_type=SockAddrStorage._get_buffer_structure_type,
),
),
(
"reserved",
BytesField(
size=SockAddrStorage._get_reserved_size,
default=SockAddrStorage._default_get_reserved_size,
),
),
]
)
super().__init__()
@staticmethod
def _get_buffer_size(structure):
if structure["family"].get_value() == SockAddrFamily.INTER_NETWORK:
return 14
else:
return 26
@staticmethod
def _get_buffer_structure_type(structure):
if structure["family"].get_value() == SockAddrFamily.INTER_NETWORK:
return SockAddrIn
else:
return SockAddrIn6
@staticmethod
def _get_reserved_size(structure):
if structure["family"].get_value() == SockAddrFamily.INTER_NETWORK:
return 112
else:
return 100
@staticmethod
def _default_get_reserved_size(structure):
return b"\x00" * SockAddrStorage._get_reserved_size(structure)
class SockAddrIn(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.32.5.1.1 SOCKADDR_IN
Socket address information for an IPv4 address
"""
def __init__(self):
self.fields = OrderedDict(
[("port", IntField(size=2)), ("ipv4_address", BytesField(size=4)), ("reserved", IntField(size=8))]
)
super().__init__()
def get_ipaddress(self):
addr_bytes = self["ipv4_address"].get_value()
return socket.inet_ntoa(addr_bytes)
def set_ipaddress(self, address):
# set's the ipv4 address field from the address string passed in, this
# needs to be the full ipv4 address including periods, e.g.
# 192.168.1.1
addr_bytes = socket.inet_aton(address)
self["ipv4_address"].set_value(addr_bytes)
class SockAddrIn6(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.32.5.1.2 SOCKADDR_IN6
Socket address information for an IPv6 address
"""
def __init__(self):
self.fields = OrderedDict(
[
("port", IntField(size=2)),
("flow_info", IntField(size=4)),
("ipv6_address", BytesField(size=16)),
("scope_id", IntField(size=4)),
]
)
super().__init__()
def get_ipaddress(self):
# get's the full IPv6 Address, note this is the full address and has
# not been concatenated
addr_bytes = self["ipv6_address"].get_value()
address = binascii.hexlify(addr_bytes).decode("utf-8")
return ":".join([address[i : i + 4] for i in range(0, len(address), 4)])
def set_ipaddress(self, address):
# set's the ipv6_address field from the address passed in, note this
# needs to be the full ipv6 address,
# e.g. fe80:0000:0000:0000:0000:0000:0000:0000 and not any short form
address = address.replace(":", "")
if len(address) != 32:
raise ValueError("When setting an IPv6 address, it must be in the full form without concatenation")
self["ipv6_address"].set_value(binascii.unhexlify(address))
class SMB2ValidateNegotiateInfoResponse(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.32.6 VALIDATE_NEGOTIATE_INFO Response
Packet sent by the server on a request validation of SMB 2 negotiate
request.
"""
def __init__(self):
self.fields = OrderedDict(
[
(
"capabilities",
FlagField(
size=4,
flag_type=Capabilities,
),
),
("guid", UuidField()),
("security_mode", EnumField(size=2, enum_type=SecurityMode, enum_strict=False)),
("dialect", EnumField(size=2, enum_type=Dialects)),
]
)
super().__init__()

File diff suppressed because it is too large Load Diff

View File

@@ -0,0 +1,12 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
import warnings
from smbprotocol.file_info import *
warnings.warn(
"The smbprotocol.query_info file has been renamed to smbprotocol.file_info and will be removed in the "
"next major release.",
DeprecationWarning,
)

View File

@@ -0,0 +1,206 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
import ntpath
from collections import OrderedDict
from smbprotocol._text import to_bytes, to_text
from smbprotocol.structure import BytesField, EnumField, IntField, Structure
class ReparseTags:
"""
[MS-FSCC] 2.1.2.1 Reparse Tags
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/c8e77b37-3909-4fe6-a4ea-2b9d423b1ee4
Also includes the tags defined in winnt.h of the Windows 10 SDK.
"""
IO_REPARSE_TAG_RESERVED_ZERO = 0x00000000
IO_REPARSE_TAG_RESERVED_ONE = 0x00000001
IO_REPARSE_TAG_MOUNT_POINT = 0xA0000003
IO_REPARSE_TAG_HSM = 0xC0000004
IO_REPARSE_TAG_DRIVER_EXTENDER = 0x80000005
IO_REPARSE_TAG_HSM2 = 0x80000006
IO_REPARSE_TAG_SIS = 0x80000007
IO_REPARSE_TAG_WIM = 0x80000008
IO_REPARSE_TAG_CSV = 0x80000009
IO_REPARSE_TAG_DFS = 0x8000000A
IO_REPARSE_TAG_FILTER_MANAGER = 0x8000000B
IO_REPARSE_TAG_SYMLINK = 0xA000000C
IO_REPARSE_TAG_IIS_CACHE = 0xA0000010
IO_REPARSE_TAG_DFSR = 0x80000012
IO_REPARSE_TAG_DEDUP = 0x80000013
IO_REPARSE_TAG_NFS = 0x80000014
IO_REPARSE_TAG_FILE_PLACEHOLDER = 0x80000015
IO_REPARSE_TAG_WOF = 0x80000017
IO_REPARSE_TAG_WCI = 0x80000018
IO_REPARSE_TAG_WCI_1 = 0x90001018
IO_REPARSE_TAG_GLOBAL_REPARSE = 0xA0000019
IO_REPARSE_TAG_CLOUD = 0x9000001A
IO_REPARSE_TAG_CLOUD_1 = 0x9000101A
IO_REPARSE_TAG_CLOUD_2 = 0x9000201A
IO_REPARSE_TAG_CLOUD_3 = 0x9000301A
IO_REPARSE_TAG_CLOUD_4 = 0x9000401A
IO_REPARSE_TAG_CLOUD_5 = 0x9000501A
IO_REPARSE_TAG_CLOUD_6 = 0x9000601A
IO_REPARSE_TAG_CLOUD_7 = 0x9000701A
IO_REPARSE_TAG_CLOUD_8 = 0x9000801A
IO_REPARSE_TAG_CLOUD_9 = 0x9000901A
IO_REPARSE_TAG_CLOUD_A = 0x9000A01A
IO_REPARSE_TAG_CLOUD_B = 0x9000B01A
IO_REPARSE_TAG_CLOUD_C = 0x9000C01A
IO_REPARSE_TAG_CLOUD_D = 0x9000D01A
IO_REPARSE_TAG_CLOUD_E = 0x9000E01A
IO_REPARSE_TAG_CLOUD_F = 0x9000F01A
IO_REPARSE_TAG_CLOUD_MASK = 0x0000F000
IO_REPARSE_TAG_APPEXECLINK = 0x8000001B
IO_REPARSE_TAG_PROJFS = 0x9000001C
IO_REPARSE_TAG_LX_SYMLINK = 0xA000001D
IO_REPARSE_TAG_STORAGE_SYNC = 0x8000001E
IO_REPARSE_TAG_WCI_TOMBSTONE = 0xA000001F
IO_REPARSE_TAG_UNHANDLED = 0x80000020
IO_REPARSE_TAG_ONEDRIVE = 0x80000021
IO_REPARSE_TAG_PROJFS_TOMBSTONE = 0xA0000022
IO_REPARSE_TAG_AF_UNIX = 0x80000023
@staticmethod
def is_reparse_tag_microsoft(tag):
"""
Determine whether a reparse point tag corresponds to a tag owned by Microsoft.
:param tag: The reparse point tag.
:return: bool to indicate whether the tag is owned by Microsoft.
"""
return tag & 0x80000000 == 0x80000000
@staticmethod
def is_reparse_tag_name_surrogate(tag):
"""
Determine whether a reparse point tag is a name surrogate. A name surrogate means that the file or directory
with this reparse tag represents another named entity in the system, such as a mounted folder or symbolic link.
:param tag: The reparse point tag.
:return: bool to indicate whether the tag is a name surrogate.
"""
return tag & 0x20000000 == 0x20000000
@staticmethod
def is_reparse_tag_directory(tag):
"""
Determine whether a directory with this reparse point can have children.
:param tag: The reparse point tag.
:return: bool to indicate whether the directory with the tag can have children.
"""
return tag & 0x10000000 == 0x10000000
class SymbolicLinkFlags:
"""
[MS-FSCC] 2.1.2.4 Symbolic Link Reparse Data Buffer - Flags
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/b41f1cbf-10df-4a47-98d4-1c52a833d913
"""
SYMLINK_FLAG_ABSOLUTE = 0x00000000
SYMLINK_FLAG_RELATIVE = 0x00000001
class ReparseDataBuffer(Structure):
"""
[MS-FSCC] 2.1.2.2 REPARSE_DATA_BUFFER
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/c3a420cb-8a72-4adf-87e8-eee95379d78f
"""
def __init__(self):
self.fields = OrderedDict(
[
(
"reparse_tag",
EnumField(
size=4,
enum_type=ReparseTags,
enum_strict=False,
),
),
(
"reparse_data_length",
IntField(
size=2,
default=lambda s: len(s["data_buffer"]),
),
),
("reserved", IntField(size=2)),
("data_buffer", BytesField(size=lambda s: s["reparse_data_length"].get_value())),
]
)
super().__init__()
class SymbolicLinkReparseDataBuffer(Structure):
"""
[MS-FSCC] 2.1.2.4 Symbolic Link Reparse Data Buffer
https://docs.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/b41f1cbf-10df-4a47-98d4-1c52a833d913
Removes the reparse data buffer headings so it is just the data in the data_buffer field of ReparseDataBuffer.
"""
def __init__(self):
self.fields = OrderedDict(
[
("substitute_name_offset", IntField(size=2)),
("substitute_name_length", IntField(size=2)),
("print_name_offset", IntField(size=2)),
("print_name_length", IntField(size=2)),
(
"flags",
EnumField(
size=4,
enum_type=SymbolicLinkFlags,
),
),
(
"buffer",
BytesField(
size=lambda s: s["substitute_name_length"].get_value() + s["print_name_length"].get_value(),
),
),
]
)
super().__init__()
def get_substitute_name(self):
return self._get_name("substitute")
def get_print_name(self):
return self._get_name("print")
def set_name(self, substitute_name, print_name):
b_substitute_name = to_bytes(to_text(substitute_name), encoding="utf-16-le")
b_print_name = to_bytes(to_text(print_name), encoding="utf-16-le")
self["substitute_name_offset"] = 0
self["substitute_name_length"] = len(b_substitute_name)
self["print_name_offset"] = len(b_substitute_name)
self["print_name_length"] = len(b_print_name)
self["buffer"] = b_substitute_name + b_print_name
def resolve_link(self, path):
link_target = self.get_substitute_name()
if self["flags"].get_value() == SymbolicLinkFlags.SYMLINK_FLAG_ABSOLUTE:
# The substitute name could use the NT Path prefix \??\UNC\server\share or \??\C:\path which we strip off.
if link_target.startswith("\\??\\UNC\\"):
link_target = "\\\\" + link_target[8:]
elif link_target.startswith("\\??\\"):
link_target = link_target[4:]
else:
link_target = ntpath.join(ntpath.dirname(path), link_target)
return ntpath.abspath(link_target)
def _get_name(self, prefix):
offset = self[f"{prefix}_name_offset"].get_value()
length = self[f"{prefix}_name_length"].get_value()
b_name = self["buffer"].get_value()[offset : offset + length]
return to_text(b_name, encoding="utf-16-le")

View File

@@ -0,0 +1,399 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
import struct
from collections import OrderedDict
from smbprotocol.structure import (
BytesField,
EnumField,
FlagField,
IntField,
ListField,
Structure,
StructureField,
)
class AccessMask:
"""
[MS-DTYP]
2.4.3 ACCESS_MASK
32-bit set of flags that are used to encode the user rights to an object.
This is just a generic setup of access mask flags to set an can vary
from the object being set. When setting the AccessMask on an ACE packet,
any 32-bit value can be used and this is just as a guideline.
"""
GENERIC_READ = 0x80000000
GENERIC_WRITE = 0x40000000
GENERIC_EXECUTE = 0x20000000
GENERIC_ALL = 0x10000000
MAXIMUM_ALLOWED = 0x02000000
ACCESS_SYSTEM_SECURITY = 0x01000000
SYNCHRONIZE = 0x00100000
WRITE_OWNER = 0x00080000
WRITE_DACL = 0x00040000
READ_CONTROL = 0x00020000
DELETE = 0x00010000
class AceType:
"""
[MS-DTYP]
2.4.4.1 ACE_HEADER AceType
The type of ACE in the ACE packet.
"""
# Current only have structures for the first 3
ACCESS_ALLOWED_ACE_TYPE = 0x00
ACCESS_DENIED_ACE_TYPE = 0x01
SYSTEM_AUDIT_ACE_TYPE = 0x02
# No structures are defined for the below
SYSTEM_ALARM_ACE_TYPE = 0x03
ACCESS_ALLOWED_COMPOUND_ACE_TYPE = 0x04
ACCESS_ALLOWED_OBJECT_ACE_TYPE = 0x05
ACCESS_DENIED_OBJECT_ACE_TYPE = 0x06
SYSTEM_AUDIT_OBJECT_ACE_TYPE = 0x07
SYSTEM_ALARM_OBJECT_ACE_TYPE = 0x08
ACCESS_ALLOWED_CALLBACK_ACE_TYPE = 0x09
ACCESS_DENIED_CALLBACK_ACE_TYPE = 0x0A
ACCESS_ALLOWED_CALLBACK_OBJECT_ACE_TYPE = 0x0B
ACCESS_DENIED_CALLBACK_OBJECT_ACE_TYPE = 0x0C
SYSTEM_AUDIT_CALLBACK_ACE_TYPE = 0x0D
SYSTEM_ALARM_CALLBACK_ACE_TYPE = 0x0E
SYSTEM_AUDIT_CALLBACK_OBJECT_ACE_TYPE = 0x0F
SYSTEM_ALARM_CALLBACK_OBJECT_ACE_TYPE = 0x10
SYSTEM_MANDATORY_LABEL_ACE_TYPE = 0x11
SYSTEM_RESOURCE_ATTRIBUTE_ACE_TYPE = 0x12
SYSTEM_SCOPED_POLICY_ID_ACE_TYPE = 0x13
class AceFlags:
"""
[MS-DTYP]
2.4.4.1 ACE_HEADER AceFlags
Controls the ACE specified in the ACE packet.
"""
CONTAINER_INHERIT_ACE = 0x02
FAILED_ACCESS_ACE_FLAG = 0x80
INHERIT_ONLY_ACE = 0x08
INHERITED_ACE = 0x10
NO_PROPAGATE_INHERITY_ACE = 0x04
OBJECT_INHERIT_ACE = 0x01
SUCCESSFUL_ACCESS_ACE_FLAG = 0x40
class AclRevision:
"""
[MS-DTYP]
2.4.5 ACL AclRevision
ACL_REVISION - AceType 0, 1, 2, 3, 11, 12, 13 are valid
ACL_REVISION_DS - AceType 5, 6, 7, 8, 11 are valid (Directory Service)
"""
ACL_REVISION = 0x02
ACL_REVISION_DS = 0x04 # not natively supported yet
class SDControl:
"""
[MS-DTYP]
2.4.6 SECURITY_DESCRIPTOR Control
Specifies control access bit flags.
"""
SELF_RELATIVE = 0x8000
RM_CONTROL_VALID = 0x4000
SACL_PROTECTED = 0x2000
DACL_PROTECTED = 0x1000
SACL_AUTO_INHERITED = 0x0800
DACL_AUTO_INHERITED = 0x0400
SACL_COMPUTED_INHERITANCE_REQUIRED = 0x0200
DACL_COMPUTED_INHERITANCE_REQUIRED = 0x0100
SERVER_SECURITY = 0x0080
DACL_TRUSTED = 0x0040
SACL_DEFAULTED = 0x0020
SACL_PRESENT = 0x0010
DACL_DEFAULTED = 0x0008
DACL_PRESENT = 0x0004
GROUP_DEFAULTED = 0x0002
OWNER_DEFAULTED = 0x0001
NONE = 0x0000
class SIDPacket(Structure):
"""
[MS-DTYP] 2.4.2.2 SID--Packet Representation
The packet representation of the SID type for use by block protocols. While
the values can be set explicitly, it may be easier to use the from_string
function store the byte structure from the string format.
"""
def __init__(self):
self.fields = OrderedDict(
[
("revision", IntField(size=1, default=1)),
("sub_authority_count", IntField(size=1, default=lambda s: len(s["sub_authorities"].get_value()))),
("reserved", IntField(size=2)),
("identifier_authority", IntField(size=4, little_endian=False)),
(
"sub_authorities",
ListField(list_type=IntField(size=4), list_count=lambda s: s["sub_authority_count"].get_value()),
),
]
)
super().__init__()
def __str__(self):
revision = self["revision"].get_value()
id_authority = self["identifier_authority"].get_value()
sub_authorities = self["sub_authorities"].get_value()
authorities_string = "-".join(str(x) for x in sub_authorities)
sid_string = f"S-{revision}-{id_authority}-{authorities_string}"
return sid_string
def from_string(self, sid_string):
"""
Used to set the structure parameters based on the input string
:param sid_string: String of the sid in S-x-x-x-x form
"""
if not sid_string.startswith("S-"):
raise ValueError("A SID string must start with S-")
sid_entries = sid_string.split("-")
if len(sid_entries) < 3:
raise ValueError(
"A SID string must start with S and contain a revision and identifier authority, e.g. S-1-0"
)
revision = int(sid_entries[1])
id_authority = int(sid_entries[2])
sub_authorities = [int(i) for i in sid_entries[3:]]
self["revision"].set_value(revision)
self["identifier_authority"].set_value(id_authority)
self["sub_authorities"] = sub_authorities
class AccessAllowedAce(Structure):
"""
[MS-DTYP] 2.4.4.3 ACCESS_ALLOWED_ACE
Used for the DACL that controls access to an object.
"""
def __init__(self):
self.fields = OrderedDict(
[
("ace_type", EnumField(size=1, default=AceType.ACCESS_ALLOWED_ACE_TYPE, enum_type=AceType)),
("ace_flags", FlagField(size=1, flag_type=AceFlags)),
("ace_size", IntField(size=2, default=lambda s: 8 + len(s["sid"]))),
("mask", FlagField(size=4, flag_type=AccessMask, flag_strict=False)),
("sid", StructureField(structure_type=SIDPacket)),
]
)
super().__init__()
class AccessDeniedAce(Structure):
"""
[MS-DTYP] 2.4.4.4 ACCESS_DENIED_ACE
Used for the DACL that controls denies to an object.
"""
def __init__(self):
self.fields = OrderedDict(
[
("ace_type", EnumField(size=1, default=AceType.ACCESS_DENIED_ACE_TYPE, enum_type=AceType)),
("ace_flags", FlagField(size=1, flag_type=AceFlags)),
("ace_size", IntField(size=2, default=lambda s: 8 + len(s["sid"]))),
("mask", FlagField(size=4, flag_type=AccessMask, flag_strict=False)),
("sid", StructureField(structure_type=SIDPacket)),
]
)
super().__init__()
class SystemAuditAce(Structure):
"""
[MS-DTYP] 2.4.4.10 SYSTEM_AUDIT_ACE
Used for the SACL that specifies what types of access cause system-level
notifications.
"""
def __init__(self):
self.fields = OrderedDict(
[
("ace_type", EnumField(size=1, default=AceType.SYSTEM_AUDIT_ACE_TYPE, enum_type=AceType)),
("ace_flags", FlagField(size=1, flag_type=AceFlags)),
("ace_size", IntField(size=2, default=lambda s: 8 + len(s["sid"]))),
("mask", FlagField(size=4, flag_type=AccessMask, flag_strict=False)),
("sid", StructureField(structure_type=SIDPacket)),
]
)
super().__init__()
class AclPacket(Structure):
"""
[MS-DTYP] 2.4.5 ACL
Access Control List packet is used to specify a list of individual ACEs.
An ACL is said to be in canonical form if:
All explicit ACEs are placed before inherited ACEs
Within the explicit ACEs, deny ACEs come before grant ACEs
Deny ACEs on the object come before deny ACEs on a child or property
Grant ACEs on the object come before grant ACEs on a child or property
Inherited ACEs are placed in the order in which they were inherited
"""
def __init__(self):
self.fields = OrderedDict(
[
("acl_revision", EnumField(size=1, default=AclRevision.ACL_REVISION, enum_type=AclRevision)),
("sbz1", IntField(size=1)),
("acl_size", IntField(size=2, default=lambda s: 8 + len(s["aces"]))),
("ace_count", IntField(size=2, default=lambda s: len(s["aces"].get_value()))),
("sbz2", IntField(size=2)),
(
"aces",
ListField(
list_count=lambda s: s["ace_count"].get_value(),
unpack_func=AclPacket._unpack_aces,
),
),
]
)
super().__init__()
@staticmethod
def _unpack_aces(structure, data):
aces = []
while data != b"" and len(aces) < structure["ace_count"].value:
ace_type = struct.unpack("<B", data[:1])[0]
ace_struct = {
AceType.ACCESS_ALLOWED_ACE_TYPE: AccessAllowedAce(),
AceType.ACCESS_DENIED_ACE_TYPE: AccessDeniedAce(),
AceType.SYSTEM_AUDIT_ACE_TYPE: SystemAuditAce(),
}.get(ace_type, None)
if not ace_struct:
ace_size = struct.unpack("<H", data[2:4])[0]
aces.append(data[:ace_size])
data = data[ace_size:]
else:
ace_struct.unpack(data)
aces.append(ace_struct)
data = data[len(ace_struct) :]
return aces
class SMB2CreateSDBuffer(Structure):
"""
[MS-SMB2] 2.2.13.2.2 SMB2_CREATE_SD_BUFFER
[MS-DTYP] 2.4.6 SECURITY_DESCRIPTOR
Used to apply a security descriptor to a newly created file.
"""
def __init__(self):
self.fields = OrderedDict(
[
("revision", IntField(size=1, default=1)),
("sbz1", IntField(size=1)),
("control", FlagField(size=2, flag_type=SDControl)),
("offset_owner", IntField(size=4)),
("offset_group", IntField(size=4)),
("offset_sacl", IntField(size=4)),
("offset_dacl", IntField(size=4)),
# buffer contains owner_sid, owner_group, sacl and dacl at
# different offset, use get/set_* to get and set the individual
# components instead of touching the buffer directly
("buffer", BytesField()),
]
)
# used to store the buffer values so it can easily be rebuilt
self._buffer = OrderedDict()
super().__init__()
def get_owner(self):
return self._get_sid_from_buffer("offset_owner")
def set_owner(self, sid):
self._buffer["owner"] = sid
self._rebuild_buffer()
def get_group(self):
return self._get_sid_from_buffer("offset_group")
def set_group(self, sid):
self._buffer["group"] = sid
self._rebuild_buffer()
def get_sacl(self):
return self._get_acl_from_buffer("offset_sacl", SDControl.SACL_PRESENT)
def set_sacl(self, acl):
if acl:
self["control"].set_flag(SDControl.SACL_PRESENT)
self._buffer["sacl"] = acl
self._rebuild_buffer()
def get_dacl(self):
return self._get_acl_from_buffer("offset_dacl", SDControl.DACL_PRESENT)
def set_dacl(self, acl):
if acl:
self["control"].set_flag(SDControl.DACL_PRESENT)
self._buffer["dacl"] = acl
self._rebuild_buffer()
def _get_sid_from_buffer(self, offset_field):
offset = self[offset_field].get_value()
if offset == 0:
return None
buffer_data = self["buffer"].get_value()[offset - 20 :]
sid = SIDPacket()
sid.unpack(buffer_data)
return sid
def _get_acl_from_buffer(self, offset_field, flag):
if not self["control"].has_flag(flag):
return None
offset = self[offset_field].get_value() - 20
buffer_data = self["buffer"].get_value()[offset:]
length = struct.unpack("<H", buffer_data[2:4])[0]
data = buffer_data[:length]
acl = AclPacket()
acl.unpack(data)
return acl
def _rebuild_buffer(self):
buffer = b""
offset_count = 20
for field, value in self._buffer.items():
if not value:
continue
offset_field = f"offset_{field}"
field_bytes = value.pack()
buffer += field_bytes
self[offset_field].set_value(offset_count)
offset_count += len(field_bytes)
self["buffer"].set_value(buffer)

View File

@@ -0,0 +1,463 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
import hashlib
import logging
from collections import OrderedDict
from typing import Literal, Optional
import spnego
from cryptography.hazmat.backends import default_backend
from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.kdf.kbkdf import KBKDFHMAC, CounterLocation, Mode
from smbprotocol import Dialects
from smbprotocol.connection import Capabilities, Ciphers, SecurityMode
from smbprotocol.exceptions import (
MoreProcessingRequired,
SMBAuthenticationError,
SMBException,
)
from smbprotocol.header import Commands, NtStatus
from smbprotocol.structure import BytesField, EnumField, FlagField, IntField, Structure
log = logging.getLogger(__name__)
class SessionFlags:
"""
[MS-SMB2] v53.0 2017-09-15
2.2.6 SMB2 SESSION_SETUP Response Flags
Flags the indicates additional information about the session.
"""
SMB2_SESSION_FLAG_IS_GUEST = 0x0001
SMB2_SESSION_FLAG_IS_NULL = 0x0002
SMB2_SESSION_FLAG_ENCRYPT_DATA = 0x0004
class SMB2SessionSetupRequest(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.5 SMB2 SESSION_SETUP Request
The SMB2 SESSION_SETUP Request packet is sent by the client to request a
new authenticated session within a new or existing SMB 2 connection.
"""
COMMAND = Commands.SMB2_SESSION_SETUP
def __init__(self):
self.fields = OrderedDict(
[
(
"structure_size",
IntField(
size=2,
default=25,
),
),
("flags", IntField(size=1)),
(
"security_mode",
EnumField(
size=1,
enum_type=SecurityMode,
),
),
(
"capabilities",
FlagField(
size=4,
flag_type=Capabilities,
),
),
("channel", IntField(size=4)),
(
"security_buffer_offset",
IntField(
size=2,
default=88, # (header size 64) + (response size 24)
),
),
(
"security_buffer_length",
IntField(
size=2,
default=lambda s: len(s["buffer"]),
),
),
("previous_session_id", IntField(size=8)),
(
"buffer",
BytesField(
size=lambda s: s["security_buffer_length"].get_value(),
),
),
]
)
super().__init__()
class SMB2SessionSetupResponse(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.6 SMB2 SESSION_SETUP Response
The SMB2 SESSION_SETUP Response packet is sent by the server in response to
an SMB2 SESSION_SETUP Request.
"""
COMMAND = Commands.SMB2_SESSION_SETUP
def __init__(self):
self.fields = OrderedDict(
[
(
"structure_size",
IntField(
size=2,
default=9,
),
),
(
"session_flags",
FlagField(
size=2,
flag_type=SessionFlags,
),
),
(
"security_buffer_offset",
IntField(
size=2,
default=72, # (header size 64) + (response size 8)
),
),
(
"security_buffer_length",
IntField(
size=2,
default=lambda s: len(s["buffer"]),
),
),
(
"buffer",
BytesField(
size=lambda s: s["security_buffer_length"].get_value(),
),
),
]
)
super().__init__()
class SMB2Logoff(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.7/8 SMB2 LOGOFF Request/Response
Request and response to request the termination of a particular session as
specified by the header.
"""
COMMAND = Commands.SMB2_LOGOFF
def __init__(self):
self.fields = OrderedDict([("structure_size", IntField(size=2, default=4)), ("reserved", IntField(size=2))])
super().__init__()
class Session:
def __init__(
self,
connection,
username: Optional[str] = None,
password: Optional[str] = None,
require_encryption=True,
hostname_override=None,
auth_protocol: Literal["negotiate", "ntlm", "kerberos"] = "negotiate",
):
"""
[MS-SMB2] v53.0 2017-09-15
3.2.1.3 Per Session
The Session object that is used to store the details for an
authenticated SMB session. There are 4 forms of authentication that are
supported;
1. SSPI Auth, Windows only if pywin32 is installed. Uses either
Kerberos or NTLM auth depending on the environment setup and can
use the current user's credentials if none are provided here.
2. NTLM Auth, requires the username and password
3. Kerberos Auth, only available in certain circumstances
4. Guest Auth, the credentials were rejected but the server allows a
fallback to guest authentication (insecure and non-default)
NTLM Auth is the fallback as it should be available in most scenarios
while Kerberos only works on a system where python-gssapi is installed
and the GGF extension for inquire_sec_context_by_oid is available
(Linux), or pywin32 is installed (Windows).
If using Kerberos Auth, the username and password can be omitted which
means the default user kerb ticket (if available) is used. If the
username is specified and not the password then it will get the kerb
ticket for the principal specified (kinit must be used to get this
ticket beforehand). If both the user and password are specified then
it will get a ticket for the user instead of relying on the default
store.
If guest auth was negotiated based on a bad credential then signing
and encryption is not allowed, for this to ultimately work the user
must set require_signing=False when creating the Connection and
require_encryption=False when creating the Session.
:param connection: The Connection object that the session will use
:param username: The username of the user to authenticate with
:param password: The password of the user to authenticate with
:param require_encryption: Whether any messages sent over the session
require encryption regardless of the server settings (Dialects 3+),
needs to be set to False for older dialects.
:param hostname_override: Specifies hostname context for Kerberos
authentication when given IP address to the connection context.
:param auth_protocol: The protocol to use for authentication. Possible
values are 'negotiate', 'ntlm' or 'kerberos'. Defaults to
'negotiate'.
"""
log.info("Initialising session with username: %s", username)
self._connected = False
self.session_id = 0
self.require_encryption = require_encryption
# Table of tree connection, lookup by TreeConnect.tree_connect_id and
# by share_name
self.tree_connect_table = {}
# First 16 bytes of the cryptographic key for this authenticated
# context, right-padded with 0 bytes
self.session_key = None
self.signing_required = connection.require_signing
self.connection = connection
self.username = username
self.password = password
self._hostname_override = hostname_override
# No need to validate this as the spnego library will raise a ValueError
self.auth_protocol = auth_protocol
# Table of OpenFile, lookup by OpenFile.file_id
self.open_table = {}
# SMB 3.x+
# List of Channel
self.channel_list = []
# 16-bit identifier incremented on a network disconnect that indicates
# to the server the client's Channel change
self.channel_sequence = None
self.encrypt_data = None
self.encryption_key = None
self.decryption_key = None
self.signing_key = None
self.application_key = None
self.full_session_key = None
# SMB 3.1.1+
# Preauth integrity value computed for the exhange of SMB2
# SESSION_SETUP request and response for this session
self.preauth_integrity_hash_value = []
def connect(self):
log.debug("Decoding SPNEGO token containing supported auth mechanisms")
try:
context = spnego.client(
self.username,
self.password,
service="cifs",
hostname=self._hostname_override or self.connection.server_name,
options=spnego.NegotiateOptions.session_key,
protocol=self.auth_protocol,
)
except spnego.exceptions.SpnegoError as err:
raise SMBAuthenticationError(f"Failed to authenticate with server: {err}") from err
in_token = self.connection.gss_negotiate_token
if self.auth_protocol != "negotiate":
in_token = None # The GSS Negotiate Token can only be used for Negotiate auth.
while not context.complete:
try:
out_token = context.step(in_token)
except spnego.exceptions.SpnegoError as err:
raise SMBAuthenticationError(f"Failed to authenticate with server: {err}") from err
if not out_token:
break
session_setup = SMB2SessionSetupRequest()
session_setup["capabilities"] = Capabilities.SMB2_GLOBAL_CAP_DFS
session_setup["security_mode"] = self.connection.client_security_mode
session_setup["buffer"] = out_token
log.info("Sending SMB2_SESSION_SETUP request message")
request = self.connection.send(session_setup, sid=self.session_id, credit_request=64)
request_id = request.message["message_id"].get_value()
log.info("Receiving SMB2_SESSION_SETUP response message")
try:
response = self.connection.receive(request)
except MoreProcessingRequired as exc:
response = exc.header
request_preauth = self.connection.preauth_integrity_session_hash_value.pop(request_id)
self.preauth_integrity_hash_value += request_preauth
# If this is the first time we received the actual session_id,
# record the returned id.
session_id = response["session_id"].get_value()
if self.session_id == 0 and session_id:
self.session_id = session_id
setup_response = SMB2SessionSetupResponse()
setup_response.unpack(response["data"].get_value())
in_token = setup_response["buffer"].get_value()
status = response["status"].get_value()
if status == NtStatus.STATUS_MORE_PROCESSING_REQUIRED:
log.info("More processing is required for SMB2_SESSION_SETUP")
log.info("Setting session id to %s", self.session_id)
self._connected = True
# Move the session from the preauth table to the actual session table.
self.connection.session_table[self.session_id] = self
# session_key is the first 16 bytes, padded 0 if less than 16
self.full_session_key = context.session_key
self.session_key = self.full_session_key[:16].ljust(16, b"\x00")
if self.connection.dialect >= Dialects.SMB_3_1_1:
preauth_hash = b"\x00" * 64
for hash_list in [self.connection.preauth_integrity_hash_value, self.preauth_integrity_hash_value]:
for message in hash_list:
# Technically the algo is based on preauth_integrity_hash_id but we only support the 1
preauth_hash = hashlib.sha512(preauth_hash + message).digest()
self.signing_key = self._smb3kdf(self.session_key, b"SMBSigningKey\x00", preauth_hash)
self.application_key = self._smb3kdf(self.session_key, b"SMBAppKey\x00", preauth_hash)
if self.connection.cipher_id in [
Ciphers.AES_256_CCM,
Ciphers.AES_256_GCM,
]:
key_length = 32
key = self.full_session_key
else:
key_length = 16
key = self.session_key
self.encryption_key = self._smb3kdf(key, b"SMBC2SCipherKey\x00", preauth_hash, length=key_length)
self.decryption_key = self._smb3kdf(key, b"SMBS2CCipherKey\x00", preauth_hash, length=key_length)
elif self.connection.dialect >= Dialects.SMB_3_0_0:
self.signing_key = self._smb3kdf(self.session_key, b"SMB2AESCMAC\x00", b"SmbSign\x00")
self.application_key = self._smb3kdf(self.session_key, b"SMB2APP\x00", b"SmbRpc\x00")
self.encryption_key = self._smb3kdf(self.session_key, b"SMB2AESCCM\x00", b"ServerIn \x00")
self.decryption_key = self._smb3kdf(self.session_key, b"SMB2AESCCM\x00", b"ServerOut\x00")
else:
self.signing_key = self.session_key
self.application_key = self.session_key
flags = setup_response["session_flags"]
if flags.has_flag(SessionFlags.SMB2_SESSION_FLAG_ENCRYPT_DATA) or self.require_encryption:
# make sure the connection actually supports encryption
if not self.connection.supports_encryption:
raise SMBException("SMB encryption is required but the connection does not support it")
self.encrypt_data = True
self.signing_required = False # encryption covers signing
else:
self.encrypt_data = False
if flags.has_flag(SessionFlags.SMB2_SESSION_FLAG_IS_GUEST) or flags.has_flag(
SessionFlags.SMB2_SESSION_FLAG_IS_NULL
):
self.session_key = None
self.signing_key = None
self.application_key = None
self.encryption_key = None
self.decryption_key = None
if self.signing_required or self.encrypt_data:
self.session_id = None
raise SMBException(
"SMB encryption or signing was required but session was authenticated as a guest "
"which does not support encryption or signing"
)
if self.signing_required:
log.info("Verifying the SMB Setup Session signature as auth is successful")
self.connection.verify_signature(response, self.session_id, force=True)
def disconnect(self, close=True, timeout=None):
"""
Logs off the session
:param close: Will close all tree connects in a session
"""
if not self._connected:
# already disconnected so let's return
return
if close:
for open in list(self.open_table.values()):
open.close(False)
for tree in list(self.tree_connect_table.values()):
tree.disconnect()
log.info("Session: %s - Logging off of SMB Session", self.username)
logoff = SMB2Logoff()
log.info("Session: %s - Sending Logoff message", self.username)
log.debug(logoff)
request = self.connection.send(logoff, sid=self.session_id)
log.info("Session: %s - Receiving Logoff response", self.username)
res = self.connection.receive(request, timeout=timeout)
res_logoff = SMB2Logoff()
res_logoff.unpack(res["data"].get_value())
log.debug(res_logoff)
self._connected = False
del self.connection.session_table[self.session_id]
def _smb3kdf(self, ki, label, context, length=16):
"""
See SMB 3.x key derivation function
https://blogs.msdn.microsoft.com/openspecification/2017/05/26/smb-2-and-smb-3-security-in-windows-10-the-anatomy-of-signing-and-cryptographic-keys/
:param ki: The session key is the KDK used as an input to the KDF
:param label: The purpose of this derived key as bytes string
:param context: The context information of this derived key as bytes
:param length: The length of the key to generate
string
:return: Key derived by the KDF as specified by [SP800-108] 5.1
"""
kdf = KBKDFHMAC(
algorithm=hashes.SHA256(),
mode=Mode.CounterMode,
length=length,
rlen=4,
llen=4,
location=CounterLocation.BeforeFixed,
label=label,
context=context,
fixed=None,
backend=default_backend(),
)
return kdf.derive(ki)

View File

@@ -0,0 +1,898 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
import copy
import datetime
import inspect
import math
import struct
import textwrap
import types
import uuid
import weakref
from abc import ABCMeta, abstractmethod
from binascii import hexlify
from smbprotocol._text import to_bytes, to_text
TAB = " " # Instead of displaying a tab on the print, use 4 spaces
class InvalidFieldDefinition(Exception):
pass
def _bytes_to_hex(bytes, pretty=False, hex_per_line=8):
hex = to_text(hexlify(bytes))
if pretty:
if hex_per_line == 0: # show hex on 1 line
hex_list = [hex]
else:
idx = hex_per_line * 2
hex_list = list(hex[i : i + idx] for i in range(0, len(hex), idx))
hexes = []
for h in hex_list:
hexes.append(" ".join(h[i : i + 2] for i in range(0, len(h), 2)).upper())
hex = "\n".join(hexes)
return hex
def _indent_lines(string, prefix):
# Would use textwrap.indent for this but it is not available for Python 2
def predicate(line):
return line.strip()
lines = []
for line in string.splitlines(True):
lines.append(prefix + line if predicate(line) else line)
return "".join(lines)
class Structure:
def __init__(self):
# Now that self.fields is set, loop through it again and set the
# metadata around the fields and set the value based on default.
# This must be done outside of the OrderedDict definition as set_value
# relies on the full structure (self) being available and error
# messages use the field name to be helpful
for name, field in self.fields.items():
field.structure = weakref.proxy(self)
field.name = name
field.set_value(field.default)
def __str__(self):
struct_name = self.__class__.__name__
raw_hex = _bytes_to_hex(self.pack(), True, hex_per_line=0)
field_strings = []
for name, field in self.fields.items():
# the field header is slightly different for a StructureField
# remove the leading space and put the value on the next line
if isinstance(field, StructureField):
field_string = f"{field.name} =\n{field}"
else:
field_string = f"{field.name} = {field}"
field_strings.append(_indent_lines(field_string, TAB))
field_strings.append("")
field_strings.append(_indent_lines("Raw Hex:", TAB))
hex_wrapper = textwrap.TextWrapper(
width=33, # set to show 8 hex values per line, 33 for 8, 56 for 16
initial_indent=TAB + TAB,
subsequent_indent=TAB + TAB,
)
field_strings.append(hex_wrapper.fill(raw_hex))
struct_name = to_text(struct_name)
field_names = "\n".join([to_text(s) for s in field_strings])
string = f"{struct_name}:\n{field_names}"
return string
def __setitem__(self, key, value):
field = self._get_field(key)
field.set_value(value)
def __getitem__(self, key):
return self._get_field(key)
def __delitem__(self, key):
self._get_field(key)
del self.fields[key]
def __len__(self):
length = 0
for field in self.fields.values():
length += len(field)
return length
def pack(self):
data = b""
for field in self.fields.values():
field_data = field.pack()
data += field_data
return data
def unpack(self, data):
mem = memoryview(data)
for key, field in self.fields.items():
mem = field.unpack(mem)
return bytes(mem) # remaining data
def _get_field(self, key):
field = self.fields.get(key, None)
if field is None:
raise ValueError(f"Structure does not contain field {key}")
return field
class Field(metaclass=ABCMeta):
def __init__(self, little_endian=True, default=None, size=None):
"""
The base class of a Field object. This contains the framework that a
field SHOULD implement in regards to packing and unpacking a value.
There should be little need to call this particular object as it is
designed to be a base class for *Type classes.
:param little_endian: When converting an int/uuid to bytes, the byte
order to pack as, False means it will be big endian
:param default: The default value of the field, this can be any
supported value such as as well as a lambda function or None
(default).
:param size: The size of the field, this can be an int, lambda function
or None (for variable length end field) unless overridden in Class
definition.
"""
field_type = self.__class__.__name__
self.little_endian = little_endian
if not (size is None or isinstance(size, int) or callable(size)):
raise InvalidFieldDefinition(f"{field_type} size for field must be an int or None for a variable length")
self.size = size
self.default = default
self.value = None
def __str__(self):
return self._to_string()
def __len__(self):
return self._get_packed_size()
@property
def _endian_prefix(self):
return "<" if self.little_endian else ">"
def pack(self):
"""
Packs the field value into a byte string so it can be sent to the
server.
:param structure: The message structure class object
:return: A byte string of the packed field's value
"""
value = self._get_calculated_value(self.value)
packed_value = self._pack_value(value)
size = self._get_calculated_size(self.size, packed_value)
packed_value_len = len(packed_value)
if packed_value_len != size:
raise ValueError(
f"Invalid packed data length for field {self.name} of {packed_value_len} "
f"does not fit field size of {size}"
)
return packed_value
def get_value(self):
"""
Returns the value set for the field, will run any lambda functions
that is set under the value attribute and return the final value.
:return: The value attribute with lambda functions run if value is a
lambda function
"""
return self._get_calculated_value(self.value)
def set_value(self, value):
"""
Parses, and sets the value attribute for the field.
:param value: The value to be parsed and set, the allowed input types
vary depending on the Field used
"""
if isinstance(value, memoryview):
value = bytes(value)
parsed_value = self._parse_value(value)
self.value = parsed_value
def unpack(self, data):
"""
Takes in a byte string and set's the field value based on field
definition.
:param structure: The message structure class object
:param data: The byte string of the data to unpack
:return: The remaining data for subsequent fields
"""
size = self._get_calculated_size(self.size, data)
self.set_value(data[0:size])
return data[len(self) :]
@abstractmethod
def _pack_value(self, value):
"""
Packs the value passed in according to the rules of the FieldType.
:param value: The value to be packed, this is derived by
_get_calculated_value(self.value)
:return: A byte string of the data once packed
"""
pass # pragma: no cover
@abstractmethod
def _parse_value(self, value):
"""
Parses the value into the FieldType type, this also validates that
the value is allowable by the FieldType.
:param value: The value to parse
:return: The value that has been parsed/casted to the correct value
"""
pass # pragma: no cover
@abstractmethod
def _get_packed_size(self):
"""
Get's the size of the data once it has been packed. Depending on the
FieldType, this can either be pre-set or calculated when called.
:return: The size of the field once it is packed
"""
pass # pragma: no cover
@abstractmethod
def _to_string(self):
"""
Creates a string which is a human readable representation of the value.
The output is dependent on the field implementation.
:return: string of the field value
"""
# creates a string which is a friendly representation of the value
pass # pragma: no cover
def _get_calculated_value(self, value):
"""
Get's the final value of the field and runs the lambda functions
recursively until a final value is derived.
:param value: The value to calculate/expand
:return: The final value
"""
if callable(value):
expanded_value = value(self.structure)
return self._get_calculated_value(expanded_value)
else:
# perform one final parsing of the value in case lambda value
# returned a different type
return self._parse_value(value)
def _get_calculated_size(self, size, data):
"""
Get's the final size of the field and runs the lambda functions
recursively until a final size is derived. If size is None then it
will just return the length of the data as it is assumed it is the
final field (None should only be set on size for the final field).
:param size: The size to calculate/expand
:param data: The data that the size is being calculated for
:return: The final size
"""
# if the size is derived from a lambda function, run it now; otherwise
# return the value we passed in or the length of the data if the size
# is None (last field value)
if size is None:
return len(data)
elif callable(size):
expanded_size = size(self.structure)
return self._get_calculated_size(expanded_size, data)
else:
return size
def _get_struct_format(self, size, unsigned=True):
"""
Get's the format specified for use in struct. This is only designed
for 1, 2, 4, or 8 byte values and will throw an exception if it is
anything else.
:param size: The size as an int
:return: The struct format specifier for the size specified
"""
if callable(size):
size = size(self.structure)
struct_format = {1: "B", 2: "H", 4: "L", 8: "Q"}
if size not in struct_format.keys():
raise InvalidFieldDefinition(f"Cannot struct format of size {size}")
format_char = struct_format[size]
if not unsigned:
format_char = format_char.lower()
return format_char
class IntField(Field):
def __init__(self, size, unsigned=True, **kwargs):
"""
Used to store an int value for a field. The size for these values MUST
be 1, 2, 4, or 8 and if another size is required use the BytesField
instead and store the values as bytes.
:param size: The size of the integer when packed
:param kwargs: Any other kwarg to be sent to Field()
"""
if size not in [1, 2, 4, 8]:
raise InvalidFieldDefinition(f"IntField size must have a value of 1, 2, 4, or 8 not {size}")
self.unsigned = unsigned
super().__init__(size=size, **kwargs)
def _pack_value(self, value):
struct_string = self._endian_prefix + self._get_struct_format(self.size, self.unsigned)
packed_int = struct.pack(struct_string, value)
return packed_int
def _parse_value(self, value):
if value is None:
int_value = 0
elif callable(value):
int_value = value
elif isinstance(value, bytes):
struct_string = self._endian_prefix + self._get_struct_format(self.size, self.unsigned)
int_value = struct.unpack(struct_string, value)[0]
elif isinstance(value, int):
int_value = value
else:
raise TypeError(f"Cannot parse value for field {self.name} of type {type(value).__name__} to an int")
return int_value
def _get_packed_size(self):
return self.size
def _to_string(self):
return str(self._get_calculated_value(self.value))
class BytesField(Field):
"""
Used to store a raw bytes value as a field. Is the most universal and can
convert from most objects to a bytes string. Use this is the field can
contain multiple values and parsing will be done outside of the class.
"""
def _pack_value(self, value):
return value
def _parse_value(self, value):
if value is None:
bytes_value = b""
elif callable(value):
bytes_value = value
elif isinstance(value, int):
struct_string = self._endian_prefix + self._get_struct_format(self.size)
bytes_value = struct.pack(struct_string, value)
elif isinstance(value, Structure):
bytes_value = value.pack()
elif isinstance(value, bytes):
bytes_value = value
else:
raise TypeError(f"Cannot parse value for field {self.name} of type {type(value).__name__} to a byte string")
return bytes_value
def _get_packed_size(self):
bytes_value = self._get_calculated_value(self.value)
return len(bytes_value)
def _to_string(self):
bytes_value = self._get_calculated_value(self.value)
return _bytes_to_hex(bytes_value, pretty=True, hex_per_line=0)
class ListField(Field):
def __init__(self, list_count=None, list_type=BytesField(), unpack_func=None, **kwargs):
"""
Used to store a list of values that are the same time, the list can
contain both fixed length values or variable length values but the
former is easier to use as it does not require lambda functions to
unpack the values. If the list values are different types, then the
BytesField list_type should be used and the data will automatically
will be converted to a bytes object. If appending a value to the list,
ensure the value it added as an actual *Field() object and not just
the raw value.
:param list_count: The number of entries in the list, the value can be
an int, lambda function or None (for variable length). The lambda
function is only evaluated in the pack and unpack methods. This
must be set if unpack_func is not set so it can unpack the data
receved from the server.
:param list_type: The *Field() definition for each list entry, defaults
to a variable length BytesField. If unpack_func is not set, the
size attribute must be set.
:param unpack_func: A lambda function used during the unpack method to
unpack the data received from the server to a list. It takes in the
(structure, data) arguments which is the structure of the whole
packet and the remaining data left to be unpacked. This MUST be
used when the list contains variable length values.
:param kwargs: Any other kwarg to be sent to Field()
"""
if list_count is not None and not (isinstance(list_count, int) or callable(list_count)):
raise InvalidFieldDefinition(
"ListField list_count must be an int, lambda, or None for a variable list length"
)
self.list_count = list_count
if not isinstance(list_type, Field):
raise InvalidFieldDefinition("ListField list_type must be a Field definition")
self.list_type = list_type
if unpack_func is not None and not callable(unpack_func):
raise InvalidFieldDefinition("ListField unpack_func must be a lambda function or None")
elif unpack_func is None and (list_count is None or list_type.size is None):
raise InvalidFieldDefinition(
"ListField must either define "
"unpack_func as a lambda or set "
"list_count and list_size with a "
"size"
)
self.unpack_func = unpack_func
super().__init__(**kwargs)
def __getitem__(self, item):
# TODO: Make this more efficient
return self.get_value()[item]
def get_value(self):
# Override default get_value() so we return a list with the actual
# value, not the Field definition
list_value = []
if callable(self.value):
value = self._get_calculated_value(self.value)
else:
value = self.value
for entry in value:
list_value.append(entry.get_value())
return list_value
def _pack_value(self, value):
data = b""
for value in list(value):
data += value.pack()
return data
def _parse_value(self, value):
if value is None:
list_value = []
elif callable(value):
return value
elif isinstance(value, bytes) and callable(self.unpack_func):
# use the lambda function to parse the bytes to a list
list_value = self.unpack_func(self.structure, value)
elif isinstance(value, bytes):
# we have a fixed length array with a specified count
list_value = self._create_list_from_bytes(self.list_count, self.list_type, value)
elif isinstance(value, list):
# manually parse each list entry to the field type specified
list_value = value
else:
raise TypeError(f"Cannot parse value for field {self.name} of type {type(value).__name__} to a list")
list_value = [self._parse_sub_value(v) for v in list_value]
return list_value
def _parse_sub_value(self, value):
if isinstance(value, Field):
new_field = value
elif isinstance(value, Structure):
new_field = StructureField(
size=len(value),
structure_type=type(value),
default=value,
)
new_field.name = f"{self.name} list entry"
new_field.structure = value
new_field.set_value(new_field.default)
else:
new_field = copy.deepcopy(self.list_type)
new_field.name = f"{self.name} list entry"
new_field.set_value(value)
return new_field
def _get_packed_size(self):
list_value = self._get_calculated_value(self.value)
size = 0
for field in list(list_value):
size += len(field)
return size
def _to_string(self):
list_value = self._get_calculated_value(self.value)
list_string = [_indent_lines(str(v), TAB) for v in list(list_value)]
if len(list_string) == 0:
string = "[]"
else:
list_str = ",\n".join(list_string)
string = f"[\n{list_str}\n]"
return string
def _create_list_from_bytes(self, list_count, list_type, value):
# calculate the list_count and rerun method if a lambda
if callable(list_count):
list_count = list_count(self.structure)
return self._create_list_from_bytes(list_count, list_type, value)
list_value = []
for idx in range(0, list_count):
new_field = copy.deepcopy(list_type)
value = new_field.unpack(value)
list_value.append(new_field)
return list_value
class StructureField(Field):
def __init__(self, structure_type, **kwargs):
"""
Used to store a message packet Structure object as a field. Can store
both an actual Structure value or a byte string.
:param structure_type: The message structure type, e.g.
SMB2NegotiateRequest. Used to marshal a byte string to a structure
object when unpacking or setting a value
:param kwargs: Any other kwarg to be sent to Field()
"""
self.structure_type = structure_type
super().__init__(**kwargs)
def __setitem__(self, key, value):
field = self._get_field(key)
field.set_value(value)
def __getitem__(self, key):
return self._get_field(key)
def set_structure_type(self, structure_type):
# Set's the structure type and convert a byte string to the actual
# structure specified
self.structure_type = structure_type
self.set_value(self.value)
def _pack_value(self, value):
# Can either be a Structure or just plain bytes, just pack the
# structure if needed
if isinstance(value, Structure):
value = value.pack()
return value
def _parse_value(self, value):
if value is None:
structure_value = b""
elif callable(value):
structure_value = value
elif isinstance(value, bytes):
structure_value = value
elif isinstance(value, Structure):
structure_value = value
else:
raise TypeError(f"Cannot parse value for field {self.name} of type {type(value).__name__} to a structure")
if isinstance(structure_value, bytes) and self.structure_type and structure_value != b"":
if callable(self.structure_type) and not inspect.isclass(self.structure_type):
structure_type = self.structure_type(self.structure)
else:
structure_type = self.structure_type
structure = structure_type()
structure.unpack(structure_value)
structure_value = structure
return structure_value
def _get_packed_size(self):
structure_value = self._get_calculated_value(self.value)
return len(structure_value)
def _to_string(self):
structure_value = self._get_calculated_value(self.value)
return str(structure_value)
def _get_field(self, key):
structure_value = self._get_calculated_value(self.value)
if isinstance(structure_value, bytes):
raise ValueError(f"Cannot get field {key} when structure is defined as a byte string")
field = structure_value._get_field(key)
return field
class DateTimeField(Field):
EPOCH_FILETIME = 116444736000000000 # epoch as a MS FILETIME int
def __init__(self, size=None, **kwargs):
"""
[MS-DTYP] 0.0 2017-09-15
2.3.3 FILETIME
The FILETIME structure is a 64-it value that represents the number of
100 nanoseconds intervals that have elapsed since January 1, 1601 UTC.
This is used to convert the FILETIME int value to a native Python
datetime object.
While the format FILETIME is used when communicating with the server,
this type allows Python code to interact with datetime objects natively
with all the conversions handled at pack/unpack time.
:param size: Must be set to None or 8, this is so we can check/override
:param kwargs: Any other kwarg to be sent to Field()
"""
if not (size is None or size == 8):
raise InvalidFieldDefinition(f"DateTimeField type must have a size of 8 not {size}")
super().__init__(size=8, **kwargs)
def _pack_value(self, value):
utc_tz = datetime.timezone.utc
utc_dt = value.replace(tzinfo=value.tzinfo if value.tzinfo else utc_tz)
td = utc_dt.astimezone(utc_tz) - datetime.datetime(1970, 1, 1, 0, 0, 0, tzinfo=utc_tz)
epoch_time_ms = td.microseconds + (td.seconds + td.days * 24 * 3600) * 10**6
ns100 = self.EPOCH_FILETIME + (epoch_time_ms * 10)
struct_string = self._endian_prefix + self._get_struct_format(8)
bytes_value = struct.pack(struct_string, ns100)
return bytes_value
def _parse_value(self, value):
if value is None:
datetime_value = datetime.datetime.today()
elif callable(value):
datetime_value = value
elif isinstance(value, bytes):
struct_string = self._endian_prefix + self._get_struct_format(8)
int_value = struct.unpack(struct_string, value)[0]
return self._parse_value(int_value) # just parse the value again
elif isinstance(value, int):
time_microseconds = (value - self.EPOCH_FILETIME) // 10
try:
datetime_value = datetime.datetime(
year=1970,
month=1,
day=1,
tzinfo=datetime.timezone.utc,
) + datetime.timedelta(microseconds=time_microseconds)
except OverflowError:
# This is unfortunately but 9999 is the max value a datetime can be so we just default to that
datetime_value = datetime.datetime.max
elif isinstance(value, datetime.datetime):
datetime_value = value
else:
raise TypeError(f"Cannot parse value for field {self.name} of type {type(value).__name__} to a datetime")
return datetime_value
def _get_packed_size(self):
return self.size
def _to_string(self):
datetime_value = self._get_calculated_value(self.value)
return datetime_value.isoformat(" ")
class UuidField(Field):
def __init__(self, size=None, **kwargs):
"""
Used to store a UUID (GUID) as a Python UUID object.
:param size: Must be set to None or 16, this is so we can
check/override
:param kwargs: Any other kwarg to be sent to Field()
"""
if not (size is None or size == 16):
raise InvalidFieldDefinition(f"UuidField type must have a size of 16 not {size}")
super().__init__(size=16, **kwargs)
def _pack_value(self, value):
if self.little_endian:
return value.bytes
else:
return value.bytes_le
def _parse_value(self, value):
if value is None:
uuid_value = uuid.UUID(bytes=b"\x00" * 16)
elif isinstance(value, bytes) and self.little_endian:
uuid_value = uuid.UUID(bytes=value)
elif isinstance(value, bytes) and not self.little_endian:
uuid_value = uuid.UUID(bytes_le=value)
elif isinstance(value, int):
uuid_value = uuid.UUID(int=value)
elif isinstance(value, uuid.UUID):
uuid_value = value
elif callable(value):
uuid_value = value
else:
raise TypeError(f"Cannot parse value for field {self.name} of type {type(value).__name__} to a uuid")
return uuid_value
def _get_packed_size(self):
return self.size
def _to_string(self):
uuid_value = self._get_calculated_value(self.value)
return str(uuid_value)
class EnumField(IntField):
def __init__(self, enum_type, enum_strict=True, **kwargs):
self.enum_type = enum_type
self.enum_strict = enum_strict
super().__init__(**kwargs)
def _parse_value(self, value):
int_value = super()._parse_value(value)
valid = False
for flag_value in vars(self.enum_type).values():
if int_value == flag_value:
valid = True
break
if not valid and int_value != 0 and self.enum_strict:
raise ValueError(f"Enum value {int_value} does not exist in enum type {self.enum_type}")
return int_value
def _to_string(self):
enum_name = None
value = self._get_calculated_value(self.value)
for enum, enum_value in vars(self.enum_type).items():
if value == enum_value:
enum_name = enum
break
if enum_name is None:
return f"({value}) UNKNOWN_ENUM"
else:
return f"({value}) {enum_name}"
class FlagField(IntField):
def __init__(self, flag_type, flag_strict=True, **kwargs):
self.flag_type = flag_type
self.flag_strict = flag_strict
super().__init__(**kwargs)
def set_flag(self, flag):
valid = False
for value in vars(self.flag_type).values():
if flag == value:
valid = True
break
if not valid and self.flag_strict:
raise ValueError(f"Flag value does not exist in flag type {self.flag_type}")
self.set_value(self.value | flag)
def has_flag(self, flag):
return self.value & flag == flag
def _parse_value(self, value):
int_value = super()._parse_value(value)
current_val = int_value
for value in vars(self.flag_type).values():
if isinstance(value, int):
current_val &= ~value
if current_val != 0 and self.flag_strict:
raise ValueError(f"Invalid flag for field {self.name} value set {current_val}")
return int_value
def _to_string(self):
field_value = self._get_calculated_value(self.value)
if field_value == 0:
return "0"
flags = []
for flag, value in vars(self.flag_type).items():
# ignore and dunder __foo__ attributes.
if not flag.startswith("__") and isinstance(value, int) and self.has_flag(value):
flags.append(flag)
flags.sort()
return f"({field_value}) " + (", ".join(flags))
class BoolField(Field):
def __init__(self, size=1, **kwargs):
"""
Used to store a boolean value in 1 byte. b"\x00" is False while b"\x01"
is True.
:param kwargs: Any other kwargs to be sent to Field()
"""
if size != 1:
raise InvalidFieldDefinition(f"BoolField size must have a value of 1, not {size}")
super().__init__(size=size, **kwargs)
def _pack_value(self, value):
return b"\x01" if value else b"\x00"
def _parse_value(self, value):
if value is None:
bool_value = False
elif isinstance(value, bool):
bool_value = value
elif isinstance(value, bytes):
bool_value = value == b"\x01"
elif callable(value):
bool_value = value
else:
raise TypeError(f"Cannot parse value for field {self.name} of type {type(value).__name__} to a bool")
return bool_value
def _get_packed_size(self):
return 1
def _to_string(self):
return str(self._get_calculated_value(self.value))
class TextField(BytesField):
def __init__(self, encoding="utf-16-le", null_terminated=False, **kwargs):
self.encoding = encoding
self.null_terminated = null_terminated
super().__init__(**kwargs)
def _pack_value(self, value):
if self.null_terminated:
value += "\x00"
return to_bytes(value, encoding=self.encoding)
def _parse_value(self, value):
if value is None:
text_value = ""
elif isinstance(value, bytes):
text_value = to_text(value, encoding=self.encoding)
elif isinstance(value, str):
text_value = value
elif callable(value):
text_value = value
else:
raise TypeError(f"Cannot parse value for field {self.name} of type {type(value).__name__} to a text string")
return text_value
def _get_packed_size(self):
text_value = self._get_calculated_value(self.value)
size = len(to_bytes(text_value, encoding=self.encoding))
if self.null_terminated:
char_len = len("\x00".encode(self.encoding))
size += char_len
return size
def _to_string(self):
return self.value
def unpack(self, data):
null_byte = "\x00".encode(self.encoding)
if self.null_terminated and self.size is None:
# If the size wasn't specified and the string contains a null terminator, cut off the bytes there.
null_index = bytes(data).find(null_byte)
if null_index != -1:
# In the case of UTF-16 we might be the index in the middle of a char, make sure we round up and get
# the boundary of each char.
actual_index = int(math.ceil(null_index / len(null_byte)) * len(null_byte))
self.set_value(data[0:actual_index])
return data[actual_index + len(null_byte) :]
size = self._get_calculated_size(self.size, data)
raw_value = data[0:size]
if self.null_terminated and bytes(raw_value).endswith(null_byte):
raw_value = raw_value[: len(null_byte) * -1]
self.set_value(raw_value)
return data[size:]

View File

@@ -0,0 +1,167 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
import errno
import logging
import select
import socket
import struct
import threading
import timeit
from collections import OrderedDict
from smbprotocol.structure import BytesField, IntField, Structure
log = logging.getLogger(__name__)
class DirectTCPPacket(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.1 Transport
The Directory TCP transport packet header MUST have the following
structure.
"""
def __init__(self):
self.fields = OrderedDict(
[
(
"stream_protocol_length",
IntField(
size=4,
little_endian=False,
default=lambda s: len(s["smb2_message"]),
),
),
(
"smb2_message",
BytesField(
size=lambda s: s["stream_protocol_length"].get_value(),
),
),
]
)
super().__init__()
class Tcp:
MAX_SIZE = 16777215
def __init__(self, server, port, timeout=None):
self.server = server
self.port = port
self.timeout = timeout
self.connected = False
self._sock = None
self._sock_lock = threading.Lock()
self._close_lock = threading.Lock()
def connect(self):
with self._sock_lock:
if not self.connected:
log.info("Connecting to DirectTcp socket")
try:
self._sock = socket.create_connection((self.server, self.port), timeout=self.timeout)
except (OSError, socket.gaierror) as err:
raise ValueError(f"Failed to connect to '{self.server}:{self.port}': {err}") from err
self._sock.settimeout(None) # Make sure the socket is in blocking mode.
self.connected = True
def close(self):
with self._sock_lock:
if self.connected:
log.info("Disconnecting DirectTcp socket")
# Sending shutdown first will tell the recv thread (for both select and recv) that the socket has data
# which returns b'' meaning it was closed.
try:
self._sock.shutdown(socket.SHUT_RDWR)
except OSError as e: # pragma: no cover
# Avoid collecting coverage here to avoid CI failing due to race condition differences
if e.errno != errno.ENOTCONN:
raise
# This is even more special, we cannot close the socket if we are in the middle of a select or recv().
# Doing so causes either a timeout (bad!) or bad fd descriptor (somewhat bad). By shutting down the
# socket first then waiting until recv() has exited the critical select/recv section we can ensure we
# gracefully handle client side socket closures both here and our recv thread without any extra waits
# or exceptions.
with self._close_lock:
self._sock.close()
self.connected = False
def send(self, header):
b_msg = header
data_length = len(b_msg)
if data_length > self.MAX_SIZE:
raise ValueError(
f"Data to be sent over Direct TCP size {data_length} exceeds the max length allowed {self.MAX_SIZE}"
)
tcp_packet = DirectTCPPacket()
tcp_packet["smb2_message"] = b_msg
data = tcp_packet.pack()
with self._sock_lock:
while data:
sent = self._sock.send(data)
data = data[sent:]
def recv(self, timeout):
# We don't need a lock for recv as the receiver is called from 1 thread.
b_packet_size, timeout = self._recv(4, timeout)
if not b_packet_size:
return b""
packet_size = struct.unpack(">L", b_packet_size)[0]
return self._recv(packet_size, timeout)[0]
def _recv(self, length, timeout):
buffer = bytearray(length)
offset = 0
while offset < length:
read_len = length - offset
log.debug(f"Socket recv({read_len}) (total {length})")
start_time = timeit.default_timer()
with self._close_lock:
if not self.connected:
# The socket was closed - need the no cover to avoid CI failing on race condition differences
return None, timeout # pragma: no cover
read = select.select([self._sock], [], [], max(timeout, 1))[0]
elapsed = timeit.default_timer() - start_time
timeout = timeout - elapsed
if not read:
raise TimeoutError(f"recv idle for {elapsed:.1f}s ({offset}/{length} bytes)")
try:
b_data = self._sock.recv(read_len)
except OSError as e:
# Windows will raise this error if the socket has been shutdown, Linux return returns an empty byte
# string so we just replicate that.
if e.errno not in [errno.ESHUTDOWN, errno.ECONNRESET, errno.ECONNABORTED]:
# Avoid collecting coverage here to avoid CI failing due to race condition differences
raise # pragma: no cover
log.warning(
"socket aborted by peer (%s), treating as EOF",
errno.errorcode.get(e.errno, e.errno),
)
b_data = b""
read_len = len(b_data)
log.debug(f"Socket recv() returned {read_len} bytes (total {length})")
if read_len == 0:
self.close()
return None, timeout # The socket has been shutdown
buffer[offset : offset + read_len] = b_data
offset += read_len
return bytes(buffer), timeout

View File

@@ -0,0 +1,373 @@
# Copyright: (c) 2019, Jordan Borean (@jborean93) <jborean93@gmail.com>
# MIT License (see LICENSE or https://opensource.org/licenses/MIT)
import logging
from collections import OrderedDict
from smbprotocol import Dialects
from smbprotocol.exceptions import (
FileClosed,
InvalidDeviceRequest,
NotSupported,
SMBException,
)
from smbprotocol.header import Commands
from smbprotocol.ioctl import (
CtlCode,
IOCTLFlags,
SMB2IOCTLRequest,
SMB2IOCTLResponse,
SMB2ValidateNegotiateInfoRequest,
SMB2ValidateNegotiateInfoResponse,
)
from smbprotocol.structure import BytesField, EnumField, FlagField, IntField, Structure
log = logging.getLogger(__name__)
class TreeFlags:
"""
[MS-SMB2] v53.0 2017-09-15
2.2.9 SMB2 TREE_CONNECT Response Flags
Flags used in SMB 3.1.1 to indicate how to process the operation.
"""
SMB2_TREE_CONNECT_FLAG_CLUSTER_RECONNECT = 0x0004
SMB2_TREE_CONNECT_FLAG_REDIRECT_TO_OWNER = 0x0002
SMB2_TREE_CONNECT_FLAG_EXTENSION_PRESENT = 0x0001
class ShareType:
"""
[MS-SMB2] v53.0 2017-09-15
2.2.10 SMB2 TREE_CONNECT Response Capabilities
The type of share being accessed
"""
SMB2_SHARE_TYPE_DISK = 0x01
SMB2_SHARE_TYPE_PIPE = 0x02
SMB2_SHARE_TYPE_PRINT = 0x03
class ShareFlags:
"""
[MS-SMB2] v53.0 2017-09-15
2.2.10 SMB2 TREE_CONNECT Response Capabilities
Properties for the share
"""
SMB2_SHAREFLAG_MANUAL_CACHING = 0x00000000
SMB2_SHAREFLAG_AUTO_CACHING = 0x00000010
SMB2_SHAREFLAG_VDO_CACHING = 0x00000020
SMB2_SHAREFLAG_NO_CACHING = 0x00000030
SMB2_SHAREFLAG_DFS = 0x00000001
SMB2_SHAREFLAG_DFS_ROOT = 0x00000002
SMB2_SHAREFLAG_RESTRICT_EXCLUSIVE_OPENS = 0x00000100
SMB2_SHAREFLAG_FORCE_SHARED_DELETE = 0x00000200
SMB2_SHAREFLAG_ALLOW_NAMESPACE_CACHING = 0x00000400
SMB2_SHAREFLAG_ACCESS_BASED_DIRECTORY_ENUM = 0x00000800
SMB2_SHAREFLAG_FORCE_LEVELII_OPLOCK = 0x00001000
SMB2_SHAREFLAG_ENABLE_HASH_V1 = 0x00002000
SMB2_SHAREFLAG_ENABLE_HASH_V2 = 0x00004000
SMB2_SHAREFLAG_ENCRYPT_DATA = 0x00008000
SMB2_SHAREFLAG_IDENTITY_REMOTING = 0x00040000
SMB2_SHAREFLAG_COMPRESS_DATA = 0x00100000
SMB2_SHAREFLAG_ISOLATED_TRANSPORT = 0x00200000
class ShareCapabilities:
"""
[MS-SMB2] v53.0 2017-09-15
2.2.10 SMB2 TREE_CONNECT Response Capabilities
Indicates various capabilities for a share
"""
SMB2_SHARE_CAP_DFS = 0x00000008
SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY = 0x00000010
SMB2_SHARE_CAP_SCALEOUT = 0x00000020
SMB2_SHARE_CAP_CLUSTER = 0x00000040
SMB2_SHARE_CAP_ASYMMETRIC = 0x00000080
SMB2_SHARE_CAP_REDIRECT_TO_OWNER = 0x00000100
class SMB2TreeConnectRequest(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.9 SMB2 TREE_CONNECT Request
Sent by the client to request access to a particular share on the server
"""
COMMAND = Commands.SMB2_TREE_CONNECT
def __init__(self):
self.fields = OrderedDict(
[
("structure_size", IntField(size=2, default=9)),
(
"flags",
FlagField(
size=2,
flag_type=TreeFlags,
),
),
(
"path_offset",
IntField(
size=2,
default=64 + 8,
),
),
(
"path_length",
IntField(
size=2,
default=lambda s: len(s["buffer"]),
),
),
("buffer", BytesField(size=lambda s: s["path_length"].get_value())),
]
)
super().__init__()
class SMB2TreeConnectResponse(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.10 SMB2 TREE_CONNECT Response
Sent by the server when an SMB2 TREE_CONNECT request is processed
successfully.
"""
COMMAND = Commands.SMB2_TREE_CONNECT
def __init__(self):
self.fields = OrderedDict(
[
("structure_size", IntField(size=2, default=16)),
(
"share_type",
EnumField(
size=1,
enum_type=ShareType,
),
),
("reserved", IntField(size=1)),
(
"share_flags",
FlagField(
size=4,
flag_type=ShareFlags,
),
),
(
"capabilities",
FlagField(
size=4,
flag_type=ShareCapabilities,
),
),
("maximal_access", IntField(size=4)),
]
)
super().__init__()
class SMB2TreeDisconnect(Structure):
"""
[MS-SMB2] v53.0 2017-09-15
2.2.11/12 SMB2 TREE_DISCONNECT Request and Response
Sent by the client to request that the tree connect specific by tree_id in
the header is disconnected.
"""
COMMAND = Commands.SMB2_TREE_DISCONNECT
def __init__(self):
self.fields = OrderedDict(
[
(
"structure_size",
IntField(
size=2,
default=4,
),
),
("reserved", IntField(size=2)),
]
)
super().__init__()
class TreeConnect:
def __init__(self, session, share_name):
"""
[MS-SMB2] v53.0 2017-09-15
3.2.1.4 Per Tree Connect
Attributes per Tree Connect (share connections)
:param session: The Session to connect to the tree with.
:param share_name: The name of the share, including the server name.
"""
self._connected = False
self.open_table = {}
self.share_name = share_name
self.tree_connect_id = None
self.session = session
self.is_dfs_share = None
# SMB 3.x+
self.is_ca_share = None
self.encrypt_data = None
self.is_scaleout_share = None
def connect(self, require_secure_negotiate=True):
"""
Connect to the share.
:param require_secure_negotiate: For Dialects 3.0 and 3.0.2, will
verify the negotiation parameters with the server to prevent
SMB downgrade attacks
"""
log.info(f"Session: {self.session.username} - Creating connection to share {self.share_name}")
utf_share_name = self.share_name.encode("utf-16-le")
connect = SMB2TreeConnectRequest()
connect["buffer"] = utf_share_name
log.info("Session: %s - Sending Tree Connect message", self.session.username)
log.debug(connect)
request = self.session.connection.send(connect, sid=self.session.session_id)
log.info("Session: %s - Receiving Tree Connect response", self.session.username)
response = self.session.connection.receive(request)
tree_response = SMB2TreeConnectResponse()
tree_response.unpack(response["data"].get_value())
log.debug(tree_response)
# https://msdn.microsoft.com/en-us/library/cc246687.aspx
self.tree_connect_id = response["tree_id"].get_value()
log.info("Session: %s - Created tree connection with ID %d", self.session.username, self.tree_connect_id)
self._connected = True
self.session.tree_connect_table[self.tree_connect_id] = self
capabilities = tree_response["capabilities"]
self.is_dfs_share = capabilities.has_flag(ShareCapabilities.SMB2_SHARE_CAP_DFS)
self.is_ca_share = capabilities.has_flag(ShareCapabilities.SMB2_SHARE_CAP_CONTINUOUS_AVAILABILITY)
dialect = self.session.connection.dialect
if dialect >= Dialects.SMB_3_0_0 and self.session.connection.supports_encryption:
self.encrypt_data = tree_response["share_flags"].has_flag(ShareFlags.SMB2_SHAREFLAG_ENCRYPT_DATA)
self.is_scaleout_share = capabilities.has_flag(ShareCapabilities.SMB2_SHARE_CAP_SCALEOUT)
if require_secure_negotiate:
self._verify_dialect_negotiate()
def disconnect(self):
"""
Disconnects the tree connection.
"""
if not self._connected:
return
log.info(f"Session: {self.session.username}, Tree: {self.share_name} - Disconnecting from Tree Connect")
req = SMB2TreeDisconnect()
log.info(f"Session: {self.session.username}, Tree: {self.share_name} - Sending Tree Disconnect message")
log.debug(req)
request = self.session.connection.send(req, sid=self.session.session_id, tid=self.tree_connect_id)
log.info(f"Session: {self.session.username}, Tree: {self.share_name} - Receiving Tree Disconnect response")
res = self.session.connection.receive(request)
res_disconnect = SMB2TreeDisconnect()
res_disconnect.unpack(res["data"].get_value())
log.debug(res_disconnect)
self._connected = False
del self.session.tree_connect_table[self.tree_connect_id]
def _verify_dialect_negotiate(self):
log_header = f"Session: {self.session.username}, Tree: {self.share_name}"
log.info("%s - Running secure negotiate process", log_header)
if not self.session.signing_key:
# This will only happen if we authenticated with the guest or anonymous user.
raise SMBException(
"Cannot verify negotiate information without a session signing key. Authenticate with "
"a non-guest or anonymous account or set require_secure_negotiate=False to disable the "
"negotiation info verification checks."
)
dialect = self.session.connection.dialect
if dialect >= Dialects.SMB_3_1_1:
# SMB 3.1.1+ uses the negotiation info to generate the signing key so doesn't need this extra exchange.
return
ioctl_request = SMB2IOCTLRequest()
ioctl_request["ctl_code"] = CtlCode.FSCTL_VALIDATE_NEGOTIATE_INFO
ioctl_request["file_id"] = b"\xff" * 16
val_neg = SMB2ValidateNegotiateInfoRequest()
val_neg["capabilities"] = self.session.connection.client_capabilities
val_neg["guid"] = self.session.connection.client_guid
val_neg["security_mode"] = self.session.connection.client_security_mode
val_neg["dialects"] = self.session.connection.negotiated_dialects
ioctl_request["buffer"] = val_neg
ioctl_request["max_output_response"] = len(val_neg)
ioctl_request["flags"] = IOCTLFlags.SMB2_0_IOCTL_IS_FSCTL
log.info("%s - Sending Secure Negotiate Validation message", log_header)
log.debug(ioctl_request)
request = self.session.connection.send(
ioctl_request, sid=self.session.session_id, tid=self.tree_connect_id, force_signature=True
)
log.info("%s - Receiving secure negotiation response", log_header)
try:
response = self.session.connection.receive(request)
except (FileClosed, InvalidDeviceRequest, NotSupported) as e:
# https://docs.microsoft.com/en-us/archive/blogs/openspecification/smb3-secure-dialect-negotiation
# Older dialects may respond with these exceptions, this is expected and we only want to fail if
# they are not signed. Check that header signature was signed, fail if it wasn't. The signature, if
# present, would have been verified when the connection received the data.
if e.header["signature"].get_value() == b"\x00" * 16:
raise
return
# If we received an actual response we want to validate the info provided matches with what was negotiated.
ioctl_resp = SMB2IOCTLResponse()
ioctl_resp.unpack(response["data"].get_value())
log.debug(ioctl_resp)
log.info("%s - Unpacking secure negotiate response info", log_header)
val_resp = SMB2ValidateNegotiateInfoResponse()
val_resp.unpack(ioctl_resp["buffer"].get_value())
log.debug(val_resp)
self._verify(
"server capabilities",
val_resp["capabilities"].get_value(),
self.session.connection.server_capabilities.get_value(),
)
self._verify("server guid", val_resp["guid"].get_value(), self.session.connection.server_guid)
self._verify(
"server security mode", val_resp["security_mode"].get_value(), self.session.connection.server_security_mode
)
self._verify("server dialect", val_resp["dialect"].get_value(), self.session.connection.dialect)
log.info("Session: %d, Tree: %d - Secure negotiate complete", self.session.session_id, self.tree_connect_id)
def _verify(self, check, actual, expected):
if actual != expected:
log_header = f"Session: {self.session.session_id}, Tree: {self.tree_connect_id}"
raise SMBException(
f"{log_header} - Secure negotiate failed to verify {check}, Actual: {actual}, Expected: {expected}",
)