bhshell 0.1.0__py3-none-any.whl

bhshell/errors.py

@@ -0,0 +1,73 @@
+"""Everything the client and query layer raise derives from BHError, so the shell
+can print it as a one-line error with an optional hint."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from bhshell.models.entities import Node
+
+
+class BHError(Exception):
+    hint: str = ""
+
+    def __init__(self, message: str, *, hint: str = "") -> None:
+        super().__init__(message)
+        self.message = message
+        if hint:
+            self.hint = hint
+
+
+class ConnectionFailed(BHError):
+    hint = "Check the backend with 'url' and 'tls', then retry."
+
+
+class AuthError(BHError):
+    hint = "Run 'login' to authenticate again."
+
+
+class NotAuthenticated(AuthError):
+    hint = "Run 'login' first."
+
+
+class MFARequired(AuthError):
+    hint = "Re-run 'login' and provide the one-time password."
+
+
+class LoginFailed(AuthError):
+    # Unlike a plain 401, a rejected login does not drop the session already in use.
+    hint = "Check the credentials and retry; the previous session (if any) is still active."
+
+
+class ForbiddenError(BHError):
+    pass
+
+
+class NotFoundError(BHError):
+    pass
+
+
+class ApiError(BHError):
+    def __init__(self, status: int, message: str, *, hint: str = "") -> None:
+        super().__init__(f"HTTP {status}: {message}", hint=hint)
+        self.status = status
+        self.detail = message
+
+
+class CypherDisabledError(BHError):
+    pass
+
+
+class UnsupportedFeature(BHError):
+    pass
+
+
+class AmbiguousMatchError(BHError):
+    hint = "Qualify the name: 'jdoe@corp.local', 'CORP\\jdoe', '--domain CORP.LOCAL' or use the SID."
+
+    def __init__(self, query: str, candidates: Sequence[Node]) -> None:
+        super().__init__(f"'{query}' matches {len(candidates)} objects")
+        self.query = query
+        self.candidates = list(candidates)

bhshell/library/asrep-roastable-users.cyp

@@ -0,0 +1,3 @@
+// name: asrep-roastable-users
+// description: Enabled users without Kerberos pre-authentication
+MATCH (u:User) WHERE u.dontreqpreauth = true AND u.enabled = true RETURN u

bhshell/library/dcsync-principals.cyp

@@ -0,0 +1,3 @@
+// name: dcsync-principals
+// description: Principals with DCSync or replication rights on a domain
+MATCH p=(n:Base)-[:DCSync|GetChanges|GetChangesAll]->(d:Domain) RETURN p

bhshell/library/domain-admins-members.cyp

@@ -0,0 +1,3 @@
+// name: domain-admins-members
+// description: Direct and nested members of every Domain Admins group
+MATCH p=(m:Base)-[:MemberOf*1..]->(g:Group) WHERE g.objectid ENDS WITH '-512' RETURN p

bhshell/library/domain-trusts.cyp

@@ -0,0 +1,3 @@
+// name: domain-trusts
+// description: All edges between domains (trusts and trust abuse edges)
+MATCH p=(a:Domain)-[r]->(b:Domain) RETURN p

bhshell/library/gpos-linked-to-domain-controllers.cyp

@@ -0,0 +1,3 @@
+// name: gpos-linked-to-domain-controllers
+// description: GPOs linked to the Domain Controllers OU (control = DC compromise)
+MATCH p=(g:GPO)-[:GPLink]->(o:OU) WHERE o.name STARTS WITH 'DOMAIN CONTROLLERS@' RETURN p

bhshell/library/kerberoastable-users.cyp

@@ -0,0 +1,3 @@
+// name: kerberoastable-users
+// description: Enabled users with an SPN (Kerberoastable)
+MATCH (u:User) WHERE u.hasspn = true AND u.enabled = true RETURN u

bhshell/library/owned-objects.cyp

@@ -0,0 +1,3 @@
+// name: owned-objects
+// description: Everything marked owned
+MATCH (n:Tag_Owned) RETURN n

bhshell/library/owned-to-tier-zero.cyp

@@ -0,0 +1,3 @@
+// name: owned-to-tier-zero
+// description: Shortest paths from owned objects to Tier Zero (raw graph; see also 'path --owned')
+MATCH p=allShortestPaths((s:Tag_Owned)-[*1..]->(t:Tag_Tier_Zero)) WHERE s <> t RETURN p LIMIT 1000

bhshell/library/sid-history.cyp

@@ -0,0 +1,3 @@
+// name: sid-history
+// description: Principals carrying another object's SID (HasSIDHistory)
+MATCH p=(n:Base)-[:HasSIDHistory]->(t:Base) RETURN p

bhshell/library/tier-zero-users.cyp

@@ -0,0 +1,3 @@
+// name: tier-zero-users
+// description: Enabled users tagged Tier Zero
+MATCH (u:User:Tag_Tier_Zero) WHERE u.enabled = true RETURN u

bhshell/library/unconstrained-delegation.cyp

@@ -0,0 +1,3 @@
+// name: unconstrained-delegation
+// description: Enabled computers and users trusted for unconstrained delegation
+MATCH (n:Base) WHERE n.unconstraineddelegation = true AND n.enabled = true RETURN n

bhshell/models/entities.py

@@ -0,0 +1,402 @@
+"""Graph and Active Directory entity models.
+
+The BH Cypher endpoint returns graphs shaped like::
+
+    {"nodes": {"<id>": {"label", "kind", "kinds", "objectId", "isTierZero",
+                        "isOwnedObject", "properties": {...}}},
+     "edges": [{"source", "target", "kind", "properties"}]}
+
+These are normalised into `Node`, `Edge` and `Graph`.
+Typed AD views (`User`, `Computer`, `Group`) expose the
+triage summary for each object type.
+"""
+
+from __future__ import annotations
+
+from collections import deque
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from typing import Any, Literal
+
+PRIMARY_KINDS = (
+    "User",
+    "Computer",
+    "Group",
+    "Domain",
+    "GPO",
+    "OU",
+    "Container",
+    "AIACA",
+    "RootCA",
+    "EnterpriseCA",
+    "NTAuthStore",
+    "CertTemplate",
+    "IssuancePolicy",
+)
+
+TIER_ZERO_LABEL = "Tag_Tier_Zero"
+OWNED_LABEL = "Tag_Owned"
+
+
+@dataclass
+class Node:
+    id: str
+    objectid: str
+    kind: str
+    name: str
+    kinds: list[str] = field(default_factory=list)
+    properties: dict[str, Any] = field(default_factory=dict)
+    tier_zero: bool = False
+    owned: bool = False
+
+    @classmethod
+    def from_cypher(cls, node_id: str, raw: dict[str, Any]) -> Node:
+        props = raw.get("properties") or {}
+        kinds = list(raw.get("kinds") or [])
+        primary = raw.get("kind") or ""
+        for candidate in PRIMARY_KINDS:
+            if candidate in kinds or candidate == primary:
+                primary = candidate
+                break
+        return cls._build(
+            node_id=str(node_id),
+            objectid=raw.get("objectId") or props.get("objectid") or "",
+            kind=primary or "Unknown",
+            name=props.get("name") or raw.get("label") or "",
+            kinds=kinds,
+            props=props,
+            tier_zero=bool(raw.get("isTierZero")),
+            owned=bool(raw.get("isOwnedObject")),
+        )
+
+    @classmethod
+    def from_rest(cls, kind: str, raw: dict[str, Any]) -> Node:
+        """Build a node from a REST entity's `props` or from an item of a related-objects list.
+
+        Entity props spell it `objectid`; list items use `objectID` and put the kind in `label`.
+        """
+        objectid = raw.get("objectid") or raw.get("objectID") or ""
+        item_kind = raw.get("kind") or raw.get("label") or kind
+        return cls._build(
+            node_id=objectid,
+            objectid=objectid,
+            kind=str(item_kind),
+            name=raw.get("name") or objectid,
+            kinds=[str(k) for k in raw.get("kinds") or [item_kind]],
+            props=raw,
+            tier_zero=bool(raw.get("isTierZero")),
+            owned=bool(raw.get("isOwnedObject")),
+        )
+
+    @classmethod
+    def _build(cls, *, node_id: str, objectid: str, kind: str, name: str, kinds: list[str],
+               props: dict[str, Any], tier_zero: bool, owned: bool) -> Node:
+        return cls(
+            id=node_id,
+            objectid=objectid,
+            kind=kind,
+            name=name,
+            kinds=kinds,
+            properties=props,
+            tier_zero=tier_zero or TIER_ZERO_LABEL in kinds,
+            owned=owned or OWNED_LABEL in kinds,
+        )
+
+    @property
+    def domain(self) -> str:
+        return str(self.properties.get("domain") or "")
+
+    @property
+    def samaccountname(self) -> str:
+        return str(self.properties.get("samaccountname") or "")
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "kind": self.kind,
+            "objectid": self.objectid,
+            "domain": self.domain,
+            "tier_zero": self.tier_zero,
+            "owned": self.owned,
+            "properties": self.properties,
+        }
+
+
+@dataclass(frozen=True)
+class Edge:
+    source: str
+    target: str
+    kind: str
+    properties: dict[str, Any] = field(default_factory=dict, compare=False, hash=False)
+
+    @classmethod
+    def from_cypher(cls, raw: dict[str, Any]) -> Edge:
+        return cls(
+            source=str(raw.get("source")),
+            target=str(raw.get("target")),
+            kind=str(raw.get("kind") or ""),
+            properties=raw.get("properties") or {},
+        )
+
+
+@dataclass
+class Graph:
+    nodes: dict[str, Node] = field(default_factory=dict)
+    edges: list[Edge] = field(default_factory=list)
+    # The Cypher query this graph came from ('' when built otherwise).
+    query: str = field(default="", compare=False, repr=False)
+
+    @classmethod
+    def from_cypher(cls, data: dict[str, Any]) -> Graph:
+        graph = cls()
+        for node_id, raw in (data.get("nodes") or {}).items():
+            graph.nodes[str(node_id)] = Node.from_cypher(node_id, raw)
+        seen: set[Edge] = set()
+        for raw in data.get("edges") or []:
+            edge = Edge.from_cypher(raw)
+            if edge not in seen:
+                seen.add(edge)
+                graph.edges.append(edge)
+        return graph
+
+    def merge(self, other: Graph) -> Graph:
+        self.nodes.update(other.nodes)
+        seen = set(self.edges)
+        self.edges.extend(e for e in other.edges if e not in seen)
+        return self
+
+    @classmethod
+    def union(cls, graphs: Iterable[Graph]) -> Graph:
+        merged = cls()
+        for g in graphs:
+            merged.merge(g)
+        return merged
+
+    def find(self, objectid: str) -> Node | None:
+        return next((n for n in self.nodes.values() if n.objectid == objectid), None)
+
+    def edges_from(self, sources: Iterable[str], kinds: Iterable[str] | None = None) -> Iterator[Edge]:
+        srcs = set(sources)
+        wanted = set(kinds) if kinds is not None else None
+        return (e for e in self.edges if e.source in srcs and (wanted is None or e.kind in wanted))
+
+    def edges_to(self, targets: Iterable[str], kinds: Iterable[str] | None = None) -> Iterator[Edge]:
+        tgts = set(targets)
+        wanted = set(kinds) if kinds is not None else None
+        return (e for e in self.edges if e.target in tgts and (wanted is None or e.kind in wanted))
+
+    def paths(self, sources: Iterable[str], targets: Iterable[str], *, max_paths: int = 1000) -> list[list[Edge]]:
+        """Enumerate shortest chains from each source to the nearest-reachable targets.
+
+        Path APIs return the *union* of all paths as one subgraph; this splits
+        it back into individual chains. A chain ends at the first target it
+        reaches, and only edges that advance the BFS distance from the source
+        are followed, so every chain is a shortest path to its target.
+        """
+        adjacency: dict[str, list[Edge]] = {}
+        for e in self.edges:
+            adjacency.setdefault(e.source, []).append(e)
+        tgts = set(targets)
+        found: list[list[Edge]] = []
+
+        for src in sources:
+            dist = {src: 0}
+            queue: deque[str] = deque([src])
+            while queue:
+                current = queue.popleft()
+                if current in tgts and current != src:
+                    continue  # never expand beyond a target
+                for e in adjacency.get(current, []):
+                    if e.target not in dist:
+                        dist[e.target] = dist[current] + 1
+                        queue.append(e.target)
+
+            # Iterative DFS along distance-increasing edges: (node, chain so far).
+            stack: list[tuple[str, list[Edge]]] = [(src, [])]
+            while stack and len(found) < max_paths:
+                node, chain = stack.pop()
+                if chain and node in tgts:
+                    found.append(chain)
+                    continue
+                for e in reversed(adjacency.get(node, [])):
+                    if dist.get(e.target) == dist[node] + 1:
+                        stack.append((e.target, [*chain, e]))
+        return found
+
+    def count_paths(self, cap: int) -> int:
+        """Count simple paths (one edge or more) in the graph, stopping at `cap`.
+
+        Every row of a `RETURN p` query is a simple path of its result graph,
+        so this is an upper bound on the number of rows the server returned.
+        """
+        adjacency: dict[str, list[str]] = {}
+        for e in self.edges:
+            adjacency.setdefault(e.source, []).append(e.target)
+        total = 0
+        for start, targets in adjacency.items():
+            on_path = {start}
+            stack: list[tuple[str, Iterator[str]]] = [(start, iter(targets))]
+            while stack:
+                node, successors = stack[-1]
+                nxt = next(successors, None)
+                if nxt is None:
+                    stack.pop()
+                    on_path.discard(node)
+                    continue
+                if nxt in on_path:
+                    continue
+                total += 1
+                if total >= cap:
+                    return total
+                if nxt in adjacency:
+                    on_path.add(nxt)
+                    stack.append((nxt, iter(adjacency[nxt])))
+        return total
+
+    def bfs(self, start: str, kind: str, *, reverse: bool = False) -> dict[str, tuple[int, str]]:
+        """`{node_id: (depth, parent_id)}` of every node reachable along `kind` edges, `start` excluded."""
+        adjacency: dict[str, list[str]] = {}
+        for e in self.edges:
+            if e.kind != kind:
+                continue
+            a, b = (e.target, e.source) if reverse else (e.source, e.target)
+            adjacency.setdefault(a, []).append(b)
+        found: dict[str, tuple[int, str]] = {}
+        queue: deque[tuple[str, int]] = deque([(start, 0)])
+        while queue:
+            current, depth = queue.popleft()
+            for nxt in adjacency.get(current, []):
+                if nxt != start and nxt not in found:
+                    found[nxt] = (depth + 1, current)
+                    queue.append((nxt, depth + 1))
+        return found
+
+
+Risk = Literal["high", "medium", "info", "none"]
+FieldType = Literal["text", "bool", "date", "list"]
+
+
+@dataclass(frozen=True)
+class SummaryField:
+    label: str
+    value: Any
+    type: FieldType = "text"
+    risk: Risk = "none"
+
+
+def epoch_to_datetime(value: Any) -> datetime | None:
+    """`None` for never/unset (BloodHound stores 0 or -1)."""
+    try:
+        ts = float(value)
+    except (TypeError, ValueError):
+        return None
+    if ts <= 0:
+        return None
+    return datetime.fromtimestamp(ts, tz=UTC)
+
+
+def opt_bool(props: dict[str, Any], key: str) -> bool | None:
+    value = props.get(key)
+    return None if value is None else bool(value)
+
+
+def last_logon(props: dict[str, Any]) -> int | float | None:
+    """Most recent of `lastlogon` and the replicated `lastlogontimestamp`."""
+    values = [v for v in (props.get("lastlogon"), props.get("lastlogontimestamp")) if isinstance(v, (int, float))]
+    return max(values) if values else None
+
+
+def _risk_if(value: bool | None, risk: Risk = "high") -> Risk:
+    return risk if value else "none"
+
+
+class ADObject:
+    def __init__(self, node: Node) -> None:
+        self.node = node
+        self.props = node.properties
+
+    @staticmethod
+    def wrap(node: Node) -> ADObject:
+        cls = {"User": User, "Computer": Computer, "Group": Group}.get(node.kind, ADObject)
+        return cls(node)
+
+    def _common_head(self) -> list[SummaryField]:
+        return [
+            SummaryField("Name", self.node.name),
+            SummaryField("Type", self.node.kind),
+            SummaryField("Object ID (SID)", self.node.objectid),
+            SummaryField("Domain", self.node.domain),
+        ]
+
+    def _common_tail(self) -> list[SummaryField]:
+        return [
+            SummaryField("Description", self.props.get("description") or ""),
+            SummaryField("Tier Zero / High Value", self.node.tier_zero, "bool",
+                         _risk_if(self.node.tier_zero, "medium")),
+            SummaryField("Owned", self.node.owned, "bool", _risk_if(self.node.owned, "info")),
+        ]
+
+    def summary(self) -> list[SummaryField]:
+        return [*self._common_head(), *self._common_tail()]
+
+
+class User(ADObject):
+    def summary(self) -> list[SummaryField]:
+        p = self.props
+        enabled = opt_bool(p, "enabled")
+        admincount = opt_bool(p, "admincount")
+        hasspn = opt_bool(p, "hasspn")
+        asrep = opt_bool(p, "dontreqpreauth")
+        unconstrained = opt_bool(p, "unconstraineddelegation")
+        t2a = opt_bool(p, "trustedtoauth")
+        sensitive = opt_bool(p, "sensitive")
+        return [
+            *self._common_head(),
+            SummaryField("Enabled", enabled, "bool"),
+            SummaryField("AdminCount", admincount, "bool", _risk_if(admincount, "medium")),
+            SummaryField("Kerberoastable (hasspn)", hasspn, "bool", _risk_if(hasspn and enabled is not False)),
+            SummaryField("SPNs", p.get("serviceprincipalnames") or [], "list"),
+            SummaryField("AS-REP Roastable (dontreqpreauth)", asrep, "bool", _risk_if(asrep and enabled is not False)),
+            SummaryField("Unconstrained Delegation", unconstrained, "bool", _risk_if(unconstrained)),
+            SummaryField("Constrained Delegation (trustedtoauth)", t2a, "bool", _risk_if(t2a)),
+            SummaryField("Allowed To Delegate To", p.get("allowedtodelegate") or [], "list"),
+            SummaryField("Password Never Expires", opt_bool(p, "pwdneverexpires"), "bool",
+                         _risk_if(opt_bool(p, "pwdneverexpires"), "medium")),
+            SummaryField("Password Not Required", opt_bool(p, "passwordnotreqd"), "bool",
+                         _risk_if(opt_bool(p, "passwordnotreqd"))),
+            SummaryField("Password Last Set", p.get("pwdlastset"), "date"),
+            SummaryField("Last Logon", last_logon(p), "date"),
+            SummaryField("Sensitive (cannot be delegated)", sensitive, "bool"),
+            *self._common_tail(),
+        ]
+
+
+class Computer(ADObject):
+    def summary(self) -> list[SummaryField]:
+        p = self.props
+        unconstrained = opt_bool(p, "unconstraineddelegation")
+        t2a = opt_bool(p, "trustedtoauth")
+        haslaps = opt_bool(p, "haslaps")
+        return [
+            *self._common_head(),
+            SummaryField("Enabled", opt_bool(p, "enabled"), "bool"),
+            SummaryField("Operating System", p.get("operatingsystem") or ""),
+            SummaryField("Unconstrained Delegation", unconstrained, "bool",
+                         _risk_if(unconstrained and not self.node.tier_zero)),
+            SummaryField("Constrained Delegation (trustedtoauth)", t2a, "bool", _risk_if(t2a)),
+            SummaryField("Allowed To Delegate To", p.get("allowedtodelegate") or [], "list"),
+            SummaryField("LAPS Enabled", haslaps, "bool", "medium" if haslaps is False else "none"),
+            SummaryField("Last Logon", last_logon(p), "date"),
+            *self._common_tail(),
+        ]
+
+
+class Group(ADObject):
+    def summary(self) -> list[SummaryField]:
+        admincount = opt_bool(self.props, "admincount")
+        return [
+            *self._common_head(),
+            SummaryField("AdminCount", admincount, "bool", _risk_if(admincount, "medium")),
+            *self._common_tail(),
+        ]

bhshell/models/results.py

@@ -0,0 +1,83 @@
+"""Result containers returned by the query layer and consumed by renderers/exporters."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any, Literal
+
+from bhshell.models.entities import ADObject, Node
+
+Backend = Literal["cypher", "rest"]
+
+
+@dataclass
+class RelationshipRow:
+    """One relationship in a view.
+
+    Not every view fills every field; `Column` definitions on the
+    owning `ViewResult` select which ones are displayed.
+    """
+
+    principal: str = ""
+    principal_kind: str = ""
+    edge: str = ""
+    target: str = ""
+    target_kind: str = ""
+    via: str = ""
+    depth: int | None = None
+    tier_zero: bool = False
+    owned: bool = False
+    objectid: str = ""
+
+    def as_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class Column:
+    """A table column: `attr` is a row key; `fmt` picks the cell formatting (see `Renderer.fmt_value`)."""
+
+    header: str
+    attr: str
+    fmt: str = ""
+
+
+@dataclass
+class ViewResult:
+    """The outcome of one relationship view (groups, outbound, ...)."""
+
+    key: str
+    title: str
+    columns: list[Column]
+    rows: list[RelationshipRow] = field(default_factory=list)
+    backend: Backend = "cypher"
+    notes: list[str] = field(default_factory=list)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "view": self.key,
+            "title": self.title,
+            "backend": self.backend,
+            "notes": self.notes,
+            "rows": [r.as_dict() for r in self.rows],
+        }
+
+
+@dataclass
+class EntityReport:
+    """A summary and/or a set of relationship views for one entity."""
+
+    node: Node
+    show_summary: bool = True
+    views: list[ViewResult] = field(default_factory=list)
+
+    @property
+    def entity(self) -> ADObject:
+        return ADObject.wrap(self.node)
+
+    def as_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {"entity": self.node.as_dict()}
+        if self.show_summary:
+            out["summary"] = {f.label: f.value for f in self.entity.summary()}
+        out["views"] = {v.key: v.as_dict() for v in self.views}
+        return out