skillsentinel-cli 0.3.1__py3-none-any.whl

skillsentinel/__init__.py

@@ -0,0 +1,3 @@
+"""SkillSentinel — post-install guard for AI-agent skills and prompt configs."""
+
+__version__ = "0.3.1"

skillsentinel/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

skillsentinel/cli.py

@@ -0,0 +1,364 @@
+"""SkillSentinel CLI: scan / watch / rules."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import shutil
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+from . import __version__
+from .detonate import DetonationRefusedError, detonate_tree
+from .rules import load_rules, SEVERITY_ORDER
+from .scanner import InputError, scan_path, to_sarif
+from .verifier import VERIFIERS_BY_NAME
+from .watch import (write_snapshot, load_snapshot, diff_snapshots, snapshot_dir,
+                    rescan_changes)
+
+SEV_EXIT: dict[str, int] = {"low": 0, "medium": 1, "high": 2, "critical": 3}
+
+# `scan --help` must state the contract a CI pipeline relies on.
+EXIT_CODES_EPILOG = """\
+exit codes:
+  0  clean — no confirmed findings
+  1  at least one confirmed finding at/above the --severity threshold
+  2  input error: missing or unreadable path, invalid or empty --rules, a .skillsentinelignore
+     pattern that ignores the whole skill, a scan that saw zero scannable files,
+     --timeout expiry, --max-files limit reached
+  3  internal error — a bug, please report it"""
+
+SEV_COLOR = {
+    "critical": "\033[91m", "high": "\033[31m",
+    "medium": "\033[33m", "low": "\033[32m", "end": "\033[0m",
+}
+
+
+def _colorized(s: str, sev: str, enabled: bool) -> str:
+    if not enabled:
+        return s
+    return f"{SEV_COLOR[sev]}{s}{SEV_COLOR['end']}"
+
+
+def _park_stdout_on_devnull() -> None:
+    """After a stdout write failed, point fd 1 at /dev/null so the interpreter's
+    shutdown flush of the leftover buffer cannot re-raise — without this a
+    broken pipe turns into an "Exception ignored" dump and rc=120. Call only
+    after the real error line is already on stderr."""
+    if sys.stdout is None:
+        return  # no stdout buffer was ever created — nothing to re-point or flush
+    try:
+        null = os.open(os.devnull, os.O_WRONLY)
+    except OSError:  # nothing to hide the failure behind: best effort only
+        return
+    try:
+        os.dup2(null, sys.stdout.fileno())
+    except (OSError, ValueError):
+        pass  # already detached/closed — nothing buffered can re-raise then
+    finally:
+        os.close(null)
+
+
+def _emit_stdout(emit: Callable[[], None], what: str) -> bool:
+    """Run a stdout-writing report block AND flush it here, so a stdout that
+    cannot be written (closed pipe, full device, fd 1 closed at exec so
+    sys.stdout is None) fails now as one clean error naming the output — not
+    at interpreter shutdown. Returns False after printing that line and
+    muting fd 1 (see _park_stdout_on_devnull)."""
+    if sys.stdout is None:
+        # fd 1 was closed before the interpreter started: print() discards
+        # silently, so treat the missing stream exactly like an unwritable
+        # one — an output error, not an internal one.
+        print(f"skillsentinel: error: cannot write {what}: stdout is closed "
+              f"(fd 1 was closed at startup)", file=sys.stderr)
+        return False
+    try:
+        emit()
+        sys.stdout.flush()
+    except (BrokenPipeError, OSError) as e:
+        print(f"skillsentinel: error: cannot write {what}: {e}",
+              file=sys.stderr)
+        _park_stdout_on_devnull()
+        return False
+    return True
+
+
+def _print_findings(result, use_color: bool, suppressed: int = 0,
+                    show_inconclusive: bool = False) -> None:
+    c = result.counts
+    total = sum(c.values())
+    dropped = len(result.demoted)
+    inconclusive = [f for f in result.demoted if f.verdict == "inconclusive"]
+    print(f"SkillSentinel v{__version__} — scanned {result.path} "
+          f"({result.files_scanned} files, {result.files_skipped} skipped, "
+          f"profile: {result.profile})")
+    if result.undecodable_files:
+        # D3: undecodable files are reported loudly, never silently dropped.
+        names = ", ".join(result.undecodable_files[:3])
+        more = f" (+{len(result.undecodable_files) - 3} more)" \
+            if len(result.undecodable_files) > 3 else ""
+        print(f"warning: {len(result.undecodable_files)} file(s) could not be "
+              f"decoded as text: {names}{more}", file=sys.stderr)
+    if not total:
+        note = f", {suppressed} suppressed by inline markers" if suppressed else ""
+        if dropped:
+            note += f"; {dropped} candidate(s) demoted — see --json for reasons"
+        print(f"No exploitable findings. Supply chain looks clean. ✓{note}")
+    else:
+        print(f"Confirmed findings: {total} "
+              f"(critical: {c['critical']}, high: {c['high']}, "
+              f"medium: {c['medium']}, low: {c['low']})"
+              + (f" — {suppressed} suppressed by inline markers" if suppressed else "")
+              + (f"; {dropped} candidate(s) demoted" if dropped else ""))
+        cur = None
+        for f in result.findings:
+            if f.severity != cur:
+                cur = f.severity
+                print(_colorized(f"\n== {cur.upper()} ==", cur, use_color))
+            print(_colorized(f"[{f.rule_id}] {f.file}:{f.line}", cur, use_color)
+                  + (f"  (x{f.count})" if f.count > 1 else "")
+                  + f"  {f.title}")
+            print(f"    {f.snippet[:160]}")
+            print(f"    verdict: {f.verdict} — {f.reason}")
+    if show_inconclusive or inconclusive:
+        print(f"\n{len(inconclusive)} inconclusive candidate(s):")
+        for f in inconclusive:
+            print(f"  [{f.rule_id}] {f.file}:{f.line} — {f.reason}")
+
+
+def load_ignore_file(root: Path) -> list[str]:
+    p = root if root.is_file() else root / ".skillsentinelignore"
+    if not p.exists() or not p.is_file():
+        return []
+    out = []
+    for line in p.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = line.strip()
+        if line and not line.startswith("#"):
+            out.append(line)
+    return out
+
+
+def cmd_scan(args: argparse.Namespace) -> int:
+    root = Path(args.path).expanduser()
+    # `.skillsentinelignore` is input from the scanned tree, so it is trusted
+    # only under --honor-ignores — exactly like inline suppression markers.
+    ignore_patterns = load_ignore_file(root) if args.honor_ignores else []
+    result = scan_path(args.path, args.rules,
+                      honor_ignores=args.honor_ignores,
+                       exclude=list(args.exclude),
+                       ignore_patterns=ignore_patterns,
+                       profile=args.profile,
+                       timeout=args.timeout,
+                       max_files=args.max_files)
+    reports = None
+    if args.detonate:
+        try:
+            reports = detonate_tree(Path(args.path), allow_net=args.allow_net,
+                                    timeout=args.detonate_timeout)
+        except DetonationRefusedError as e:
+            print(f"detonation refused: {e}", file=sys.stderr)
+            return 2
+    def _text_report() -> None:
+        _print_findings(result, use_color=sys.stdout is not None and sys.stdout.isatty(),
+                        suppressed=result.suppressed,
+                        show_inconclusive=args.show_inconclusive)
+        if reports is not None:
+            print(f"\n-- Detonation ({len(reports)} scripts) --")
+            for r in reports:
+                if not r.executed:
+                    print(f"[skip] {r.file}: {'; '.join(r.notes)}")
+                    continue
+                net = ", ".join(r.network_attempts) or "none observed"
+                print(f"[ran ] {r.file}  exit={r.exit_code}  egress: {net}")
+                for n in r.notes:
+                    if "timed out" in n.lower():
+                        print(f"[warn] {r.file}: {n}")
+                if any("network NOT isolated" in n for n in r.notes):
+                    print("[warn] network NOT isolated (--allow-net): the "
+                          "sandbox shares the host network — real egress "
+                          "is possible")
+
+    if args.json:
+        payload = result.to_dict()
+        if reports is not None:
+            payload["detonations"] = [r.to_dict() for r in reports]
+        if not _emit_stdout(lambda: print(json.dumps(payload, indent=2)),
+                            "the JSON report to stdout"):
+            return 2
+    elif not _emit_stdout(_text_report, "the report to stdout"):
+        return 2
+    if args.sarif:
+        sarif = to_sarif(result)
+        try:
+            Path(args.sarif).write_text(json.dumps(sarif, indent=2), encoding="utf-8")
+        except OSError as e:  # the report target is part of the input contract too
+            print(f"skillsentinel: error: cannot write the SARIF report to "
+                  f"{args.sarif}: {e}", file=sys.stderr)
+            return 2
+        if not args.json and not _emit_stdout(
+                lambda: print(f"\nSARIF written to {args.sarif}"),
+                "the SARIF confirmation to stdout"):
+            return 2
+    if result.limit_reached is not None:
+        n, m = result.limit_reached
+        print(f"error: limit reached: {n} of {m} files scanned "
+              f"(raise --max-files to see the rest)", file=sys.stderr)
+        return 2
+    threshold = SEVERITY_ORDER[args.severity]
+    return 1 if result.max_severity_rank() >= threshold else 0
+
+
+def cmd_watch(args: argparse.Namespace) -> int:
+    root = Path(args.path).expanduser().resolve()
+    if args.watch_cmd == "init":
+        snap = write_snapshot(root, Path(args.snapshot))
+        print(f"Snapshot saved: {args.snapshot} "
+              f"({len(snap['entries'])} files under {snap['root']})")
+        return 0
+    if args.watch_cmd == "diff":
+        snap_path = Path(args.snapshot)
+        if not snap_path.exists():
+            print(f"error: snapshot not found: {snap_path} — run `watch init` first",
+                  file=sys.stderr)
+            return 2
+        try:
+            old = load_snapshot(snap_path)
+        except (OSError, ValueError) as e:
+            raise InputError(f"cannot read snapshot {snap_path}: {e}") from None
+        new = snapshot_dir(root)
+        d = diff_snapshots(old, new)
+        if d["clean"]:
+            print(f"Clean: no drift across {len(new['entries'])} files.")
+            return 0
+        print("DRIFT DETECTED:")
+        for k in ("added", "changed", "removed"):
+            for p in d[k]:
+                print(f"  {k:>7}: {p}")
+        if getattr(args, "rescan", False):
+            findings = rescan_changes(root, d)
+            if findings:
+                print(f"\nRescan of changed/added files — "
+                      f"{len(findings)} confirmed finding(s):")
+                for f in findings:
+                    print(f"  [{f.rule_id}] {f.file}:{f.line}  {f.title}")
+                    print(f"    {f.snippet[:160]}")
+                    print(f"    verdict: {f.verdict} — {f.reason}")
+            else:
+                print("\nRescan of changed/added files: no confirmed findings.")
+        return 1
+    print(json.dumps(snapshot_dir(root), indent=2))
+    return 0
+
+
+def cmd_rules(args: argparse.Namespace) -> int:
+    try:
+        rules = load_rules(args.rules)
+    except (OSError, ValueError) as e:
+        raise InputError(
+            f"cannot load rules from {args.rules or 'the built-in catalog'}: {e}") from None
+    if args.json:
+        print(json.dumps({
+            "count": len(rules),
+            "rules": [{
+                "id": r.id, "title": r.title, "severity": r.severity,
+                "category": r.category, "owasp": r.owasp,
+                "description": r.description,
+            } for r in rules]}, indent=2))
+    else:
+        print(f"{len(rules)} rules:")
+        for r in sorted(rules, key=lambda x: (x.category, x.id)):
+            print(f"  {r.id}  {r.severity:<8} {r.category:<18} {r.title}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="skillsentinel",
+        description="Post-install security scanner for AI-agent skills and prompt configs.")
+    p.add_argument("--version", action="version", version=f"skillsentinel {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("scan", help="scan a skill file or directory",
+                       epilog=EXIT_CODES_EPILOG,
+                       formatter_class=argparse.RawDescriptionHelpFormatter)
+    s.add_argument("path", help="file or directory to scan")
+    s.add_argument("--json", action="store_true", help="machine-readable JSON output")
+    s.add_argument("--sarif", metavar="OUT.sarif", help="also write SARIF 2.1.0 report")
+    s.add_argument("--severity", choices=list(SEVERITY_ORDER), default="low",
+                   help="exit 1 only for findings at/above this severity (default: low)")
+    s.add_argument("--rules", help="path to alternative rules.json")
+    s.add_argument("--profile", choices=list(VERIFIERS_BY_NAME), default="balanced",
+                   help="verification strictness: strict (every candidate confirmed, "
+                        "demoted is empty) / balanced (default) / loose / paranoid")
+    s.add_argument("--honor-ignores", action="store_true",
+                   help="honor inline `skillsentinel:ignore` markers and "
+                        "`.skillsentinelignore` patterns (OFF by default: a scanned "
+                        "file must not be able to silence its own detection)")
+    s.add_argument("--exclude", action="append", default=[], metavar="GLOB",
+                   help="skip files matching this glob (repeatable)")
+    s.add_argument("--timeout", type=float, default=None, metavar="SEC",
+                   help="abort the scan after SEC seconds and exit 2 (0 disables); "
+                        "protects CI against pathological trees")
+    s.add_argument("--max-files", type=int, default=None, metavar="N",
+                   help="scan at most N files, then exit 2 with a limit report; "
+                        "bounds huge trees without silently ignoring the rest")
+    s.add_argument("--detonate", action="store_true",
+                   help="run discovered scripts in a disposable bwrap sandbox "
+                        "with no network access (--unshare-net; requires "
+                        "bubblewrap, skipped with a notice otherwise)")
+    s.add_argument("--allow-net", action="store_true",
+                   help="with --detonate: lift network isolation — the sandbox "
+                        "CAN open real connections (each detonation prints a "
+                        "'network NOT isolated' warning)")
+    s.add_argument("--detonate-timeout", type=int, default=10, metavar="SEC",
+                   help="with --detonate: kill each sandboxed script after SEC "
+                        "seconds and record a timeout warning (0 disables; "
+                        "default: 10)")
+    s.add_argument("--show-inconclusive", action="store_true",
+                   help="also list candidates the verifier graded inconclusive "
+                        "(unknown context) with their file:line and reason")
+    s.set_defaults(func=cmd_scan)
+
+    w = sub.add_parser("watch", help="snapshot installed skills and detect drift")
+    wsub = w.add_subparsers(dest="watch_cmd")
+    for name, helptext in (("init", "record a hash snapshot"),
+                           ("diff", "compare current tree against the snapshot"),
+                           ("show", "print the current snapshot as JSON")):
+        wp = wsub.add_parser(name, help=helptext)
+        wp.add_argument("path", help="directory of installed skills")
+        wp.add_argument("--snapshot", default=".skillsentinel-snapshot.json",
+                        help="snapshot file path (default: .skillsentinel-snapshot.json)")
+    wsub.choices["diff"].add_argument(
+        "--rescan", action="store_true",
+        help="also re-scan changed/added files and print their confirmed findings")
+    w.set_defaults(func=cmd_watch, watch_cmd="show")
+
+    r = sub.add_parser("rules", help="list detection rules")
+    r.add_argument("--json", action="store_true", help="JSON output")
+    r.add_argument("--rules", help="path to alternative rules.json")
+    r.set_defaults(func=cmd_rules)
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except InputError as e:
+        print(f"skillsentinel: error: {e}", file=sys.stderr)
+        return 2
+    except OSError as e:
+        # IO trouble reaching the input (vanished path, unreadable file): the
+        # scan target's problem, not the scanner's — still exit 2, one line.
+        print(f"skillsentinel: error: {e}", file=sys.stderr)
+        return 2
+    except Exception as e:  # noqa: BLE001 — the CLI boundary turns bugs into exit 3
+        print(f"skillsentinel: internal error: {type(e).__name__}: {e}",
+              file=sys.stderr)
+        return 3
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

skillsentinel/detonate.py

@@ -0,0 +1,236 @@
+"""`--detonate`: run skill scripts in a disposable bwrap sandbox, record egress attempts.
+
+Network isolation by default: the sandbox is built with --unshare-net, so no process
+inside can open a connection — attempted tool egress (curl/wget/nc/ssh/...) is still
+observed via PATH shims that log the destination. The sandbox also gets its own PID
+namespace (--unshare-pid): killing the bwrap supervisor at a detonation timeout takes
+the whole sandbox tree down with it, so a payload cannot survive as a host orphan.
+The capability preflight runs in every mode: if the host bwrap cannot honor the unshare
+options the mode relies on (--unshare-net and --unshare-pid; only --unshare-pid under
+`allow_net=True`), detonation is refused outright (never a live-egress or
+leaky-process-tree fallback); the caller reports it on stderr and exits 2.
+`allow_net=True` lifts the network isolation explicitly and stamps the report with a
+'network NOT isolated' warning. If bwrap is unavailable, detonation is skipped and
+reported as such.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass, field, asdict
+from pathlib import Path
+
+NETLOG_HELPER = r"""#!/usr/bin/env python3
+import sys, os
+log = os.environ.get("SANDBOX_NETLOG", "/netlog.txt")
+with open(log, "a") as f:
+    f.write(sys.argv[0].rsplit("/", 1)[-1] + " " + " ".join(sys.argv[1:]) + "\n")
+sys.exit(7)
+"""
+
+SHIM_TOOLS = ("curl", "wget", "nc", "ncat", "ping", "telnet", "ssh", "scp", "ftp", "dig")
+
+
+class DetonationRefusedError(RuntimeError):
+    """bwrap cannot guarantee sandbox isolation — detonation must not run."""
+
+
+@dataclass
+class DetonationReport:
+    file: str
+    executed: bool
+    sandbox: str
+    exit_code: int | None = None
+    stdout_tail: str = ""
+    stderr_tail: str = ""
+    network_attempts: list[str] = field(default_factory=list)
+    notes: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def _tails(out: str, err: str, n: int = 500) -> tuple[str, str]:
+    return out[-n:], err[-n:]
+
+
+def find_scripts(root: Path) -> list[Path]:
+    scripts = []
+    for p in sorted(root.rglob("*")):
+        if not p.is_file() or p.is_symlink():
+            continue
+        if p.suffix in (".sh", ".py", ".bash") or p.name == "install":
+            scripts.append(p)
+    return scripts
+
+
+def _base_bind_args() -> list[str]:
+    """Bind the minimal read-only host dirs needed to run python/sh."""
+    args = []
+    for d in ("/usr", "/lib", "/lib64", "/bin", "/sbin", "/etc/alternatives"):
+        if Path(d).exists():
+            args += ["--ro-bind", d, d]
+    return args
+
+
+def _bwrap_capability_probe(bwrap: str, flags: list[str]) -> tuple[bool, str]:
+    """Non-destructive preflight: can this bwrap build the sandbox we need?
+
+    Runs /usr/bin/true once in a throwaway sandbox with `flags` — the unshare
+    options the caller's mode relies on: --unshare-net (no egress from the
+    sandbox) and --unshare-pid (the payload dies with the bwrap supervisor, so
+    a timeout cannot leave it running as a host orphan) — plus the same base
+    binds the real detonation uses. Old bwrap builds reject the options
+    outright ("unrecognized option", exit 1); any probe failure counts as
+    "cannot isolate", so the caller refuses instead of running untrusted code
+    with live egress or a leaking process tree. Returns (ok, detail), where
+    detail carries the probe's stderr (or launch failure) so the refusal
+    message can name the flag that was missing.
+    """
+    try:
+        proc = subprocess.run(
+            [bwrap, *flags, *_base_bind_args(), "/usr/bin/true"],
+            capture_output=True, text=True, timeout=10,
+        )
+    except (OSError, subprocess.TimeoutExpired) as e:
+        return False, f"probe did not complete: {e}"
+    return proc.returncode == 0, (proc.stderr or "").strip()
+
+
+def detonate_file(path: Path, timeout: int | None = 10,
+                  allow_net: bool = False) -> DetonationReport:
+    bwrap = shutil.which("bwrap")
+    if bwrap is None:
+        return DetonationReport(
+            file=str(path), executed=False, sandbox="none",
+            notes=["bwrap not available — detonation skipped "
+                   "(install bubblewrap to enable)"],
+        )
+
+    # preflight in every mode: a detonation timeout must never leave payload
+    # processes on the host, so --unshare-pid is probed (and required) even
+    # when network isolation is lifted; --unshare-net is probed alongside it
+    # only in the mode that actually uses it
+    probe_flags = (["--unshare-pid"] if allow_net
+                   else ["--unshare-net", "--unshare-pid"])
+    capable, detail = _bwrap_capability_probe(bwrap, probe_flags)
+    if not capable:
+        detail_note = f" Probe said: {detail}" if detail else ""
+        if allow_net:
+            raise DetonationRefusedError(
+                f"{bwrap} does not support --unshare-pid — detonation "
+                "refused: without its own PID namespace a detonation timeout "
+                "can leave payload processes running on the host, and "
+                "--allow-net lifts only the network guarantee, not this one. "
+                f"Upgrade bubblewrap to a build with --unshare-pid support."
+                f"{detail_note}")
+        raise DetonationRefusedError(
+            f"{bwrap} does not support --unshare-net/--unshare-pid — "
+            "detonation refused: without them the sandbox would run untrusted "
+            "code with real egress and a detonation timeout could leave "
+            "payload processes running on the host. Upgrade bubblewrap to a "
+            "build with --unshare-net and --unshare-pid support, or pass "
+            f"--allow-net to explicitly accept a networked sandbox."
+            f"{detail_note}")
+
+    with tempfile.TemporaryDirectory(prefix="ssdet_") as tmp:
+        tmpdir = Path(tmp)
+        netlog = tmpdir / "netlog.txt"
+        netlog.touch()
+        work = tmpdir / "work"
+        work.mkdir()
+        home = tmpdir / "home"
+        home.mkdir()
+        script_copy = work / path.name
+        script_copy.write_bytes(path.read_bytes())
+        if script_copy.suffix in (".sh", ".bash") or script_copy.name == "install":
+            script_copy.chmod(0o755)
+
+        shims = tmpdir / "shims"
+        shims.mkdir()
+        for tool in SHIM_TOOLS:
+            f = shims / tool
+            f.write_text(NETLOG_HELPER)
+            f.chmod(0o755)
+
+        cmd = [
+            bwrap,
+            *_base_bind_args(),
+            "--proc", "/proc",
+            "--dev", "/dev",
+            "--tmpfs", "/tmp",
+            "--ro-bind", str(work), "/work",
+            "--ro-bind", str(shims), "/shims",
+            "--bind", str(home), "/home/sandbox",
+            "--bind", str(netlog), "/netlog.txt",
+            "--chdir", "/work",
+        ]
+        if not allow_net:
+            cmd.append("--unshare-net")
+        # own PID namespace: when the bwrap supervisor is killed at a timeout,
+        # the kernel tears down the whole sandbox tree — without it the payload
+        # would outlive the monitor as an orphan host process
+        cmd += ["--unshare-pid", "--die-with-parent", "--new-session"]
+        if script_copy.suffix == ".py":
+            cmd += ["python3", f"/work/{path.name}"]
+        else:
+            cmd += ["/bin/sh", f"/work/{path.name}"]
+
+        env = {
+            "PATH": "/shims:/usr/bin:/bin",
+            "HOME": "/home/sandbox",
+            "SANDBOX_NETLOG": "/netlog.txt",
+        }
+        timeout_note = None
+        run_kwargs: dict = {"capture_output": True, "text": True, "env": env}
+        if timeout is not None and timeout > 0:
+            run_kwargs["timeout"] = timeout
+        try:
+            proc = subprocess.run(cmd, **run_kwargs)
+            rc, out, err = proc.returncode, proc.stdout, proc.stderr
+        except subprocess.TimeoutExpired as e:
+            # the sandbox was killed at the deadline — recorded as a warning,
+            # never propagated: one runaway script must not end the run
+            rc = None
+            out = (e.stdout or "")
+            out = out.decode() if isinstance(out, bytes) else out
+            err = "detonation timed out"
+            timeout_note = (f"detonation timed out after {timeout} s — the "
+                            "script was killed; scanning continues")
+        except OSError as e:
+            return DetonationReport(
+                file=str(path), executed=False, sandbox="bwrap",
+                notes=[f"failed to launch bwrap: {e}"],
+            )
+
+        try:
+            attempts = [l for l in netlog.read_text().splitlines() if l.strip()]
+        except OSError:
+            attempts = []
+
+        o, e2 = _tails(out, err)
+        if allow_net:
+            net_note = ("network NOT isolated (--allow-net): the sandbox shares "
+                        "the host network — real egress is possible")
+        else:
+            net_note = ("network isolated (--unshare-net): no connection can be "
+                        "opened from inside the sandbox")
+        notes = [net_note,
+                 "attempted tool egress is logged via PATH shims "
+                 "(curl/wget/nc/ssh/...)"]
+        if timeout_note is not None:
+            notes.append(timeout_note)
+        return DetonationReport(
+            file=str(path), executed=True, sandbox="bwrap",
+            exit_code=rc, stdout_tail=o, stderr_tail=e2,
+            network_attempts=attempts,
+            notes=notes,
+        )
+
+
+def detonate_tree(root: Path, allow_net: bool = False,
+                  timeout: int | None = 10) -> list[DetonationReport]:
+    return [detonate_file(p, timeout=timeout, allow_net=allow_net)
+            for p in find_scripts(root)]