dissect.util 3.24.dev1__cp314-cp314t-manylinux_2_28_s390x.whl

dissect/util/ldap.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import operator
+import re
+from enum import Enum
+
+from dissect.util.exceptions import Error
+
+
+class InvalidQueryError(Error):
+    pass
+
+
+class LogicalOperator(Enum):
+    AND = "&"
+    OR = "|"
+    NOT = "!"
+
+
+_LOGICAL_OPERATORS = tuple(op.value for op in LogicalOperator)
+
+
+class ComparisonOperator(Enum):
+    GE = ">="
+    LE = "<="
+    GT = ">"
+    LT = "<"
+    EQ = "="
+    APPROX = "~="
+    BIT = ":="
+    EXTENDED = ":"
+
+
+_NORMAL_COMPARISON_OPERATORS = [op for op in ComparisonOperator if op != ComparisonOperator.EXTENDED]
+_SORTED_COMPARISON_OPERATORS = sorted(_NORMAL_COMPARISON_OPERATORS, key=lambda op: len(op.value), reverse=True)
+
+_RE_EXTENDED = re.compile(r"(.+?):(.+?):=(.+)?")
+
+
+class SearchFilter:
+    """Represents an LDAP search filter (simple or nested).
+
+    Args:
+        query: The LDAP search filter string.
+    """
+
+    def __init__(self, query: str) -> None:
+        self.query: str = query
+
+        self.children: list[SearchFilter] = []
+        self.operator: LogicalOperator | ComparisonOperator | None = None
+        self.attribute: str | None = None
+        self.value: str | None = None
+        self._extended_rule: str | None = None
+
+        _validate_syntax(query)
+
+        if query[1:-1].startswith(_LOGICAL_OPERATORS):
+            self._parse_nested()
+        else:
+            self._parse_simple()
+
+    def __repr__(self) -> str:
+        if self.is_nested():
+            return f"<SearchFilter nested operator={self.operator.value!r} children={self.children}>"
+        return f"<SearchFilter attribute={self.attribute!r} operator={self.operator.value!r} value={self.value}>"
+
+    @classmethod
+    def parse(cls, query: str, optimize: bool = True) -> SearchFilter:
+        """Parse an LDAP query into a filter object, with optional optimization."""
+        result = cls(query)
+        if optimize:
+            return optimize_ldap_query(result)[0]
+        return result
+
+    def is_nested(self) -> bool:
+        """Return whether the filter is nested (i.e., contains logical operators and child filters)."""
+        return isinstance(self.operator, LogicalOperator)
+
+    def format(self) -> str:
+        """Format the search filter back into an LDAP query string."""
+        if self.is_nested():
+            childs = "".join([child.format() for child in self.children])
+            return f"({self.operator.value}{childs})"
+
+        if self.operator == ComparisonOperator.EXTENDED:
+            return f"({self.attribute}:{self._extended_rule}:={self.value})"
+
+        return f"({self.attribute}{self.operator.value}{self.value})"
+
+    def _parse_simple(self) -> None:
+        """Parse simple filter."""
+        query = self.query[1:-1]
+
+        # Check for extended matching rules first
+        if ":" in query and (match := _RE_EXTENDED.match(query)):
+            self.operator = ComparisonOperator.EXTENDED
+            self.attribute, self._extended_rule, self.value = match.groups()
+            return
+
+        # Regular operator parsing
+        test = query
+        operators: list[ComparisonOperator] = []
+        for op in _SORTED_COMPARISON_OPERATORS:
+            if op.value not in test:
+                continue
+
+            if test.count(op.value) > 1:
+                raise InvalidQueryError(f"Comparison operator {op.value} found multiple times in query: {self.query}")
+
+            operators.append(op)
+            test = test.replace(op.value, "")
+
+        if len(operators) == 0:
+            raise InvalidQueryError(
+                f"No comparison operator found in query: {self.query}. "
+                f"Expected one of {[op.value for op in _NORMAL_COMPARISON_OPERATORS]}."
+            )
+
+        if len(operators) > 1:
+            raise InvalidQueryError(
+                f"Multiple comparison operators found in query: {self.query} -> {[o.value for o in operators]} "
+                f"Expected only one of {[op.value for op in _NORMAL_COMPARISON_OPERATORS]}."
+            )
+
+        self.operator = operators[0]
+        self.attribute, _, self.value = query.partition(self.operator.value)
+
+    def _parse_nested(self) -> None:
+        """Parse nested filter."""
+        query = self.query[1:-1]
+        self.operator = LogicalOperator(query[0])
+
+        start = 1
+        while start < len(query):
+            end = start + 1
+            depth = 1
+
+            while end < len(query) and depth > 0:
+                if query[end] == "(":
+                    depth += 1
+                elif query[end] == ")":
+                    depth -= 1
+                end += 1
+
+            self.children.append(SearchFilter(query[start:end]))
+            start = end
+
+
+_ATTRIBUTE_WEIGHTS = {
+    "objectGUID": 1,
+    "distinguishedName": 1,
+    "sAMAccountName": 2,
+    "userPrincipalName": 2,
+    "mail": 2,
+    "sAMAccountType": 3,
+    "servicePrincipalName": 3,
+    "userAccountControl": 4,
+    "memberOf": 5,
+    "member": 5,
+    "pwdLastSet": 5,
+    "primaryGroupID": 6,
+    "whenCreated": 6,
+    "ou": 6,
+    "lastLogonTimestamp": 6,
+    "cn": 7,
+    "givenName": 7,
+    "name": 7,
+    "telephoneNumber": 7,
+    "objectCategory": 8,
+    "description": 9,
+    "objectClass": 10,
+}
+
+
+def optimize_ldap_query(query: SearchFilter) -> tuple[SearchFilter, int]:
+    """Optimize an LDAP query in-place.
+
+    Removes redundant conditions and sorts filters and conditions based on how specific they are.
+
+    Args:
+        query: The LDAP query to optimize.
+
+    Returns:
+        A tuple containing the optimized LDAP query and its weight.
+    """
+    # Simplify single-child AND/OR
+    if query.is_nested() and len(query.children) == 1 and query.operator in (LogicalOperator.AND, LogicalOperator.OR):
+        return optimize_ldap_query(query.children[0])
+
+    # Sort nested children by weight
+    if query.is_nested() and len(query.children) > 1:
+        children = sorted((optimize_ldap_query(child) for child in query.children), key=operator.itemgetter(1))
+
+        query.children = [child for child, _ in children]
+        query.query = query.format()
+
+        return query, max(weight for _, weight in children)
+
+    # Handle NOT
+    if query.is_nested() and len(query.children) == 1 and query.operator == LogicalOperator.NOT:
+        child, weight = optimize_ldap_query(query.children[0])
+
+        query.children[0] = child
+        query.query = query.format()
+
+        return query, weight
+
+    # Base case: simple filter
+    if not query.is_nested():
+        return query, _ATTRIBUTE_WEIGHTS.get(query.attribute, max(_ATTRIBUTE_WEIGHTS.values()))
+
+    return query, max(_ATTRIBUTE_WEIGHTS.values())
+
+
+def _validate_syntax(query: str) -> None:
+    """Validate basic LDAP query syntax.
+
+    Args:
+        query: The LDAP query to validate.
+    """
+    if not query:
+        raise InvalidQueryError("Empty query")
+
+    if not query.startswith("(") or not query.endswith(")"):
+        raise InvalidQueryError(f"Query must be wrapped in parentheses: {query}")
+
+    if query.count("(") != query.count(")"):
+        raise InvalidQueryError(f"Unbalanced parentheses in query: {query}")
+
+    # Check for empty parentheses
+    if "()" in query:
+        raise InvalidQueryError(f"Empty parentheses found in query: {query}")
+
+    # Check for queries that start with double opening parentheses
+    if query.startswith("(("):
+        raise InvalidQueryError(f"Invalid query structure: {query}")

dissect/util/plist.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import plistlib
+import uuid
+from collections import UserDict
+from typing import TYPE_CHECKING, Any, BinaryIO
+
+from dissect.util.ts import cocoatimestamp
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+
+class NSKeyedArchiver:
+    def __init__(self, fh: BinaryIO):
+        self.plist = plistlib.load(fh)
+
+        if not isinstance(self.plist, dict) or not all(
+            key in self.plist for key in ["$version", "$archiver", "$top", "$objects"]
+        ):
+            raise ValueError("File is not an NSKeyedArchiver plist")
+
+        self._objects = self.plist.get("$objects")
+        self._cache = {}
+
+        self.top = {}
+        for name, value in self.plist.get("$top", {}).items():
+            self.top[name] = self._parse(value)
+
+    def __getitem__(self, key: str) -> Any:
+        return self.top[key]
+
+    def __repr__(self) -> str:
+        return f"<NSKeyedArchiver top={self.top}>"
+
+    def get(self, key: str, default: Any | None = None) -> Any:
+        return self.top.get(key, default)
+
+    def _parse(self, uid: Any) -> Any:
+        if not isinstance(uid, plistlib.UID):
+            return uid
+
+        num = uid.data
+        if num in self._cache:
+            return self._cache[num]
+        result = self._parse_obj(self._objects[num])
+        self._cache[num] = result
+        return result
+
+    def _parse_obj(self, obj: Any) -> Any:
+        if isinstance(obj, dict):
+            klass = obj.get("$class")
+            if klass:
+                klass_name = self._parse(klass).get("$classname")
+                return CLASSES.get(klass_name, NSObject)(self, obj)
+            return obj
+
+        if isinstance(obj, list):
+            return list(map(self._parse, obj))
+
+        if isinstance(obj, bool | bytes | int | float) or obj is None:
+            return obj
+
+        if isinstance(obj, str):
+            return None if obj == "$null" else obj
+
+        return None
+
+
+class NSObject:
+    def __init__(self, nskeyed: NSKeyedArchiver, obj: dict[str, Any]):
+        self.nskeyed = nskeyed
+        self.obj = obj
+
+        self._class = nskeyed._parse(obj.get("$class", {}))
+        self._classname = self._class.get("$classname", "Unknown")
+        self._classes = self._class.get("$classes", [])
+
+    def __getitem__(self, attr: str) -> Any:
+        obj = self.obj[attr]
+        return self.nskeyed._parse(obj)
+
+    def __getattr__(self, attr: str) -> Any:
+        try:
+            return self[attr]
+        except KeyError:
+            raise AttributeError(attr)
+
+    def __repr__(self):
+        return f"<{self._classname}>"
+
+    def keys(self) -> list[str]:
+        return self.obj.keys()
+
+    def get(self, attr: str, default: Any | None = None) -> Any:
+        try:
+            return self[attr]
+        except KeyError:
+            return default
+
+
+class NSDictionary(UserDict, NSObject):
+    def __init__(self, nskeyed: NSKeyedArchiver, obj: dict[str, Any]):
+        NSObject.__init__(self, nskeyed, obj)
+        self.data = {nskeyed._parse(key): obj for key, obj in zip(obj["NS.keys"], obj["NS.objects"], strict=False)}
+
+    def __repr__(self) -> str:
+        return NSObject.__repr__(self)
+
+    def __getitem__(self, key: str) -> Any:
+        return self.nskeyed._parse(self.data[key])
+
+
+def parse_nsarray(nskeyed: NSKeyedArchiver, obj: dict[str, Any]) -> list[Any]:
+    return list(map(nskeyed._parse, obj["NS.objects"]))
+
+
+def parse_nsset(nskeyed: NSKeyedArchiver, obj: dict[str, Any]) -> list[Any]:
+    # Some values are not hashable, so return as list
+    return parse_nsarray(nskeyed, obj)
+
+
+def parse_nsdata(nskeyed: NSKeyedArchiver, obj: dict[str, Any]) -> Any:
+    return obj["NS.data"]
+
+
+def parse_nsdate(nskeyed: NSKeyedArchiver, obj: dict[str, Any]) -> datetime:
+    return cocoatimestamp(obj["NS.time"])
+
+
+def parse_nsuuid(nskeyed: NSKeyedArchiver, obj: dict[str, Any]) -> uuid.UUID:
+    return uuid.UUID(bytes=obj["NS.uuidbytes"])
+
+
+def parse_nsurl(nskeyed: NSKeyedArchiver, obj: dict[str, Any]) -> str:
+    base = nskeyed._parse(obj["NS.base"])
+    relative = nskeyed._parse(obj["NS.relative"])
+    if base:
+        return f"{base}/{relative}"
+    return relative
+
+
+CLASSES = {
+    "NSArray": parse_nsarray,
+    "NSMutableArray": parse_nsarray,
+    "NSDictionary": NSDictionary,
+    "NSMutableDictionary": NSDictionary,
+    "NSSet": parse_nsset,
+    "NSMutableSet": parse_nsset,
+    "NSData": parse_nsdata,
+    "NSMutableData": parse_nsdata,
+    "NSDate": parse_nsdate,
+    "NSUUID": parse_nsuuid,
+    "NSURL": parse_nsurl,
+    "NSNull": lambda nskeyed, obj: None,
+}

dissect/util/sid.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import io
+import struct
+from typing import BinaryIO
+
+
+def read_sid(fh: BinaryIO | bytes, endian: str = "<", swap_last: bool = False) -> str:
+    """Read a Windows SID from bytes.
+
+    Normally we'd do this with cstruct, but do it with just struct to keep dissect.util dependency-free.
+    On the upside, this also improves performance!
+
+    This is equivalent to the following structure::
+
+        typedef struct _SID {
+            BYTE        Revision;
+            BYTE        SubAuthorityCount;
+            CHAR        IdentifierAuthority[6];
+            DWORD       SubAuthority[SubAuthorityCount];
+        } SID;
+
+    Args:
+        fh: A file-like object or bytes object to read the SID from.
+        endian: Optional endianness for reading the sub authorities.
+        swap_list: Optional flag for swapping the endianess of the _last_ sub authority entry.
+    """
+    if isinstance(fh, bytes):
+        fh = io.BytesIO(fh)
+
+    if len(buf := fh.read(8)) != 8:
+        return ""
+
+    revision = buf[0]
+    sub_authority_count = buf[1]
+    authority = int.from_bytes(buf[2:], "big")
+
+    sub_authority_buf = bytearray(fh.read(sub_authority_count * 4))
+    if sub_authority_count and swap_last:
+        sub_authority_buf[-4:] = sub_authority_buf[-4:][::-1]
+
+    sub_authorities = struct.unpack(f"{endian}{sub_authority_count}I", sub_authority_buf)
+
+    sid_elements = [
+        "S",
+        f"{revision}",
+        f"{authority}",
+    ]
+    sid_elements.extend(map(str, sub_authorities))
+    return "-".join(sid_elements)
+
+
+def write_sid(sid: str, endian: str = "<", swap_last: bool = False) -> bytes:
+    """Write a Windows SID string to bytes.
+
+    Args:
+        sid: SID in the form ``S-Revision-Authority-SubAuth1-...``.
+        endian: Optional endianness for reading the sub authorities.
+        swap_last: Optional flag for swapping the endianess of the _last_ sub authority entry.
+    """
+    if not sid:
+        return b""
+
+    parts = sid.split("-")
+    if len(parts) < 3 or parts[0].upper() != "S":
+        raise ValueError("Invalid SID string format: insufficient parts")
+
+    revision = int(parts[1]).to_bytes(1, "little")
+    authority = int(parts[2]).to_bytes(6, "big")
+    sub_authorities = [int(x) for x in parts[3:]]
+
+    header = revision + len(sub_authorities).to_bytes(1, "little") + authority
+
+    if not sub_authorities:
+        return header
+
+    sub_bytes = bytearray(struct.pack(f"{endian}{len(sub_authorities)}I", *sub_authorities))
+    if swap_last:
+        sub_bytes[-4:] = sub_bytes[-4:][::-1]
+
+    return header + bytes(sub_bytes)