argus-probe 0.1.1__py3-none-any.whl

argus_probe/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.1"

argus_probe/__main__.py

@@ -0,0 +1,28 @@
+"""argus-probe entry point."""
+
+import click
+
+from argus_probe.cmd_init import init_command
+from argus_probe.cmd_run import cmd_run
+from argus_probe.cmd_report import cmd_report
+from argus_probe.cmd_list_probes import cmd_list_probes
+from argus_probe.cmd_coverage import cmd_coverage
+from argus_probe.cmd_validate_target import cmd_validate_target
+
+
+@click.group()
+@click.version_option()
+def main():
+    """Argus red-team CLI."""
+
+
+main.add_command(init_command, "init")
+main.add_command(cmd_run, "run")
+main.add_command(cmd_report, "report")
+main.add_command(cmd_list_probes, "list-probes")
+main.add_command(cmd_coverage, "coverage")
+main.add_command(cmd_validate_target, "validate-target")
+
+
+if __name__ == "__main__":
+    main()

argus_probe/api_client.py

@@ -0,0 +1,70 @@
+"""Minimal httpx wrapper around the Argus REST API."""
+
+from __future__ import annotations
+
+import time
+
+import httpx
+
+
+def post_run(api_url: str, token: str, body: dict, timeout: float = 30.0) -> dict:
+    with httpx.Client(timeout=timeout) as client:
+        resp = client.post(f"{api_url}/api/v1/redteam/runs", json=body, headers={"x-api-token": token})
+        resp.raise_for_status()
+        return resp.json()
+
+
+def get_run(api_url: str, token: str, run_id: str, timeout: float = 30.0) -> dict:
+    with httpx.Client(timeout=timeout) as client:
+        resp = client.get(f"{api_url}/api/v1/redteam/runs/{run_id}", headers={"x-api-token": token})
+        resp.raise_for_status()
+        return resp.json()
+
+
+def get_report(api_url: str, token: str, run_id: str, format: str, timeout: float = 30.0) -> str:
+    with httpx.Client(timeout=timeout) as client:
+        resp = client.get(
+            f"{api_url}/api/v1/redteam/runs/{run_id}/report",
+            params={"format": format},
+            headers={"x-api-token": token},
+        )
+        resp.raise_for_status()
+        return resp.text
+
+
+def poll_until_complete(api_url: str, token: str, run_id: str, interval: float = 2.0, max_wait: float = 1800.0) -> dict:
+    deadline = time.monotonic() + max_wait
+    while time.monotonic() < deadline:
+        run = get_run(api_url, token, run_id)
+        if run["status"] in ("completed", "failed", "cancelled"):
+            return run
+        time.sleep(interval)
+    raise TimeoutError(f"run {run_id} did not complete within {max_wait}s")
+
+
+def list_probes(api_url: str, token: str, timeout: float = 30.0) -> list[str]:
+    """GET /api/v1/redteam/probes (TBD endpoint — Plan 3 Task 14 adds it)."""
+    with httpx.Client(timeout=timeout) as client:
+        resp = client.get(f"{api_url}/api/v1/redteam/probes", headers={"x-api-token": token})
+        resp.raise_for_status()
+        return resp.json()["probe_ids"]
+
+
+def get_coverage(api_url: str, token: str, timeout: float = 30.0) -> dict:
+    """GET /api/v1/redteam/coverage — what the probe library covers. Runs no probes, costs nothing."""
+    with httpx.Client(timeout=timeout) as client:
+        resp = client.get(f"{api_url}/api/v1/redteam/coverage", headers={"x-api-token": token})
+        resp.raise_for_status()
+        return resp.json()["coverage"]
+
+
+def get_diff(api_url: str, token: str, run_id: str, base: str, timeout: float = 30.0) -> dict:
+    """GET /api/v1/redteam/runs/{run_id}/diff — failures new, fixed or unchanged versus the latest run on `base`."""
+    with httpx.Client(timeout=timeout) as client:
+        resp = client.get(
+            f"{api_url}/api/v1/redteam/runs/{run_id}/diff",
+            params={"base": base},
+            headers={"x-api-token": token},
+        )
+        resp.raise_for_status()
+        return resp.json()

argus_probe/baseline_key.py

@@ -0,0 +1,19 @@
+"""Stable id of the target a run tests, so a baseline only matches runs against the same target."""
+from __future__ import annotations
+
+import hashlib
+import json
+
+_SECRET_WORDS = ("key", "token", "secret", "password", "auth", "header", "cookie")
+
+
+def _clean(value):
+    if isinstance(value, dict):
+        return {k: _clean(v) for k, v in value.items() if not any(w in str(k).lower() for w in _SECRET_WORDS)}
+    if isinstance(value, list):
+        return [_clean(v) for v in value]
+    return value
+
+
+def baseline_key(target: dict) -> str:
+    return hashlib.sha256(json.dumps(_clean(target), sort_keys=True).encode()).hexdigest()[:32]

argus_probe/cmd_coverage.py

@@ -0,0 +1,44 @@
+"""argus-probe coverage — show what the probe library covers.
+
+Runs no probes and costs nothing: a prospect must be able to ask what we
+cover before paying for a scan. Prints every cell of each standard,
+including the empty ones — silently omitting what we do not cover would
+invert the point of this command.
+"""
+
+import json
+
+import click
+
+from argus_probe import api_client
+
+STANDARDS = ["owasp-llm-top10", "mitre-atlas", "nist-ai-rmf", "eu-ai-act"]
+
+
+@click.command()
+@click.option("--token", envvar="ARGUS_API_TOKEN", required=True)
+@click.option("--api-url", envvar="ARGUS_API_URL", required=True, help="Argus API base URL (or env ARGUS_API_URL).")
+@click.option("--standard", "standard", type=click.Choice(STANDARDS), default=None,
+              help="Show only this standard (default: all).")
+@click.option("--json", "as_json", is_flag=True, help="Emit the raw coverage manifest as JSON.")
+def cmd_coverage(token: str, api_url: str, standard: str, as_json: bool):
+    """Show what the probe library covers, offline — no probes run."""
+    coverage = api_client.get_coverage(api_url, token)
+    if as_json:
+        if standard:
+            coverage = {**coverage, "standards": {standard: coverage["standards"][standard]}}
+        click.echo(json.dumps(coverage))
+        return
+
+    keys = [standard] if standard else STANDARDS
+    for key in keys:
+        data = coverage["standards"][key]
+        click.echo(f"\n{key} ({data['universe']} universe)")
+        for cell in data["cells"]:
+            name = cell.get("name", "")
+            click.echo(
+                f"  {cell['id']:<8} {name:<40} {cell['probes_in_library']:>4} probes  {cell['library_status']}"
+            )
+
+    totals = coverage["totals"]
+    click.echo(f"\n{totals['probes_in_library']} probes in library, {totals['probes_run']} run this scan")

argus_probe/cmd_init.py

@@ -0,0 +1,187 @@
+"""argus-probe init subcommand: scaffold a target.json + optional GH Action workflow."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import click
+
+from argus_probe.target_loader import _KNOWN_KINDS
+
+# Per-kind question definitions. Each tuple: (field_name, prompt_text, default_or_None)
+_KIND_QUESTIONS: dict[str, list[tuple[str, str, str | None]]] = {
+    "openai_compat": [
+        ("endpoint_url", "Endpoint URL", "https://api.openai.com/v1/chat/completions"),
+        ("model", "Model name", None),
+        ("api_key_env", "API key env var", "OPENAI_API_KEY"),
+    ],
+    "anthropic_native": [
+        ("model", "Model name", "claude-haiku-4-5-20251001"),
+        ("api_key_env", "API key env var", "ANTHROPIC_API_KEY"),
+    ],
+    "custom_http": [
+        ("request_url", "Request URL", None),
+        ("request_body_template", "Request body template (Jinja2 with {{prompt}})",
+         '{"input": {{prompt|tojson}}}'),
+        ("response_jsonpath", "Response JSONPath", "$.output"),
+    ],
+    "grpc": [
+        ("endpoint", "Endpoint (host:port)", "localhost:50051"),
+        ("service_method", "Service method (pkg.Service/Method)", None),
+        ("prompt_field", "Prompt field name", "user_input"),
+        ("response_field", "Response field name", "response"),
+    ],
+    "browser_use": [
+        ("agent_url", "Browser-using agent URL", None),
+        ("scenario_kind", "Scenario kind (dom_injection/ui_phishing/visual_injection/os_cmd)", "dom_injection"),
+    ],
+    "payment_agent": [
+        ("testbed_url", "Payment testbed URL", "http://127.0.0.1:8090"),
+        (
+            "inner_json",
+            "Inner target spec (JSON) for the transport that talks to your agent",
+            '{"kind": "openai_compat", "endpoint_url": "http://127.0.0.1:8091/v1/chat/completions", "model": "argus-demo-payment-agent"}',
+        ),
+    ],
+    "mcp_agent": [
+        ("testbed_url", "MCP testbed URL", "http://127.0.0.1:8092"),
+        (
+            "inner_json",
+            "Inner target spec (JSON) for the transport that talks to your agent",
+            '{"kind": "openai_compat", "endpoint_url": "http://127.0.0.1:8093/v1/chat/completions", "model": "argus-demo-mcp-agent"}',
+        ),
+    ],
+    "testbed_agent": [
+        ("environment", "Environment (mcp/payment)", "mcp"),
+        ("testbed_url", "Testbed URL", "http://127.0.0.1:8092"),
+        (
+            "inner_json",
+            "Inner target spec (JSON) for the transport that talks to your agent",
+            '{"kind": "openai_compat", "endpoint_url": "http://127.0.0.1:8093/v1/chat/completions", "model": "argus-demo-mcp-agent"}',
+        ),
+    ],
+    "http_upload": [
+        ("upload_url", "Upload URL", None),
+        ("upload_field_name", "Upload form field name", "file"),
+        ("upload_filename", "Upload filename", "payload.svg"),
+        ("upload_content_type", "Upload content type", "image/svg+xml"),
+        ("render_url_jsonpath", "Render URL JSONPath (extracts the render URL from the upload response)", "$.url"),
+    ],
+}
+
+_WORKFLOW_TEMPLATE = """\
+# .github/workflows/argus-probe.yml
+# Generated by `argus-probe init`. Customize as needed.
+name: argus-probe
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  schedule:
+    # Weekly Monday 06:00 UTC
+    - cron: '0 6 * * 1'
+  workflow_dispatch: {{}}
+
+jobs:
+  redteam:
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write   # upload-sarif
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+      - run: pip install "git+https://github.com/gy15901580825/Argus.git#subdirectory=cli"
+      # PRs gate only on failures new relative to the base branch; pushes to main record the baseline.
+      - run: >
+          argus-probe run --target {target_path}
+          --probes owasp_01_prompt_injection_basic,syscard_crescendo
+          --format sarif --out argus.sarif --fail-on critical
+          ${{{{ github.event_name == 'pull_request' && format('--compare-to {{0}}', github.base_ref) || '' }}}}
+        env:
+          ARGUS_API_URL: ${{{{ vars.ARGUS_API_URL }}}}
+          ARGUS_API_TOKEN: ${{{{ secrets.ARGUS_API_TOKEN }}}}
+      - uses: github/codeql-action/upload-sarif@v3
+        with:
+          sarif_file: argus.sarif
+"""
+
+
+@click.command("init")
+@click.option(
+    "--kind",
+    required=True,
+    type=click.Choice(sorted(_KNOWN_KINDS)),
+    help="Target adapter kind",
+)
+@click.option(
+    "--output",
+    default="argus-target.json",
+    show_default=True,
+    help="Output target.json path",
+)
+@click.option(
+    "--workflow/--no-workflow",
+    default=None,
+    help="Generate .github/workflows/argus-probe.yml (prompts if neither flag given)",
+)
+def init_command(kind: str, output: str, workflow: bool | None) -> None:
+    """Generate a target.json (and optional GitHub Action workflow) for Argus."""
+    click.echo(f"Argus target initializer")
+    click.echo(f"Target kind: {kind}")
+    questions = _KIND_QUESTIONS[kind]
+
+    spec: dict[str, object] = {"kind": kind}
+    for field, prompt_text, default in questions:
+        if default is not None:
+            value = click.prompt(prompt_text, default=default, show_default=True)
+        else:
+            value = click.prompt(prompt_text)
+        spec[field] = value
+
+    # api_key_env → api_key (CLI run command resolves $-vars at runtime)
+    if "api_key_env" in spec:
+        env_var = spec.pop("api_key_env")
+        spec["api_key"] = "${" + str(env_var) + "}"
+
+    # inner_json → inner (payment_agent / mcp_agent / testbed_agent nest another target spec
+    # for the transport that actually talks to the agent)
+    if "inner_json" in spec:
+        raw_inner = spec.pop("inner_json")
+        try:
+            spec["inner"] = json.loads(str(raw_inner))
+        except json.JSONDecodeError as exc:
+            raise click.UsageError(f"inner target spec is not valid JSON: {exc}") from exc
+
+    # sandbox is a safety interlock, not a question: payment_agent,
+    # mcp_agent and testbed_agent drive an agent that spends money / reaches a live MCP server,
+    # and both api_service and the CLI loader refuse a spec without
+    # sandbox: true — there is no way to turn it off, so it must never be
+    # presented as something a user could answer "no" to.
+    if kind in ("payment_agent", "mcp_agent", "testbed_agent"):
+        spec["sandbox"] = True
+
+    # Confirm-overwrite if target file exists
+    target_path = Path(output)
+    if target_path.exists():
+        if not click.confirm(f"{output} exists. Overwrite?", default=False):
+            raise click.Abort()
+
+    target_path.write_text(json.dumps(spec, indent=2) + "\n")
+    click.echo(f"✅ Wrote {target_path}")
+
+    # Workflow file
+    if workflow is None:
+        workflow = click.confirm("Generate GitHub Action workflow?", default=False)
+    if workflow:
+        wf_path = Path(".github/workflows/argus-probe.yml")
+        wf_path.parent.mkdir(parents=True, exist_ok=True)
+        wf_path.write_text(_WORKFLOW_TEMPLATE.format(target_path=target_path.name))
+        click.echo(f"✅ Wrote {wf_path}")
+
+    click.echo("")
+    click.echo(f"Next: argus-probe run --target {target_path.name}")
+    click.echo("Set ARGUS_API_URL (repository variable) and ARGUS_API_TOKEN (secret) in CI to enable scheduled runs.")

argus_probe/cmd_list_probes.py

@@ -0,0 +1,19 @@
+"""argus-probe list-probes — show available probe ids."""
+
+import click
+
+from argus_probe import api_client
+
+
+@click.command()
+@click.option("--token", envvar="ARGUS_API_TOKEN", required=True)
+@click.option("--api-url", envvar="ARGUS_API_URL", required=True, help="Argus API base URL (or env ARGUS_API_URL).")
+@click.option("--filter", "filter_substr", default="", help="Show only ids containing this substring.")
+def cmd_list_probes(token: str, api_url: str, filter_substr: str):
+    """List probe ids available on the connected Argus instance."""
+    ids = api_client.list_probes(api_url, token)
+    if filter_substr:
+        ids = [i for i in ids if filter_substr.lower() in i.lower()]
+    for i in sorted(ids):
+        click.echo(i)
+    click.echo(f"\n{len(ids)} probes")

argus_probe/cmd_report.py

@@ -0,0 +1,20 @@
+"""argus-probe report — render an existing run's report."""
+
+from pathlib import Path
+
+import click
+
+from argus_probe import api_client
+
+
+@click.command()
+@click.option("--run-id", required=True)
+@click.option("--format", "report_format", type=click.Choice(["html", "sarif", "junit"]), default="html")
+@click.option("--out", "out_file", type=click.Path(), required=True)
+@click.option("--token", envvar="ARGUS_API_TOKEN", required=True)
+@click.option("--api-url", envvar="ARGUS_API_URL", required=True, help="Argus API base URL (or env ARGUS_API_URL).")
+def cmd_report(run_id: str, report_format: str, out_file: str, token: str, api_url: str):
+    """Render an existing run's report to disk."""
+    report = api_client.get_report(api_url, token, run_id, report_format)
+    Path(out_file).write_text(report)
+    click.echo(f"Wrote {report_format} report for run {run_id} to {out_file}")

argus_probe/cmd_run.py

@@ -0,0 +1,172 @@
+"""argus-probe run — POST a redteam run + poll + write report."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+import click
+import httpx
+from click.core import ParameterSource
+
+from argus_probe import api_client, git_context
+from argus_probe.baseline_key import baseline_key
+from argus_probe.local_run import LocalUnavailable, run_local_and_render
+from argus_probe.severity import SEVERITY_ORDER, findings_at_or_above
+from argus_probe.target_loader import load_target_spec, TargetLoadError
+
+# Exit codes must fit 0-255; sys.exit(402) surfaced as 146 on Linux and macOS.
+EXIT_COST_CAP = 4
+
+
+@click.command()
+@click.option("--target", required=True, help="Target spec: JSON object (inline) or path to JSON file.")
+@click.option("--probes", "probe_ids", required=True, help="Comma-separated probe ids OR 'all'.")
+@click.option("--format", "report_format", type=click.Choice(["html", "sarif", "junit"]), default="html")
+@click.option("--out", "out_file", type=click.Path(), required=True, help="Output report file path.")
+@click.option("--token", envvar="ARGUS_API_TOKEN", default=None, help="Your Argus API token (or env ARGUS_API_TOKEN). Not used with --local.")
+@click.option("--api-url", envvar="ARGUS_API_URL", default=None, help="Argus API base URL (or env ARGUS_API_URL). Not used with --local.")
+@click.option("--max-wait", type=float, default=1800.0, help="Max seconds to wait for run completion. Ignored with --local.")
+@click.option("--per-run-cap", "per_run_cap", type=float, default=None, help="Maximum USD cost for this run; enforced before any LLM call in both server and local mode. Default: $0.50.")
+@click.option("--fail-on", "fail_on", type=click.Choice(SEVERITY_ORDER), default=None,
+              help="Exit 3 when any finding has verdict=fail and severity at or above this level.")
+@click.option("--local", "local", is_flag=True, default=False,
+              help="Run probes in this process instead of submitting to an Argus API server. Needs the argus-orchestrator package and a judge API key in the environment.")
+@click.option("--compare-to", "compare_to", default=None,
+              help="Base branch: report and gate only on failures that are new relative to the latest run on it. Server mode only.")
+def cmd_run(target: str, probe_ids: str, report_format: str, out_file: str, token: str | None, api_url: str | None, max_wait: float, per_run_cap: float | None, fail_on: str | None, local: bool, compare_to: str | None):
+    """Submit a red-team run and write the report to disk."""
+    try:
+        spec = load_target_spec(target)
+    except TargetLoadError as e:
+        click.echo(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    tokens = [s.strip() for s in probe_ids.split(",") if s.strip()]
+    if not tokens:
+        # An empty list is the wire convention for "the whole library", so an
+        # empty --probes must not fall through to it: `--probes ""` would
+        # quietly launch a full sweep the user never asked for.
+        raise click.UsageError("--probes needs at least one probe id, or 'all'")
+    if "all" in tokens:
+        # Silently dropping `all` from a mixed list would run a fraction of the
+        # intended probes while the run still looks successful — the worst
+        # outcome for a security gate. Refuse instead.
+        if len(tokens) > 1:
+            raise click.UsageError("'all' cannot be combined with specific probe ids")
+        # Empty probe_ids means "all" per orchestrator convention.
+        tokens = []
+
+    if local:
+        if compare_to:
+            raise click.UsageError("--compare-to needs run history on an Argus server; it does not work with --local")
+        ctx = click.get_current_context()
+        typed = [
+            name for name, param in (("--api-url", "api_url"), ("--token", "token"))
+            if ctx.get_parameter_source(param) == ParameterSource.COMMANDLINE
+        ]
+        if typed:
+            raise click.UsageError(f"--local runs in this process; do not pass {' or '.join(typed)}")
+        _run_locally(spec, tokens, per_run_cap, report_format, out_file, fail_on)
+        return
+    if api_url is None:
+        raise click.UsageError("Missing option '--api-url'")
+    if token is None:
+        raise click.UsageError("Missing option '--token'")
+
+    body = {
+        "target": spec,
+        "probe_ids": tokens,
+    }
+    if per_run_cap is not None:
+        body["per_run_cap_usd"] = per_run_cap
+    body.update(git_context.detect())
+    if compare_to and "repo" not in body:
+        raise click.UsageError("--compare-to needs the repository name; run inside a git checkout with an origin remote, or set GITHUB_REPOSITORY")
+    body["baseline_key"] = baseline_key(spec)
+
+    click.echo(f"Submitting run to {api_url}/api/v1/redteam/runs ...")
+    try:
+        resp = api_client.post_run(api_url, token, body=body)
+    except httpx.HTTPStatusError as e:
+        if e.response.status_code == 402:
+            try:
+                detail = e.response.json().get("detail", "cost cap exceeded")
+            except Exception:
+                detail = "cost cap exceeded"
+            click.echo(f"Argus rejected run for cost: {detail}", file=sys.stderr)
+            sys.exit(EXIT_COST_CAP)
+        raise
+    run_id = resp["run_id"]
+    click.echo(f"  run_id: {run_id}")
+
+    click.echo("Polling until completion...")
+    run = api_client.poll_until_complete(api_url, token, run_id, max_wait=max_wait)
+    click.echo(f"  status: {run['status']}, findings: {len(run.get('findings', []))}")
+
+    click.echo(f"Fetching {report_format} report...")
+    report = api_client.get_report(api_url, token, run_id, report_format)
+    Path(out_file).write_text(report)
+    click.echo(f"Wrote report to {out_file}")
+    if run["status"] != "completed":
+        click.echo(f"Error: run {run_id} ended with status {run['status']}", file=sys.stderr)
+        sys.exit(1)
+    if compare_to:
+        try:
+            d = api_client.get_diff(api_url, token, run_id, compare_to)
+        except httpx.HTTPStatusError as e:
+            try:
+                detail = e.response.json().get("detail", e.response.status_code)
+            except Exception:
+                detail = e.response.status_code
+            click.echo(f"Error: could not compare with {compare_to}: {detail}", file=sys.stderr)
+            sys.exit(1)
+        base = d.get("base_run_id") or "none (first run on this branch)"
+        click.echo(f"Compared with {compare_to} (baseline run {base}): "
+                   f"new: {len(d['new'])}, fixed: {len(d['fixed'])}, still failing: {len(d['still_failing'])}, "
+                   f"not run: {len(d['not_run'])}")
+        for item in d["new"]:
+            click.echo(f"  new  {item['severity']:<9} {item['probe_id']}")
+        _apply_fail_on([{"verdict": "fail", **i} for i in d["new"]], fail_on)
+    else:
+        _apply_fail_on(run.get("findings", []), fail_on)
+
+
+def _apply_fail_on(findings: list[dict], fail_on: str | None) -> None:
+    """Exit 3 when findings cross the --fail-on threshold. Report is already on disk."""
+    if fail_on is None:
+        return
+    hits = findings_at_or_above(findings, fail_on)
+    if hits:
+        ids = ", ".join(sorted({h.get("probe_id", "?") for h in hits}))
+        click.echo(
+            f"{len(hits)} finding(s) at or above {fail_on}: {ids}",
+            file=sys.stderr,
+        )
+        sys.exit(3)
+
+
+def _run_locally(spec, tokens, per_run_cap, report_format, out_file, fail_on) -> None:
+    if spec.get("kind") == "browser_use":
+        click.echo(
+            "Error: --local does not support browser_use targets; they need the "
+            "orchestrator service and a client_agent. Submit the run to an Argus API server instead.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+    click.echo(f"Running {('all probes' if not tokens else f'{len(tokens)} probe(s)')} locally ...")
+    try:
+        report, findings = run_local_and_render(spec, tokens, per_run_cap, report_format)
+    except LocalUnavailable as e:
+        click.echo(f"Error: {e}", file=sys.stderr)
+        sys.exit(2)
+    except Exception as e:  # LocalRunError or a mid-run failure; no traceback for the operator
+        code = getattr(e, "code", None)
+        if code == "cost":
+            click.echo(f"Run rejected for cost: {e}", file=sys.stderr)
+            sys.exit(EXIT_COST_CAP)
+        click.echo(f"Error: {e}", file=sys.stderr)
+        sys.exit(1)
+    Path(out_file).write_text(report)
+    click.echo(f"Wrote report to {out_file}")
+    _apply_fail_on(findings, fail_on)

argus_probe/cmd_validate_target.py

@@ -0,0 +1,31 @@
+"""argus-probe validate-target — quick reachability check on a target endpoint."""
+
+from pathlib import Path
+
+import click
+import httpx
+import yaml
+
+
+@click.command()
+@click.option("--target", "target_file", type=click.Path(exists=True), required=True)
+def cmd_validate_target(target_file: str):
+    """POST a tiny chat-completions probe to the target and report reachability + shape compliance."""
+    spec = yaml.safe_load(Path(target_file).read_text())
+    url = spec["endpoint_url"]
+    headers = {}
+    if spec.get("api_key"):
+        headers["Authorization"] = f"Bearer {spec['api_key']}"
+    body = {"model": spec["model"], "messages": [{"role": "user", "content": "ping"}], "max_tokens": 10}
+    try:
+        resp = httpx.post(url, headers=headers, json=body, timeout=15.0)
+    except httpx.RequestError as e:
+        raise click.ClickException(f"network error: {e}")
+    if resp.status_code != 200:
+        raise click.ClickException(f"target returned {resp.status_code}: {resp.text[:200]}")
+    try:
+        data = resp.json()
+        text = data["choices"][0]["message"]["content"]
+    except (KeyError, IndexError, ValueError) as e:
+        raise click.ClickException(f"target response shape invalid: {e}")
+    click.echo(f"OK — target {url} replied with {len(text)} chars")

argus_probe/git_context.py

@@ -0,0 +1,40 @@
+"""Which repo, branch and commit this run tests, from CI variables or git."""
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+from typing import Mapping
+
+_REMOTE = re.compile(r"[:/]([^/:]+/[^/]+?)(?:\.git)?$")
+
+
+def _git(cwd: str | None, *args: str) -> str | None:
+    try:
+        out = subprocess.run(["git", *args], cwd=cwd, capture_output=True, text=True, timeout=5)
+    except (OSError, subprocess.SubprocessError):
+        return None
+    return out.stdout.strip() or None if out.returncode == 0 else None
+
+
+def detect(env: Mapping[str, str] | None = None, cwd: str | None = None) -> dict[str, str]:
+    env = os.environ if env is None else env
+    ctx: dict[str, str] = {}
+    if env.get("GITHUB_REPOSITORY"):
+        ctx["repo"] = env["GITHUB_REPOSITORY"].lower()
+        branch = env.get("GITHUB_HEAD_REF") or env.get("GITHUB_REF_NAME")
+        if branch:
+            ctx["branch"] = branch
+        if env.get("GITHUB_SHA"):
+            ctx["commit"] = env["GITHUB_SHA"]
+        return ctx
+    remote = _git(cwd, "remote", "get-url", "origin")
+    if remote and (m := _REMOTE.search(remote)):
+        ctx["repo"] = m.group(1).lower()
+    branch = _git(cwd, "rev-parse", "--abbrev-ref", "HEAD")
+    if branch and branch != "HEAD":
+        ctx["branch"] = branch
+    commit = _git(cwd, "rev-parse", "HEAD")
+    if commit:
+        ctx["commit"] = commit
+    return ctx