bhshell 0.1.0__py3-none-any.whl

bhshell/__init__.py

@@ -0,0 +1,3 @@
+"""bhshell - an interactive shell for BloodHound."""
+
+__version__ = "0.1.0"

bhshell/__main__.py

@@ -0,0 +1,3 @@
+from bhshell.cli import main
+
+raise SystemExit(main())

bhshell/cli.py

@@ -0,0 +1,55 @@
+"""Command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Sequence
+
+from cmd2.string_utils import quote_if_needed
+
+from bhshell import __version__
+from bhshell.client.client import normalize_url
+from bhshell.config import Config
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="bhshell", description="Interactive shell for BloodHound.")
+    p.add_argument("--url", help="BH backend URL (persisted; default http://127.0.0.1:8080/)")
+    p.add_argument("-k", "--insecure", action="store_true", help="disable TLS certificate verification (persisted; 'tls on' re-enables it)")
+    p.add_argument("--no-resume", action="store_true", help="do not resume the cached session")
+    p.add_argument("-c", "--command", action="append", default=[], metavar="CMD",
+                   help="run CMD and exit (repeatable)")
+    p.add_argument("-s", "--script", metavar="FILE", help="run commands from FILE and exit")
+    p.add_argument("--debug", action="store_true", help="show tracebacks for errors")
+    p.add_argument("--version", action="version", version=f"bhshell {__version__}")
+    return p
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    config = Config.load()
+    changed = False
+    if args.url:
+        try:
+            config.url = normalize_url(args.url)
+        except ValueError as exc:
+            print(f"error: {exc}", file=sys.stderr)
+            return 2
+        changed = True
+    if args.insecure:
+        config.verify_tls = False
+        changed = True
+    if changed:
+        config.save()
+
+    from bhshell.shell.app import BHShell  # imported late so '--help' stays fast
+
+    app = BHShell(config, debug=args.debug, resume=not args.no_resume)
+    if args.command or args.script:
+        commands = list(args.command)
+        if args.script:
+            commands.append(f"run_script {quote_if_needed(args.script)}")
+        app.runcmds_plus_hooks(commands)
+        return app.exit_code or (1 if app.command_failures else 0)
+    return app.cmdloop() or 0

bhshell/client/auth.py

@@ -0,0 +1,74 @@
+"""Request authenticators for the BH API.
+
+Two schemes are supported:
+
+* `JWTAuth` - `Authorization: Bearer <session_token>` obtained from
+  `POST /api/v2/login`.
+* `HMACAuth` - BH API tokens (Token ID + Token Key). Each request is
+  signed with a chained HMAC-SHA256 as documented by SpecterOps:
+
+  1. `k1 = HMAC(token_key, METHOD + URI)`
+  2. `k2 = HMAC(k1, RequestDate[:13])`  (RFC3339 date truncated to the hour)
+  3. `signature = HMAC(k2, body)`
+
+  Headers: `Authorization: bhesignature <token_id>`, `RequestDate` and
+  `Signature` (base64).
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import hmac
+from collections.abc import Callable
+from datetime import datetime
+from urllib.parse import urlsplit
+
+from requests import PreparedRequest
+from requests.auth import AuthBase
+
+
+class JWTAuth(AuthBase):
+    def __init__(self, token: str) -> None:
+        self.token = token
+
+    def __call__(self, r: PreparedRequest) -> PreparedRequest:
+        r.headers["Authorization"] = f"Bearer {self.token}"
+        return r
+
+
+class HMACAuth(AuthBase):
+    def __init__(
+        self,
+        token_id: str,
+        token_key: str,
+        *,
+        clock: Callable[[], datetime] | None = None,
+    ) -> None:
+        self.token_id = token_id
+        self._key = token_key.encode()
+        self._clock = clock or (lambda: datetime.now().astimezone())
+
+    @staticmethod
+    def _request_uri(url: str) -> str:
+        parts = urlsplit(url)
+        return parts.path + (f"?{parts.query}" if parts.query else "")
+
+    def sign(self, method: str, uri: str, body: bytes | None, request_date: str) -> str:
+        digester = hmac.new(self._key, None, hashlib.sha256)
+        digester.update(f"{method.upper()}{uri}".encode())
+        digester = hmac.new(digester.digest(), None, hashlib.sha256)
+        digester.update(request_date[:13].encode())
+        digester = hmac.new(digester.digest(), None, hashlib.sha256)
+        if body:
+            digester.update(body)
+        return base64.b64encode(digester.digest()).decode()
+
+    def __call__(self, r: PreparedRequest) -> PreparedRequest:
+        request_date = self._clock().isoformat("T")
+        body = r.body.encode() if isinstance(r.body, str) else r.body
+        signature = self.sign(r.method or "GET", self._request_uri(r.url or ""), body, request_date)
+        r.headers["Authorization"] = f"bhesignature {self.token_id}"
+        r.headers["RequestDate"] = request_date
+        r.headers["Signature"] = signature
+        return r

bhshell/client/client.py

@@ -0,0 +1,337 @@
+"""BH REST API v2 transport: auth, retries, error mapping and pagination.
+
+Returns decoded JSON as-is; bhshell.queries makes sense of it."""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+from collections.abc import Iterator
+from typing import Any, Literal
+from urllib.parse import urljoin, urlsplit
+
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util.retry import Retry
+
+from bhshell import __version__
+from bhshell.client.auth import HMACAuth, JWTAuth
+from bhshell.config import DEFAULT_URL
+from bhshell.errors import (
+    ApiError,
+    AuthError,
+    ConnectionFailed,
+    CypherDisabledError,
+    ForbiddenError,
+    LoginFailed,
+    MFARequired,
+    NotAuthenticated,
+    NotFoundError,
+)
+
+AuthMode = Literal["none", "jwt", "hmac"]
+
+_MFA_MARKERS = ("otp", "one time", "one-time", "mfa", "totp")
+
+
+def normalize_url(url: str) -> str:
+    url = url.strip()
+    if not url:
+        return DEFAULT_URL
+    if "://" not in url:
+        url = f"http://{url}"
+    parts = urlsplit(url)
+    if parts.scheme not in ("http", "https") or not parts.netloc:
+        raise ValueError(f"Invalid backend URL: {url!r}")
+    return f"{parts.scheme}://{parts.netloc}{parts.path.rstrip('/')}/"
+
+
+def route_missing(exc: NotFoundError) -> bool:
+    """Whether a 404 means the endpoint does not exist (Go's router), not that nothing was found."""
+    return "page not found" in exc.message.lower()
+
+
+def jwt_claims(token: str) -> dict[str, Any]:
+    """The payload of a JWT, not verified."""
+    try:
+        payload = token.split(".")[1]
+        payload += "=" * (-len(payload) % 4)
+        return json.loads(base64.urlsafe_b64decode(payload))
+    except (IndexError, ValueError):
+        return {}
+
+
+class BHClient:
+    def __init__(
+        self,
+        base_url: str = DEFAULT_URL,
+        *,
+        verify_tls: bool = True,
+        timeout: tuple[float, float] = (5.0, 60.0),
+        page_size: int = 500,
+    ) -> None:
+        self.base_url = normalize_url(base_url)
+        self.verify_tls = verify_tls
+        self.timeout = timeout
+        self.page_size = page_size
+        self.auth_mode: AuthMode = "none"
+        self.username: str = ""
+        self.token_id: str = ""
+        self.jwt: str = ""
+        self._auth: requests.auth.AuthBase | None = None
+
+        self._session = requests.Session()
+        self._session.headers.update({"User-Agent": f"bhshell/{__version__}", "Accept": "application/json"})
+        retry = Retry(
+            total=3,
+            backoff_factor=0.5,
+            status_forcelist=(429, 502, 503, 504),
+            # Only idempotent methods, and never after a read timeout: a slow Cypher
+            # query (POST) would otherwise run up to four times on the server.
+            read=False,
+            allowed_methods=frozenset({"GET", "PUT", "DELETE"}),
+            respect_retry_after_header=True,
+            raise_on_status=False,
+        )
+        adapter = HTTPAdapter(max_retries=retry)
+        self._session.mount("http://", adapter)
+        self._session.mount("https://", adapter)
+
+    @property
+    def host(self) -> str:
+        return urlsplit(self.base_url).netloc
+
+    @property
+    def is_authenticated(self) -> bool:
+        return self._auth is not None
+
+    def set_url(self, url: str) -> None:
+        """Credentials are dropped when the URL changes."""
+        new = normalize_url(url)
+        if new != self.base_url:
+            self.clear_auth()
+        self.base_url = new
+
+    def set_jwt(self, token: str, username: str = "") -> None:
+        self._auth = JWTAuth(token)
+        self.auth_mode = "jwt"
+        self.jwt = token
+        self.username = username
+        self.token_id = ""
+
+    def set_hmac(self, token_id: str, token_key: str) -> None:
+        self._auth = HMACAuth(token_id, token_key)
+        self.auth_mode = "hmac"
+        self.token_id = token_id
+        self.jwt = ""
+        self.username = ""
+
+    def auth_state(self) -> tuple[Any, ...]:
+        return (self._auth, self.auth_mode, self.username, self.token_id, self.jwt)
+
+    def restore_auth(self, state: tuple[Any, ...]) -> None:
+        self._auth, self.auth_mode, self.username, self.token_id, self.jwt = state
+
+    def clear_auth(self) -> None:
+        self._auth = None
+        self.auth_mode = "none"
+        self.username = ""
+        self.token_id = ""
+        self.jwt = ""
+
+    def token_expiry(self) -> float | None:
+        if self.auth_mode != "jwt":
+            return None
+        exp = jwt_claims(self.jwt).get("exp")
+        return float(exp) if isinstance(exp, (int, float)) else None
+
+    def token_expired(self) -> bool:
+        exp = self.token_expiry()
+        return exp is not None and exp <= time.time()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+        json_body: Any = None,
+        auth: bool = True,
+    ) -> Any:
+        if auth and self._auth is None:
+            raise NotAuthenticated("Not authenticated")
+        url = urljoin(self.base_url, path.lstrip("/"))
+        try:
+            resp = self._session.request(
+                method,
+                url,
+                params=params,
+                json=json_body,
+                auth=self._auth if auth else None,
+                timeout=self.timeout,
+                verify=self.verify_tls,
+            )
+        except requests.exceptions.SSLError as exc:
+            raise ConnectionFailed(
+                f"TLS error talking to {self.host}: {exc}",
+                hint="Use 'tls off' for self-signed certificates.",
+            ) from exc
+        except requests.exceptions.Timeout as exc:
+            raise ConnectionFailed(f"Request to {url} timed out") from exc
+        except requests.exceptions.RequestException as exc:
+            raise ConnectionFailed(f"Cannot reach BH at {self.base_url} ({exc.__class__.__name__})") from exc
+        return self._handle(resp)
+
+    @staticmethod
+    def _error_message(resp: requests.Response) -> str:
+        try:
+            body = resp.json()
+        except ValueError:
+            return resp.text.strip()[:300] or resp.reason or "unknown error"
+        if isinstance(body, dict):
+            errors = body.get("errors")
+            if isinstance(errors, list) and errors:
+                msgs = [e.get("message", "") for e in errors if isinstance(e, dict)]
+                if any(msgs):
+                    return "; ".join(m for m in msgs if m)
+            for key in ("message", "error"):
+                if isinstance(body.get(key), str):
+                    return body[key]
+        return str(body)[:300]
+
+    def _handle(self, resp: requests.Response) -> Any:
+        if resp.status_code < 300:
+            if not resp.content:
+                return None
+            try:
+                return resp.json()
+            except ValueError as exc:
+                raise ApiError(resp.status_code, "Response is not valid JSON") from exc
+        msg = self._error_message(resp)
+        if resp.status_code == 401:
+            raise AuthError(f"Unauthorized: {msg}")
+        if resp.status_code == 403:
+            raise ForbiddenError(f"Forbidden: {msg}")
+        if resp.status_code == 404:
+            raise NotFoundError(msg or "Not found")
+        raise ApiError(resp.status_code, msg)
+
+    def get(self, path: str, **params: Any) -> Any:
+        return self.request("GET", path, params=params or None)
+
+    def paginate(self, path: str, *, limit: int | None = None, **params: Any) -> Iterator[dict[str, Any]]:
+        skip = 0
+        yielded = 0
+        while True:
+            page = self.get(path, skip=skip, limit=self.page_size, **params) or {}
+            items = page.get("data") or []
+            if isinstance(items, dict):  # e.g. asset-group-tags selectors: {"data": {"selectors": [...]}}
+                items = next((v for v in items.values() if isinstance(v, list)), [])
+            if not items:
+                return
+            for item in items:
+                yield item
+                yielded += 1
+                if limit is not None and yielded >= limit:
+                    return
+            count = page.get("count")
+            skip += len(items)
+            # Trust the total when there is one: the server may cap `limit` below our page size.
+            done = (skip >= count) if isinstance(count, int) else (len(items) < self.page_size)
+            if done:
+                return
+
+    def login(self, username: str, password: str, otp: str | None = None) -> dict[str, Any]:
+        """Switch to JWT auth. Returns the login response's `data` (user_id, auth_expired, session_token)."""
+        body: dict[str, Any] = {"login_method": "secret", "username": username, "secret": password}
+        if otp:
+            body["otp"] = otp
+        try:
+            resp = self.request("POST", "api/v2/login", json_body=body, auth=False)
+        except (AuthError, ApiError) as exc:
+            text = exc.message.lower()
+            if not otp and any(marker in text for marker in _MFA_MARKERS):
+                raise MFARequired("A one-time password is required for this account") from exc
+            if isinstance(exc, AuthError):
+                raise LoginFailed("Login failed: invalid username or password") from exc
+            raise
+        data = (resp or {}).get("data") or {}
+        token = data.get("session_token")
+        if not token:
+            raise ApiError(200, "Login response did not contain a session token")
+        self.set_jwt(token, username)
+        return data
+
+    def logout(self) -> None:
+        try:
+            if self.auth_mode == "jwt":
+                self.request("POST", "api/v2/logout")
+        except (AuthError, NotFoundError, ApiError, ConnectionFailed):
+            pass
+        finally:
+            self.clear_auth()
+
+    def self_info(self) -> dict[str, Any]:
+        # BH answers unauthenticated requests here with 200 {"data": null} instead of 401.
+        data = (self.get("api/v2/self") or {}).get("data")
+        if not data:
+            raise AuthError("Not authenticated (server returned no principal)")
+        return data
+
+    def version(self) -> dict[str, Any]:
+        return (self.get("api/version") or {}).get("data") or {}
+
+    def cypher(self, query: str, include_properties: bool = True) -> dict[str, Any]:
+        body = {"query": query, "include_properties": include_properties}
+        try:
+            resp = self.request("POST", "api/v2/graphs/cypher", json_body=body)
+        except NotFoundError as exc:  # also how BH answers an empty result
+            if route_missing(exc):
+                raise CypherDisabledError("The cypher endpoint does not exist on this server") from exc
+            return {"nodes": {}, "edges": [], "literals": []}
+        except ForbiddenError as exc:
+            raise CypherDisabledError(f"Cypher queries are not permitted: {exc.message}") from exc
+        except ApiError as exc:
+            if exc.status in (405, 501):
+                raise CypherDisabledError(f"Cypher queries are disabled: {exc.detail}") from exc
+            raise
+        data = (resp or {}).get("data") or {}
+        nodes = data.get("nodes") or {}
+        edges = data.get("edges") or []
+        return {"nodes": nodes, "edges": edges, "literals": data.get("literals") or []}
+
+    def search(self, query: str, kind: str | None = None) -> list[dict[str, Any]]:
+        params: dict[str, Any] = {"q": query}
+        if kind:
+            params["type"] = kind
+        resp = self.get("api/v2/search", **params) or {}
+        data = resp.get("data") or []
+        return data if isinstance(data, list) else []
+
+    def entity(self, kind: str, objectid: str) -> dict[str, Any]:
+        resp = self.get(f"api/v2/{_collection(kind)}/{objectid}", counts="false") or {}
+        data = resp.get("data") or {}
+        return data.get("props") or data
+
+    def entity_related(
+        self, kind: str, objectid: str, relation: str, *, limit: int | None = None
+    ) -> list[dict[str, Any]]:
+        path = f"api/v2/{_collection(kind)}/{objectid}/{relation}"
+        return list(self.paginate(path, limit=limit, type="list"))
+
+
+def _collection(kind: str) -> str:
+    mapping = {
+        "user": "users",
+        "computer": "computers",
+        "group": "groups",
+        "domain": "domains",
+        "gpo": "gpos",
+        "ou": "ous",
+        "container": "containers",
+    }
+    try:
+        return mapping[kind.lower()]
+    except KeyError as exc:
+        raise ValueError(f"No REST collection for kind {kind!r}") from exc

bhshell/config.py

@@ -0,0 +1,162 @@
+"""Persistent configuration and session cache.
+
+Layout (overridable with the `BHSHELL_HOME` environment variable):
+
+    ~/.bhshell/
+        config.toml    # backend URL, TLS, timeouts, last username, query folders
+        session.json   # cached JWT (mode 0600)
+        history        # cmd2 command history
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import os
+import tomllib
+from dataclasses import asdict, dataclass, fields
+from pathlib import Path
+from typing import Any
+
+DEFAULT_URL = "http://127.0.0.1:8080/"
+
+
+def config_home() -> Path:
+    home = Path(os.environ.get("BHSHELL_HOME", Path.home() / ".bhshell")).expanduser()
+    home.mkdir(mode=0o700, parents=True, exist_ok=True)
+    return home
+
+
+# Lowest accepted value of numeric settings (`display_rows` 0 means "all rows").
+_MINIMUMS: dict[str, float] = {"connect_timeout": 1, "read_timeout": 1, "page_size": 1, "max_results": 1,
+                               "display_rows": 0}
+
+
+def parse_bool(value: str) -> bool:
+    lowered = value.strip().lower()
+    if lowered in ("1", "true", "yes", "on"):
+        return True
+    if lowered in ("0", "false", "no", "off"):
+        return False
+    raise ValueError(f"not a boolean: {value!r}")
+
+
+def _toml_value(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return repr(value)
+    # JSON string escaping is a valid subset of TOML basic strings.
+    return json.dumps(str(value))
+
+
+def _write_private(path: Path, content: str) -> None:
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as fh:
+        fh.write(content)
+    os.chmod(path, 0o600)
+
+
+@dataclass
+class Config:
+    url: str = DEFAULT_URL
+    verify_tls: bool = True
+    connect_timeout: float = 5.0
+    read_timeout: float = 60.0
+    last_username: str = ""
+    page_size: int = 500
+    max_results: int = 5000
+    display_rows: int = 100
+    cache_session: bool = True
+    # Extra folders of .cyp queries for 'query', separated like PATH (':' on Unix, ';' on Windows).
+    query_dirs: str = ""
+
+    @classmethod
+    def path(cls) -> Path:
+        return config_home() / "config.toml"
+
+    @classmethod
+    def load(cls) -> Config:
+        """Unknown keys and invalid values are ignored."""
+        path = cls.path()
+        if not path.exists():
+            return cls()
+        try:
+            data = tomllib.loads(path.read_text(encoding="utf-8"))
+        except (OSError, tomllib.TOMLDecodeError):
+            return cls()
+        known = {f.name for f in fields(cls)}
+        cfg = cls()
+        for key, value in data.items():
+            if key in known:
+                try:
+                    setattr(cfg, key, cls.coerce(key, value))
+                except (TypeError, ValueError):
+                    pass
+        return cfg
+
+    @classmethod
+    def coerce(cls, key: str, value: Any) -> Any:
+        """Convert `value` to the type of setting `key`.
+
+        Raises TypeError for a value of the wrong type, ValueError for an invalid one.
+        """
+        default = getattr(cls(), key)
+        if isinstance(default, bool):
+            return value if isinstance(value, bool) else parse_bool(str(value))
+        if isinstance(default, (int, float)):
+            if isinstance(value, bool):
+                raise TypeError(f"expected a number, got {value!r}")
+            number = type(default)(value)
+            if not math.isfinite(number):
+                raise ValueError(f"not a finite number: {value!r}")
+            minimum = _MINIMUMS.get(key)
+            if minimum is not None and number < minimum:
+                raise ValueError(f"must be at least {minimum}")
+            return number
+        if key == "url":
+            from bhshell.client.client import normalize_url  # late: the client imports this module
+
+            return normalize_url(str(value))
+        return str(value)
+
+    def save(self) -> None:
+        lines = ["# bhshell configuration", *(f"{k} = {_toml_value(v)}" for k, v in asdict(self).items())]
+        _write_private(self.path(), "\n".join(lines) + "\n")
+
+
+@dataclass
+class CachedSession:
+    url: str
+    token: str
+    username: str = ""
+
+    @staticmethod
+    def path() -> Path:
+        return config_home() / "session.json"
+
+    @classmethod
+    def load(cls) -> CachedSession | None:
+        path = cls.path()
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            session = cls(url=data["url"], token=data["token"], username=data.get("username", ""))
+        except (OSError, ValueError, KeyError, TypeError):
+            return None
+        if not all(isinstance(v, str) for v in (session.url, session.token, session.username)):
+            return None
+        return session
+
+    def save(self) -> None:
+        _write_private(self.path(), json.dumps(asdict(self)))
+
+    @classmethod
+    def clear(cls) -> None:
+        try:
+            cls.path().unlink()
+        except FileNotFoundError:
+            pass
+
+
+def history_file() -> Path:
+    return config_home() / "history"