bhshell 0.1.0__py3-none-any.whl

bhshell/shell/commands/connection.py

@@ -0,0 +1,236 @@
+"""Connection, authentication and configuration commands."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import time
+from dataclasses import fields
+from getpass import getpass
+
+from cmd2 import Cmd2ArgumentParser, RawDescriptionCmd2HelpFormatter, with_argparser
+from rich.text import Text
+
+from bhshell.config import CachedSession, Config
+from bhshell.errors import (
+    ApiError,
+    AuthError,
+    BHError,
+    CypherDisabledError,
+    LoginFailed,
+    MFARequired,
+    NotFoundError,
+)
+from bhshell.shell.commands.base import BaseCommands
+
+
+def _url_parser() -> Cmd2ArgumentParser:
+    p = Cmd2ArgumentParser(description="Show or set the BH backend URL (default http://127.0.0.1:8080/).")
+    p.add_argument("url", nargs="?", help="new backend URL, e.g. https://BH.lab:8443")
+    return p
+
+
+def _tls_parser() -> Cmd2ArgumentParser:
+    p = Cmd2ArgumentParser(description="Show or toggle TLS certificate verification.")
+    p.add_argument("state", nargs="?", choices=["on", "off"], help="'off' accepts self-signed certificates")
+    return p
+
+
+def _login_parser() -> Cmd2ArgumentParser:
+    p = Cmd2ArgumentParser(
+        description="Authenticate to BH.",
+        epilog=(
+            "Username/password (JWT): secrets are prompted for, or read from BH_PASSWORD.\n"
+            "API token (HMAC): use --token; the ID/key are read from BH_TOKEN_ID / BH_TOKEN_KEY\n"
+            "or prompted for. Secrets are never accepted as arguments so they stay out of history."
+        ),
+        formatter_class=RawDescriptionCmd2HelpFormatter,
+    )
+    p.add_argument("-u", "--username", help="BH username (defaults to the last one used)")
+    p.add_argument("--otp", metavar="CODE", help="TOTP one-time password, if MFA is enabled")
+    p.add_argument("--token", action="store_true", help="authenticate with an API token (ID + key)")
+    p.add_argument("--token-id", metavar="ID", help="API token ID (implies --token)")
+    return p
+
+
+def _config_parser() -> Cmd2ArgumentParser:
+    keys = [f.name for f in fields(Config)]
+    p = Cmd2ArgumentParser(description="Show or change persistent settings (~/.bhshell/config.toml).")
+    p.add_argument("key", nargs="?", choices=keys, help="setting name")
+    p.add_argument("value", nargs="?", help="new value")
+    return p
+
+
+class ConnectionCommands(BaseCommands):
+    DEFAULT_CATEGORY = "Connection"
+
+    @with_argparser(_url_parser)
+    def do_url(self, args: argparse.Namespace) -> None:
+        """Show or set the BH backend URL."""
+        app = self.app
+        if not args.url:
+            app.ui.info(f"Backend URL: {app.client.base_url}")
+            return
+        previous = app.client.base_url
+        was_auth = app.client.is_authenticated
+        app.client.set_url(args.url)
+        app.config.url = app.client.base_url
+        app.config.save()
+        if app.client.base_url != previous:
+            app.entities.reset()
+            if was_auth:
+                CachedSession.clear()
+                app.ui.warn("Backend changed: local session cleared, run 'login' again.")
+        app.ui.success(f"Backend URL set to {app.client.base_url}")
+
+    @with_argparser(_tls_parser)
+    def do_tls(self, args: argparse.Namespace) -> None:
+        """Show or toggle TLS certificate verification."""
+        app = self.app
+        if args.state:
+            app.config.verify_tls = args.state == "on"
+            app.config.save()
+            app.apply_tls_setting()
+        state = "on" if app.config.verify_tls else "off (insecure)"
+        app.ui.info(f"TLS certificate verification: {state}")
+
+    @with_argparser(_login_parser)
+    def do_login(self, args: argparse.Namespace) -> None:
+        """Authenticate with username/password (JWT) or an API token (HMAC)."""
+        if args.token or args.token_id:
+            self._login_token(args.token_id)
+        else:
+            self._login_password(args.username, args.otp)
+
+    def _login_token(self, token_id: str | None) -> None:
+        app = self.app
+        token_id = token_id or os.environ.get("BH_TOKEN_ID") or app.read_input("Token ID: ").strip()
+        token_key = os.environ.get("BH_TOKEN_KEY") or getpass("Token key: ")
+        if not token_id or not token_key:
+            raise BHError("Token ID and key are required")
+        previous = app.client.auth_state()
+        app.client.set_hmac(token_id, token_key)
+        try:
+            me = app.client.self_info()
+        except BHError as exc:
+            app.client.restore_auth(previous)  # keep the session that was active before
+            if isinstance(exc, AuthError):
+                raise LoginFailed(f"API token rejected: {exc.message}") from exc
+            raise
+        CachedSession.clear()  # a token login supersedes any cached JWT
+        app.entities.reset()
+        app.ui.success(f"Authenticated with API token as {me.get('principal_name') or token_id}")
+
+    def _login_password(self, username: str | None, otp: str | None) -> None:
+        app = self.app
+        username = username or app.read_input(f"Username [{app.config.last_username}]: ").strip()
+        username = username or app.config.last_username
+        if not username:
+            raise BHError("A username is required")
+        password = os.environ.get("BH_PASSWORD") or getpass("Password: ")
+        try:
+            data = app.client.login(username, password, otp)
+        except MFARequired:
+            code = app.read_input("One-time password: ").strip()
+            data = app.client.login(username, password, code)
+        app.entities.reset()
+        app.config.last_username = username
+        app.config.save()
+        if app.config.cache_session:
+            CachedSession(url=app.client.base_url, token=app.client.jwt, username=username).save()
+        app.ui.success(f"Logged in as {username} on {app.client.host}")
+        if data.get("auth_expired"):
+            app.ui.warn("The password for this account has expired; change it in the BH UI.")
+
+    def do_logout(self, _: object) -> None:
+        """Invalidate the current session and clear cached credentials."""
+        app = self.app
+        if not app.client.is_authenticated:
+            app.ui.info("Not logged in.")
+            return
+        app.client.logout()
+        CachedSession.clear()
+        app.entities.reset()
+        app.ui.success("Logged out.")
+
+    def do_whoami(self, _: object) -> None:
+        """Show connection state, the authenticated principal and token validity."""
+        app = self.app
+        client = app.client
+        rows: list[tuple[str, object]] = [
+            ("Backend", client.base_url),
+            ("TLS verification", "on" if client.verify_tls else Text("off", style="yellow")),
+        ]
+        if not client.is_authenticated:
+            rows.append(("State", Text("disconnected", style="red")))
+            app.ui.key_values("Status", rows)
+            return
+        me = client.self_info()
+        roles = ", ".join(r.get("name", "") for r in me.get("roles") or []) or "-"
+        rows += [
+            ("State", Text("authenticated", style="green")),
+            ("Auth mode", "JWT session" if client.auth_mode == "jwt" else f"API token ({client.token_id})"),
+            ("Principal", me.get("principal_name") or client.username or "-"),
+            ("Email", me.get("email_address") or "-"),
+            ("Roles", roles),
+        ]
+        exp = client.token_expiry()
+        if exp is not None:
+            minutes = max(int(exp - time.time()), 0) // 60
+            expires = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(exp))
+            rows.append(("Token expires", f"{expires} (in {minutes} min)"))
+        try:
+            version = client.version()
+            rows.append(("Server version", version.get("server_version") or "-"))
+        except (NotFoundError, ApiError):
+            rows.append(("Server version", "-"))
+        rows.append(("Cypher", self._cypher_state()))
+        app.ui.key_values("Status", rows)
+
+    def _cypher_state(self) -> Text:
+        entities = self.app.entities
+        if entities.cypher_available is None:
+            try:
+                entities.run_cypher("MATCH (n:Domain) RETURN n LIMIT 1")
+            except CypherDisabledError:
+                pass
+            except ApiError as exc:
+                return Text(f"error ({exc.detail})", style="yellow")
+        if entities.cypher_available:
+            return Text("available", style="green")
+        return Text("unavailable (using REST fallback)", style="yellow")
+
+    def do_status(self, args: object) -> None:
+        """Alias of 'whoami'."""
+        self.do_whoami(args)
+
+    @with_argparser(_config_parser)
+    def do_config(self, args: argparse.Namespace) -> None:
+        """Show or change persistent settings."""
+        app = self.app
+        cfg = app.config
+        if args.key and args.value is not None:
+            if args.key == "url":
+                self.do_url(args.value)
+                return
+            try:
+                value = Config.coerce(args.key, args.value)
+            except (TypeError, ValueError) as exc:
+                raise BHError(f"Invalid value for {args.key}: {exc}") from exc
+            setattr(cfg, args.key, value)
+            cfg.save()
+            self._apply(cfg)
+            app.ui.success(f"{args.key} = {value!r}")
+            return
+        keys = [args.key] if args.key else [f.name for f in fields(Config)]
+        app.ui.key_values(f"Config ({Config.path()})", [(k, repr(getattr(cfg, k))) for k in keys])
+
+    def _apply(self, cfg: Config) -> None:
+        app = self.app
+        app.client.timeout = (cfg.connect_timeout, cfg.read_timeout)
+        app.client.page_size = cfg.page_size
+        app.entities.max_results = cfg.max_results
+        app.apply_tls_setting()
+        if not cfg.cache_session:
+            CachedSession.clear()
+

bhshell/shell/commands/cypher.py

@@ -0,0 +1,97 @@
+"""Raw Cypher command."""
+
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from pathlib import Path
+
+from cmd2 import Statement
+
+from bhshell.errors import BHError
+from bhshell.shell.commands.base import BaseCommands, output_path
+
+CYPHER_HELP = """\
+Usage: cypher [--json] [-o FILE] [-f QUERY_FILE] [QUERY]
+
+Run a raw Cypher query against BH (POST /api/v2/graphs/cypher) and render
+the returned nodes and edges. The query is taken verbatim from the command
+line, so '|', '>' and quotes need no escaping. The query must return nodes or
+paths, e.g.:
+
+  cypher MATCH (n:User) WHERE n.hasspn = true RETURN n LIMIT 20
+  cypher MATCH p=(u:User)-[:MemberOf*1..]->(g:Group) WHERE g.name STARTS WITH 'DOMAIN ADMINS@' RETURN p
+  cypher -f queries/kerberoastable.cyp -o kerberoastable.csv
+
+Options:
+  --json        print the normalised result as JSON
+  -o FILE       export to FILE (.json or .csv; CSV contains the nodes)
+  -f FILE       read the query from FILE
+"""
+
+
+@dataclass
+class CypherArgs:
+    query: str
+    json: bool = False
+    output: str | None = None
+
+
+def parse_cypher_args(text: str) -> CypherArgs:
+    """Parse leading options from a raw `cypher` argument string."""
+    rest = text.strip()
+    args = CypherArgs(query="")
+    query_file: str | None = None
+    while rest.startswith("-"):
+        flag, _, remainder = rest.partition(" ")
+        remainder = remainder.lstrip()
+        if flag == "--json":
+            args.json = True
+        elif flag in ("-o", "--output", "-f", "--file"):
+            value, _, remainder = remainder.partition(" ")
+            if not value:
+                raise BHError(f"Option {flag} requires a value")
+            if flag in ("-o", "--output"):
+                try:
+                    args.output = output_path(value)
+                except argparse.ArgumentTypeError as exc:
+                    raise BHError(str(exc)) from exc
+            else:
+                query_file = value
+        else:
+            break
+        rest = remainder.lstrip()
+    if query_file:
+        try:
+            rest = Path(query_file).expanduser().read_text(encoding="utf-8")
+        except OSError as exc:
+            raise BHError(f"Cannot read {query_file}: {exc.strerror}") from exc
+    rest = rest.strip()
+    if len(rest) > 1 and rest[0] in "\"'" and rest[-1] == rest[0]:
+        rest = rest[1:-1].strip()
+    args.query = rest
+    return args
+
+
+class CypherCommands(BaseCommands):
+    DEFAULT_CATEGORY = "Cypher"
+
+    def do_cypher(self, statement: Statement) -> None:
+        """Run a raw Cypher query (see 'help cypher')."""
+        raw = statement.raw.strip()
+        text = raw.split(None, 1)[1] if " " in raw or "\t" in raw else ""
+        if text.strip() in ("-h", "--help") or not text.strip():
+            self.app.poutput(CYPHER_HELP)
+            return
+        args = parse_cypher_args(text)
+        if not args.query:
+            raise BHError("No query given")
+        app = self.app
+        app.require_auth()
+        graph = app.entities.run_cypher(args.query)
+        for node in graph.nodes.values():
+            app.remember(node)
+        self.show_graph(graph, as_json=args.json, output=args.output)
+
+    def help_cypher(self) -> None:
+        self.app.poutput(CYPHER_HELP)

bhshell/shell/commands/domains.py

@@ -0,0 +1,80 @@
+"""Domain overview and trust commands."""
+
+from __future__ import annotations
+
+import argparse
+
+from cmd2 import Cmd2ArgumentParser, with_argparser
+
+from bhshell.models.results import Column
+from bhshell.queries.domains import DomainService
+from bhshell.render import export
+from bhshell.shell.commands.base import BaseCommands, add_output_args
+
+DOMAIN_COLS = [
+    Column("Domain", "name"), Column("SID", "sid"), Column("Level", "functional_level"),
+    Column("Users (enabled)", "users_fmt"), Column("Computers (enabled)", "computers_fmt"),
+    Column("Groups", "groups"), Column("Tier Zero", "tier_zero"), Column("Last collected", "last_collected"),
+]
+TRUST_COLS = [
+    Column("Trusting (source)", "trusting"), Column("Trusted (target)", "trusted"), Column("Kind", "kind"),
+    Column("Type", "trust_type"), Column("Transitive", "transitive", "bool"),
+    Column("SID filtering", "sid_filtering_fmt"), Column("Abuse edges", "abuse"), Column("Issues", "issues"),
+]
+
+
+def _output_parser(description: str) -> Cmd2ArgumentParser:
+    p = Cmd2ArgumentParser(description=description)
+    add_output_args(p)
+    return p
+
+
+def _pair(total: object, enabled: object) -> str:
+    if total is None:
+        return "-"
+    return f"{total} ({enabled if enabled is not None else '-'})"
+
+
+class DomainCommands(BaseCommands):
+    DEFAULT_CATEGORY = "Analysis"
+
+    @with_argparser(lambda: _output_parser("Per-domain overview (object counts, functional level, collection)."))
+    def do_domains(self, args: argparse.Namespace) -> None:
+        """Per-domain overview."""
+        app = self.app
+        app.require_auth()
+        infos = DomainService(app.entities).domains()
+        rows = [d.as_dict() for d in infos]
+        if args.json:
+            app.poutput(export.to_json(rows))
+        else:
+            display = [{**r, "users_fmt": _pair(r["users"], r["enabled_users"]),
+                        "computers_fmt": _pair(r["computers"], r["enabled_computers"])} for r in rows]
+            app.ui.table("Domains", DOMAIN_COLS, display)
+        if args.output:
+            fields = list(rows[0]) if rows else ["name"]
+            self.export(args.output, rows, (fields, rows))
+
+    @with_argparser(lambda: _output_parser(
+        "Domain trusts. 'A trusts B' means principals of B can access resources in A."))
+    def do_trusts(self, args: argparse.Namespace) -> None:
+        """Domain trust map with SID-filtering status."""
+        app = self.app
+        app.require_auth()
+        trusts = DomainService(app.entities).trusts()
+        rows = [t.as_dict() for t in trusts]
+        if args.json:
+            app.poutput(export.to_json(rows))
+        else:
+            display = []
+            for t, r in zip(trusts, rows, strict=True):
+                if t.same_forest:
+                    sid = "n/a (same forest)"
+                else:
+                    sid = {True: "enforced", False: "DISABLED", None: "unknown (default: enforced)"}[t.sid_filtering]
+                display.append({**r, "sid_filtering_fmt": sid})
+            app.ui.table("Trusts", TRUST_COLS, display,
+                         notes=["Access flows from the trusted (target) domain into the trusting (source) domain."])
+        if args.output:
+            fields = list(rows[0]) if rows else ["trusting"]
+            self.export(args.output, rows, (fields, rows))

bhshell/shell/commands/entities.py

@@ -0,0 +1,88 @@
+"""Entity lookup commands: user, computer, group, lookup."""
+
+from __future__ import annotations
+
+import argparse
+
+from cmd2 import Cmd2ArgumentParser, RawDescriptionCmd2HelpFormatter, with_argparser
+
+from bhshell.queries.service import VIEWS
+from bhshell.render import export
+from bhshell.shell.commands.base import BaseCommands, add_output_args
+
+_NAME_HELP = "samaccountname, NAME@DOMAIN, DOMAIN\\NAME, FQDN (computers) or SID"
+
+
+def _entity_parser(kind: str | None) -> Cmd2ArgumentParser:
+    what = kind.lower() if kind else "object (user, computer or group; type auto-detected)"
+    p = Cmd2ArgumentParser(
+        description=f"Show a triage summary for a {what}, and optional relationship views.",
+        epilog="Without view flags the summary is shown. With view flags only those views are shown;\n"
+               "--all shows the summary plus every applicable view.",
+        formatter_class=RawDescriptionCmd2HelpFormatter,
+    )
+    p.add_argument("name", help=_NAME_HELP, choices_provider=BaseCommands.recent_names)
+    p.add_argument("-d", "--domain", help="restrict the lookup to a domain (FQDN or NetBIOS)")
+
+    views = p.add_argument_group("relationship views")
+    views.add_argument("-g", "--groups", action="store_true", help="group memberships (direct + nested)")
+    if kind in (None, "Group"):
+        views.add_argument("-m", "--members", action="store_true", help="group members (direct + nested)")
+    views.add_argument("-O", "--outbound", action="store_true", help="dangerous rights held over other objects")
+    views.add_argument("-I", "--inbound", action="store_true", help="principals with dangerous rights over it")
+    views.add_argument("-s", "--sessions", action="store_true", help="HasSession relationships")
+    views.add_argument("-p", "--local-admin", "--privs", dest="privs", action="store_true",
+                       help="AdminTo / CanRDP / ExecuteDCOM / CanPSRemote / SQLAdmin")
+    views.add_argument("-a", "--all", action="store_true", help="summary + every applicable view")
+
+    out = p.add_argument_group("output")
+    out.add_argument("-n", "--max-rows", type=int, metavar="N",
+                     help="max table rows per view (default: config display_rows; 0 = all)")
+    add_output_args(out)
+    return p
+
+
+class EntityCommands(BaseCommands):
+    DEFAULT_CATEGORY = "Entities"
+
+    def _run(self, args: argparse.Namespace, kind: str | None) -> None:
+        app = self.app
+        app.require_auth()
+        node = app.entities.resolve(args.name, kind, args.domain)
+        app.remember(node)
+
+        if args.all:
+            selected = app.entities.applicable_views(node)
+        else:
+            requested = [key for key in VIEWS if getattr(args, key, False)]
+            selected = [key for key in requested if node.kind in VIEWS[key]]
+            for key in set(requested) - set(selected):
+                app.ui.warn(f"View '{key}' does not apply to a {node.kind}; skipped.")
+        report = app.entities.report(node, selected, show_summary=args.all or not selected)
+
+        if args.json:
+            app.poutput(export.to_json(report.as_dict()))
+        else:
+            app.ui.report(report, self.max_rows(args))
+        if args.output:
+            self.export(args.output, report.as_dict(), export.report_rows(report))
+
+    @with_argparser(lambda: _entity_parser("User"))
+    def do_user(self, args: argparse.Namespace) -> None:
+        """Query a user by samaccountname."""
+        self._run(args, "User")
+
+    @with_argparser(lambda: _entity_parser("Computer"))
+    def do_computer(self, args: argparse.Namespace) -> None:
+        """Query a computer by name / samaccountname / FQDN."""
+        self._run(args, "Computer")
+
+    @with_argparser(lambda: _entity_parser("Group"))
+    def do_group(self, args: argparse.Namespace) -> None:
+        """Query a group by name."""
+        self._run(args, "Group")
+
+    @with_argparser(lambda: _entity_parser(None))
+    def do_lookup(self, args: argparse.Namespace) -> None:
+        """Query any user, computer or group (type auto-detected)."""
+        self._run(args, None)

bhshell/shell/commands/hunt.py

@@ -0,0 +1,151 @@
+"""Domain-wide weakness checks."""
+
+from __future__ import annotations
+
+import argparse
+from collections.abc import Sequence
+
+from cmd2 import (
+    Choices,
+    Cmd2ArgumentParser,
+    RawDescriptionCmd2HelpFormatter,
+    with_argparser,
+)
+
+from bhshell.errors import BHError
+from bhshell.models.results import Column
+from bhshell.queries.hunt import (
+    CHECKS,
+    CHECKS_BY_ID,
+    FROM_OWNED,
+    SCOPED_CHECKS,
+    Check,
+    Finding,
+    HuntOptions,
+    HuntService,
+)
+from bhshell.queries.service import PATH_KINDS, truncation_note
+from bhshell.render import export
+from bhshell.shell.commands.base import BaseCommands, add_output_args
+
+
+def _check_id(value: str) -> str:
+    # A type check rather than `choices=`: before Python 3.12, argparse validates the empty default
+    # of an `nargs="*"` positional against `choices` and rejects a bare `hunt`.
+    if value not in CHECKS_BY_ID:
+        raise argparse.ArgumentTypeError(f"invalid choice: '{value}' (choose from {', '.join(CHECKS_BY_ID)})")
+    return value
+
+
+def _hunt_parser() -> Cmd2ArgumentParser:
+    p = Cmd2ArgumentParser(
+        description="Run domain-wide weakness checks.",
+        epilog="hunt               summary of every check\n"
+               "hunt CHECK ...     details of the given checks\n"
+               "hunt --all         details of every check\n"
+               "hunt --list        describe the checks\n"
+               "hunt --owned       what the owned objects (and their groups) can do\n"
+               "hunt --from NAME   the same, from one object\n\n"
+               "Checks: " + ", ".join(c.id for c in CHECKS),
+        formatter_class=RawDescriptionCmd2HelpFormatter,
+    )
+    p.add_argument("checks", nargs="*", type=_check_id, metavar="CHECK", help="check id(s)",
+                   choices_provider=lambda _self: Choices.from_values(CHECKS_BY_ID, is_sorted=True))
+    p.add_argument("--all", action="store_true", help="show details of every check")
+    p.add_argument("--list", action="store_true", help="list available checks")
+    scope = p.add_mutually_exclusive_group()
+    scope.add_argument("--owned", action="store_true",
+                       help="only rights held by owned objects and their groups (checks marked 'scoped')")
+    scope.add_argument("--from", dest="source", metavar="NAME",
+                       help="only rights held by NAME and its groups (checks marked 'scoped')",
+                       choices_provider=BaseCommands.recent_names)
+    p.add_argument("-d", "--domain", help="restrict to a domain (FQDN or NetBIOS)")
+    p.add_argument("--days", type=int, default=HuntOptions.days,
+                   help="password age threshold for stale-passwords (days)")
+    p.add_argument("-n", "--max-rows", type=int, metavar="N",
+                   help="max table rows per check (default: config display_rows; 0 = all)")
+    add_output_args(p)
+    return p
+
+
+def _csv_rows(findings: list[Finding]) -> tuple[list[str], list[dict]]:
+    fields: list[str] = ["check", "severity"]
+    rows: list[dict] = []
+    for f in findings:
+        for row in f.rows:
+            for key in row:
+                if key not in fields:
+                    fields.append(key)
+            rows.append({"check": f.check.id, "severity": f.check.severity, **row})
+    return fields, rows
+
+
+class HuntCommands(BaseCommands):
+    DEFAULT_CATEGORY = "Analysis"
+
+    @with_argparser(_hunt_parser)
+    def do_hunt(self, args: argparse.Namespace) -> None:
+        """Run domain-wide weakness checks (Kerberoasting, delegation, DCSync, AD CS, trusts, ...)."""
+        app = self.app
+        if args.list:
+            rows = [{"severity": c.severity, "id": c.id, "scoped": c.scoped, "description": c.description}
+                    for c in CHECKS]
+            app.ui.table("Hunt checks", [Column("Severity", "severity", "severity"), Column("Check", "id"),
+                                         Column("Scoped", "scoped", "bool"), Column("Description", "description")],
+                         rows)
+            return
+        app.require_auth()
+        detail = args.all or bool(args.checks)
+        service = HuntService(app.entities)
+        opts = HuntOptions(domain=args.domain or "", days=args.days, limit=app.config.max_results,
+                           enrich=detail or args.json or bool(args.output))
+        checks = [CHECKS_BY_ID[i] for i in dict.fromkeys(args.checks)] if args.checks else CHECKS
+        if args.owned or args.source:
+            checks = self._scoped_checks(checks, bool(args.checks))
+            opts.principals = self._scope(service, args)
+        findings = [service.run(check, opts) for check in checks]
+
+        if args.json:
+            app.poutput(export.to_json([f.as_dict() for f in findings]))
+        elif not detail:
+            app.ui.hunt_summary(findings)
+            flag = " --owned" if args.owned else f" --from {args.source}" if args.source else ""
+            example = "tier-zero-control" if flag else "kerberoastable"
+            app.ui.info(f"Details: 'hunt CHECK{flag}' (e.g. 'hunt {example}{flag}'), or 'hunt --all{flag}'.")
+        else:
+            max_rows = self.max_rows(args)
+            for f in findings:
+                notes = [f.check.description]
+                if f.truncated:
+                    notes.append(truncation_note(opts.limit, [f.total], "results"))
+                if f.error:
+                    notes.append(f"error: {f.error}")
+                notes += f.notes
+                columns = f.check.columns
+                if opts.scoped:
+                    columns = (*(f.check.scoped_columns or columns), FROM_OWNED)
+                app.ui.table(f"[{f.check.severity}] {f.check.title}", columns, f.rows,
+                             max_rows=max_rows, notes=notes)
+        if args.output:
+            self.export(args.output, [f.as_dict() for f in findings], _csv_rows(findings))
+
+    @staticmethod
+    def _scoped_checks(checks: Sequence[Check], explicit: bool) -> list[Check]:
+        """The checks that run with --owned / --from: all of them when named explicitly, or an error."""
+        if not explicit:
+            return list(SCOPED_CHECKS)
+        unscoped = [c.id for c in checks if not c.scoped]
+        if unscoped:
+            raise BHError(f"{', '.join(unscoped)}: not available with --owned / --from",
+                          hint="'hunt --list' shows which checks are scoped.")
+        return list(checks)
+
+    def _scope(self, service: HuntService, args: argparse.Namespace) -> dict[str, list[str]]:
+        if args.owned:
+            scope = service.owned_scope()
+            if not scope:
+                raise BHError("Nothing is marked owned", hint="Mark objects with 'owned add NAME'.")
+            return scope
+        node = self.app.entities.resolve(args.source, domain=args.domain, kinds=PATH_KINDS)
+        self.app.remember(node)
+        return service.principal_scope(node)