abrade-cli 0.1.2__tar.gz → 0.1.4__tar.gz

{abrade_cli-0.1.2 → abrade_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: abrade-cli
-Version: 0.1.2
+Version: 0.1.4
 Summary: Abrade's self-hosted CLI — run the same injection suite entirely offline, no SaaS required.
 Keywords: ai-agents,security-testing,prompt-injection,red-teaming,llm-security
 Author: Abrade

{abrade_cli-0.1.2 → abrade_cli-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "abrade-cli"
-version = "0.1.2"
+version = "0.1.4"
 description = "Abrade's self-hosted CLI — run the same injection suite entirely offline, no SaaS required."
 readme = "README.md"
 requires-python = ">=3.12"

{abrade_cli-0.1.2 → abrade_cli-0.1.4}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "abrade-cli"
-version = "0.1.2"
+version = "0.1.4"
 description = "Abrade's self-hosted CLI — run the same injection suite entirely offline, no SaaS required."
 readme = "README.md"
 # The project, not a personal handle. PyPI renders this as "Author" on

{abrade_cli-0.1.2 → abrade_cli-0.1.4}/src/abrade_cli/auth.py

@@ -20,10 +20,21 @@ import urllib.request
 from pathlib import Path
 from typing import TYPE_CHECKING
 
+from abrade_cli.safeio import write_secret_text
+
 if TYPE_CHECKING:
     from abrade_cli.models import RunRecord
 
-DEFAULT_API_URL = "http://localhost:8123"
+# The hosted console. This defaulted to http://localhost:8123, which is
+# where the API runs under docker-compose — correct for someone developing
+# Abrade, wrong for everyone who installs it. `abrade login` from a clean
+# machine tried to reach a port on the user's own laptop and failed with a
+# connection error that named localhost, which reads like the CLI is
+# broken rather than misconfigured.
+#
+# ABRADE_API_URL still overrides, which is how local development points it
+# back at compose.
+DEFAULT_API_URL = "https://abrade.ai"
 
 
 class AbradeApiError(Exception):
@@ -64,14 +75,19 @@ def save_credentials(
     *, api_key: str, api_url: str, org: dict, home: Path | None = None
 ) -> None:
     path = _credentials_path(home)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    path.write_text(
+    # Was write_text() followed by chmod(0o600). Between those two calls
+    # the file holding a live API key sat at whatever the umask allowed —
+    # 0644 on a typical workstation — and that window is the whole
+    # exposure. Creating it 0600 has no window. ~/.abrade itself is
+    # tightened to 0700 for the same reason: it previously inherited the
+    # umask too.
+    write_secret_text(
+        path,
         json.dumps(
             {"api_key": api_key, "api_url": api_url, "org_name": org.get("name")},
             indent=2,
-        )
+        ),
     )
-    path.chmod(0o600)  # contains a live secret, unlike tos_accepted.json
 
 
 def load_credentials(home: Path | None = None) -> dict | None:

{abrade_cli-0.1.2 → abrade_cli-0.1.4}/src/abrade_cli/cli.py

@@ -16,7 +16,7 @@ from abrade_cli.execution import MissingCredentialError
 from abrade_cli.models import SuiteMode
 from abrade_cli.report import render_pdf
 from abrade_cli.runner import run_suite
-from abrade_cli.storage import list_runs, load_run, save_run
+from abrade_cli.storage import latest_run_id, list_runs, load_run, save_run
 
 app = typer.Typer(
     name="abrade",
@@ -97,6 +97,85 @@ def init(
     console.print(f"[green]Wrote {path}.[/green] Edit it, then run `abrade run`.")
 
 
+@app.command()
+def upgrade(
+    check_only: bool = typer.Option(
+        False,
+        "--check",
+        help="Exit non-zero if a newer version exists. For CI.",
+    ),
+) -> None:
+    """Check whether a newer CLI is published, and how to install it."""
+    from abrade_cli import upgrade as upgrade_module
+
+    installed = _installed_version()
+    try:
+        release = upgrade_module.check(installed)
+    except upgrade_module.UpgradeCheckError as exc:
+        # A failed check must not look like "you are up to date". Someone
+        # offline is the expected case for this tool, not an error worth a
+        # stack trace — but they should know the question went unanswered.
+        console.print(f"[yellow]Could not check for updates:[/yellow] {exc}")
+        console.print(f"Installed: [bold]{installed}[/bold]")
+        raise typer.Exit(code=0 if not check_only else 1) from exc
+
+    if not release.outdated:
+        console.print(f"[green]Up to date.[/green] abrade {release.installed}")
+        return
+
+    console.print(
+        f"[yellow]Update available:[/yellow] "
+        f"{release.installed} → [bold]{release.latest}[/bold]"
+    )
+    console.print(f"\n  {upgrade_module.install_command()}\n")
+    if check_only:
+        raise typer.Exit(code=1)
+
+
+@app.command()
+def verify(
+    agent: Path = typer.Option(config_module.DEFAULT_CONFIG_PATH, "--agent"),
+    corpus_path: Path | None = typer.Option(None, "--corpus"),
+    probe: bool = typer.Option(
+        False,
+        "--probe",
+        help="Also send ONE real request to the model endpoint. Costs tokens.",
+    ),
+) -> None:
+    """Check the configuration a run needs, without firing a suite."""
+    from abrade_cli import verify as verify_module
+
+    checks = verify_module.run_checks(
+        config_path=agent, corpus_path=corpus_path, probe=probe
+    )
+
+    symbol = {
+        verify_module.Level.OK: "[green]ok  [/green]",
+        verify_module.Level.WARN: "[yellow]warn[/yellow]",
+        verify_module.Level.FAIL: "[red]FAIL[/red]",
+    }
+    for check in checks:
+        console.print(f"  {symbol[check.level]}  [bold]{check.name}[/bold]")
+        console.print(f"        [dim]{check.detail}[/dim]")
+
+    failures = [c for c in checks if c.blocking]
+    warnings = [c for c in checks if c.level is verify_module.Level.WARN]
+
+    console.print()
+    if failures:
+        console.print(
+            f"[red]{len(failures)} blocking problem(s).[/red] "
+            f"`abrade run` would not produce a meaningful result."
+        )
+        # Non-zero so CI can gate on this rather than discovering the same
+        # problems one failed run later.
+        raise typer.Exit(code=1)
+    if warnings:
+        console.print(f"[yellow]Ready, with {len(warnings)} warning(s).[/yellow]")
+        return
+    console.print("[green]Ready.[/green]")
+
+
 @app.command()
 def run(
     agent: Path = typer.Option(config_module.DEFAULT_CONFIG_PATH, "--agent"),
@@ -236,7 +315,12 @@ def report(
 
 @app.command()
 def push(
-    run_id: str = typer.Option(..., "--run"),
+    run_id: str | None = typer.Option(None, "--run"),
+    # For CI, which has just produced a run and has no way to learn its id
+    # without parsing stdout. Ordered by write time, not by id — see
+    # storage.latest_run_id, because run ids are UUIDs and sorting them
+    # would upload an arbitrary run.
+    latest: bool = typer.Option(False, "--latest"),
     agent: Path = typer.Option(config_module.DEFAULT_CONFIG_PATH, "--agent"),
     api_url: str | None = typer.Option(None, "--api-url"),
 ) -> None:
@@ -245,6 +329,20 @@ def push(
     Optional — abrade run/list/report never require this. Nothing is sent
     unless you run this command explicitly (see `abrade login --help`).
     """
+    if latest and run_id:
+        console.print("[red]Pass either --run or --latest, not both.[/red]")
+        raise typer.Exit(code=2)
+    if latest:
+        run_id = latest_run_id()
+        if run_id is None:
+            console.print("[red]No local runs found — run `abrade run` first.[/red]")
+            raise typer.Exit(code=1)
+    if not run_id:
+        console.print(
+            "[red]Which run? Pass --run <id>, or --latest for the most recent.[/red]"
+        )
+        raise typer.Exit(code=2)
+
     try:
         record = load_run(run_id)
     except FileNotFoundError as exc:

{abrade_cli-0.1.2 → abrade_cli-0.1.4}/src/abrade_cli/report.py

@@ -4,6 +4,7 @@ from fpdf import FPDF
 from fpdf.enums import XPos, YPos
 
 from abrade_cli.models import RunRecord
+from abrade_cli.safeio import harden_existing, secure_dir
 
 # Same palette as Console's light-theme tokens.css and the CLI's own
 # VERDICT_COLOR in cli.py — one source of truth for what each verdict
@@ -146,6 +147,17 @@ def render_pdf(run: RunRecord, output_path: Path) -> Path:
         pdf.rect(pdf.l_margin - 4, top, 1.2, pdf.get_y() - top - 1, style="F")
         pdf.ln(3)
 
-    output_path.parent.mkdir(parents=True, exist_ok=True)
+    # A report contains every finding the run produced — the agent's raw
+    # replies and the planted canaries — so it is as sensitive as the
+    # evidence it summarises, and it was being written at whatever the
+    # umask allowed (0644 typically).
+    #
+    # fpdf2's output() takes a path, not a file descriptor, so this cannot
+    # use the create-at-0600 primitive the other writers do. Tightening
+    # immediately afterwards leaves a window this code cannot close
+    # without reimplementing the PDF writer; it is narrow, and the
+    # alternative was a world-readable report forever.
+    secure_dir(output_path.parent)
     pdf.output(str(output_path))
+    harden_existing(output_path)
     return output_path

abrade_cli-0.1.4/src/abrade_cli/safeio.py

@@ -0,0 +1,147 @@
+"""Writing files that hold evidence or credentials, safely. (ABR-017)
+
+Four call sites wrote sensitive material four slightly different ways, and
+each got a different subset of this right. One primitive instead, because
+the parts that were missing are exactly the parts that are easy to forget:
+
+**Permissions must exist before the content does.** `write_text()` then
+`chmod(0o600)` leaves the file world-readable under a typical 022 umask
+for the window between the two calls, and that window is when a co-tenant
+process reads it. `os.open(..., 0o600)` has no window.
+
+**Writes must not follow symlinks.** Without `O_NOFOLLOW`, a local actor
+who controls the path can point `.abrade/runs/<id>.json` at any file the
+user can write, and the CLI truncates it. `O_NOFOLLOW` makes that an
+error instead.
+
+**Replacement must be atomic.** Writing in place with `O_TRUNC` means a
+crash — or a full disk — leaves a truncated file that still parses as
+"the run". Crash corruption needs no attacker, which makes it the more
+likely of the two failures here. Writing a temp file and `os.replace()`
+means a reader sees either the old content or the new, never half.
+
+**fsync before rename**, or the rename can land before the bytes do and a
+power loss leaves an empty file where a complete one is expected.
+
+POSIX-only in one respect: `O_NOFOLLOW` does not exist on Windows, and
+`os.open` ignores the mode argument there. The CLI's threat model is a
+shared CI runner or a developer workstation, both POSIX in practice; on
+Windows this degrades to an atomic write without the symlink guard rather
+than failing.
+"""
+
+from __future__ import annotations
+
+import os
+import tempfile
+from pathlib import Path
+
+# Owner-only, for anything holding evidence or a credential.
+SECRET_FILE_MODE = 0o600
+SECRET_DIR_MODE = 0o700
+
+_NOFOLLOW = getattr(os, "O_NOFOLLOW", 0)
+
+
+class UnsafePathError(RuntimeError):
+    """The target is a symlink, or its directory is not owner-controlled."""
+
+
+def secure_dir(path: Path) -> Path:
+    """Create (or tighten) a directory to 0700 and return it.
+
+    `mkdir(mode=...)` is masked by the umask and skipped entirely when the
+    directory already exists, so the mode is set explicitly either way —
+    the pre-existing directory is the common case and the one that would
+    otherwise keep whatever permissions it was created with.
+    """
+    path.mkdir(parents=True, exist_ok=True, mode=SECRET_DIR_MODE)
+    try:
+        os.chmod(path, SECRET_DIR_MODE)
+    except OSError:
+        # A directory we cannot chmod (someone else's, or a read-only
+        # mount) is not worth aborting a run over — the file write below
+        # still creates 0600, and it will fail loudly if the directory is
+        # genuinely unusable.
+        pass
+    return path
+
+
+def _reject_symlink(path: Path) -> None:
+    # lstat rather than exists(): exists() follows the link and reports on
+    # the target, which is the thing being defended against.
+    try:
+        if path.is_symlink():
+            raise UnsafePathError(
+                f"{path} is a symlink. Refusing to write evidence or "
+                f"credentials through one — the target may be a file you did "
+                f"not intend to overwrite."
+            )
+    except OSError:
+        return
+
+
+def write_secret_text(path: Path, content: str) -> Path:
+    """Atomically write `content` to `path`, owner-readable only.
+
+    The temp file is created in the destination directory rather than
+    /tmp, because `os.replace` is only atomic within a filesystem and
+    /tmp is frequently a different one.
+    """
+    _reject_symlink(path)
+    secure_dir(path.parent)
+
+    fd, tmp_name = tempfile.mkstemp(
+        dir=str(path.parent), prefix=f".{path.name}.", suffix=".tmp"
+    )
+    tmp = Path(tmp_name)
+    try:
+        os.fchmod(fd, SECRET_FILE_MODE)
+        with os.fdopen(fd, "w") as handle:
+            handle.write(content)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(tmp, path)
+    except BaseException:
+        # Never leave a partial temp file holding evidence behind.
+        tmp.unlink(missing_ok=True)
+        raise
+    return path
+
+
+def create_secret_file_exclusively(path: Path, content: str) -> bool:
+    """Write `content` only if `path` does not already exist.
+
+    Returns False when it did. `O_EXCL | O_CREAT` makes the check and the
+    creation one operation — an `exists()` test followed by a write is a
+    race, and the loser silently overwrites whatever the winner put there.
+    """
+    secure_dir(path.parent)
+    try:
+        fd = os.open(
+            path,
+            os.O_WRONLY | os.O_CREAT | os.O_EXCL | _NOFOLLOW,
+            SECRET_FILE_MODE,
+        )
+    except FileExistsError:
+        return False
+    with os.fdopen(fd, "w") as handle:
+        handle.write(content)
+        handle.flush()
+        os.fsync(handle.fileno())
+    return True
+
+
+def harden_existing(path: Path) -> None:
+    """Tighten a file some other library created.
+
+    For outputs written by code that does not accept a file descriptor —
+    fpdf2's `output()` takes a path. The window between its create and
+    this chmod is real and unavoidable without reimplementing the writer;
+    it is narrower than leaving the file 0644 forever, which is what
+    happened before.
+    """
+    try:
+        os.chmod(path, SECRET_FILE_MODE)
+    except OSError:
+        pass

{abrade_cli-0.1.2 → abrade_cli-0.1.4}/src/abrade_cli/storage.py

@@ -4,11 +4,15 @@ here ever leaves the local filesystem (hard constraint #4).
 """
 
 import json
-import os
 from dataclasses import asdict
 from pathlib import Path
 
 from abrade_cli.models import Posture, ResultRow, RunRecord, SuiteMode, Verdict
+from abrade_cli.safeio import (
+    create_secret_file_exclusively,
+    secure_dir,
+    write_secret_text,
+)
 
 RUNS_DIR = Path(".abrade") / "runs"
 
@@ -33,34 +37,31 @@ def save_run(run: RunRecord, base: Path | None = None) -> Path:
     makes that safe by default rather than by documentation.
     """
     path = _run_path(run.id, base)
-    path.parent.mkdir(parents=True, exist_ok=True, mode=0o700)
-    # mkdir's mode is masked by umask and skipped entirely if the
-    # directory already exists, so set it explicitly either way.
-    os.chmod(path.parent, 0o700)
+    secure_dir(path.parent)
     _ensure_gitignore(path.parent)
 
-    # Create with 0600 rather than writing and then chmod-ing: between
-    # those two calls the file is readable, and that window is when a
-    # co-tenant process gets it.
-    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
-    with os.fdopen(fd, "w") as handle:
-        handle.write(json.dumps(asdict(run), indent=2, default=str))
-    os.chmod(path, 0o600)
-    return path
+    # Atomic, 0600 from creation, and refuses to write through a symlink.
+    # The previous version opened the real path with O_TRUNC, so a crash
+    # mid-write left a truncated file that still looked like the run — and
+    # crash corruption, unlike symlink redirection, needs no attacker.
+    return write_secret_text(path, json.dumps(asdict(run), indent=2, default=str))
 
 
 def _ensure_gitignore(runs_dir: Path) -> None:
-    """Keep run evidence out of the customer's repository."""
-    marker = runs_dir.parent / ".gitignore"
-    if marker.exists():
-        return
-    fd = os.open(marker, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
-    with os.fdopen(fd, "w") as handle:
-        handle.write(
-            "# Run evidence contains raw agent replies, injected telemetry\n"
-            "# and planted canaries. Not for version control.\n"
-            "*\n"
-        )
+    """Keep run evidence out of the customer's repository.
+
+    Exclusive-create rather than exists()-then-write: those are two
+    operations, and between them another process can create the file, at
+    which point this one silently truncates whatever was written. It also
+    means an existing .gitignore is never overwritten, which was the
+    intent of the original `exists()` check.
+    """
+    create_secret_file_exclusively(
+        runs_dir.parent / ".gitignore",
+        "# Run evidence contains raw agent replies, injected telemetry\n"
+        "# and planted canaries. Not for version control.\n"
+        "*\n",
+    )
 
 
 def load_run(run_id: str, base: Path | None = None) -> RunRecord:
@@ -109,6 +110,22 @@ def load_run(run_id: str, base: Path | None = None) -> RunRecord:
     )
 
 
+def latest_run_id(base: Path | None = None) -> str | None:
+    """The most recently written run, or None if there are none.
+
+    Ordered by write time rather than by id. Run ids are UUIDs, so sorting
+    them alphabetically returns an arbitrary run — and `abrade push
+    --latest` picking the wrong one would upload the wrong evidence
+    silently, which is worse than failing.
+    """
+    root = base or Path.cwd()
+    runs_dir = root / RUNS_DIR
+    if not runs_dir.exists():
+        return None
+    runs = sorted(runs_dir.glob("*.json"), key=lambda p: p.stat().st_mtime)
+    return runs[-1].stem if runs else None
+
+
 def list_runs(base: Path | None = None) -> list[str]:
     root = base or Path.cwd()
     runs_dir = root / RUNS_DIR

abrade_cli-0.1.4/src/abrade_cli/upgrade.py

@@ -0,0 +1,97 @@
+"""Is this copy of the CLI current, and how would you replace it?
+
+Deliberately never automatic. This CLI's whole claim is "self-hosted,
+offline-by-default" — a version check that phoned PyPI on every `abrade
+run` would make that false for a convenience nobody asked for, and would
+leak a usage signal from air-gapped environments that chose this tool
+precisely because it does not talk to anyone. So the network call happens
+only when someone types `abrade upgrade`.
+
+The command deliberately does NOT perform the upgrade. It prints the
+command for the installer it detected. Running the upgrade itself means
+guessing between uv, pipx and pip, and guessing wrong means either a
+confusing failure or — worse — a second copy installed alongside the first
+under a different manager, which is exactly the state that produces "I
+updated it and the new command still isn't there".
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from pathlib import Path
+
+PYPI_URL = "https://pypi.org/pypi/abrade-cli/json"
+
+
+class UpgradeCheckError(RuntimeError):
+    pass
+
+
+@dataclass(frozen=True)
+class Release:
+    installed: str
+    latest: str
+
+    @property
+    def outdated(self) -> bool:
+        return _parse(self.latest) > _parse(self.installed)
+
+
+def _parse(version: str) -> tuple:
+    """Compare versions numerically, so 0.1.10 sorts above 0.1.9.
+
+    A string comparison gets that backwards, and the failure is silent:
+    the CLI would simply stop reporting upgrades once the patch number
+    reached double digits. Non-numeric segments (rc, dev) sort below a
+    plain release, which is the conservative direction — it can suggest an
+    upgrade that is not needed, never hide one that is.
+    """
+    parts = []
+    for chunk in version.split("."):
+        digits = ""
+        for char in chunk:
+            if not char.isdigit():
+                break
+            digits += char
+        parts.append((int(digits) if digits else 0, chunk == digits))
+    return tuple(parts)
+
+
+def latest_version(*, timeout: float = 10.0) -> str:
+    try:
+        with urllib.request.urlopen(PYPI_URL, timeout=timeout) as response:  # noqa: S310 — fixed https URL constant
+            return str(json.loads(response.read())["info"]["version"])
+    except urllib.error.URLError as exc:
+        raise UpgradeCheckError(f"Could not reach PyPI: {exc.reason}") from exc
+    except (KeyError, ValueError) as exc:
+        raise UpgradeCheckError("PyPI returned an unexpected response.") from exc
+
+
+def install_command() -> str:
+    """The upgrade command for whichever installer put this here.
+
+    Detected from the path of the running interpreter rather than asked
+    for, because the common failure is not knowing which manager was used
+    — and the answer is sitting in sys.executable.
+    """
+    executable = Path(sys.executable).resolve()
+    parts = {p.lower() for p in executable.parts}
+
+    if "uv" in parts or "uv-tool" in parts or os.environ.get("UV_TOOL_DIR"):
+        return "uv tool upgrade abrade-cli"
+    if "pipx" in parts:
+        return "pipx upgrade abrade-cli"
+    if any("virtualenvs" in p or ".venv" in p for p in parts):
+        # Inside a project environment, so upgrading globally would touch a
+        # different copy than the one being run.
+        return "uv pip install --upgrade abrade-cli"
+    return "pip install --upgrade abrade-cli"
+
+
+def check(installed: str, *, timeout: float = 10.0) -> Release:
+    return Release(installed=installed, latest=latest_version(timeout=timeout))

abrade_cli-0.1.4/src/abrade_cli/verify.py

@@ -0,0 +1,248 @@
+"""Pre-flight checks for everything a run needs, before it needs it.
+
+A run fires a whole suite of payloads at a live agent and judges each one —
+two LLM calls per injection, against two different credentials. Every one
+of the things that can be missing is discovered *during* that, when the
+cost has already been paid and a partly-finished run has to be explained.
+
+The checks are ordered cheapest-first and none of them spend a token by
+default. The endpoint probe is opt-in for exactly that reason: confirming
+an endpoint answers means sending it a real request, and a pre-flight check
+that quietly bills you is a worse trade than one that says "not checked".
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import Path
+from urllib.parse import urlparse
+
+
+class Level(StrEnum):
+    OK = "ok"
+    WARN = "warn"
+    FAIL = "fail"
+
+
+@dataclass(frozen=True)
+class Check:
+    name: str
+    level: Level
+    detail: str
+
+    @property
+    def blocking(self) -> bool:
+        return self.level is Level.FAIL
+
+
+def _config_checks(config_path: Path) -> tuple[list[Check], object | None]:
+    from abrade_cli import config as config_module
+
+    try:
+        config = config_module.load_config(config_path)
+    except FileNotFoundError as exc:
+        return [Check("agent config", Level.FAIL, str(exc))], None
+    except Exception as exc:  # noqa: BLE001 — yaml and pydantic both land here
+        # Pydantic's own message names the offending field, which is more
+        # useful than anything paraphrasing it would be.
+        return [Check("agent config", Level.FAIL, f"{config_path}: {exc}")], None
+
+    checks = [
+        Check("agent config", Level.OK, f"{config_path} parsed — agent {config.name!r}")
+    ]
+
+    # A default system prompt means the scaffold was never edited, so the
+    # run would measure the template rather than the customer's agent. Not
+    # fatal — someone may genuinely be trying the tool out — but reporting
+    # it as fine would make the resulting verdicts look meaningful.
+    if "Replace this with your actual agent" in config.system_prompt:
+        checks.append(
+            Check(
+                "system prompt",
+                Level.WARN,
+                "still the scaffold's placeholder — the run would test the "
+                "template, not your agent",
+            )
+        )
+    else:
+        checks.append(Check("system prompt", Level.OK, "customised"))
+
+    return checks, config
+
+
+def _credential_checks(config) -> list[Check]:  # noqa: ANN001
+    checks: list[Check] = []
+
+    aut_env = config.model_key_env
+    if os.environ.get(aut_env, "").strip():
+        checks.append(
+            Check(f"${aut_env}", Level.OK, "set (agent-under-test credential)")
+        )
+    else:
+        checks.append(
+            Check(
+                f"${aut_env}",
+                Level.FAIL,
+                "unset — this is the credential the run authenticates to your "
+                "agent with. Every injection would fail before reaching it.",
+            )
+        )
+
+    judge_env = "ABRADE_JUDGE_API_KEY"
+    if os.environ.get(judge_env, "").strip():
+        checks.append(Check(f"${judge_env}", Level.OK, "set (judge credential)"))
+    else:
+        checks.append(
+            Check(
+                f"${judge_env}",
+                Level.FAIL,
+                "unset — every result would score ERROR. A scan that cannot "
+                "reach the judge is not a passing scan.",
+            )
+        )
+
+    # The one configuration mistake that is silently expensive rather than
+    # loudly broken: the same key on both sides still runs, still scores,
+    # and quietly means a payload that talks the agent into disclosing its
+    # credential has disclosed the judge's.
+    aut_value = os.environ.get(aut_env, "").strip()
+    judge_value = os.environ.get(judge_env, "").strip()
+    if aut_value and judge_value and aut_value == judge_value:
+        checks.append(
+            Check(
+                "credential separation",
+                Level.FAIL,
+                f"${aut_env} and ${judge_env} are the SAME value. The agent "
+                f"under test is being handed the judge's credential, so any "
+                f"payload that succeeds in extracting it has extracted the "
+                f"one key that scores your results.",
+            )
+        )
+    elif aut_value and judge_value:
+        checks.append(Check("credential separation", Level.OK, "two distinct keys"))
+
+    return checks
+
+
+def _endpoint_checks(config, *, probe: bool) -> list[Check]:  # noqa: ANN001
+    endpoint = config.model_endpoint
+    parsed = urlparse(endpoint)
+
+    if parsed.scheme not in ("http", "https") or not parsed.netloc:
+        return [
+            Check(
+                "model endpoint",
+                Level.FAIL,
+                f"{endpoint!r} is not a valid http(s) URL",
+            )
+        ]
+
+    checks = [Check("model endpoint", Level.OK, endpoint)]
+
+    # Plaintext to anywhere but the local machine puts the agent's
+    # credential on the wire in clear. Localhost is the lab case and is
+    # fine, so it is not worth a warning that trains people to ignore
+    # warnings.
+    host = parsed.hostname or ""
+    if parsed.scheme == "http" and host not in ("localhost", "127.0.0.1", "::1"):
+        checks.append(
+            Check(
+                "endpoint transport",
+                Level.WARN,
+                f"plaintext http to {host} — the agent credential would cross "
+                f"the network unencrypted",
+            )
+        )
+
+    if not probe:
+        checks.append(
+            Check(
+                "endpoint reachable",
+                Level.WARN,
+                "not checked — pass --probe to send one real request",
+            )
+        )
+        return checks
+
+    checks.append(_probe(config))
+    return checks
+
+
+def _probe(config) -> Check:  # noqa: ANN001
+    """One real Messages call, minimal tokens.
+
+    Deliberately the same client the run uses rather than a bare socket
+    connect: what matters is not whether the port is open but whether the
+    credential is accepted and the endpoint speaks the wire format. A TCP
+    check would pass against something that 401s every request.
+    """
+    from anthropic import Anthropic, APIStatusError
+
+    key = os.environ.get(config.model_key_env, "").strip()
+    if not key:
+        return Check(
+            "endpoint reachable", Level.FAIL, "cannot probe without a credential"
+        )
+
+    try:
+        client = Anthropic(api_key=key, base_url=config.model_endpoint, timeout=30.0)
+        client.messages.create(
+            model=config.model,
+            max_tokens=1,
+            messages=[{"role": "user", "content": "ping"}],
+        )
+    except APIStatusError as exc:
+        return Check(
+            "endpoint reachable",
+            Level.FAIL,
+            f"HTTP {exc.status_code} from {config.model_endpoint} — "
+            + (
+                "credential rejected"
+                if exc.status_code in (401, 403)
+                else "endpoint error"
+            ),
+        )
+    except Exception as exc:  # noqa: BLE001 — connection, timeout, protocol
+        return Check(
+            "endpoint reachable",
+            Level.FAIL,
+            f"{type(exc).__name__} contacting {config.model_endpoint}: {exc}",
+        )
+    return Check("endpoint reachable", Level.OK, "answered a live request")
+
+
+def _corpus_checks(corpus_path: Path | None) -> list[Check]:
+    from abrade_cli import corpus as corpus_module
+
+    try:
+        injections = corpus_module.load_corpus(corpus_path)
+    except Exception as exc:  # noqa: BLE001
+        return [Check("corpus", Level.FAIL, f"could not load: {exc}")]
+
+    if not injections:
+        return [
+            Check("corpus", Level.FAIL, "loaded but empty — nothing would be fired")
+        ]
+    return [Check("corpus", Level.OK, f"{len(injections)} injection(s) available")]
+
+
+def run_checks(
+    *,
+    config_path: Path,
+    corpus_path: Path | None = None,
+    probe: bool = False,
+) -> list[Check]:
+    """Every check, in cheapest-first order. Never raises — a failed check
+    is data, and the caller decides the exit code."""
+    checks, config = _config_checks(config_path)
+    if config is None:
+        # Everything downstream needs a parsed config; reporting ten
+        # cascading failures from one missing file is noise.
+        return checks
+
+    checks.extend(_credential_checks(config))
+    checks.extend(_endpoint_checks(config, probe=probe))
+    checks.extend(_corpus_checks(corpus_path))
+    return checks