refutescan 0.1.0__py3-none-any.whl

refutescan/__init__.py

@@ -0,0 +1,38 @@
+"""refutescan — a two-LLM, refute-first agentic source-code vulnerability scanner.
+
+A fast model NAVIGATES the repo with read-only tools and casts a wide net of
+candidate findings; a stronger model then REFUTES each one against the real code
+slice before it surfaces — so you get the recall of an agentic scanner without
+the false-positive flood. Scans run jailed in an ephemeral docker sandbox
+(clone-in-container, no network, read-only, non-root) by default. Bring your own
+LLMs.
+
+    from refutescan import scan
+    from refutescan.adapters import openai_navigator_factory, openai_judge_factory
+
+    result = scan(
+        "https://github.com/owner/repo",
+        navigator_factory=openai_navigator_factory(),
+        judge_factory=openai_judge_factory(),
+    )
+    for f in result.findings:
+        print(f["severity"], f["title"], f["file"], f["line"])
+"""
+
+from .models import ScanConfig, ScanResult, Verdict
+from .scanner import derive_title, looks_like_git_url, scan
+from .vulns import SEVERITIES, VULN_CLASSES
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "scan",
+    "ScanConfig",
+    "ScanResult",
+    "Verdict",
+    "VULN_CLASSES",
+    "SEVERITIES",
+    "looks_like_git_url",
+    "derive_title",
+    "__version__",
+]

refutescan/adapters/__init__.py

@@ -0,0 +1,11 @@
+"""Ready-made model factories for common providers.
+
+These are thin conveniences over LangChain chat models so you don't have to wire
+the injection seam yourself. Import the one you want; each needs its provider
+extra installed (e.g. ``pip install refutescan[openai]``). Bring your own by
+passing any LangChain-style chat model — see ``refutescan.providers``.
+"""
+
+from .openai_chat import openai_judge_factory, openai_navigator_factory
+
+__all__ = ["openai_navigator_factory", "openai_judge_factory"]

refutescan/adapters/openai_chat.py

@@ -0,0 +1,51 @@
+"""OpenAI (or any OpenAI-compatible endpoint) model factories.
+
+Requires ``langchain-openai`` (the ``openai`` extra). Set ``OPENAI_API_KEY``, or
+pass ``base_url`` to point at a compatible gateway (vLLM, Ollama's OpenAI shim,
+Azure OpenAI, a local proxy, …).
+
+    from refutescan import scan
+    from refutescan.adapters import openai_navigator_factory, openai_judge_factory
+
+    result = scan(
+        "https://github.com/owner/repo",
+        navigator_factory=openai_navigator_factory("gpt-4o-mini"),
+        judge_factory=openai_judge_factory("gpt-4o"),
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ..providers import JudgeFactory, NavigatorFactory
+
+
+def _chat(model: str, **kwargs: Any):
+    try:
+        from langchain_openai import ChatOpenAI
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            "refutescan's OpenAI adapter needs langchain-openai. "
+            "Install it with: pip install 'refutescan[openai]'"
+        ) from e
+    return ChatOpenAI(model=model, temperature=0, **kwargs)
+
+
+def openai_navigator_factory(model: str = "gpt-4o-mini", **kwargs: Any) -> NavigatorFactory:
+    """A navigator factory using a fast OpenAI tool-calling model (the wide-net pass)."""
+    def factory():
+        return _chat(model, **kwargs)
+    return factory
+
+
+def openai_judge_factory(model: str = "gpt-4o", **kwargs: Any) -> JudgeFactory:
+    """A judge factory using a stronger OpenAI model with structured output (refute pass)."""
+    def factory():
+        llm = _chat(model, **kwargs)
+
+        def judge(prompt: str, schema: type):
+            return llm.with_structured_output(schema).invoke(prompt)
+
+        return judge
+    return factory

refutescan/cli.py

@@ -0,0 +1,116 @@
+"""Command-line entry points.
+
+  refutescan <path-or-git-url> [options]   — run a scan, print findings
+  refutescan-build-sandbox                 — build the docker jail image
+
+The scan CLI uses the OpenAI adapter by default (needs the ``openai`` extra and
+OPENAI_API_KEY, or --base-url for a compatible gateway). For other providers,
+call ``refutescan.scan`` directly with your own factories.
+"""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+
+from . import __version__
+from .models import ScanConfig
+
+
+def _sev_marker(sev: str) -> str:
+    return {"critical": "[CRIT]", "high": "[HIGH]", "medium": "[MED ]",
+            "low": "[LOW ]", "info": "[INFO]"}.get(sev, "[????]")
+
+
+def main(argv=None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="refutescan",
+        description="Two-LLM, refute-first agentic source-code vulnerability scanner.")
+    ap.add_argument("source", help="a local directory path or a git URL to clone")
+    ap.add_argument("--branch", default="", help="git branch to clone (git sources only)")
+    ap.add_argument("--sandbox", default="auto", choices=["auto", "docker", "inprocess"],
+                    help="isolation backend (default: auto)")
+    ap.add_argument("--navigator-model", default="gpt-4o-mini",
+                    help="navigator (wide-net) model (default: gpt-4o-mini)")
+    ap.add_argument("--judge-model", default="gpt-4o",
+                    help="judge (refute) model (default: gpt-4o)")
+    ap.add_argument("--base-url", default=None,
+                    help="OpenAI-compatible base URL (vLLM, Azure, local proxy, …)")
+    ap.add_argument("--json", action="store_true", help="emit the full result as JSON")
+    ap.add_argument("--version", action="version", version=f"refutescan {__version__}")
+    args = ap.parse_args(argv)
+
+    try:
+        from .adapters import openai_judge_factory, openai_navigator_factory
+    except Exception as e:  # pragma: no cover
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+
+    kw = {"base_url": args.base_url} if args.base_url else {}
+    from . import scan
+
+    def _progress(phase: str) -> None:
+        if not args.json:
+            print(f"  … {phase}", file=sys.stderr)
+
+    try:
+        result = scan(
+            args.source,
+            navigator_factory=openai_navigator_factory(args.navigator_model, **kw),
+            judge_factory=openai_judge_factory(args.judge_model, **kw),
+            branch=args.branch,
+            config=ScanConfig(sandbox=args.sandbox),
+            progress=_progress,
+        )
+    except Exception as e:
+        print(f"scan failed: {type(e).__name__}: {e}", file=sys.stderr)
+        return 1
+
+    if args.json:
+        print(result.model_dump_json(indent=2))
+        return 0 if not result.findings else 1
+
+    s = result.summary
+    print(f"\nScanned {s.get('files_scanned')} files / {s.get('total_loc')} LOC"
+          f"  ·  {'sandboxed' if result.sandboxed else 'in-process'}")
+    print(f"{result.candidate_count} candidate(s) → {len(result.findings)} confirmed, "
+          f"{len(result.culled)} culled\n")
+    if not result.findings:
+        print("No confirmed findings.")
+        return 0
+    for f in result.findings:
+        conf = f.get("confidence")
+        conf_s = f" (conf {conf:.2f})" if isinstance(conf, (int, float)) else ""
+        print(f"{_sev_marker(f.get('severity', ''))} {f.get('title')}{conf_s}")
+        print(f"        {f.get('file')}:{f.get('line')}  [{f.get('vuln_class')}]")
+        if f.get("reasoning"):
+            print(f"        {f['reasoning']}")
+        print()
+    return 1  # non-zero exit when findings exist (CI-friendly)
+
+
+def build_sandbox(argv=None) -> int:
+    """Build the docker jail image (refutescan-build-sandbox)."""
+    from .sandbox.docker import sandbox_dir
+    ap = argparse.ArgumentParser(
+        prog="refutescan-build-sandbox",
+        description="Build the refutescan docker sandbox image.")
+    ap.add_argument("--image", default="refutescan-sandbox:current", help="image tag to build")
+    args = ap.parse_args(argv)
+    d = sandbox_dir()
+    print(f"Building {args.image} from {d} ...")
+    try:
+        subprocess.run(["docker", "build", "-t", args.image, str(d)], check=True)
+    except FileNotFoundError:
+        print("error: docker not found on PATH", file=sys.stderr)
+        return 2
+    except subprocess.CalledProcessError as e:
+        print(f"docker build failed ({e.returncode})", file=sys.stderr)
+        return e.returncode
+    print(f"Done. Image: {args.image}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

refutescan/codemap.py

@@ -0,0 +1,84 @@
+"""Deterministic, LLM-free repository map.
+
+A single os.walk that classifies files (source / manifest / entrypoint), counts
+LOC, and returns the relative source-file list the navigator will reach. Cheap,
+reproducible, and the same logic that runs inside the sandbox toolrunner.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+# Source file extensions worth scanning. Anything else (assets, lockfiles,
+# binaries, minified bundles) is counted as context, not handed to the LLM.
+SOURCE_EXTS = {
+    ".py", ".js", ".jsx", ".ts", ".tsx", ".java", ".go", ".rb", ".php", ".cs",
+    ".c", ".cc", ".cpp", ".h", ".hpp", ".rs", ".kt", ".scala", ".swift", ".sh",
+    ".bash", ".pl", ".pm", ".sql", ".html", ".vue", ".lua", ".groovy", ".tf",
+}
+# Directories never worth walking — vendored / generated / VCS metadata.
+SKIP_DIRS = {
+    ".git", ".hg", ".svn", "node_modules", "vendor", "venv", ".venv", "env",
+    "__pycache__", ".mypy_cache", ".pytest_cache", "dist", "build", ".next",
+    "site-packages", "target", ".idea", ".vscode", ".gradle", "bin", "obj",
+    "coverage", ".tox", ".cache", "bower_components",
+}
+# Dependency manifests we surface in the map (signal for what the app is).
+MANIFESTS = {
+    "requirements.txt", "pyproject.toml", "setup.py", "Pipfile", "package.json",
+    "go.mod", "pom.xml", "build.gradle", "Gemfile", "composer.json", "Cargo.toml",
+    "csproj",
+}
+# Entry-point filename hints (heuristic — where untrusted input often lands).
+ENTRY_HINTS = {
+    "app.py", "main.py", "manage.py", "wsgi.py", "asgi.py", "server.py",
+    "index.js", "server.js", "app.js", "main.go", "main.rs", "index.php",
+    "application.java",
+}
+
+
+def build_map(root: Path, max_map_files: int = 400,
+              max_file_bytes: int = 200_000) -> Tuple[Dict[str, Any], List[str]]:
+    """Walk the tree once. Returns (map_dict, relative_source_file_paths)."""
+    root = root.resolve()
+    langs: Dict[str, int] = {}
+    manifests: List[str] = []
+    entrypoints: List[str] = []
+    source_files: List[str] = []
+    total_files = 0
+    total_loc = 0
+
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in SKIP_DIRS and not d.startswith(".")]
+        for fn in filenames:
+            total_files += 1
+            ext = os.path.splitext(fn)[1].lower()
+            full = Path(dirpath) / fn
+            rel = str(full.relative_to(root))
+            if fn in MANIFESTS or fn.endswith(".csproj"):
+                manifests.append(rel)
+            if fn in ENTRY_HINTS:
+                entrypoints.append(rel)
+            if ext in SOURCE_EXTS and len(source_files) < max_map_files:
+                source_files.append(rel)
+                langs[ext] = langs.get(ext, 0) + 1
+                try:
+                    if full.stat().st_size <= max_file_bytes:
+                        with open(full, "r", errors="ignore") as fh:
+                            total_loc += sum(1 for _ in fh)
+                except Exception:
+                    pass
+
+    code_map = {
+        "root_name": root.name,
+        "total_files": total_files,
+        "source_files_scanned": len(source_files),
+        "truncated": len(source_files) >= max_map_files,
+        "total_loc": total_loc,
+        "languages": dict(sorted(langs.items(), key=lambda kv: -kv[1])),
+        "manifests": manifests[:30],
+        "entrypoints": entrypoints[:30],
+    }
+    return code_map, source_files

refutescan/fileaccess.py

@@ -0,0 +1,142 @@
+"""File access behind one interface, two backends.
+
+The navigator's tools and the validator's slice re-reads go through a
+``FileAccess`` object, so the same scan logic runs either in-process (guarded
+host) or via the docker sandbox without branching all over the pipeline.
+
+  • ``LocalFileAccess``   — reads the host filesystem, confined by safe_path()
+                            + the secret denylist (defense-in-depth fallback).
+  • ``SandboxFileAccess`` — delegates every touch to the toolrunner inside the
+                            locked-down container via the sandbox handle.
+"""
+
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import Any, Dict, List, Tuple
+
+from .codemap import SKIP_DIRS, build_map
+from .models import ScanConfig
+from .safety import safe_path
+
+
+class LocalFileAccess:
+    """In-process file access on the host, confined by safe_path() + denylist."""
+
+    def __init__(self, root: Path, config: ScanConfig) -> None:
+        self.root = root.resolve()
+        self.cfg = config
+
+    def build_map(self) -> Tuple[Dict[str, Any], List[str]]:
+        return build_map(self.root, self.cfg.max_map_files, self.cfg.max_file_bytes)
+
+    def list_dir(self, path: str = "") -> str:
+        try:
+            p = safe_path(self.root, path)
+        except Exception as e:
+            return f"error: {e}"
+        if not p.is_dir():
+            return f"error: not a directory: {path}"
+        entries = []
+        for child in sorted(p.iterdir()):
+            if child.name in SKIP_DIRS:
+                continue
+            entries.append(child.name + ("/" if child.is_dir() else ""))
+        return "\n".join(entries[:300]) or "(empty)"
+
+    def read_file(self, path: str, start_line: int = 1, max_lines: int = 200) -> str:
+        try:
+            p = safe_path(self.root, path)
+            with open(p, "r", errors="ignore") as fh:
+                lines = fh.readlines()
+        except Exception as e:
+            return f"error: {e}"
+        start = max(1, int(start_line or 1))
+        n = min(int(max_lines or 200), self.cfg.max_read_lines)
+        chunk = lines[start - 1: start - 1 + n]
+        body = "".join(f"{start+i:>5}  {ln.rstrip()}\n" for i, ln in enumerate(chunk))
+        return body[:self.cfg.max_file_bytes] or "(no lines in range)"
+
+    def grep(self, pattern: str, files: List[str], path_contains: str = "") -> str:
+        try:
+            rx = re.compile(pattern)
+        except re.error as e:
+            return f"error: bad regex: {e}"
+        hits: List[str] = []
+        for rel in files:
+            if path_contains and path_contains not in rel:
+                continue
+            try:
+                p = safe_path(self.root, rel)
+                with open(p, "r", errors="ignore") as fh:
+                    for i, ln in enumerate(fh, 1):
+                        if rx.search(ln):
+                            hits.append(f"{rel}:{i}: {ln.strip()[:200]}")
+                            if len(hits) >= self.cfg.max_grep_hits:
+                                return "\n".join(hits) + "\n…(truncated)"
+            except Exception:
+                continue
+        return "\n".join(hits) or "(no matches)"
+
+    def read_slice(self, rel: str, line: int, ctx: int = 25) -> str:
+        try:
+            p = safe_path(self.root, rel)
+            with open(p, "r", errors="ignore") as fh:
+                lines = fh.readlines()
+        except Exception as e:
+            return f"<could not read {rel}: {type(e).__name__}>"
+        if line and line > 0:
+            lo = max(0, line - ctx - 1)
+            hi = min(len(lines), line + ctx)
+        else:
+            lo, hi = 0, min(len(lines), 2 * ctx)
+        numbered = [f"{i+1:>5}  {lines[i].rstrip()}" for i in range(lo, hi)]
+        return "\n".join(numbered)[:8000]
+
+    def stop(self) -> None:
+        pass
+
+
+class SandboxFileAccess:
+    """File access delegated to the docker sandbox via the toolrunner."""
+
+    def __init__(self, sandbox) -> None:
+        self.sb = sandbox
+
+    def build_map(self) -> Tuple[Dict[str, Any], List[str]]:
+        out = self.sb.call("build_map", {})
+        if "error" in out:
+            raise RuntimeError(f"sandbox build_map: {out['error']}")
+        return out["map"], out["files"]
+
+    def list_dir(self, path: str = "") -> str:
+        try:
+            out = self.sb.call("list_dir", {"path": path})
+        except Exception as e:
+            return f"error: {e}"
+        return out.get("error") and f"error: {out['error']}" or out.get("result", "")
+
+    def read_file(self, path: str, start_line: int = 1, max_lines: int = 200) -> str:
+        try:
+            out = self.sb.call("read_file", {"path": path, "start_line": start_line, "max_lines": max_lines})
+        except Exception as e:
+            return f"error: {e}"
+        return out.get("error") and f"error: {out['error']}" or out.get("result", "")
+
+    def grep(self, pattern: str, files: List[str], path_contains: str = "") -> str:
+        try:
+            out = self.sb.call("grep", {"pattern": pattern, "files": files, "path_contains": path_contains})
+        except Exception as e:
+            return f"error: {e}"
+        return out.get("error") and f"error: {out['error']}" or out.get("result", "")
+
+    def read_slice(self, rel: str, line: int, ctx: int = 25) -> str:
+        try:
+            out = self.sb.call("read_slice", {"path": rel, "line": line, "ctx": ctx})
+        except Exception as e:
+            return f"<could not read {rel}: {type(e).__name__}>"
+        return out.get("result") or f"<could not read {rel}>"
+
+    def stop(self) -> None:
+        self.sb.stop()

refutescan/models.py

@@ -0,0 +1,91 @@
+"""Typed data shapes for the scan pipeline.
+
+``ScanConfig`` is a plain dataclass (bounds + isolation knobs). The finding/
+verdict shapes are pydantic so the judge's structured-output call validates and
+retries on a malformed model response. ``Verdict`` is the schema the kernel
+hands to the injected judge; everything else is what the kernel returns.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Literal
+
+from pydantic import BaseModel, Field
+
+
+# ── Configuration ───────────────────────────────────────────────────────────────
+
+@dataclass
+class ScanConfig:
+    """Bounds and isolation settings for a scan. Defaults are sane for a typical
+    web-app repo; raise the bounds for larger codebases at the cost of more LLM
+    calls and wall-clock."""
+
+    # Walk / read bounds — keep a scan from running away on a huge repo.
+    max_map_files: int = 400          # source files the map tracks / navigator can reach
+    max_file_bytes: int = 200_000     # per-file read ceiling
+    max_read_lines: int = 600         # per read_file call
+    max_grep_hits: int = 80           # per grep call
+
+    # Navigator (the wide-net pass).
+    nav_max_iters: int = 40           # tool-loop turns
+    nav_deadline: float = 300.0       # wall-clock budget (seconds)
+    max_candidates: int = 60          # candidates handed to the judge
+
+    # Validator (the refute-first pass).
+    judge_timeout: float = 60.0       # per-candidate judge deadline
+
+    # Source preparation.
+    clone_timeout: int = 120          # git clone budget (seconds)
+    git_allowed_protocols: str = "http:https:ssh:git"
+
+    # Isolation. sandbox: "auto" (docker if available, else in-process),
+    # "docker" (force; error if unavailable), "inprocess" (force guarded host).
+    sandbox: str = "auto"
+    sandbox_image: str = "refutescan-sandbox:current"
+    sandbox_uid: str = "10001"
+    sandbox_pids: str = "256"
+    sandbox_memory: str = "2g"
+    sandbox_cpus: str = "2"
+    docker_bin: str = "docker"
+    exec_timeout: int = 90            # per docker-exec tool call
+    container_ttl: int = 1200         # audit container sleep budget (> nav_deadline)
+
+    # In-process backend only: confine local-path scans to these roots. Empty =
+    # unrestricted (the docker jail is the boundary). Secret denylist always on.
+    allowed_roots: List[Path] = field(default_factory=list)
+
+
+# ── Judge I/O ───────────────────────────────────────────────────────────────────
+
+class Verdict(BaseModel):
+    """The structured verdict the judge returns for one candidate. This is the
+    schema the kernel hands to the injected judge callable."""
+
+    is_real: bool = Field(description="True ONLY if the code shown demonstrates a real, "
+                                      "exploitable vulnerability with a concrete untrusted "
+                                      "source reaching a dangerous sink. Default to false when unsure.")
+    reachable: bool = Field(description="True if untrusted input can actually reach this sink "
+                                        "(not gated by validation/auth that neutralizes it).")
+    confidence: float = Field(description="0.0–1.0 confidence that this is a true positive.")
+    severity: Literal["critical", "high", "medium", "low", "info"] = Field(
+        description="Impact severity if exploitable.")
+    reasoning: str = Field(description="2–4 sentences: the data flow you confirmed, or precisely "
+                                       "why this is a false positive.")
+    repro: str = Field(description="If real: concrete repro / exploitation steps. Else: empty.")
+    recommendation: str = Field(description="If real: the targeted fix. Else: empty.")
+
+
+# ── Result shapes (returned to the caller) ──────────────────────────────────────
+
+class ScanResult(BaseModel):
+    """Everything one scan produced. The consumer persists/renders this."""
+
+    code_map: Dict[str, Any]
+    findings: List[Dict[str, Any]]   # confirmed, sorted worst-first
+    culled: List[Dict[str, Any]]     # refuted/timed-out candidates, with reasons
+    summary: Dict[str, Any]
+    candidate_count: int
+    sandboxed: bool

refutescan/providers.py

@@ -0,0 +1,32 @@
+"""The model-injection seam — how a caller plugs its own LLMs into the scan.
+
+refutescan is model-agnostic: it never imports a provider SDK in the core. The
+caller passes two factories.
+
+navigator_factory() -> a chat model
+    A LangChain-style chat model that supports ``.bind_tools(tools)`` and
+    ``.invoke(messages)`` returning a message whose ``.tool_calls`` the loop
+    reads. This drives the wide-net pass. A fast/cheap tool-calling model is the
+    right fit (it is fine that it over-reports — the judge culls).
+
+judge_factory() -> judge(prompt: str, schema: type[BaseModel]) -> BaseModel
+    A callable that runs ONE structured-output completion: given a prompt and a
+    pydantic model, return a validated instance. This is the refute-first pass;
+    a stronger model is the right fit. The kernel wraps each call in a hard
+    timeout, so the callable itself need not.
+
+See ``refutescan.adapters`` for ready-made factories (e.g. OpenAI).
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from pydantic import BaseModel
+
+# A factory returning a tool-capable chat model (bind_tools + invoke).
+NavigatorFactory = Callable[[], Any]
+
+# A factory returning a judge callable: (prompt, schema) -> validated instance.
+JudgeCallable = Callable[[str, type], BaseModel]
+JudgeFactory = Callable[[], JudgeCallable]

refutescan/safety.py

@@ -0,0 +1,89 @@
+"""Path-safety and secret-denylist guards shared by every file-access backend.
+
+These are defense-in-depth. The real isolation boundary is the docker sandbox
+(``--network none``, read-only, non-root, only the target mounted). But the
+in-process backend reads files as the host user, so the same guards run there —
+and they run *inside* the container too (see ``sandbox/toolrunner.py``), so a
+single bypassed layer never exposes credentials.
+
+The constants here are deliberately conservative defaults. ``toolrunner.py``
+keeps its own copies because it ships into a minimal image with no refutescan
+install; keep the two in sync.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import os
+from pathlib import Path
+from typing import Iterable, List, Optional
+
+# Path components we never descend into or read — credential & VCS/runtime stores.
+SECRET_DIR_NAMES = {
+    ".ssh", ".gnupg", ".aws", ".azure", ".kube", ".docker", ".secrets", "secrets",
+    ".git",
+}
+
+# Basename globs we never read, even inside an allowed root — keys, certs, env files.
+SECRET_FILE_GLOBS = (
+    "*.key", "*.pem", "*.age", "*.p12", "*.pfx", "*.keystore", "*.jks",
+    ".env", ".env.*", "*.env", "id_rsa*", "id_ed25519*", "id_ecdsa*", "id_dsa*",
+    ".netrc", ".pgpass", ".htpasswd", "credentials", "*.secret", "*.secrets",
+)
+
+# Transports git may use when cloning — excludes ext::/fd:: (command execution).
+GIT_ALLOWED_PROTOCOLS = "http:https:ssh:git"
+
+
+def parse_roots(spec: Optional[str]) -> List[Path]:
+    """Parse a colon-separated roots string into resolved Paths ([] if falsy)."""
+    if not spec:
+        return []
+    return [
+        Path(os.path.expanduser(p)).resolve()
+        for p in spec.split(":")
+        if p.strip()
+    ]
+
+
+def within_allowed_roots(p: Path, roots: Optional[Iterable[Path]]) -> bool:
+    """True iff p resolves inside one of the configured roots.
+
+    An empty/None roots list means "unrestricted" — the right default for a
+    library running on the user's own machine, where the docker jail (or the
+    user's own intent) is the boundary, not a host allowlist.
+    """
+    roots = list(roots or [])
+    if not roots:
+        return True
+    p = p.resolve()
+    return any(p == r or r in p.parents for r in roots)
+
+
+def deny_secret(p: Path, root: Path) -> None:
+    """Refuse credential/key/env paths even within an allowed root. Raises ValueError."""
+    try:
+        rel = p.relative_to(root)
+    except ValueError:
+        rel = p
+    for part in rel.parts:
+        if part in SECRET_DIR_NAMES:
+            raise ValueError(f"refusing to read sensitive path '{part}/'")
+    name = p.name
+    for glob in SECRET_FILE_GLOBS:
+        if fnmatch.fnmatch(name, glob):
+            raise ValueError(f"refusing to read sensitive file '{name}'")
+
+
+def safe_path(root: Path, rel: str) -> Path:
+    """Resolve rel under root; reject path escapes and secret-shaped files.
+
+    The single choke point every navigator tool (list_dir / read_file / grep)
+    and the judge's slice re-read go through, so the denylist covers them all.
+    """
+    root = root.resolve()
+    p = (root / (rel or "").lstrip("/")).resolve()
+    if root != p and root not in p.parents:
+        raise ValueError("path escapes the repository root")
+    deny_secret(p, root)
+    return p