bhshell 0.1.0__py3-none-any.whl

bhshell/queries/cypher.py

@@ -0,0 +1,155 @@
+"""Cypher query templates.
+
+BH's Cypher endpoint does not accept bound parameters, so every value is
+embedded as an escaped string literal via `lit`. Queries return paths or
+nodes (not scalars) so that results come back as a graph.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+from bhshell.queries.edges import EXEC_EDGES, HAS_SESSION, MEMBER_OF
+
+
+def lit(value: str) -> str:
+    escaped = value.replace("\\", "\\\\").replace("'", "\\'")
+    return f"'{escaped}'"
+
+
+_RETURN_LIMIT = re.compile(r"\s+RETURN\s+(\w+)\s+LIMIT\s+(\d+)\s*$", re.IGNORECASE)
+
+
+def limit_of(query: str) -> int | None:
+    """The LIMIT of a `... RETURN x LIMIT n` query (`None` for other shapes)."""
+    m = _RETURN_LIMIT.search(query)
+    return int(m.group(2)) if m else None
+
+
+def to_count(query: str) -> str | None:
+    """Turn `... RETURN x LIMIT n` into `... RETURN count(x)` (`None` for other shapes)."""
+    m = _RETURN_LIMIT.search(query)
+    return f"{query[:m.start()]} RETURN count({m.group(1)})" if m else None
+
+
+def where(*conds: str) -> str:
+    """` WHERE a AND b` from the non-empty conditions, or ''."""
+    present = [c for c in conds if c]
+    return f" WHERE {' AND '.join(present)}" if present else ""
+
+
+def domain_condition(alias: str, domain: str) -> str:
+    """Restrict `alias` to `domain`: an FQDN matches exactly, a NetBIOS name any FQDN it starts ('' = all)."""
+    if not domain:
+        return ""
+    d = domain.upper()
+    if "." in d:
+        return f"{alias}.domain = {lit(d)}"
+    return f"({alias}.domain = {lit(d)} OR {alias}.domain STARTS WITH {lit(d + '.')})"
+
+
+def edge_types(edges: Iterable[str]) -> str:
+    """`A|B|C`, for a relationship pattern."""
+    return "|".join(sorted(edges))
+
+
+def _label(kind: str | None) -> str:
+    return f":{kind}" if kind else ":Base"
+
+
+def by_objectid(objectid: str) -> str:
+    return f"MATCH (n:Base) WHERE n.objectid = {lit(objectid)} RETURN n"
+
+
+def by_name(conditions: list[str], kind: str | None, limit: int) -> str:
+    return f"MATCH (n{_label(kind)}) WHERE {' OR '.join(conditions)} RETURN n LIMIT {limit}"
+
+
+def name_conditions(sam: str, fqdn: str | None, kind: str | None) -> list[str]:
+    """WHERE conditions matching an object by samaccountname or FQDN.
+
+    BloodHound stores `name` upper-cased as `SAM@DOMAIN` (users, groups)
+    or `HOST.DOMAIN` (computers); `samaccountname` keeps the original case.
+    """
+    upper = sam.upper()
+    host = upper.rstrip("$")
+    conds: list[str] = []
+    if fqdn:
+        conds.append(f"n.name = {lit(fqdn.upper())}")
+    if kind in (None, "User", "Group"):
+        conds.append(f"n.name STARTS WITH {lit(upper + '@')}")
+    if kind in (None, "Computer"):
+        conds += [
+            f"n.name STARTS WITH {lit(host + '.')}",
+            f"n.name = {lit(host)}",
+            f"n.samaccountname = {lit(host + '$')}",
+        ]
+    conds.append(f"n.samaccountname = {lit(sam)}")
+    return list(dict.fromkeys(conds))
+
+
+def member_of(objectid: str) -> str:
+    return f"MATCH p=(n:Base)-[:{MEMBER_OF}*1..]->(g:Group) WHERE n.objectid = {lit(objectid)} RETURN p"
+
+
+def members(objectid: str, limit: int) -> str:
+    return f"MATCH p=(m:Base)-[:{MEMBER_OF}*1..]->(g:Group) WHERE g.objectid = {lit(objectid)} RETURN p LIMIT {limit}"
+
+
+def _rel(edges: Iterable[str] | None) -> str:
+    return f"[r:{edge_types(edges)}]" if edges else "[r]"
+
+
+def outgoing_direct(objectid: str, limit: int, edges: Iterable[str] | None = None) -> str:
+    """Outgoing edges of the node (all kinds when `edges` is `None`)."""
+    return f"MATCH p=(n:Base)-{_rel(edges)}->(t:Base) WHERE n.objectid = {lit(objectid)} RETURN p LIMIT {limit}"
+
+
+def outgoing_inherited(objectid: str, limit: int, edges: Iterable[str] | None = None) -> str:
+    """Edges held by any group the node is (transitively) a member of."""
+    return (
+        f"MATCH p=(n:Base)-[:{MEMBER_OF}*1..]->(g:Group)-{_rel(edges)}->(t:Base) "
+        f"WHERE n.objectid = {lit(objectid)} RETURN p LIMIT {limit}"
+    )
+
+
+def incoming(objectid: str, edges: Iterable[str], limit: int) -> str:
+    return (
+        f"MATCH p=(s:Base)-[r:{edge_types(edges)}]->(n:Base) "
+        f"WHERE n.objectid = {lit(objectid)} RETURN p LIMIT {limit}"
+    )
+
+
+def incoming_any(objectid: str, limit: int) -> str:
+    """Fallback for `incoming` when a kind in the filter is unknown to the server."""
+    return f"MATCH p=(s:Base)-[r]->(n:Base) WHERE n.objectid = {lit(objectid)} RETURN p LIMIT {limit}"
+
+
+def exec_rights_inbound_unrolled(objectid: str, limit: int, edges: Iterable[str] = EXEC_EDGES) -> str:
+    return (
+        f"MATCH p=(m:Base)-[:{MEMBER_OF}*1..]->(g:Group)-[r:{edge_types(edges)}]->(c:Computer) "
+        f"WHERE c.objectid = {lit(objectid)} RETURN p LIMIT {limit}"
+    )
+
+
+def sessions_of_user(objectid: str, limit: int) -> str:
+    return (
+        f"MATCH p=(c:Computer)-[:{HAS_SESSION}]->(u:User) "
+        f"WHERE u.objectid = {lit(objectid)} RETURN p LIMIT {limit}"
+    )
+
+
+def sessions_on_computer(objectid: str, limit: int) -> str:
+    return (
+        f"MATCH p=(c:Computer)-[:{HAS_SESSION}]->(u:User) "
+        f"WHERE c.objectid = {lit(objectid)} RETURN p LIMIT {limit}"
+    )
+
+
+def sessions_of_group_members(objectid: str, limit: int) -> str:
+    return (
+        f"MATCH p=(c:Computer)-[:{HAS_SESSION}]->(u:User)-[:{MEMBER_OF}*1..]->(g:Group) "
+        f"WHERE g.objectid = {lit(objectid)} RETURN p LIMIT {limit}"
+    )
+

bhshell/queries/domains.py

@@ -0,0 +1,136 @@
+"""Domain overview and trust analysis."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from bhshell.errors import NotFoundError
+from bhshell.models.entities import TIER_ZERO_LABEL, Graph, Node, opt_bool
+from bhshell.queries import cypher as Q
+from bhshell.queries.edges import TRUST_ABUSE_EDGES, TRUST_EDGES
+from bhshell.queries.service import EntityService
+
+TRUSTS_QUERY = "MATCH p=(a:Domain)-[r]->(b:Domain) RETURN p"
+
+
+@dataclass
+class DomainInfo:
+    name: str
+    sid: str
+    functional_level: str = ""
+    collected: bool | None = None
+    last_collected: str = ""
+    counts: dict[str, int | None] = field(default_factory=dict)
+
+    def as_dict(self) -> dict[str, Any]:
+        return {**{k: v for k, v in asdict(self).items() if k != "counts"}, **self.counts}
+
+
+@dataclass
+class TrustInfo:
+    """One trust: `trusting` trusts `trusted`; principals of `trusted` can access `trusting`."""
+
+    trusting: str
+    trusted: str
+    kind: str
+    trust_type: str = ""
+    transitive: bool | None = None
+    sid_filtering: bool | None = None
+    tgt_delegation: bool | None = None
+    abuse: list[str] = field(default_factory=list)
+
+    @property
+    def same_forest(self) -> bool:
+        return self.kind == "SameForestTrust"
+
+    @property
+    def issues(self) -> list[str]:
+        """Weaknesses the collected data shows.
+
+        SID filtering is on by default for cross-forest (and external) trusts and off within a
+        forest, so a missing `spoofsidhistoryblocked` property on a cross-forest trust is not
+        reported: only an explicit `false`, a same-forest trust, or a BloodHound abuse edge is.
+        """
+        out = [f"abusable: {a}" for a in self.abuse]
+        if self.same_forest:
+            out.append("same forest: SID filtering not enforced")
+        elif self.sid_filtering is False:
+            out.append("SID filtering disabled")
+        if self.tgt_delegation:
+            out.append("TGT delegation enabled")
+        return out
+
+    def as_dict(self) -> dict[str, Any]:
+        return {**asdict(self), "abuse": ", ".join(self.abuse), "issues": "; ".join(self.issues)}
+
+
+def trusts_from_graph(graph: Graph) -> list[TrustInfo]:
+    trusts: dict[tuple[str, str], TrustInfo] = {}
+    abuse: dict[tuple[str, str], list[str]] = {}
+    for e in graph.edges:
+        src, dst = graph.nodes[e.source].name, graph.nodes[e.target].name
+        if e.kind in TRUST_EDGES:
+            trusts[(src, dst)] = TrustInfo(
+                trusting=src, trusted=dst, kind=e.kind,
+                trust_type=str(e.properties.get("trusttype") or ""),
+                transitive=opt_bool(e.properties, "transitive"),
+                sid_filtering=opt_bool(e.properties, "spoofsidhistoryblocked"),
+                tgt_delegation=opt_bool(e.properties, "tgtdelegation"),
+            )
+        elif e.kind in TRUST_ABUSE_EDGES:
+            # Abuse edges point in the direction of access: trusted -> trusting.
+            abuse.setdefault((dst, src), []).append(e.kind)
+    for key, kinds in abuse.items():
+        trust = trusts.setdefault(key, TrustInfo(trusting=key[0], trusted=key[1], kind="(abuse only)"))
+        trust.abuse = sorted(set(kinds))
+    return sorted(trusts.values(), key=lambda t: (not t.issues, t.trusting, t.trusted))
+
+
+class DomainService:
+    def __init__(self, entities: EntityService) -> None:
+        self.entities = entities
+        self.client = entities.client
+
+    def domains(self) -> list[DomainInfo]:
+        nodes = {n.objectid: n for n in self.entities.run_cypher("MATCH (n:Domain) RETURN n").nodes.values()}
+        infos: list[DomainInfo] = []
+        try:
+            listed = (self.client.get("api/v2/available-domains") or {}).get("data") or []
+        except NotFoundError:
+            listed = []
+        seen: set[str] = set()
+        for item in listed:
+            if item.get("type", "active-directory") != "active-directory":
+                continue
+            sid = item.get("id", "")
+            seen.add(sid)
+            infos.append(self._info(item.get("name", sid), sid, nodes.get(sid), item.get("collected")))
+        for sid, node in nodes.items():
+            if sid not in seen:
+                infos.append(self._info(node.name, sid, node, None))
+        return sorted(infos, key=lambda d: d.name)
+
+    def _info(self, name: str, sid: str, node: Node | None, collected: bool | None) -> DomainInfo:
+        props = node.properties if node is not None else {}
+        info = DomainInfo(
+            name=name, sid=sid, collected=collected,
+            functional_level=str(props.get("functionallevel") or ""),
+            last_collected=str(props.get("lastcollected") or props.get("lastseen") or "")[:19],
+        )
+        in_domain, enabled = f"n.domain = {Q.lit(name.upper())}", "n.enabled = true"
+        info.counts = {
+            "users": self._count("(n:User)", in_domain),
+            "enabled_users": self._count("(n:User)", in_domain, enabled),
+            "computers": self._count("(n:Computer)", in_domain),
+            "enabled_computers": self._count("(n:Computer)", in_domain, enabled),
+            "groups": self._count("(n:Group)", in_domain),
+            "tier_zero": self._count(f"(n:{TIER_ZERO_LABEL})", in_domain),
+        }
+        return info
+
+    def _count(self, match: str, *conditions: str) -> int | None:
+        return self.entities.count(f"MATCH {match}{Q.where(*conditions)} RETURN count(n)")
+
+    def trusts(self) -> list[TrustInfo]:
+        return trusts_from_graph(self.entities.run_cypher(TRUSTS_QUERY))

bhshell/queries/edges.py

@@ -0,0 +1,109 @@
+"""Edge (relationship) taxonomy used by the relationship views."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+MEMBER_OF = "MemberOf"
+HAS_SESSION = "HasSession"
+
+# Direct object control (ACL abuse).
+ACL_EDGES: frozenset[str] = frozenset({
+    "GenericAll", "GenericWrite", "WriteDacl", "WriteOwner", "Owns",
+    "ForceChangePassword", "AddMember", "AddSelf", "AllExtendedRights",
+    "AddKeyCredentialLink", "WriteSPN", "WriteAccountRestrictions",
+    "WriteGPLink", "WriteOwnerLimitedRights", "OwnsLimitedRights",
+})  # OwnsRaw / WriteOwnerRaw are intentionally excluded: they duplicate Owns / WriteOwner.
+
+# Rights that let the holder re-enable a disabled account (write its userAccountControl, directly
+# or by first granting themselves the right). WriteAccountRestrictions covers userAccountControl.
+ENABLE_EDGES: frozenset[str] = frozenset({
+    "GenericAll", "GenericWrite", "WriteAccountRestrictions", "Owns", "WriteDacl", "WriteOwner",
+})
+
+# Credential access primitives.
+CREDENTIAL_EDGES: frozenset[str] = frozenset({
+    "ReadLAPSPassword", "ReadGMSAPassword", "SyncLAPSPassword", "DumpSMSAPassword",
+    "DCSync", "GetChanges", "GetChangesAll", "GetChangesInFilteredSet", "HasSIDHistory",
+})
+
+# Kerberos delegation.
+DELEGATION_EDGES: frozenset[str] = frozenset({
+    "AllowedToDelegate", "AllowedToAct", "AddAllowedToAct", "CoerceToTGT",
+})
+
+# AD CS abuse.
+ADCS_EDGES: frozenset[str] = frozenset({
+    "Enroll", "ManageCA", "ManageCertificates", "GoldenCert", "WritePKIEnrollmentFlag",
+    "WritePKINameFlag", "ADCSESC1", "ADCSESC3", "ADCSESC4", "ADCSESC6a", "ADCSESC6b",
+    "ADCSESC9a", "ADCSESC9b", "ADCSESC10a", "ADCSESC10b", "ADCSESC13",
+})
+
+# NTLM relay / coercion.
+COERCION_EDGES: frozenset[str] = frozenset({
+    "CoerceAndRelayNTLMToSMB", "CoerceAndRelayNTLMToLDAP", "CoerceAndRelayNTLMToLDAPS",
+    "CoerceAndRelayNTLMToADCS",
+})
+
+# Code execution / logon rights on computers.
+EXEC_EDGES: frozenset[str] = frozenset({"AdminTo", "CanRDP", "ExecuteDCOM", "CanPSRemote", "SQLAdmin"})
+
+# Domain trust relationships (`A -[trust]-> B`: A trusts B, principals of B can access A).
+TRUST_EDGES: frozenset[str] = frozenset({"SameForestTrust", "CrossForestTrust"})
+# Trust edges BloodHound adds when a trust's configuration is abusable.
+TRUST_ABUSE_EDGES: frozenset[str] = frozenset({"SpoofSIDHistory", "AbuseTGTDelegation"})
+
+# Everything shown by the `outbound` / `inbound` views.
+CONTROL_EDGES: frozenset[str] = ACL_EDGES | CREDENTIAL_EDGES | DELEGATION_EDGES | ADCS_EDGES | COERCION_EDGES
+
+# Edges BloodHound treats as traversable for attack-path finding.
+TRAVERSABLE_EDGES: frozenset[str] = (
+    (CONTROL_EDGES - {"GetChanges", "GetChangesAll", "GetChangesInFilteredSet", "Enroll", "ManageCA",
+                      "ManageCertificates", "WritePKIEnrollmentFlag", "WritePKINameFlag"})
+    | EXEC_EDGES | TRUST_EDGES | TRUST_ABUSE_EDGES
+    | {MEMBER_OF, HAS_SESSION, "Contains", "GPLink", "DCFor", "WriteSPN"}
+)
+
+# Hops that need no action: rights flow along them by themselves.
+PASSIVE_EDGES: frozenset[str] = frozenset({MEMBER_OF, "Contains", "GPLink", "DCFor"})
+
+# Names accepted by `path --exclude` for groups of edges.
+EDGE_GROUPS: dict[str, frozenset[str]] = {
+    "sessions": frozenset({HAS_SESSION}),
+    "acl": ACL_EDGES,
+    "exec": EXEC_EDGES,
+    "delegation": DELEGATION_EDGES,
+    "adcs": (ADCS_EDGES | {"CoerceAndRelayNTLMToADCS"}) & TRAVERSABLE_EDGES,
+    "relay": COERCION_EDGES,
+    "trusts": TRUST_EDGES | TRUST_ABUSE_EDGES,
+}
+
+Severity = Literal["critical", "high", "medium", "low"]
+SEVERITIES: tuple[Severity, ...] = ("critical", "high", "medium", "low")  # worst first
+
+_CRITICAL = frozenset({
+    "GenericAll", "WriteDacl", "WriteOwner", "Owns", "DCSync", "GetChangesAll", "AllExtendedRights",
+    "AdminTo", "GoldenCert", "ADCSESC1", "ADCSESC3", "ADCSESC4", "ADCSESC6a", "ADCSESC6b",
+    "ADCSESC9a", "ADCSESC9b", "ADCSESC10a", "ADCSESC10b", "ADCSESC13", "HasSIDHistory",
+})
+_HIGH = frozenset({
+    "GenericWrite", "ForceChangePassword", "AddMember", "AddSelf", "AddKeyCredentialLink",
+    "ReadLAPSPassword", "ReadGMSAPassword", "SyncLAPSPassword", "DumpSMSAPassword",
+    "AllowedToDelegate", "AllowedToAct", "AddAllowedToAct", "WriteAccountRestrictions",
+    "CanPSRemote", "SQLAdmin", "WriteGPLink", "ManageCA", "CoerceToTGT",
+    *COERCION_EDGES,
+})
+
+
+def severity(edge: str) -> Severity:
+    """Rough offensive impact of an edge, used for colouring."""
+    if edge in _CRITICAL:
+        return "critical"
+    if edge in _HIGH:
+        return "high"
+    return "medium"
+
+
+def severity_rank(edge: str) -> int:
+    """Sort key: 0 for critical edges, 1 for high, 2 for medium."""
+    return SEVERITIES.index(severity(edge))