Estructura inicial funcional con documentación en el README.md de la FastAPI
This commit is contained in:
456
env/lib/python3.12/site-packages/smbprotocol/dfs.py
vendored
Normal file
456
env/lib/python3.12/site-packages/smbprotocol/dfs.py
vendored
Normal 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)
|
||||
Reference in New Issue
Block a user