suvoro 0.1.0__py3-none-any.whl

suvoro/__init__.py

@@ -0,0 +1,79 @@
+"""Suvoro SDK — programmatic, headless interface to the Suvoro engine.
+
+Quickstart::
+
+    import asyncio
+    from suvoro import SuvoroClient, ScanOptions
+    from suvoro.events import ScannerCompletedEvent, FindingDiscoveredEvent
+
+    async def main():
+        client = SuvoroClient(
+            model="openai/gpt-4o",   # optional — only needed for AI steps
+            api_key="...",           # or set OPENAI_API_KEY in environment
+        )
+
+        result = await client.audit.run(
+            workspace_path="./my-project",
+            options=ScanOptions(
+                scanners=["semgrep", "gitleaks", "osv", "bandit"],
+                triage=True,
+            ),
+            on_event=lambda evt: print(evt),
+        )
+
+        print(f"Found {len(result.findings)} issues")
+        for f in result.findings:
+            print(f"  [{f.severity}] {f.title} — {f.file}:{f.line_start}")
+
+    asyncio.run(main())
+
+Sync usage::
+
+    result = SuvoroClient().audit.run_sync("./my-project", ScanOptions())
+"""
+
+from suvoro.client import AuditHandle, SuvoroClient
+from suvoro.events import (
+    BaseEvent,
+    ErrorEvent,
+    FindingDiscoveredEvent,
+    PatchVerifiedEvent,
+    ProofCompletedEvent,
+    ScanCompletedEvent,
+    ScannerCompletedEvent,
+    ScannerStartedEvent,
+    ScanStartedEvent,
+    TriageStartedEvent,
+)
+from suvoro.options import BudgetOptions, ModelConfig, ScanOptions
+from suvoro.result import AuditFinding, AuditResult, PlainEnglishSummary, ScannerSummary, VerifiedPatch
+
+__all__ = [
+    # Main client
+    "SuvoroClient",
+    "AuditHandle",
+    # Options
+    "ScanOptions",
+    "ModelConfig",
+    "BudgetOptions",
+    # Results
+    "AuditResult",
+    "AuditFinding",
+    "VerifiedPatch",
+    "PlainEnglishSummary",
+    "ScannerSummary",
+    # Events
+    "BaseEvent",
+    "ScanStartedEvent",
+    "ScanCompletedEvent",
+    "ScannerStartedEvent",
+    "ScannerCompletedEvent",
+    "FindingDiscoveredEvent",
+    "TriageStartedEvent",
+    "ProofCompletedEvent",
+    "PatchVerifiedEvent",
+    "ErrorEvent",
+]
+
+__version__ = "0.1.0"
+

suvoro/_meta.py

@@ -0,0 +1,17 @@
+"""Single source of truth for product naming."""
+
+from __future__ import annotations
+
+PRODUCT_NAME = "Suvoro"
+"""Human-readable product name used in reports and banners."""
+
+CLI_NAME = "suvoro"
+"""Executable name (must match ``[project.scripts]`` in pyproject.toml)."""
+
+STATE_DIR_NAME = ".suvoro"
+"""Per-project state directory (ledger, reports, logs)."""
+
+ENV_PREFIX = "SUVORO_"
+"""Prefix for configuration environment variables."""
+
+USER_AGENT_NAME = "Suvoro"

suvoro/cli/__init__.py

@@ -0,0 +1 @@
+# suvoro CLI subpackage

suvoro/cli/commands/__init__.py

@@ -0,0 +1 @@
+# suvoro CLI commands subpackage

suvoro/cli/commands/audit.py

@@ -0,0 +1,271 @@
+"""audit — scan, optional AI review steps, report.
+
+Phases:
+
+1. Scan (always): discover -> scanners -> normalise -> triage (if a triage
+   model is configured) -> persist.
+2. Prove + red team (**experimental, off by default**): needs
+   ``--experimental-prove`` (or ``experimental.prove: true``), a configured
+   prover model, Docker, and gVisor unless ``sandbox.require_gvisor: false``.
+   Any missing precondition skips the phase with a clear message; the audit
+   still finishes and writes its report.
+3. Code-quality review (only if a ``models.qa`` model is configured).
+4. Report (always), including scanner coverage.
+
+No model is ever chosen implicitly: an unconfigured step is skipped, never
+silently routed to a default provider.
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime, timezone
+
+from rich.console import Console
+
+from suvoro.core.config import ModelRef, SuvoroConfig
+from suvoro.core.logging import get_logger
+from suvoro.core.schemas import Finding, Severity
+
+log = get_logger("cli.audit")
+# Progress and summaries go to stderr; only the report itself goes to stdout.
+console = Console(stderr=True)
+
+_PROVE_SEVERITIES = {Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM}
+_SEVERITY_ORDER = [Severity.CRITICAL, Severity.HIGH, Severity.MEDIUM, Severity.LOW, Severity.INFO]
+_INACTIVE = {"suppressed", "accepted_risk", "wont_fix", "resolved"}
+
+
+def _model_configured(ref: ModelRef | None) -> bool:
+    return bool(ref and ref.model)
+
+
+def _provider(ref: ModelRef):
+    from suvoro.models.provider import LiteLLMProvider
+
+    return LiteLLMProvider(
+        ref.full_name,
+        api_key=ref.resolved_api_key or None,
+        api_base=ref.api_base or None,
+    )
+
+
+def _parse_severity(value: str | None, default: Severity) -> Severity:
+    if not value:
+        return default
+    try:
+        return Severity(value.strip().lower())
+    except ValueError:
+        console.print(f"[yellow]Unknown severity '{value}', using '{default.value}'.[/yellow]")
+        return default
+
+
+def _run_prove_phase(
+    cfg: SuvoroConfig,
+    target: str,
+    findings: list[Finding],
+    *,
+    max_prove: int,
+    prove_severity: str | None,
+) -> None:
+    """Experimental: sandboxed checks for top findings, then a bounded red team."""
+    from suvoro.sandbox.docker import DockerSandboxProvider, SandboxUnavailable
+
+    if not _model_configured(cfg.models.prover):
+        console.print("[yellow]Skipping prove: no models.prover configured.[/yellow]")
+        return
+
+    sandbox = DockerSandboxProvider(cfg.sandbox)
+    try:
+        sandbox.check_available()
+    except SandboxUnavailable as e:
+        console.print(f"[yellow]Skipping prove/red team: {e}[/yellow]", markup=False)
+        return
+
+    if prove_severity:
+        allowed = {_parse_severity(prove_severity, Severity.HIGH)}
+    else:
+        allowed = _PROVE_SEVERITIES
+    provable = [f for f in findings if f.severity in allowed and f.status.value not in _INACTIVE]
+    if not provable:
+        console.print("[dim]No findings at provable severity.[/dim]")
+        return
+
+    from suvoro.sandbox.prover import ProverAgent
+    from suvoro.storage.ledger import SQLiteLedger
+
+    ledger = SQLiteLedger(cfg.db_path)
+    model = _provider(cfg.models.prover)
+    prover = ProverAgent(model=model, sandbox=sandbox, ledger=ledger, project_path=target)
+    to_prove = provable[:max_prove]
+    console.print(f"Checking {len(to_prove)} of {len(provable)} eligible findings (max {max_prove})...")
+    try:
+        prover.start_session()
+        for i, finding in enumerate(to_prove, 1):
+            console.print(f"[{i}/{len(to_prove)}] {finding.id} - {finding.title[:60]}", markup=False)
+            try:
+                attempt = prover.prove(finding)
+                ok = attempt.result.startswith("Exit Code: 0")
+                console.print(
+                    f"  {'confirmed by check' if ok else 'not confirmed'}: {attempt.hypothesis[:80]}",
+                    markup=False,
+                )
+            except Exception as e:
+                console.print(f"  check failed: {e}", markup=False)
+                log.warning("Prove failed for %s: %s", finding.id, e)
+
+        if cfg.experimental.redteam:
+            rt = cfg.models.redteam
+            if not (_model_configured(rt.planner) and _model_configured(rt.reviewer)):
+                console.print("[yellow]Skipping red team: planner/reviewer models not configured.[/yellow]")
+            else:
+                from suvoro.qa.agent import QAAgent
+                from suvoro.sandbox.redteam import run_redteam
+
+                console.print(
+                    f"Running bounded red team (max {rt.max_iterations} iterations, "
+                    f"{rt.max_llm_calls} LLM calls, {rt.max_seconds}s)..."
+                )
+                try:
+                    final_state = run_redteam({
+                        "project_context": QAAgent(model=model, project_path=target)._gather_context(),
+                        "planner_model": _provider(rt.planner),
+                        "reviewer_model": _provider(rt.reviewer),
+                        "sandbox": sandbox,
+                        "ledger": ledger,
+                        "container_id": prover._active_container,
+                        "mock_env": prover.mock_env,
+                        "max_iterations": rt.max_iterations,
+                        "max_llm_calls": rt.max_llm_calls,
+                        "max_seconds": rt.max_seconds,
+                        "timeout_per_attempt": rt.timeout_per_attempt,
+                    })
+                    for attempt in final_state.get("completed_attempts", []):
+                        ok = attempt.result.startswith("Exit Code: 0")
+                        console.print(f"  {'confirmed' if ok else 'not confirmed'}: {attempt.hypothesis[:80]}", markup=False)
+                    console.print(f"  Red team stopped: {final_state.get('stop_reason') or 'done'}", markup=False)
+                except Exception as e:
+                    console.print(f"  Red team phase failed: {e}", markup=False)
+                    log.warning("Red Team failed: %s", e)
+    finally:
+        prover.stop_session()
+
+
+def _run_qa_phase(cfg: SuvoroConfig, target: str) -> None:
+    if not _model_configured(cfg.models.qa):
+        console.print("[dim]Skipping code-quality review: no models.qa configured.[/dim]")
+        return
+    from suvoro.qa.agent import QAAgent
+
+    try:
+        qa_report = QAAgent(model=_provider(cfg.models.qa), project_path=target).run_qa()
+    except Exception as e:
+        console.print(f"Code-quality review failed: {e}", markup=False)
+        log.warning("QA phase failed: %s", e)
+        return
+    console.print("Code-quality review complete.")
+    console.print(f"Summary: {qa_report.summary}", markup=False)
+    for title, items in (
+        ("Production risks", qa_report.production_risks),
+        ("Observability gaps", qa_report.logging_suggestions),
+        ("Possibly stale code", qa_report.stale_code_flags),
+    ):
+        if items:
+            console.print(f"\n{title}:")
+            for it in items:
+                console.print(f"  - {it}", markup=False)
+
+
+def run_audit(
+    cfg: SuvoroConfig,
+    target: str,
+    *,
+    max_prove: int = 10,
+    prove_severity: str | None = None,
+    output_format: str = "markdown",
+    min_severity: str = "low",
+    experimental_prove: bool = False,
+    dast_url: str | None = None,
+) -> int:
+    """Execute the audit. Never raises for missing optional dependencies."""
+    import sys
+
+    from suvoro.pipeline import execute_scan, print_scanner_summary
+    from suvoro.reports.renderer import render_report
+    from suvoro.storage.ledger import SQLiteLedger
+
+    audit_start = time.monotonic()
+    durations: dict[str, float] = {}
+    min_sev = _parse_severity(min_severity, Severity.LOW)
+
+    # Phase 1
+    console.rule("Phase 1: Scanning")
+    t = time.monotonic()
+    state = execute_scan(target, cfg, dast_url=dast_url)
+    durations["scan"] = time.monotonic() - t
+    if state.get("errors"):
+        console.print("Scan failed: " + "; ".join(state["errors"]), markup=False)
+        return 2
+    scanners = state.get("scan_results", [])
+    findings = [Finding(**f) for f in state.get("findings", [])]
+
+    # Phase 2 (experimental)
+    if experimental_prove or cfg.experimental.prove:
+        console.rule("Phase 2: Sandboxed checks (experimental)")
+        t = time.monotonic()
+        try:
+            _run_prove_phase(cfg, target, findings, max_prove=max_prove, prove_severity=prove_severity)
+        except Exception as e:  # never lose the report because of an optional phase
+            console.print(f"Prove phase failed: {e}", markup=False)
+            log.exception("Prove phase failed")
+        durations["prove"] = time.monotonic() - t
+    else:
+        console.print("[dim]Prove/red team are experimental and off (use --experimental-prove).[/dim]")
+
+    # Phase 3
+    console.rule("Phase 3: Code-quality review")
+    t = time.monotonic()
+    _run_qa_phase(cfg, target)
+    durations["qa"] = time.monotonic() - t
+
+    # Phase 4
+    console.rule("Phase 4: Report")
+    ledger = SQLiteLedger(cfg.db_path)
+    all_final = ledger.latest_findings()
+    cutoff = _SEVERITY_ORDER.index(min_sev)
+    final = [f for f in all_final if _SEVERITY_ORDER.index(f.severity) <= cutoff]
+    report_text = render_report(final, output_format, scanners=scanners)
+
+    try:
+        reports_dir = cfg.state_dir / "reports"
+        reports_dir.mkdir(parents=True, exist_ok=True)
+        ext = "json" if output_format.lower() == "json" else ("sarif" if output_format.lower() == "sarif" else "md")
+        now_str = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+        stamped = reports_dir / f"audit_report_{now_str}.{ext}"
+        latest = reports_dir / f"latest_audit.{ext}"
+        stamped.write_text(report_text, encoding="utf-8")
+        latest.write_text(report_text, encoding="utf-8")
+        console.print(f"Report saved to: {stamped}", markup=False, highlight=False)
+    except OSError as e:
+        log.warning("Could not write audit report: %s", e)
+
+    sys.stdout.write(report_text if report_text.endswith("\n") else report_text + "\n")
+    sys.stdout.flush()
+
+    print_scanner_summary(scanners, console)
+    active = [f for f in final if f.status.value not in _INACTIVE]
+    critical = sum(1 for f in active if f.severity == Severity.CRITICAL)
+    high = sum(1 for f in active if f.severity == Severity.HIGH)
+    total = time.monotonic() - audit_start
+    console.print(
+        f"{len(active)} active findings at or above {min_sev.value} "
+        f"({critical} critical, {high} high) in {total:.1f}s",
+        markup=False,
+    )
+    log.info("Audit finished in %.2fs (%s)", total, durations)
+
+    if active:
+        return 1
+    if not state.get("complete"):
+        return 2
+    return 0

suvoro/cli/commands/baseline.py

@@ -0,0 +1,33 @@
+"""baseline command implementation — FR-03."""
+
+from __future__ import annotations
+
+from rich.console import Console
+
+from suvoro.core.config import SuvoroConfig
+from suvoro.core.schemas import BaselineSnapshot
+from suvoro.findings.baseline import compute_fingerprint
+
+console = Console()
+
+
+def manage_baseline(cfg: SuvoroConfig, action: str) -> None:
+    """Manage scan baselines."""
+    from suvoro.storage.ledger import SQLiteLedger
+
+    ledger = SQLiteLedger(cfg.db_path)
+
+    if action == "update":
+        findings = ledger.latest_findings()
+        fingerprints = [compute_fingerprint(f) for f in findings]
+        baseline = BaselineSnapshot(
+            fingerprints=fingerprints,
+            created_by="user",
+        )
+        ledger.save_baseline(baseline)
+        console.print(
+            f"[green]Baseline updated with {len(fingerprints)} finding(s).[/green]\n"
+            f"  Baseline ID: {baseline.id}"
+        )
+    else:
+        console.print(f"[red]Unknown baseline action: {action}[/red]")

suvoro/cli/commands/findings.py

@@ -0,0 +1,98 @@
+"""findings / show command implementations."""
+
+from __future__ import annotations
+
+from rich.console import Console
+from rich.table import Table
+from rich.text import Text
+
+from suvoro.core.config import SuvoroConfig
+from suvoro.core.schemas import Severity
+from suvoro.remediation.safety import sanitize_for_terminal
+from suvoro.storage.ledger import SQLiteLedger
+
+console = Console()
+
+_SEVERITY_COLORS = {
+    Severity.CRITICAL: "bold red",
+    Severity.HIGH: "red",
+    Severity.MEDIUM: "yellow",
+    Severity.LOW: "cyan",
+    Severity.INFO: "dim",
+}
+
+
+def list_findings(cfg: SuvoroConfig, *, status: str | None, severity: str | None) -> None:
+    """List findings with optional filters."""
+    ledger = SQLiteLedger(cfg.db_path)
+    filters = {}
+    if status:
+        filters["status"] = status
+    if severity:
+        filters["severity"] = severity
+
+    findings = ledger.latest_findings(**filters)
+    if not findings:
+        console.print("[dim]No findings found.[/dim]")
+        return
+
+    table = Table(title="suvoro Findings", show_lines=True)
+    table.add_column("ID", style="bold")
+    table.add_column("Severity")
+    table.add_column("Status")
+    table.add_column("Source")
+    table.add_column("Title", max_width=50)
+    table.add_column("File")
+    table.add_column("Score", justify="right")
+
+    for f in sorted(findings, key=lambda x: x.risk_score, reverse=True):
+        sev_style = _SEVERITY_COLORS.get(f.severity, "")
+        table.add_row(
+            f.id,
+            f"[{sev_style}]{f.severity.value.upper()}[/{sev_style}]",
+            f.status.value,
+            Text(f.source),
+            Text(sanitize_for_terminal(f.title)),
+            Text(f"{f.file}:{f.line_start}" if f.line_start else f.file),
+            f"{f.risk_score:.1f}",
+        )
+
+    console.print(table)
+    console.print(f"\n[bold]{len(findings)}[/bold] finding(s) total.")
+
+
+def show_finding(cfg: SuvoroConfig, finding_id: str) -> None:
+    """Show detailed info for a single finding."""
+    ledger = SQLiteLedger(cfg.db_path)
+    finding = ledger.get_finding(finding_id)
+    if finding is None:
+        console.print(Text(f"Finding {finding_id} not found."))
+        return
+
+    console.print(f"\n[bold]Finding {finding.id}[/bold]")
+    console.print(Text(sanitize_for_terminal(f"  Title:       {finding.title}")))
+    console.print(Text(sanitize_for_terminal(f"  Source:      {finding.source}")))
+    console.print(Text(sanitize_for_terminal(f"  Category:    {finding.category}")))
+    console.print(Text(sanitize_for_terminal(f"  Severity:    {finding.severity.value}")))
+    console.print(Text(sanitize_for_terminal(f"  Confidence:  {finding.confidence:.0%}")))
+    console.print(Text(sanitize_for_terminal(f"  Status:      {finding.status.value}")))
+    console.print(Text(sanitize_for_terminal(f"  Risk Score:  {finding.risk_score:.1f}")))
+    console.print(Text(sanitize_for_terminal(f"  File:        {finding.file}")))
+    if finding.line_start:
+        console.print(Text(sanitize_for_terminal(f"  Lines:       {finding.line_start}-{finding.line_end or finding.line_start}")))
+    if finding.rule_id:
+        console.print(Text(sanitize_for_terminal(f"  Rule:        {finding.rule_id}")))
+    if finding.cve:
+        console.print(Text(sanitize_for_terminal(f"  CVE:         {finding.cve}")))
+    if finding.osv_id:
+        console.print(Text(sanitize_for_terminal(f"  OSV:         {finding.osv_id}")))
+    if finding.package:
+        console.print(Text(sanitize_for_terminal(f"  Package:     {finding.package}@{finding.version}")))
+    console.print(Text(sanitize_for_terminal(f"  Description: {finding.description}")))
+
+    # Show evidence
+    evidence = ledger.get_evidence(finding_id)
+    if evidence:
+        console.print(f"\n  [bold]Evidence ({len(evidence)} item(s)):[/bold]")
+        for e in evidence:
+            console.print(Text(f"    ({e.kind.value}) from {e.source} @ {e.created_at}"))

suvoro/cli/commands/fix.py

@@ -0,0 +1,138 @@
+"""fix command: generate a patch, verify it in a throwaway copy, apply on approval."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from rich.console import Console
+from rich.text import Text
+
+from suvoro.core.config import SuvoroConfig
+from suvoro.core.schemas import Finding, FindingStatus, StatusChange
+
+console = Console(stderr=True)
+
+_INACTIVE = (
+    FindingStatus.SUPPRESSED,
+    FindingStatus.ACCEPTED_RISK,
+    FindingStatus.WONT_FIX,
+    FindingStatus.RESOLVED,
+)
+
+
+def _show(label: str, value: str) -> None:
+    """Print untrusted text with no markup and no terminal control sequences."""
+    from suvoro.remediation.safety import sanitize_for_terminal
+
+    console.print(Text(f"{label}{sanitize_for_terminal(value)}"))
+
+
+def _process(cfg: SuvoroConfig, finding: Finding, *, auto_approve: bool, run_tests: bool) -> str:
+    """Handle one finding. Returns 'applied' | 'skipped' | 'failed' | 'declined'."""
+    from suvoro.remediation.approval import apply_patch, describe, prompt_approval
+    from suvoro.remediation.patcher import generate_patch
+    from suvoro.remediation.safety import check_patch_scope
+    from suvoro.remediation.verifier import verify_patch
+    from suvoro.storage.ledger import SQLiteLedger
+
+    proposal = generate_patch(cfg, finding)
+    if not proposal.diff:
+        console.print("No patch could be generated (is models.remediation configured?).")
+        return "skipped"
+
+    _show("Root cause: ", proposal.root_cause)
+    _show("Impact: ", proposal.impact)
+    console.print(Text("\nProposed diff:"))
+    _show("", proposal.diff)
+
+    in_scope, why = check_patch_scope(proposal.diff, {finding.file})
+    if not in_scope:
+        console.print(Text(f"Rejected: {why}. Patches may only change the finding's own file."))
+        return "failed"
+
+    console.print(Text("\nVerifying in a throwaway copy of the project..."))
+    result = verify_patch(cfg, finding, proposal, run_tests=run_tests)
+    console.print(Text(f"  Applies cleanly:   {'yes' if result.applied_cleanly else 'NO'}"))
+    console.print(Text(f"  Tests:             {describe(result.tests_passed)}"))
+    console.print(Text(f"  Scanner re-check:  {describe(result.scanner_clear)}"))
+    if result.regression_test_passed is not None or run_tests:
+        console.print(Text(f"  Regression test:   {describe(result.regression_test_passed)}"))
+    _show("  Details: ", result.details)
+
+    if result.any_failed:
+        console.print(Text("Verification failed. Not applying."))
+        return "failed"
+
+    if auto_approve:
+        approved = True
+        if not result.fully_verified:
+            console.print(Text("--yes: applying a patch that is only partly verified (see above)."))
+    else:
+        approved = prompt_approval(proposal, result)
+    if not approved:
+        console.print(Text("Fix not applied."))
+        return "declined"
+
+    ok, details = apply_patch(Path(cfg.project_root), proposal.diff)
+    if not ok:
+        console.print(Text(f"Failed to apply the patch to the project: {details}"))
+        return "failed"
+
+    ledger = SQLiteLedger(cfg.db_path)
+    new_status = FindingStatus.FIX_VERIFIED if result.fully_verified else FindingStatus.FIX_PROPOSED
+    ledger.update_finding_status(StatusChange(
+        finding_id=finding.id, old_status=finding.status, new_status=new_status,
+        actor="user" if not auto_approve else "user(--yes)",
+        reason="patch applied" + ("" if result.fully_verified else " (partly unverified)"),
+    ))
+    console.print(Text(f"Fix applied to {finding.file}. Review it with `git diff` and re-scan."))
+    return "applied"
+
+
+def fix_finding(
+    cfg: SuvoroConfig, finding_id: str, *, auto_approve: bool = False, run_tests: bool = False
+) -> int:
+    from suvoro.storage.ledger import SQLiteLedger
+
+    ledger = SQLiteLedger(cfg.db_path)
+    finding = ledger.get_finding(finding_id)
+    if finding is None:
+        console.print(Text(f"Finding {finding_id} not found."))
+        return 2
+    console.print(Text(f"\nGenerating fix for {finding_id}..."))
+    outcome = _process(cfg, finding, auto_approve=auto_approve, run_tests=run_tests)
+    return 0 if outcome in ("applied", "declined") else 1
+
+
+def fix_all_findings(
+    cfg: SuvoroConfig,
+    *,
+    severity: str | None = None,
+    auto_approve: bool = False,
+    run_tests: bool = False,
+) -> int:
+    """Batch fix active findings from the latest scan."""
+    from suvoro.storage.ledger import SQLiteLedger
+
+    ledger = SQLiteLedger(cfg.db_path)
+    active = [f for f in ledger.latest_findings() if f.status not in _INACTIVE]
+    active = [f for f in active if f.category not in ("sbom",)]
+    if severity:
+        active = [f for f in active if f.severity.value == severity.lower()]
+    if not active:
+        console.print("No actionable findings to fix.")
+        return 0
+
+    console.print(Text(f"\nFixing {len(active)} finding(s)...\n"))
+    counts: dict[str, int] = {}
+    for i, finding in enumerate(active, 1):
+        console.rule(Text(f"[{i}/{len(active)}] {finding.id} - {finding.title[:60]}"))
+        outcome = _process(cfg, finding, auto_approve=auto_approve, run_tests=run_tests)
+        counts[outcome] = counts.get(outcome, 0) + 1
+    console.rule("Batch remediation complete")
+    console.print(Text(
+        f"applied {counts.get('applied', 0)}, failed {counts.get('failed', 0)}, "
+        f"declined {counts.get('declined', 0)}, skipped {counts.get('skipped', 0)} "
+        f"of {len(active)}"
+    ))
+    return 1 if counts.get("failed") else 0