repomix-output.xml

This file is a merged representation of a subset of the codebase, containing specifically included files and files not matching ignore patterns, combined into a single document by Repomix.

<file_summary>
This section contains a summary of this file.

<purpose>
This file contains a packed representation of a subset of the repository's contents that is considered the most important context.
It is designed to be easily consumable by AI systems for analysis, code review,
or other automated processes.
</purpose>

<file_format>
The content is organized as follows:
1. This summary section
2. Repository information
3. Directory structure
4. Repository files (if enabled)
5. Multiple file entries, each consisting of:
  - File path as an attribute
  - Full contents of the file
</file_format>

<usage_guidelines>
- This file should be treated as read-only. Any changes should be made to the
  original repository files, not this packed version.
- When processing this file, use the file path to distinguish
  between different files in the repository.
- Be aware that this file may contain sensitive information. Handle it with
  the same level of security as you would the original repository.
</usage_guidelines>

<notes>
- Some files may have been excluded based on .gitignore rules and Repomix's configuration
- Binary files are not included in this packed representation. Please refer to the Repository Structure section for a complete list of file paths, including binary files
- Only files matching these patterns are included: **/*
- Files matching these patterns are excluded: .git/**, .hg/**, .svn/**, **/node_modules/**, vendor/**, **/.bundle/**, **/.gradle/**, **/.npm/**, **/.yarn/**, **/target/**, dist/**, build/**, out/**, tmp/**, temp/**, coverage/**, .nyc_output/**, .pytest_cache/**, .mypy_cache/**, **/__pycache__/**, **/*.py[cod], **/.DS_Store, **/Thumbs.db, .idea/**, .vscode/**, **/*.swp, **/*.swo, **/*.bak, **/*.log, **/npm-debug.log*, **/yarn-debug.log*, **/yarn-error.log*, **/repomix-output.*, **/repopack-output.*, .env, .env.*
- Files matching patterns in .gitignore are excluded
- Files are sorted by Git change count (files with more changes are at the bottom)
</notes>

</file_summary>

<directory_structure>
references/
  install-tools.md
  package-intake.md
  parser-contract.md
  remediation-policy.md
  report-schema.md
  scanner-behavior.md
scripts/
  vulnscan/
    cli/
      __init__.py
      args.py
      output.py
      package.py
      scan.py
    parsers/
      __init__.py
      containers.py
      dependencies.py
      secrets.py
      static.py
      supply_chain.py
      utils.py
      workflows.py
    __init__.py
    ci.py
    common.py
    config.py
    discovery.py
    engines.py
    hygiene.py
    inventory.py
    orchestration.py
    remediation.py
    reporting.py
    sast.py
    sbom.py
    secrets.py
    supply_chain.py
    tracker.py
  nightly-vuln-scan.py
  validate-config.sh
  validate-tools.sh
  vuln-scan.py
templates/
  config-starter.yaml
tests/
  fixtures/
    docker/
      Dockerfile
    github-actions/
      .github/
        workflows/
          ci.yml
    go/
      go.mod
    javascript-no-lock/
      package.json
    jvm/
      pom.xml
    monorepo/
      apps/
        web/
          package-lock.json
          package.json
      packages/
        api/
          requirements.txt
    no-manifest/
      README.md
    npm/
      package-lock.json
      package.json
    pnpm/
      package.json
      pnpm-lock.yaml
    python/
      requirements.txt
    rust/
      Cargo.lock
      Cargo.toml
    terraform/
      main.tf
    vscode-extension/
      package.json
    yarn/
      package.json
      yarn.lock
  test_cli.py
  test_config_discovery_inventory.py
  test_engine_dependencies.py
  test_engine_external.py
  test_parsers.py
  test_scanner.py
  test_tracker.py
.gitignore
AGENTS.md
INSTALL.md
LICENSE
README.md
repomix.config.json
SKILL.md
TODO.md
</directory_structure>

<files>
This section contains the contents of the repository's files.

<file path="references/remediation-policy.md">
# Remediation Policy

Scanning is read-only by default. Remediation runs only when the user explicitly
requests it or the command includes `--auto-remediate`.

Use `remediation-prep` before editing when the user wants a fix plan:

```bash
python3 scripts/vuln-scan.py scan \
  --root /path/to/repo \
  --scan-mode remediation-prep \
  --format text
```

Remediation prep groups findings into:

- direct dependency update candidates
- transitive override candidates
- manual major-upgrade candidates
- likely unfixable or design-limitation findings
- tracked secret rotation work
- CI workflow permission or pinning changes
- manual review

When remediation is explicitly enabled, Codex runs once per affected repo with a
bounded prompt and a repo-local working directory. It must not branch, commit,
push, delete unrelated files, rotate credentials, or rewrite history.

Tracker writes must be atomic and must happen only after same-engine
verification. If the tracker JSON is corrupt, create a backup and recover to an
empty tracker rather than failing the whole scan.
</file>

<file path="references/report-schema.md">
# Report Schema

JSON summaries are the source of truth. Text output is a rendering of the same
data.

Top-level fields:

- `generated_at`
- `artifact_dir`
- `scanned_projects`
- `affected_projects`
- `finding_count`
- `severity_counts`
- `engine_counts`
- `category_counts`
- `scanner_stats`
- `commands`
- `scope`
- `remediation`
- `setup_debt`
- `skipped_by_tracker`
- `skipped_targets`
- `coverage`
- `results`

Project results include:

- `label`
- `git_root`
- `ecosystems`
- `findings`
- `setup_debt`
- `coverage`

Coverage states are deliberately separate from finding counts:

- `verified_clean`
- `scanned`
- `not_requested`
- `not_applicable`
- `skipped`
- `unsupported`
- `scanner_missing`
- `scanner_failed`
- `timed_out`

Never infer that a category is clean from zero findings alone. Check the project
coverage state and setup-debt items.
</file>

<file path="references/scanner-behavior.md">
# Scanner Behavior

The scanner CLI is the primary entrypoint:

```bash
python3 scripts/vuln-scan.py scan \
  --config templates/config-starter.yaml \
  --root /path/to/workspace \
  --scan-mode full \
  --output /tmp/vuln-summary.json \
  --artifact-dir /tmp/vuln-artifacts \
  --format text
```

Normal scans are read-only. Remediation requires explicit opt-in:

```bash
python3 scripts/vuln-scan.py scan \
  --root /path/to/repo \
  --scan-mode dependencies \
  --auto-remediate
```

Discovery creates separate project targets for package roots, workflows,
containers, IaC, and VS Code extensions. `package.json` without a supported
lockfile is still a target, but dependency coverage is reported as unsupported
setup debt instead of silently omitting the project.

Scope gates run before scanner execution. Use `--allowed-root`,
`--allowed-label-prefix`, `--forbidden-label-prefix`, and
`--fail-on-scope-violation` for unattended scans.

Clean unattended cron output may be exactly `[SILENT]` only when there are zero
findings, zero setup-debt items, zero scope violations, and no scanner timeout or
parser failure.
</file>

<file path="scripts/vulnscan/cli/__init__.py">
"""Command-line interface for the local vulnerability scanner."""

from __future__ import annotations

import sys

from .args import COMMANDS, build_parser, normalize_argv
from .output import (
    SEVERITY_ORDER,
    build_plan_summary,
    build_scope_failure_summary,
    filter_findings_by_severity,
    render_package_intake_text,
    render_report,
    summary_can_be_silent,
    write_and_print_summary,
)
from .package import package_intake
from .scan import run_scan
from ..config import load_config
from ..inventory import render_deep_tool_validation, render_engine_inventory, render_tool_validation

__all__ = [
    "COMMANDS",
    "SEVERITY_ORDER",
    "build_parser",
    "build_plan_summary",
    "build_scope_failure_summary",
    "filter_findings_by_severity",
    "main",
    "normalize_argv",
    "package_intake",
    "render_package_intake_text",
    "render_report",
    "run_scan",
    "summary_can_be_silent",
    "write_and_print_summary",
]


def main(argv: list[str] | None = None) -> int:
    command, normalized = normalize_argv(list(sys.argv[1:] if argv is None else argv))
    if command == "render-report":
        return render_report(normalized)
    if command == "package-intake":
        return package_intake(normalized)

    parser = build_parser()
    args = parser.parse_args(normalized)
    if args.list_engines:
        config = load_config(args.config)
        print(render_engine_inventory(args.format, config))
        return 0
    if args.validate_tools:
        config = load_config(args.config)
        if args.deep:
            print(render_deep_tool_validation(args.format, config))
        else:
            print(render_tool_validation(args.format, config))
        return 0
    return run_scan(args)
</file>

<file path="scripts/vulnscan/cli/output.py">
"""CLI report rendering and summary helpers."""

from __future__ import annotations

import argparse
import json
import time
from pathlib import Path
from typing import Any

from ..common import now_iso
from ..config import cfg_get
from ..inventory import MODE_IMPLEMENTATION
from ..reporting import render_summary_text

SEVERITY_ORDER = {"UNKNOWN": 1, "INFO": 1, "REVIEW": 1, "LOW": 1, "MEDIUM": 2, "HIGH": 3, "CRITICAL": 4}


def build_scope_failure_summary(
    *,
    artifact_dir: Path,
    started: float,
    scan_mode: str,
    projects_count: int,
    max_depth: int,
    scope_report: dict[str, Any],
    skipped_targets: list[dict[str, str]],
) -> dict[str, Any]:
    return {
        "generated_at": now_iso(),
        "artifact_dir": str(artifact_dir),
        "scanned_projects": 0,
        "affected_projects": 0,
        "finding_count": 0,
        "severity_counts": {},
        "engine_counts": {},
        "scanner_stats": {
            "duration_seconds": round(time.time() - started, 2),
            "scan_mode": scan_mode,
            "mode_status": MODE_IMPLEMENTATION[scan_mode],
            "project_discovery": {"projects": projects_count, "git_roots": 0, "max_depth": max_depth},
        },
        "scope": scope_report,
        "remediation": {"enabled": False},
        "setup_debt": [{"repo": "__scope__", "item": "scope violation; scan not started"}],
        "skipped_targets": skipped_targets,
        "skipped_by_tracker": 0,
        "top_affected": [],
        "secret_findings": [],
        "results": [],
    }


def summary_can_be_silent(summary: dict[str, Any], config: dict[str, Any]) -> bool:
    if not bool(cfg_get(config, "scan.silent_when_clean", False)):
        return False
    stats = summary.get("scanner_stats") or {}
    return (
        stats.get("command", "scan") == "scan"
        and summary.get("finding_count", 0) == 0
        and not summary.get("setup_debt")
        and not summary.get("scope", {}).get("out_of_scope_count")
        and not any((stats.get("osv") or {}).get(key, 0) for key in ("timeout", "parse_failed"))
        and not any((stats.get("javascript") or {}).get(key, 0) for key in ("bun_parse_failed", "bun_error", "npm_parse_failed", "npm_error", "pnpm_parse_failed", "pnpm_error"))
        and not (stats.get("mode_setup_debt") or [])
    )


def write_and_print_summary(summary: dict[str, Any], args: argparse.Namespace, config: dict[str, Any] | None = None) -> None:
    if getattr(args, "output", None):
        args.output.parent.mkdir(parents=True, exist_ok=True)
        args.output.write_text(json.dumps(summary, indent=2 if args.pretty else None, sort_keys=True), encoding="utf-8")
    if config is not None and args.format == "text" and summary_can_be_silent(summary, config):
        print("[SILENT]")
        return
    if args.format == "text":
        print(render_summary_text(summary))
    else:
        print(json.dumps(summary, indent=2 if args.pretty else None, sort_keys=True))


def render_report(argv: list[str]) -> int:
    parser = argparse.ArgumentParser(description="Render a saved vulnerability scan JSON summary")
    parser.add_argument("summary", type=Path, help="Path to a saved summary JSON file")
    parser.add_argument("--format", choices=["json", "text"], default="text")
    parser.add_argument("--pretty", action="store_true")
    args = parser.parse_args(argv)
    summary = json.loads(args.summary.read_text(encoding="utf-8"))
    if args.format == "text":
        print(render_summary_text(summary))
    else:
        print(json.dumps(summary, indent=2 if args.pretty else None, sort_keys=True))
    return 0


def render_package_intake_text(report: dict[str, Any]) -> str:
    lines = [
        f"Package intake: {report.get('ecosystem')}:{report.get('package')}",
        f"Decision: {report.get('decision')}",
        f"Findings: {report.get('finding_count', 0)}",
    ]
    setup_debt = (report.get("scanner_stats") or {}).get("setup_debt") or []
    if setup_debt:
        lines.append("Setup debt:")
        for item in setup_debt[:20]:
            lines.append(f"- {item.get('scanner')} {item.get('target')}: {item.get('reason')}")
    for finding in report.get("findings", [])[:20]:
        lines.append(f"- {finding.get('severity')} {finding.get('rule_id')}: {finding.get('title')}")
    return "\n".join(lines)


def filter_findings_by_severity(findings: list[dict[str, Any]], threshold: str) -> tuple[list[dict[str, Any]], int]:
    normalized = str(threshold or "none").upper()
    if normalized == "NONE":
        return findings, 0
    minimum = SEVERITY_ORDER.get(normalized, SEVERITY_ORDER["LOW"])
    kept = [finding for finding in findings if SEVERITY_ORDER.get(str(finding.get("severity") or "UNKNOWN").upper(), 0) >= minimum]
    return kept, len(findings) - len(kept)


def build_plan_summary(
    *,
    artifact_dir: Path,
    started: float,
    scan_mode: str,
    max_depth: int,
    projects: list[Any],
    git_roots: list[Path],
    scope_report: dict[str, Any],
    skipped_targets: list[dict[str, str]],
) -> dict[str, Any]:
    return {
        "generated_at": now_iso(),
        "artifact_dir": str(artifact_dir),
        "scanned_projects": 0,
        "affected_projects": 0,
        "finding_count": 0,
        "severity_counts": {},
        "engine_counts": {},
        "scanner_stats": {
            "duration_seconds": round(time.time() - started, 2),
            "scan_mode": scan_mode,
            "mode_status": MODE_IMPLEMENTATION[scan_mode],
            "command": "plan",
            "project_discovery": {"projects": len(projects), "git_roots": len(git_roots), "max_depth": max_depth},
        },
        "scope": scope_report,
        "remediation": {"enabled": False},
        "setup_debt": [],
        "skipped_by_tracker": 0,
        "skipped_targets": skipped_targets,
        "planned_projects": [
            {
                "label": project.label,
                "path": str(project.path),
                "git_root": str(project.git_root) if project.git_root else None,
                "ecosystems": sorted(project.ecosystems),
            }
            for project in projects
        ],
        "top_affected": [],
        "secret_findings": [],
        "results": [],
    }
</file>

<file path="scripts/vulnscan/cli/package.py">
"""Package intake CLI command."""

from __future__ import annotations

import argparse
import json
import tempfile
from pathlib import Path

from .output import render_package_intake_text
from ..config import load_config
from ..supply_chain import run_guarddog_package_intake


def package_intake(argv: list[str]) -> int:
    parser = argparse.ArgumentParser(description="Scan a named package before adding it to a repo")
    parser.add_argument("ecosystem", choices=["npm", "pypi", "go", "rubygems", "github_action", "extension"])
    parser.add_argument("package")
    parser.add_argument("--version")
    parser.add_argument("--config", type=Path)
    parser.add_argument("--artifact-dir", type=Path)
    parser.add_argument("--output", type=Path)
    parser.add_argument("--format", choices=["json", "text"], default="text")
    parser.add_argument("--pretty", action="store_true")
    args = parser.parse_args(argv)
    config = load_config(args.config)
    artifact_dir = args.artifact_dir or Path(tempfile.mkdtemp(prefix="vuln-intake-"))
    artifact_dir.mkdir(parents=True, exist_ok=True)
    report, _stats = run_guarddog_package_intake(args.ecosystem, args.package, config, artifact_dir, version=args.version)
    if args.output:
        args.output.parent.mkdir(parents=True, exist_ok=True)
        args.output.write_text(json.dumps(report, indent=2 if args.pretty else None, sort_keys=True), encoding="utf-8")
    if args.format == "json":
        print(json.dumps(report, indent=2 if args.pretty else None, sort_keys=True))
    else:
        print(render_package_intake_text(report))
    return 1 if report["decision"] in {"avoid", "blocked pending review"} else 0
</file>

<file path="scripts/vulnscan/parsers/__init__.py">
"""Scanner output parser compatibility exports."""

from __future__ import annotations

from .containers import parse_trivy
from .dependencies import parse_bun, parse_cargo_audit, parse_npm, parse_osv, parse_pip_audit, parse_pnpm, severity_from_osv
from .secrets import normalize_secret_finding, parse_gitleaks, parse_trufflehog_lines
from .static import parse_grype, parse_scorecard, parse_semgrep, parse_syft_metadata, scorecard_severity, semgrep_severity
from .supply_chain import guarddog_severity, parse_guarddog
from .utils import dedupe_findings, extract_json, first_reference_url, norm_severity, normalize_dependency_finding, normalize_finding, redact_sensitive_values
from .workflows import classify_workflow_issue, parse_actionlint_lines, parse_zizmor, workflow_severity

__all__ = [
    "classify_workflow_issue",
    "dedupe_findings",
    "extract_json",
    "first_reference_url",
    "guarddog_severity",
    "norm_severity",
    "normalize_dependency_finding",
    "normalize_finding",
    "normalize_secret_finding",
    "parse_actionlint_lines",
    "parse_bun",
    "parse_cargo_audit",
    "parse_gitleaks",
    "parse_grype",
    "parse_guarddog",
    "parse_npm",
    "parse_osv",
    "parse_pip_audit",
    "parse_pnpm",
    "parse_scorecard",
    "parse_semgrep",
    "parse_syft_metadata",
    "parse_trivy",
    "parse_trufflehog_lines",
    "parse_zizmor",
    "redact_sensitive_values",
    "scorecard_severity",
    "semgrep_severity",
    "severity_from_osv",
    "workflow_severity",
]
</file>

<file path="scripts/vulnscan/parsers/dependencies.py">
"""Dependency vulnerability parser adapters."""

from __future__ import annotations

import json
import re
from pathlib import Path
from typing import Any

from .utils import dedupe_findings, norm_severity, normalize_dependency_finding


def severity_from_osv(vuln: dict[str, Any]) -> str:
    db = vuln.get("database_specific") or {}
    sev = db.get("severity") or vuln.get("severity")
    if isinstance(sev, str):
        return norm_severity(sev)
    if isinstance(sev, list):
        for item in sev:
            if not isinstance(item, dict):
                continue
            score = item.get("score")
            if not isinstance(score, str):
                continue
            match = re.search(r"(\d+(?:\.\d+)?)", score)
            if not match:
                continue
            numeric = float(match.group(1))
            if numeric >= 9:
                return "CRITICAL"
            if numeric >= 7:
                return "HIGH"
            if numeric >= 4:
                return "MEDIUM"
            return "LOW"
    return "UNKNOWN"


def parse_osv(path: Path, source_label: str) -> tuple[list[dict[str, Any]], str | None]:
    if not path.exists() or path.stat().st_size == 0:
        return [], "empty_output"
    try:
        data = json.loads(path.read_text(encoding="utf-8", errors="replace"))
    except Exception as exc:
        return [], f"parse_failed:{exc}"
    findings: list[dict[str, Any]] = []
    for result in data.get("results") or []:
        for package in result.get("packages") or []:
            pinfo = package.get("package") or {}
            name = pinfo.get("name") or package.get("name") or "unknown"
            ecosystem = pinfo.get("ecosystem") or package.get("ecosystem") or "unknown"
            for vuln in package.get("vulnerabilities") or []:
                refs = vuln.get("references") or []
                url = None
                if refs and isinstance(refs[0], dict):
                    url = refs[0].get("url")
                findings.append(
                    normalize_dependency_finding(
                        {
                        "source_engine": "osv-scanner",
                        "source_label": source_label,
                        "package": name,
                        "ecosystem": ecosystem,
                        "severity": severity_from_osv(vuln),
                        "advisory_id": vuln.get("id"),
                        "title": vuln.get("summary") or vuln.get("details", "")[:160] or vuln.get("id"),
                        "url": url or f"https://osv.dev/vulnerability/{vuln.get('id')}",
                        }
                    )
                )
    return dedupe_findings(findings), None


def parse_bun(data: Any) -> tuple[list[dict[str, Any]], str | None]:
    if data is None:
        return [], "parse_failed"
    if isinstance(data, dict) and "error" in data:
        err = data.get("error") or {}
        return [], f"bun_error:{err.get('code', 'unknown')}"
    findings: list[dict[str, Any]] = []
    for package, advisories in (data or {}).items():
        if not isinstance(advisories, list):
            continue
        for advisory in advisories:
            if not isinstance(advisory, dict):
                continue
            findings.append(
                normalize_dependency_finding(
                    {
                    "source_engine": "bun-audit",
                    "package": package,
                    "ecosystem": "npm",
                    "severity": norm_severity(advisory.get("severity")),
                    "advisory_id": str(advisory.get("id")) if advisory.get("id") is not None else None,
                    "title": advisory.get("title") or "",
                    "url": advisory.get("url"),
                    "fixed_version": advisory.get("patched_versions") or advisory.get("patchedVersions"),
                    }
                )
            )
    return findings, None


def parse_npm(data: Any) -> tuple[list[dict[str, Any]], str | None]:
    if data is None:
        return [], "parse_failed"
    if isinstance(data, dict) and "error" in data and not data.get("vulnerabilities"):
        err = data.get("error") or {}
        return [], f"npm_error:{err.get('code', 'unknown')}"
    findings: list[dict[str, Any]] = []
    for package, info in (data.get("vulnerabilities") or {}).items():
        if not isinstance(info, dict):
            continue
        via = info.get("via") or []
        severity = norm_severity(info.get("severity"))
        direct = [x for x in via if isinstance(x, dict)]
        if direct:
            for advisory in direct:
                findings.append(
                    normalize_dependency_finding(
                        {
                        "source_engine": "npm-audit",
                        "package": package,
                        "ecosystem": "npm",
                        "severity": norm_severity(advisory.get("severity") or severity),
                        "advisory_id": str(advisory.get("source") or advisory.get("id")) if (advisory.get("source") or advisory.get("id")) is not None else None,
                        "title": advisory.get("title") or advisory.get("name") or "",
                        "url": advisory.get("url"),
                        }
                    )
                )
        else:
            findings.append(
                normalize_dependency_finding(
                    {
                    "source_engine": "npm-audit",
                    "package": package,
                    "ecosystem": "npm",
                    "severity": severity,
                    "advisory_id": None,
                    "title": f"npm audit vulnerability in {package}",
                    "url": None,
                    }
                )
            )
    return findings, None


def parse_pnpm(data: Any) -> tuple[list[dict[str, Any]], str | None]:
    if data is None:
        return [], "parse_failed"
    if isinstance(data, dict) and "error" in data and not data.get("advisories"):
        err = data.get("error") or {}
        return [], f"pnpm_error:{err.get('code', 'unknown')}"
    findings: list[dict[str, Any]] = []
    advisories = data.get("advisories") if isinstance(data, dict) else None
    if not isinstance(advisories, dict):
        return [], "parse_failed"
    for advisory_id, advisory in advisories.items():
        if not isinstance(advisory, dict):
            continue
        findings.append(
            normalize_dependency_finding(
                {
                "source_engine": "pnpm-audit",
                "package": advisory.get("module_name") or advisory.get("name") or "unknown",
                "ecosystem": "npm",
                "severity": norm_severity(advisory.get("severity")),
                "advisory_id": str(advisory.get("id") or advisory_id) if (advisory.get("id") or advisory_id) is not None else None,
                "title": advisory.get("title") or advisory.get("overview") or "",
                "url": advisory.get("url"),
                "fixed_version": advisory.get("patched_versions") or advisory.get("patchedVersions"),
                }
            )
        )
    return findings, None


def parse_pip_audit(data: Any) -> tuple[list[dict[str, Any]], str | None]:
    if data is None:
        return [], "parse_failed"
    if isinstance(data, list):
        dependencies = data
    elif isinstance(data, dict):
        if data.get("error") and not data.get("dependencies"):
            return [], f"pip_audit_error:{data.get('error')}"
        dependencies = data.get("dependencies") or data.get("results") or []
    else:
        return [], "parse_failed"
    if not isinstance(dependencies, list):
        return [], "parse_failed"

    findings: list[dict[str, Any]] = []
    for dependency in dependencies:
        if not isinstance(dependency, dict):
            continue
        name = dependency.get("name") or dependency.get("package") or "unknown"
        version = dependency.get("version")
        vulns = dependency.get("vulns") or dependency.get("vulnerabilities") or []
        if not isinstance(vulns, list):
            continue
        for vuln in vulns:
            if not isinstance(vuln, dict):
                continue
            aliases = vuln.get("aliases") if isinstance(vuln.get("aliases"), list) else []
            advisory_id = vuln.get("id") or vuln.get("advisory_id") or (aliases[0] if aliases else None)
            fix_versions = vuln.get("fix_versions") or vuln.get("fix_versions_for_vulnerability") or vuln.get("fixed_versions")
            findings.append(
                normalize_dependency_finding(
                    {
                        "source_engine": "pip-audit",
                        "package": name,
                        "ecosystem": "python",
                        "installed_version": version,
                        "severity": vuln.get("severity") or vuln.get("cvss_severity") or "UNKNOWN",
                        "advisory_id": str(advisory_id) if advisory_id is not None else None,
                        "title": vuln.get("description") or vuln.get("summary") or str(advisory_id or ""),
                        "url": vuln.get("url") or (f"https://osv.dev/vulnerability/{advisory_id}" if advisory_id else None),
                        "fixed_version": fix_versions,
                    }
                )
            )
    return dedupe_findings(findings), None


def parse_cargo_audit(data: Any) -> tuple[list[dict[str, Any]], str | None]:
    if data is None or not isinstance(data, dict):
        return [], "parse_failed"
    vulnerabilities = data.get("vulnerabilities") or {}
    if not isinstance(vulnerabilities, dict):
        return [], "parse_failed"
    vuln_list = vulnerabilities.get("list") or vulnerabilities.get("warnings") or []
    if not isinstance(vuln_list, list):
        return [], "parse_failed"

    findings: list[dict[str, Any]] = []
    for item in vuln_list:
        if not isinstance(item, dict):
            continue
        advisory = item.get("advisory") or {}
        package = item.get("package") or {}
        versions = item.get("versions") or {}
        if not isinstance(advisory, dict):
            advisory = {}
        if not isinstance(package, dict):
            package = {}
        if not isinstance(versions, dict):
            versions = {}
        package_name = package.get("name") or advisory.get("package") or item.get("package") or "unknown"
        severity = advisory.get("severity") or advisory.get("cvss") or "UNKNOWN"
        findings.append(
            normalize_dependency_finding(
                {
                    "source_engine": "cargo-audit",
                    "package": package_name,
                    "ecosystem": "rust",
                    "installed_version": package.get("version"),
                    "severity": severity,
                    "advisory_id": advisory.get("id"),
                    "title": advisory.get("title") or advisory.get("description") or advisory.get("id"),
                    "url": advisory.get("url") or (f"https://rustsec.org/advisories/{advisory.get('id')}" if advisory.get("id") else None),
                    "fixed_version": versions.get("patched"),
                }
            )
        )
    return dedupe_findings(findings), None
</file>

<file path="scripts/vulnscan/parsers/secrets.py">
"""Secret scanner parser adapters."""

from __future__ import annotations

import json
from typing import Any

from .utils import dedupe_findings, norm_severity


def normalize_secret_finding(finding: dict[str, Any]) -> dict[str, Any]:
    out = dict(finding)
    for key in ("value", "Value", "secret", "Secret", "match", "Match", "raw", "Raw", "rawV2", "RawV2"):
        out.pop(key, None)
    out.setdefault("category", "secret")
    out.setdefault("confidence", "detected_pattern")
    out.setdefault("verification_state", "unverified")
    out.setdefault("git_tracked", None)
    if "detector" not in out and out.get("type"):
        out["detector"] = out["type"]
    out["severity"] = norm_severity(out.get("severity"))
    return out


def parse_gitleaks(data: Any, source_label: str) -> tuple[list[dict[str, Any]], str | None]:
    if data is None:
        return [], "parse_failed"
    if isinstance(data, dict) and data.get("error"):
        return [], f"gitleaks_error:{data.get('error')}"
    if not isinstance(data, list):
        return [], "parse_failed"
    findings: list[dict[str, Any]] = []
    for item in data:
        if not isinstance(item, dict):
            continue
        findings.append(
            normalize_secret_finding(
                {
                    "source_engine": "gitleaks",
                    "source_label": source_label,
                    "type": item.get("RuleID") or item.get("ruleID") or item.get("Description") or "secret",
                    "severity": "HIGH",
                    "title": item.get("Description") or item.get("RuleID") or "Secret detected",
                    "file": item.get("File") or item.get("file"),
                    "line": item.get("StartLine") or item.get("startLine") or item.get("Line") or item.get("line"),
                    "commit": item.get("Commit") or item.get("commit"),
                    "git_tracked": True if (item.get("Commit") or item.get("commit")) else None,
                    "verification_state": "unverified",
                    "confidence": "detected_pattern",
                    "remediation_hint": "Rotate the credential if real, remove it from tracked files, and consider history cleanup.",
                }
            )
        )
    return dedupe_findings(findings), None


def parse_trufflehog_lines(text: str, source_label: str, include_unverified: bool = False) -> tuple[list[dict[str, Any]], str | None]:
    findings: list[dict[str, Any]] = []
    if not text.strip():
        return findings, None
    for raw_line in text.splitlines():
        if not raw_line.strip():
            continue
        try:
            item = json.loads(raw_line)
        except json.JSONDecodeError:
            return [], "parse_failed"
        if not isinstance(item, dict):
            continue
        verified = bool(item.get("Verified") if "Verified" in item else item.get("verified"))
        if not include_unverified and not verified:
            continue
        source_metadata = item.get("SourceMetadata") if isinstance(item.get("SourceMetadata"), dict) else {}
        data = source_metadata.get("Data") if isinstance(source_metadata.get("Data"), dict) else {}
        git_data = data.get("Git") if isinstance(data.get("Git"), dict) else {}
        findings.append(
            normalize_secret_finding(
                {
                    "source_engine": "trufflehog",
                    "source_label": source_label,
                    "type": item.get("DetectorName") or item.get("detectorName") or item.get("DetectorType") or "secret",
                    "severity": "CRITICAL" if verified else "HIGH",
                    "title": item.get("DetectorName") or item.get("detectorName") or "Secret detected",
                    "file": git_data.get("file") or git_data.get("File") or item.get("SourceName") or item.get("sourceName"),
                    "line": git_data.get("line") or git_data.get("Line"),
                    "commit": git_data.get("commit") or git_data.get("Commit"),
                    "git_tracked": True,
                    "verification_state": "verified" if verified else "unverified",
                    "confidence": "verified" if verified else "detected_pattern",
                    "remediation_hint": "Rotate verified credentials immediately, remove them from tracked files, and evaluate history cleanup.",
                }
            )
        )
    return dedupe_findings(findings), None
</file>

<file path="scripts/vulnscan/parsers/static.py">
"""Static analysis, SBOM, and hygiene parser adapters."""

from __future__ import annotations

from typing import Any

from .utils import dedupe_findings, norm_severity, normalize_dependency_finding, normalize_finding


def semgrep_severity(value: Any) -> str:
    text = str(value or "UNKNOWN").upper()
    if text == "ERROR":
        return "HIGH"
    if text == "WARNING":
        return "MEDIUM"
    if text == "INFO":
        return "LOW"
    return norm_severity(text)


def parse_semgrep(data: Any, source_label: str) -> tuple[list[dict[str, Any]], str | None]:
    if data is None or not isinstance(data, dict):
        return [], "parse_failed"
    if data.get("errors") and not isinstance(data.get("results"), list):
        return [], f"semgrep_error:{data.get('errors')}"
    results = data.get("results")
    if not isinstance(results, list):
        return [], "parse_failed"
    findings: list[dict[str, Any]] = []
    for item in results:
        if not isinstance(item, dict):
            continue
        extra = item.get("extra") if isinstance(item.get("extra"), dict) else {}
        start = item.get("start") if isinstance(item.get("start"), dict) else {}
        metadata = extra.get("metadata") if isinstance(extra.get("metadata"), dict) else {}
        rule_id = item.get("check_id") or item.get("rule_id") or "semgrep"
        findings.append(
            normalize_finding(
                {
                    "source_engine": "semgrep",
                    "source_label": source_label,
                    "severity": semgrep_severity(extra.get("severity")),
                    "rule_id": rule_id,
                    "advisory_id": rule_id,
                    "title": extra.get("message") or rule_id,
                    "url": metadata.get("source") or metadata.get("reference") or metadata.get("url"),
                    "file": item.get("path"),
                    "line": start.get("line"),
                    "column": start.get("col"),
                    "remediation_hint": extra.get("fix") or extra.get("message"),
                },
                category="sast",
                confidence="scanner_rule",
            )
        )
    return dedupe_findings(findings), None


def parse_syft_metadata(data: Any) -> tuple[dict[str, Any], str | None]:
    if data is None or not isinstance(data, dict):
        return {}, "parse_failed"
    components = data.get("components")
    artifacts = data.get("artifacts")
    packages = components if isinstance(components, list) else artifacts if isinstance(artifacts, list) else []
    if not isinstance(packages, list):
        return {}, "parse_failed"
    return {
        "format": data.get("bomFormat") or data.get("schema") or "unknown",
        "package_count": len(packages),
    }, None


def parse_grype(data: Any, source_label: str) -> tuple[list[dict[str, Any]], str | None]:
    if data is None or not isinstance(data, dict):
        return [], "parse_failed"
    matches = data.get("matches")
    if not isinstance(matches, list):
        return [], "parse_failed"
    findings: list[dict[str, Any]] = []
    for match in matches:
        if not isinstance(match, dict):
            continue
        vuln = match.get("vulnerability") if isinstance(match.get("vulnerability"), dict) else {}
        artifact = match.get("artifact") if isinstance(match.get("artifact"), dict) else {}
        locations = artifact.get("locations") if isinstance(artifact.get("locations"), list) else []
        file_path = None
        if locations and isinstance(locations[0], dict):
            file_path = locations[0].get("path")
        urls = vuln.get("urls") if isinstance(vuln.get("urls"), list) else []
        findings.append(
            normalize_dependency_finding(
                {
                    "source_engine": "grype",
                    "source_label": source_label,
                    "package": artifact.get("name") or "unknown",
                    "ecosystem": artifact.get("type") or "unknown",
                    "installed_version": artifact.get("version"),
                    "fixed_version": vuln.get("fix", {}).get("versions") if isinstance(vuln.get("fix"), dict) else None,
                    "severity": vuln.get("severity"),
                    "advisory_id": vuln.get("id"),
                    "title": vuln.get("description") or vuln.get("id"),
                    "url": urls[0] if urls else None,
                    "file": file_path,
                    "category": "dependency",
                    "confidence": "known_vulnerability",
                }
            )
        )
    return dedupe_findings(findings), None


def scorecard_severity(score: float) -> str:
    if score <= 2:
        return "HIGH"
    if score <= 6:
        return "MEDIUM"
    return "LOW"


def parse_scorecard(data: Any, source_label: str, minimum_score: float = 10) -> tuple[list[dict[str, Any]], str | None]:
    if data is None or not isinstance(data, dict):
        return [], "parse_failed"
    checks = data.get("checks")
    if not isinstance(checks, list):
        return [], "parse_failed"
    findings: list[dict[str, Any]] = []
    for check in checks:
        if not isinstance(check, dict):
            continue
        score_raw = check.get("score")
        try:
            score = float(score_raw)
        except (TypeError, ValueError):
            continue
        if score >= minimum_score:
            continue
        name = check.get("name") or check.get("check") or "Scorecard check"
        documentation = check.get("documentation") if isinstance(check.get("documentation"), dict) else {}
        details = check.get("details") if isinstance(check.get("details"), list) else []
        findings.append(
            normalize_finding(
                {
                    "source_engine": "scorecard",
                    "source_label": source_label,
                    "severity": scorecard_severity(score),
                    "rule_id": name,
                    "advisory_id": name,
                    "title": check.get("reason") or f"OpenSSF Scorecard check below threshold: {name}",
                    "url": documentation.get("url") or check.get("documentation_url"),
                    "score": score,
                    "score_threshold": minimum_score,
                    "details": details[:10],
                    "remediation_hint": documentation.get("short") or check.get("reason"),
                },
                category="hygiene",
                confidence="scanner_rule",
            )
        )
    return dedupe_findings(findings), None
</file>

<file path="scripts/vulnscan/parsers/supply_chain.py">
"""Supply-chain scanner parser adapters."""

from __future__ import annotations

from typing import Any

from .utils import dedupe_findings, norm_severity, normalize_finding


def guarddog_severity(item: dict[str, Any]) -> str:
    severity = item.get("severity") or item.get("level") or item.get("confidence")
    if severity:
        return norm_severity(severity)
    return "HIGH"


def _guarddog_iter_items(data: Any) -> list[dict[str, Any]]:
    if isinstance(data, list):
        return [item for item in data if isinstance(item, dict)]
    if not isinstance(data, dict):
        return []
    for key in ("issues", "findings", "results", "matches", "detections"):
        value = data.get(key)
        if isinstance(value, list):
            return [item for item in value if isinstance(item, dict)]
    return []


def parse_guarddog(data: Any, source_label: str, ecosystem: str | None = None) -> tuple[list[dict[str, Any]], str | None]:
    if data is None:
        return [], "parse_failed"
    if isinstance(data, dict) and data.get("error"):
        return [], f"guarddog_error:{data.get('error')}"
    items = _guarddog_iter_items(data)
    findings: list[dict[str, Any]] = []
    for item in items:
        extra = item.get("extra") if isinstance(item.get("extra"), dict) else {}
        metadata = extra.get("metadata") if isinstance(extra.get("metadata"), dict) else {}
        rule_id = (
            item.get("rule")
            or item.get("rule_id")
            or item.get("check_id")
            or item.get("id")
            or metadata.get("rule")
            or "guarddog"
        )
        message = item.get("message") or item.get("description") or extra.get("message") or str(rule_id)
        location = item.get("location") if isinstance(item.get("location"), dict) else {}
        start = item.get("start") if isinstance(item.get("start"), dict) else {}
        findings.append(
            normalize_finding(
                {
                    "source_engine": "guarddog",
                    "source_label": source_label,
                    "severity": guarddog_severity(item),
                    "rule_id": rule_id,
                    "advisory_id": rule_id,
                    "title": message,
                    "url": item.get("url") or metadata.get("source"),
                    "package": item.get("package") or item.get("package_name") or item.get("name"),
                    "ecosystem": ecosystem or item.get("ecosystem") or item.get("source"),
                    "file": item.get("path") or item.get("file") or location.get("path"),
                    "line": item.get("line") or location.get("line") or start.get("line"),
                    "remediation_hint": "Review package behavior before adding or updating this dependency.",
                },
                category="supply-chain",
                confidence=str(item.get("confidence") or "heuristic").lower(),
            )
        )
    return dedupe_findings(findings), None
</file>

<file path="scripts/vulnscan/parsers/utils.py">
"""Shared parser normalization helpers."""

from __future__ import annotations

import json
from typing import Any

SECRET_VALUE_KEYS = {"value", "secret", "match", "raw", "rawv2"}


def redact_sensitive_values(data: Any) -> Any:
    if isinstance(data, dict):
        redacted: dict[str, Any] = {}
        for key, value in data.items():
            if key.lower() in SECRET_VALUE_KEYS:
                redacted[key] = "[REDACTED]"
            else:
                redacted[key] = redact_sensitive_values(value)
        return redacted
    if isinstance(data, list):
        return [redact_sensitive_values(item) for item in data]
    return data


def extract_json(text: str) -> Any:
    if not text:
        return None
    object_start = text.find("{")
    array_start = text.find("[")
    starts = [idx for idx in (object_start, array_start) if idx >= 0]
    if not starts:
        return None
    start = min(starts)
    stack: list[str] = []
    in_str = False
    esc = False
    for idx, char in enumerate(text[start:], start):
        if in_str:
            if esc:
                esc = False
            elif char == "\\":
                esc = True
            elif char == '"':
                in_str = False
        else:
            if char == '"':
                in_str = True
            elif char == "{":
                stack.append("}")
            elif char == "[":
                stack.append("]")
            elif char in {"}", "]"}:
                if not stack or stack[-1] != char:
                    return None
                stack.pop()
                if not stack:
                    try:
                        return json.loads(text[start : idx + 1])
                    except json.JSONDecodeError:
                        return None
    return None


def norm_severity(value: Any) -> str:
    text = str(value or "unknown").lower()
    if text == "moderate":
        text = "medium"
    return text.upper()


def normalize_dependency_finding(finding: dict[str, Any]) -> dict[str, Any]:
    out = dict(finding)
    out.setdefault("category", "dependency")
    out.setdefault("confidence", "known_vulnerability")
    if out.get("severity"):
        out["severity"] = norm_severity(out["severity"])
    else:
        out["severity"] = "UNKNOWN"
    return out


def normalize_finding(finding: dict[str, Any], *, category: str, confidence: str) -> dict[str, Any]:
    out = dict(finding)
    out.setdefault("category", category)
    out.setdefault("confidence", confidence)
    out["severity"] = norm_severity(out.get("severity"))
    return out


def first_reference_url(item: dict[str, Any]) -> str | None:
    refs = item.get("References") or item.get("references") or []
    if isinstance(refs, list) and refs:
        return str(refs[0])
    return item.get("PrimaryURL") or item.get("primary_url") or item.get("URL") or item.get("url")


def dedupe_findings(findings: list[dict[str, Any]]) -> list[dict[str, Any]]:
    out: list[dict[str, Any]] = []
    seen: set[tuple[Any, ...]] = set()
    for finding in findings:
        key = (
            finding.get("category"),
            finding.get("package"),
            finding.get("ecosystem"),
            finding.get("advisory_id"),
            finding.get("file"),
            finding.get("line"),
            (finding.get("title") or "").lower(),
        )
        if key in seen:
            continue
        seen.add(key)
        out.append(finding)
    return out
</file>

<file path="scripts/vulnscan/parsers/workflows.py">
"""CI workflow scanner parser adapters."""

from __future__ import annotations

import json
from typing import Any

from .utils import dedupe_findings, norm_severity, normalize_finding


def classify_workflow_issue(rule_id: Any, message: Any = "") -> str:
    text = f"{rule_id or ''} {message or ''}".lower()
    if "permission" in text:
        return "overbroad_permissions"
    if "unpinned" in text or "pin" in text or "ref-confusion" in text or "stale-action" in text:
        return "unpinned_actions"
    if "pull_request_target" in text or "pull-request-target" in text:
        return "unsafe_pull_request_target"
    if "template-injection" in text or "script injection" in text or "untrusted" in text or "injection" in text:
        return "workflow_injection"
    if "secret" in text or "credential" in text or "github_env" in text or "github-env" in text or "github_output" in text:
        return "workflow_secret_exposure"
    if "uses" in text or "action" in text:
        return "untrusted_actions"
    return "workflow_correctness"


def workflow_severity(rule_id: Any, message: Any = "", fallback: Any = None) -> str:
    if fallback:
        return norm_severity(fallback)
    issue_type = classify_workflow_issue(rule_id, message)
    if issue_type in {"overbroad_permissions", "workflow_injection", "workflow_secret_exposure", "unsafe_pull_request_target"}:
        return "HIGH"
    return "MEDIUM"


def _zizmor_location(item: dict[str, Any]) -> tuple[str | None, int | None]:
    locations = item.get("locations")
    if not isinstance(locations, list) or not locations:
        return None, None
    location = locations[0] if isinstance(locations[0], dict) else {}
    symbolic = location.get("symbolic") if isinstance(location.get("symbolic"), dict) else {}
    concrete = location.get("concrete") if isinstance(location.get("concrete"), dict) else {}
    file_path = None
    key = symbolic.get("key") if isinstance(symbolic.get("key"), dict) else {}
    local = key.get("Local") if isinstance(key.get("Local"), dict) else {}
    if isinstance(local, dict):
        file_path = local.get("given_path") or local.get("path")
    line = None
    loc = concrete.get("location") if isinstance(concrete.get("location"), dict) else {}
    start = loc.get("start_point") if isinstance(loc.get("start_point"), dict) else {}
    row = start.get("row")
    if isinstance(row, int):
        line = row + 1
    return file_path, line


def parse_zizmor(data: Any, source_label: str) -> tuple[list[dict[str, Any]], str | None]:
    if data is None:
        return [], "parse_failed"
    if isinstance(data, dict) and data.get("error"):
        return [], f"zizmor_error:{data.get('error')}"
    if not isinstance(data, list):
        return [], "parse_failed"
    findings: list[dict[str, Any]] = []
    for item in data:
        if not isinstance(item, dict):
            continue
        determinations = item.get("determinations") if isinstance(item.get("determinations"), dict) else {}
        rule_id = item.get("ident") or item.get("rule_id") or "zizmor"
        title = item.get("desc") or item.get("title") or rule_id
        file_path, line = _zizmor_location(item)
        findings.append(
            normalize_finding(
                {
                    "source_engine": "zizmor",
                    "source_label": source_label,
                    "severity": determinations.get("severity") or "UNKNOWN",
                    "confidence": str(determinations.get("confidence") or "scanner_rule").lower(),
                    "advisory_id": rule_id,
                    "rule_id": rule_id,
                    "title": title,
                    "url": item.get("url"),
                    "file": file_path,
                    "line": line,
                    "workflow_issue_type": classify_workflow_issue(rule_id, title),
                    "remediation_hint": title,
                },
                category="workflow",
                confidence=str(determinations.get("confidence") or "scanner_rule").lower(),
            )
        )
    return dedupe_findings(findings), None


def parse_actionlint_lines(text: str, source_label: str) -> tuple[list[dict[str, Any]], str | None]:
    findings: list[dict[str, Any]] = []
    if not text.strip():
        return findings, None
    for raw_line in text.splitlines():
        if not raw_line.strip():
            continue
        try:
            item = json.loads(raw_line)
        except json.JSONDecodeError:
            return [], "parse_failed"
        if not isinstance(item, dict):
            continue
        rule_id = item.get("kind") or item.get("Kind") or item.get("rule") or item.get("Rule") or "actionlint"
        message = item.get("message") or item.get("Message") or item.get("msg") or ""
        findings.append(
            normalize_finding(
                {
                    "source_engine": "actionlint",
                    "source_label": source_label,
                    "severity": workflow_severity(rule_id, message),
                    "advisory_id": rule_id,
                    "rule_id": rule_id,
                    "title": message or str(rule_id),
                    "file": item.get("filepath") or item.get("Filepath") or item.get("file") or item.get("File"),
                    "line": item.get("line") or item.get("Line"),
                    "column": item.get("column") or item.get("Column") or item.get("col") or item.get("Col"),
                    "workflow_issue_type": classify_workflow_issue(rule_id, message),
                    "remediation_hint": message,
                },
                category="workflow",
                confidence="scanner_rule",
            )
        )
    return dedupe_findings(findings), None
</file>

<file path="scripts/vulnscan/__init__.py">
"""Helpers for the vulnerability scanning skill CLI."""
</file>

<file path="scripts/vulnscan/ci.py">
"""GitHub Actions workflow scanner runners."""

from __future__ import annotations

import json
import shutil
from pathlib import Path
from typing import Any

from .common import command_record, run, setup_debt_item, stable_id
from .config import cfg_get
from .discovery import ProjectRoot
from .parsers import dedupe_findings, extract_json, parse_actionlint_lines, parse_zizmor


def scan_ci_projects(projects: list[ProjectRoot], config: dict[str, Any], artifact_dir: Path) -> tuple[dict[str, list[dict[str, Any]]], dict[str, Any]]:
    workflow_projects = [project for project in projects if "ci" in project.ecosystems]
    stats: dict[str, Any] = {
        "enabled": True,
        "projects": len(workflow_projects),
        "zizmor": {"enabled": bool(cfg_get(config, "engines.zizmor.enabled", True)), "missing": False, "ran": 0, "clean": 0, "findings": 0, "timeout": 0, "parse_failed": 0, "error": 0},
        "actionlint": {"enabled": bool(cfg_get(config, "engines.actionlint.enabled", True)), "missing": False, "ran": 0, "clean": 0, "findings": 0, "timeout": 0, "parse_failed": 0, "error": 0},
        "commands": [],
        "setup_debt": [],
    }
    findings_by_project: dict[str, list[dict[str, Any]]] = {}
    if not workflow_projects:
        return findings_by_project, stats

    for project in workflow_projects:
        project_findings: list[dict[str, Any]] = []
        zizmor_findings = _scan_zizmor(project, config, artifact_dir, stats)
        actionlint_findings = _scan_actionlint(project, config, artifact_dir, stats)
        project_findings.extend(zizmor_findings)
        project_findings.extend(actionlint_findings)
        findings_by_project[project.label] = dedupe_findings(project_findings)
    return findings_by_project, stats


def workflow_files(project: ProjectRoot) -> list[Path]:
    return sorted(
        path
        for path in project.path.iterdir()
        if path.is_file() and path.suffix.lower() in {".yml", ".yaml"}
    )


def _scan_zizmor(project: ProjectRoot, config: dict[str, Any], artifact_dir: Path, stats: dict[str, Any]) -> list[dict[str, Any]]:
    engine_stats = stats["zizmor"]
    if not engine_stats["enabled"]:
        return []
    command = str(cfg_get(config, "engines.zizmor.command", "zizmor") or "zizmor")
    binary = shutil.which(command)
    if not binary:
        engine_stats["missing"] = True
        stats["setup_debt"].append(
            setup_debt_item(
                scanner="zizmor",
                target=project.label,
                command=command,
                reason="missing binary",
                missing_binary=command,
                suggested_next_action="Install zizmor or disable engines.zizmor.enabled",
            )
        )
        return []

    artifact = artifact_dir / "ci" / f"{stable_id(project.label)}_zizmor.json"
    timeout = int(cfg_get(config, "engines.zizmor.timeout_seconds", 120))
    format_name = str(cfg_get(config, "engines.zizmor.format", "json-v1") or "json-v1")
    cmd = [binary, "--format", format_name]
    if bool(cfg_get(config, "engines.zizmor.offline", True)):
        cmd.append("--offline")
    cmd.append(str(project.path))
    result = run(cmd, cwd=project.git_root or project.path, timeout=timeout, outfile=artifact)
    engine_stats["ran"] += 1
    status = "completed"
    findings: list[dict[str, Any]] = []
    if result["code"] == 124:
        engine_stats["timeout"] += 1
        status = "timed_out"
        stats["setup_debt"].append(
            setup_debt_item(
                scanner="zizmor",
                target=project.label,
                command=cmd,
                reason="timeout",
                timeout=timeout,
                suggested_next_action="Retry with a higher engines.zizmor.timeout_seconds value or run zizmor directly",
            )
        )
    else:
        data = extract_json(artifact.read_text(encoding="utf-8", errors="replace") if artifact.exists() else "")
        parsed, err = parse_zizmor(data, project.label)
        if err:
            engine_stats["parse_failed"] += 1 if err == "parse_failed" else 0
            engine_stats["error"] += 0 if err == "parse_failed" else 1
            status = "parser_failed" if err == "parse_failed" else "scanner_failed"
            stats["setup_debt"].append(
                setup_debt_item(
                    scanner="zizmor",
                    target=project.label,
                    command=cmd,
                    reason="parser failure" if err == "parse_failed" else "scanner failed",
                    parser_failure=err if err == "parse_failed" else None,
                    suggested_next_action="Inspect the zizmor artifact and update parse_zizmor if the output format changed",
                )
            )
        elif parsed:
            findings = parsed
            engine_stats["findings"] += len(parsed)
        else:
            engine_stats["clean"] += 1
    stats["commands"].append(command_record(scanner="zizmor", target=project.label, command=cmd, cwd=project.git_root or project.path, artifact=artifact, status=status, exit_code=result["code"]))
    return findings


def _scan_actionlint(project: ProjectRoot, config: dict[str, Any], artifact_dir: Path, stats: dict[str, Any]) -> list[dict[str, Any]]:
    engine_stats = stats["actionlint"]
    if not engine_stats["enabled"]:
        return []
    command = str(cfg_get(config, "engines.actionlint.command", "actionlint") or "actionlint")
    binary = shutil.which(command)
    if not binary:
        engine_stats["missing"] = True
        stats["setup_debt"].append(
            setup_debt_item(
                scanner="actionlint",
                target=project.label,
                command=command,
                reason="missing binary",
                missing_binary=command,
                suggested_next_action="Install actionlint or disable engines.actionlint.enabled",
            )
        )
        return []

    files = workflow_files(project)
    if not files:
        return []
    artifact = artifact_dir / "ci" / f"{stable_id(project.label)}_actionlint.jsonl"
    timeout = int(cfg_get(config, "engines.actionlint.timeout_seconds", 120))
    format_template = str(cfg_get(config, "engines.actionlint.format", "{{json .}}") or "{{json .}}")
    cmd = [binary, "-format", format_template, *[str(path) for path in files]]
    result = run(cmd, cwd=project.git_root or project.path, timeout=timeout, outfile=artifact)
    engine_stats["ran"] += 1
    status = "completed"
    findings: list[dict[str, Any]] = []
    if result["code"] == 124:
        engine_stats["timeout"] += 1
        status = "timed_out"
        stats["setup_debt"].append(
            setup_debt_item(
                scanner="actionlint",
                target=project.label,
                command=cmd,
                reason="timeout",
                timeout=timeout,
                suggested_next_action="Retry with a higher engines.actionlint.timeout_seconds value or run actionlint directly",
            )
        )
    else:
        text = artifact.read_text(encoding="utf-8", errors="replace") if artifact.exists() else ""
        parsed, err = parse_actionlint_lines(text, project.label)
        if err:
            engine_stats["parse_failed"] += 1 if err == "parse_failed" else 0
            engine_stats["error"] += 0 if err == "parse_failed" else 1
            status = "parser_failed" if err == "parse_failed" else "scanner_failed"
            stats["setup_debt"].append(
                setup_debt_item(
                    scanner="actionlint",
                    target=project.label,
                    command=cmd,
                    reason="parser failure" if err == "parse_failed" else "scanner failed",
                    parser_failure=err if err == "parse_failed" else None,
                    suggested_next_action="Inspect the actionlint artifact and update parse_actionlint_lines if the output format changed",
                )
            )
        elif parsed:
            findings = parsed
            engine_stats["findings"] += len(parsed)
            artifact.write_text("\n".join(json.dumps(item, sort_keys=True) for item in parsed) + "\n", encoding="utf-8")
        else:
            engine_stats["clean"] += 1
    stats["commands"].append(command_record(scanner="actionlint", target=project.label, command=cmd, cwd=project.git_root or project.path, artifact=artifact, status=status, exit_code=result["code"]))
    return findings
</file>

<file path="scripts/vulnscan/common.py">
"""Shared utilities for scanner modules."""

from __future__ import annotations

import hashlib
import subprocess
from datetime import datetime, timezone
from pathlib import Path
from typing import Any


def now_iso() -> str:
    return datetime.now(timezone.utc).replace(microsecond=0).isoformat().replace("+00:00", "Z")


def stable_id(value: str) -> str:
    return hashlib.sha256(value.encode("utf-8")).hexdigest()[:16]


def command_record(
    *,
    scanner: str,
    target: str,
    command: list[str],
    cwd: Path | None = None,
    artifact: Path | None = None,
    status: str = "planned",
    exit_code: int | None = None,
) -> dict[str, Any]:
    return {
        "scanner": scanner,
        "target": target,
        "command": command,
        "cwd": str(cwd) if cwd else None,
        "artifact": str(artifact) if artifact else None,
        "status": status,
        "exit_code": exit_code,
    }


def setup_debt_item(
    *,
    scanner: str,
    target: str,
    command: str | list[str] | None,
    reason: str,
    missing_binary: str | None = None,
    timeout: int | None = None,
    parser_failure: str | None = None,
    unsupported_target: str | None = None,
    suggested_next_action: str | None = None,
) -> dict[str, Any]:
    return {
        "scanner": scanner,
        "target": target,
        "command": command,
        "reason": reason,
        "missing_binary": missing_binary,
        "timeout": timeout,
        "parser_failure": parser_failure,
        "unsupported_target": unsupported_target,
        "suggested_next_action": suggested_next_action,
    }


def run(cmd: list[str], cwd: Path | None = None, timeout: int = 60, outfile: Path | None = None) -> dict[str, Any]:
    try:
        if outfile:
            outfile.parent.mkdir(parents=True, exist_ok=True)
            with outfile.open("w", encoding="utf-8", errors="replace") as f:
                proc = subprocess.run(cmd, cwd=str(cwd) if cwd else None, stdout=f, stderr=subprocess.PIPE, text=True, timeout=timeout)
            return {"code": proc.returncode, "stdout": "", "stderr": proc.stderr or ""}
        proc = subprocess.run(cmd, cwd=str(cwd) if cwd else None, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=timeout)
        return {"code": proc.returncode, "stdout": proc.stdout or "", "stderr": proc.stderr or ""}
    except subprocess.TimeoutExpired as exc:
        stdout = exc.stdout or ""
        stderr = exc.stderr or ""
        if isinstance(stdout, bytes):
            stdout = stdout.decode("utf-8", "replace")
        if isinstance(stderr, bytes):
            stderr = stderr.decode("utf-8", "replace")
        return {"code": 124, "stdout": stdout, "stderr": stderr + "\nTIMEOUT"}
</file>

<file path="scripts/vulnscan/hygiene.py">
"""Repository hygiene scanner runners."""

from __future__ import annotations

import shutil
from pathlib import Path
from typing import Any

from .common import command_record, run, setup_debt_item, stable_id
from .config import cfg_get
from .discovery import relpath
from .parsers import dedupe_findings, extract_json, parse_scorecard


def scan_scorecard_git_roots(
    git_roots: list[Path],
    workspace_root: Path,
    config: dict[str, Any],
    artifact_dir: Path,
    *,
    explicit_request: bool,
) -> tuple[dict[str, list[dict[str, Any]]], dict[str, Any]]:
    stats: dict[str, Any] = {
        "enabled": bool(cfg_get(config, "engines.scorecard.enabled", False)) or explicit_request,
        "explicit_request": explicit_request,
        "missing": False,
        "ran": 0,
        "clean": 0,
        "findings": 0,
        "timeout": 0,
        "parse_failed": 0,
        "error": 0,
        "commands": [],
        "setup_debt": [],
    }
    findings_by_git_root: dict[str, list[dict[str, Any]]] = {}
    if not stats["enabled"]:
        return findings_by_git_root, stats

    command = str(cfg_get(config, "engines.scorecard.command", "scorecard") or "scorecard")
    binary = shutil.which(command)
    if not binary:
        stats["missing"] = True
        stats["setup_debt"].append(
            setup_debt_item(
                scanner="scorecard",
                target=str(workspace_root),
                command=command,
                reason="missing binary",
                missing_binary=command,
                suggested_next_action="Install scorecard, enable it only for repos where network/GitHub access is acceptable, or disable engines.scorecard.enabled",
            )
        )
        return findings_by_git_root, stats

    timeout = int(cfg_get(config, "engines.scorecard.timeout_seconds", 300))
    format_name = str(cfg_get(config, "engines.scorecard.format", "json") or "json")
    minimum_score = float(cfg_get(config, "engines.scorecard.minimum_check_score", 10) or 10)
    show_details = bool(cfg_get(config, "engines.scorecard.show_details", True))
    use_local = bool(cfg_get(config, "engines.scorecard.use_local", True))
    for git_root in git_roots:
        label = relpath(git_root, workspace_root)
        artifact = artifact_dir / "hygiene" / f"{stable_id(label)}_scorecard.json"
        cmd = [binary, f"--format={format_name}"]
        if show_details:
            cmd.append("--show-details")
        if use_local:
            cmd.append(f"--local={git_root}")
        else:
            repo = str(cfg_get(config, "engines.scorecard.repo", "") or "")
            if not repo:
                stats["setup_debt"].append(
                    setup_debt_item(
                        scanner="scorecard",
                        target=label,
                        command=cmd,
                        reason="unsupported target",
                        unsupported_target="engines.scorecard.use_local=false requires engines.scorecard.repo",
                        suggested_next_action="Set engines.scorecard.repo or use local Scorecard scans",
                    )
                )
                continue
            cmd.append(f"--repo={repo}")
        result = run(cmd, timeout=timeout, outfile=artifact)
        stats["ran"] += 1
        status = "completed"
        if result["code"] == 124:
            stats["timeout"] += 1
            status = "timed_out"
            stats["setup_debt"].append(
                setup_debt_item(
                    scanner="scorecard",
                    target=label,
                    command=cmd,
                    reason="timeout",
                    timeout=timeout,
                    suggested_next_action="Retry with a higher engines.scorecard.timeout_seconds value or run scorecard directly",
                )
            )
        else:
            data = extract_json(artifact.read_text(encoding="utf-8", errors="replace") if artifact.exists() else "")
            findings, err = parse_scorecard(data, label, minimum_score=minimum_score)
            if err:
                stats["parse_failed"] += 1 if err == "parse_failed" else 0
                stats["error"] += 0 if err == "parse_failed" else 1
                status = "parser_failed" if err == "parse_failed" else "scanner_failed"
                stats["setup_debt"].append(
                    setup_debt_item(
                        scanner="scorecard",
                        target=label,
                        command=cmd,
                        reason="parser failure" if err == "parse_failed" else "scanner failed",
                        parser_failure=err if err == "parse_failed" else None,
                        suggested_next_action="Inspect the Scorecard artifact and update parse_scorecard if the output format changed",
                    )
                )
            elif findings:
                stats["findings"] += len(findings)
                findings_by_git_root[label] = dedupe_findings(findings)
            else:
                stats["clean"] += 1
        stats["commands"].append(command_record(scanner="scorecard", target=label, command=cmd, artifact=artifact, status=status, exit_code=result["code"]))
    return findings_by_git_root, stats
</file>

<file path="scripts/vulnscan/orchestration.py">
"""Registry-backed workspace engine orchestration."""

from __future__ import annotations

from pathlib import Path
from typing import Any, Callable

from .ci import scan_ci_projects
from .discovery import ProjectRoot
from .engines import scan_osv_git_roots, scan_trivy_filesystems
from .hygiene import scan_scorecard_git_roots
from .inventory import engine_registry
from .sast import scan_semgrep_git_roots
from .sbom import scan_sbom_git_roots
from .supply_chain import scan_guarddog_projects

WorkspaceRunner = Callable[[dict[str, Any]], tuple[dict[str, list[dict[str, Any]]], dict[str, Any]]]


def workspace_engine_names(scan_mode: str) -> list[str]:
    if scan_mode == "dependencies":
        return ["osv-scanner"]
    if scan_mode == "remediation-prep":
        return ["osv-scanner", "zizmor", "actionlint"]
    if scan_mode == "full":
        return ["osv-scanner", "trivy", "zizmor", "actionlint", "semgrep"]
    if scan_mode == "ci":
        return ["zizmor", "actionlint"]
    if scan_mode == "sast":
        return ["semgrep"]
    if scan_mode == "sbom":
        return ["syft", "grype"]
    if scan_mode == "hygiene":
        return ["scorecard"]
    if scan_mode == "supply-chain":
        return ["guarddog"]
    return []


def selected_workspace_engines(scan_mode: str, config: dict[str, Any]) -> list[str]:
    registry = engine_registry()
    selected: list[str] = []
    for name in workspace_engine_names(scan_mode):
        adapter = registry[name]
        if not adapter.enabled(config):
            continue
        if adapter.category == "ci":
            if "ci" not in selected:
                selected.append("ci")
            continue
        if adapter.category == "sbom":
            if "sbom" not in selected:
                selected.append("sbom")
            continue
        selected.append(name)
    return selected


def empty_workspace_outputs() -> dict[str, Any]:
    return {
        "osv-scanner": ({}, {"enabled": False, "missing": False, "ran": 0, "vulnerable": 0, "clean": 0, "timeout": 0, "empty": 0, "parse_failed": 0}),
        "trivy": ({}, {"enabled": False, "ran": 0, "clean": 0, "findings": 0, "timeout": 0, "parse_failed": 0}),
        "ci": ({}, {"enabled": False, "projects": 0}),
        "semgrep": ({}, {"enabled": False, "ran": 0, "clean": 0, "findings": 0, "timeout": 0, "parse_failed": 0}),
        "sbom": ({}, {"enabled": False}),
        "scorecard": ({}, {"enabled": False, "explicit_request": False}),
        "guarddog": ({}, {"enabled": False}),
    }


def run_workspace_engines(
    *,
    scan_mode: str,
    projects: list[ProjectRoot],
    git_roots: list[Path],
    workspace_root: Path,
    config: dict[str, Any],
    artifact_dir: Path,
) -> dict[str, Any]:
    outputs = empty_workspace_outputs()
    context = {
        "projects": projects,
        "git_roots": git_roots,
        "workspace_root": workspace_root,
        "config": config,
        "artifact_dir": artifact_dir,
    }
    runners: dict[str, WorkspaceRunner] = {
        "osv-scanner": run_osv,
        "trivy": run_trivy,
        "ci": run_ci,
        "semgrep": run_semgrep,
        "sbom": run_sbom,
        "scorecard": run_scorecard,
        "guarddog": run_guarddog,
    }
    for name in selected_workspace_engines(scan_mode, config):
        outputs[name] = runners[name](context)
    return outputs


def run_osv(context: dict[str, Any]) -> tuple[dict[str, list[dict[str, Any]]], dict[str, Any]]:
    return scan_osv_git_roots(context["git_roots"], context["workspace_root"], context["config"], context["artifact_dir"])


def run_trivy(context: dict[str, Any]) -> tuple[dict[str, list[dict[str, Any]]], dict[str, Any]]:
    return scan_trivy_filesystems(context["git_roots"], context["workspace_root"], context["config"], context["artifact_dir"])


def run_ci(context: dict[str, Any]) -> tuple[dict[str, list[dict[str, Any]]], dict[str, Any]]:
    return scan_ci_projects(context["projects"], context["config"], context["artifact_dir"])


def run_semgrep(context: dict[str, Any]) -> tuple[dict[str, list[dict[str, Any]]], dict[str, Any]]:
    return scan_semgrep_git_roots(context["git_roots"], context["workspace_root"], context["config"], context["artifact_dir"])


def run_sbom(context: dict[str, Any]) -> tuple[dict[str, list[dict[str, Any]]], dict[str, Any]]:
    return scan_sbom_git_roots(context["git_roots"], context["workspace_root"], context["config"], context["artifact_dir"], vulnerability_scan_requested=True)


def run_scorecard(context: dict[str, Any]) -> tuple[dict[str, list[dict[str, Any]]], dict[str, Any]]:
    return scan_scorecard_git_roots(context["git_roots"], context["workspace_root"], context["config"], context["artifact_dir"], explicit_request=True)


def run_guarddog(context: dict[str, Any]) -> tuple[dict[str, list[dict[str, Any]]], dict[str, Any]]:
    return scan_guarddog_projects(context["projects"], context["config"], context["artifact_dir"])
</file>

<file path="scripts/vulnscan/sast.py">
"""Source-code security scanner runners."""

from __future__ import annotations

import shutil
from pathlib import Path
from typing import Any

from .common import command_record, run, setup_debt_item, stable_id
from .config import cfg_get, cfg_list
from .discovery import relpath
from .parsers import dedupe_findings, extract_json, parse_semgrep


def scan_semgrep_git_roots(git_roots: list[Path], workspace_root: Path, config: dict[str, Any], artifact_dir: Path) -> tuple[dict[str, list[dict[str, Any]]], dict[str, Any]]:
    stats: dict[str, Any] = {
        "enabled": bool(cfg_get(config, "engines.semgrep.enabled", True)),
        "missing": False,
        "ran": 0,
        "clean": 0,
        "findings": 0,
        "timeout": 0,
        "parse_failed": 0,
        "error": 0,
        "commands": [],
        "setup_debt": [],
    }
    findings_by_git_root: dict[str, list[dict[str, Any]]] = {}
    if not stats["enabled"]:
        return findings_by_git_root, stats

    command = str(cfg_get(config, "engines.semgrep.command", "semgrep") or "semgrep")
    binary = shutil.which(command)
    if not binary:
        stats["missing"] = True
        stats["setup_debt"].append(
            setup_debt_item(
                scanner="semgrep",
                target=str(workspace_root),
                command=command,
                reason="missing binary",
                missing_binary=command,
                suggested_next_action="Install semgrep or disable engines.semgrep.enabled",
            )
        )
        return findings_by_git_root, stats

    timeout = int(cfg_get(config, "engines.semgrep.timeout_seconds", 300))
    rule_paths = [str(value) for value in cfg_list(config, "engines.semgrep.rule_paths")]
    config_auto = str(cfg_get(config, "engines.semgrep.config_auto", "auto") or "auto")
    excludes = [str(value) for value in cfg_list(config, "engines.semgrep.exclude")]
    for git_root in git_roots:
        label = relpath(git_root, workspace_root)
        artifact = artifact_dir / "sast" / f"{stable_id(label)}_semgrep.json"
        cmd = [binary, "--json", "--output", str(artifact)]
        if rule_paths:
            for rule_path in rule_paths:
                cmd.extend(["--config", rule_path])
        else:
            cmd.extend(["--config", config_auto])
        for exclude in excludes:
            cmd.extend(["--exclude", exclude])
        cmd.append(str(git_root))
        result = run(cmd, timeout=timeout)
        stats["ran"] += 1
        status = "completed"
        if result["code"] == 124:
            stats["timeout"] += 1
            status = "timed_out"
            stats["setup_debt"].append(
                setup_debt_item(
                    scanner="semgrep",
                    target=label,
                    command=cmd,
                    reason="timeout",
                    timeout=timeout,
                    suggested_next_action="Retry with a higher engines.semgrep.timeout_seconds value or run semgrep directly",
                )
            )
            findings_by_git_root[label] = []
            stats["commands"].append(command_record(scanner="semgrep", target=label, command=cmd, artifact=artifact, status=status, exit_code=result["code"]))
            continue

        data = extract_json(artifact.read_text(encoding="utf-8", errors="replace") if artifact.exists() else "")
        findings, err = parse_semgrep(data, label)
        if err:
            stats["parse_failed"] += 1 if err == "parse_failed" else 0
            stats["error"] += 0 if err == "parse_failed" else 1
            status = "parser_failed" if err == "parse_failed" else "scanner_failed"
            stats["setup_debt"].append(
                setup_debt_item(
                    scanner="semgrep",
                    target=label,
                    command=cmd,
                    reason="parser failure" if err == "parse_failed" else "scanner failed",
                    parser_failure=err if err == "parse_failed" else None,
                    suggested_next_action="Inspect the Semgrep artifact and update parse_semgrep if the output format changed",
                )
            )
        elif findings:
            stats["findings"] += len(findings)
        else:
            stats["clean"] += 1
        findings_by_git_root[label] = dedupe_findings(findings)
        stats["commands"].append(command_record(scanner="semgrep", target=label, command=cmd, artifact=artifact, status=status, exit_code=result["code"]))
    return findings_by_git_root, stats
</file>

<file path="scripts/vulnscan/sbom.py">
"""SBOM generation and SBOM vulnerability scanner runners."""

from __future__ import annotations

import shutil
from pathlib import Path
from typing import Any

from .common import command_record, run, setup_debt_item, stable_id
from .config import cfg_get
from .discovery import relpath
from .parsers import dedupe_findings, extract_json, parse_grype, parse_syft_metadata


def scan_sbom_git_roots(
    git_roots: list[Path],
    workspace_root: Path,
    config: dict[str, Any],
    artifact_dir: Path,
    *,
    vulnerability_scan_requested: bool,
) -> tuple[dict[str, list[dict[str, Any]]], dict[str, Any]]:
    stats: dict[str, Any] = {
        "enabled": True,
        "syft": {"enabled": bool(cfg_get(config, "engines.syft.enabled", True)), "missing": False, "ran": 0, "generated": 0, "timeout": 0, "parse_failed": 0, "error": 0, "sboms": []},
        "grype": {"enabled": bool(cfg_get(config, "engines.grype.enabled", True)), "missing": False, "ran": 0, "clean": 0, "findings": 0, "timeout": 0, "parse_failed": 0, "error": 0, "skipped": 0},
        "commands": [],
        "setup_debt": [],
    }
    findings_by_git_root: dict[str, list[dict[str, Any]]] = {}
    sboms = _run_syft(git_roots, workspace_root, config, artifact_dir, stats)
    _run_grype(sboms, config, artifact_dir, stats, findings_by_git_root, vulnerability_scan_requested=vulnerability_scan_requested)
    return findings_by_git_root, stats


def _run_syft(git_roots: list[Path], workspace_root: Path, config: dict[str, Any], artifact_dir: Path, stats: dict[str, Any]) -> list[tuple[str, Path]]:
    engine_stats = stats["syft"]
    sboms: list[tuple[str, Path]] = []
    if not engine_stats["enabled"]:
        return sboms
    command = str(cfg_get(config, "engines.syft.command", "syft") or "syft")
    binary = shutil.which(command)
    if not binary:
        engine_stats["missing"] = True
        stats["setup_debt"].append(
            setup_debt_item(
                scanner="syft",
                target=str(workspace_root),
                command=command,
                reason="missing binary",
                missing_binary=command,
                suggested_next_action="Install syft or disable engines.syft.enabled",
            )
        )
        return sboms

    output_format = str(cfg_get(config, "engines.syft.output_format", "cyclonedx-json") or "cyclonedx-json")
    timeout = int(cfg_get(config, "engines.syft.timeout_seconds", 300))
    for git_root in git_roots:
        label = relpath(git_root, workspace_root)
        artifact = artifact_dir / "sbom" / f"{stable_id(label)}.cdx.json"
        cmd = [binary, str(git_root), "-o", output_format]
        result = run(cmd, timeout=timeout, outfile=artifact)
        engine_stats["ran"] += 1
        status = "completed"
        if result["code"] == 124:
            engine_stats["timeout"] += 1
            status = "timed_out"
            stats["setup_debt"].append(
                setup_debt_item(
                    scanner="syft",
                    target=label,
                    command=cmd,
                    reason="timeout",
                    timeout=timeout,
                    suggested_next_action="Retry with a higher engines.syft.timeout_seconds value or run syft directly",
                )
            )
        else:
            data = extract_json(artifact.read_text(encoding="utf-8", errors="replace") if artifact.exists() else "")
            metadata, err = parse_syft_metadata(data)
            if err:
                engine_stats["parse_failed"] += 1
                status = "parser_failed"
                stats["setup_debt"].append(
                    setup_debt_item(
                        scanner="syft",
                        target=label,
                        command=cmd,
                        reason="parser failure",
                        parser_failure=err,
                        suggested_next_action="Inspect the Syft SBOM artifact and update parse_syft_metadata if the output format changed",
                    )
                )
            else:
                engine_stats["generated"] += 1
                engine_stats["sboms"].append({"target": label, "artifact": str(artifact), **metadata})
                sboms.append((label, artifact))
        stats["commands"].append(command_record(scanner="syft", target=label, command=cmd, artifact=artifact, status=status, exit_code=result["code"]))
    return sboms


def _run_grype(
    sboms: list[tuple[str, Path]],
    config: dict[str, Any],
    artifact_dir: Path,
    stats: dict[str, Any],
    findings_by_git_root: dict[str, list[dict[str, Any]]],
    *,
    vulnerability_scan_requested: bool,
) -> None:
    engine_stats = stats["grype"]
    if not engine_stats["enabled"]:
        return
    if bool(cfg_get(config, "engines.grype.skip_when_trivy_covers_target", True)) and not vulnerability_scan_requested:
        engine_stats["skipped"] += len(sboms)
        return

    command = str(cfg_get(config, "engines.grype.command", "grype") or "grype")
    binary = shutil.which(command)
    if not binary:
        engine_stats["missing"] = True
        stats["setup_debt"].append(
            setup_debt_item(
                scanner="grype",
                target=",".join(label for label, _ in sboms) or "__sbom__",
                command=command,
                reason="missing binary",
                missing_binary=command,
                suggested_next_action="Install grype or disable engines.grype.enabled",
            )
        )
        return

    timeout = int(cfg_get(config, "engines.grype.timeout_seconds", 300))
    for label, sbom_path in sboms:
        artifact = artifact_dir / "sbom" / f"{stable_id(label)}_grype.json"
        cmd = [binary, f"sbom:{sbom_path}", "-o", "json"]
        result = run(cmd, timeout=timeout, outfile=artifact)
        engine_stats["ran"] += 1
        status = "completed"
        if result["code"] == 124:
            engine_stats["timeout"] += 1
            status = "timed_out"
            stats["setup_debt"].append(
                setup_debt_item(
                    scanner="grype",
                    target=label,
                    command=cmd,
                    reason="timeout",
                    timeout=timeout,
                    suggested_next_action="Retry with a higher engines.grype.timeout_seconds value or run grype directly",
                )
            )
        else:
            data = extract_json(artifact.read_text(encoding="utf-8", errors="replace") if artifact.exists() else "")
            findings, err = parse_grype(data, label)
            if err:
                engine_stats["parse_failed"] += 1 if err == "parse_failed" else 0
                engine_stats["error"] += 0 if err == "parse_failed" else 1
                status = "parser_failed" if err == "parse_failed" else "scanner_failed"
                stats["setup_debt"].append(
                    setup_debt_item(
                        scanner="grype",
                        target=label,
                        command=cmd,
                        reason="parser failure" if err == "parse_failed" else "scanner failed",
                        parser_failure=err if err == "parse_failed" else None,
                        suggested_next_action="Inspect the Grype artifact and update parse_grype if the output format changed",
                    )
                )
            elif findings:
                engine_stats["findings"] += len(findings)
                findings_by_git_root[label] = dedupe_findings(findings)
            else:
                engine_stats["clean"] += 1
        stats["commands"].append(command_record(scanner="grype", target=label, command=cmd, artifact=artifact, status=status, exit_code=result["code"]))
</file>

<file path="scripts/vuln-scan.py">
#!/usr/bin/env python3
"""General entrypoint for the local vulnerability scanner."""

from __future__ import annotations

from vulnscan.cli import main


if __name__ == "__main__":
    raise SystemExit(main())
</file>

<file path="tests/fixtures/docker/Dockerfile">
FROM scratch
</file>

<file path="tests/fixtures/github-actions/.github/workflows/ci.yml">
name: ci
on: push
jobs: {}
</file>

<file path="tests/fixtures/go/go.mod">
module example.test/fixture

go 1.22
</file>

<file path="tests/fixtures/javascript-no-lock/package.json">
{"name":"fixture-javascript-no-lock","dependencies":{"left-pad":"1.3.0"}}
</file>

<file path="tests/fixtures/jvm/pom.xml">
<project><modelVersion>4.0.0</modelVersion><groupId>test</groupId><artifactId>fixture</artifactId><version>0.1.0</version></project>
</file>

<file path="tests/fixtures/monorepo/apps/web/package-lock.json">
{"lockfileVersion":3,"packages":{}}
</file>

<file path="tests/fixtures/monorepo/apps/web/package.json">
{"name":"fixture-web","dependencies":{"left-pad":"1.3.0"}}
</file>

<file path="tests/fixtures/monorepo/packages/api/requirements.txt">
flask==3.0.0
</file>

<file path="tests/fixtures/no-manifest/README.md">
# No Manifest Fixture

This fixture should not be discovered as a scanner target.
</file>

<file path="tests/fixtures/npm/package-lock.json">
{
  "name": "fixture-npm",
  "lockfileVersion": 3,
  "packages": {
    "": {
      "dependencies": {
        "left-pad": "1.3.0"
      }
    }
  }
}
</file>

<file path="tests/fixtures/npm/package.json">
{"name":"fixture-npm","dependencies":{"left-pad":"1.3.0"}}
</file>

<file path="tests/fixtures/pnpm/package.json">
{"name":"fixture-pnpm","dependencies":{"left-pad":"1.3.0"}}
</file>

<file path="tests/fixtures/pnpm/pnpm-lock.yaml">
lockfileVersion: '9.0'
</file>

<file path="tests/fixtures/python/requirements.txt">
requests==2.31.0
</file>

<file path="tests/fixtures/rust/Cargo.lock">
# fixture lockfile
</file>

<file path="tests/fixtures/rust/Cargo.toml">
[package]
name = "fixture-rust"
version = "0.1.0"
edition = "2021"
</file>

<file path="tests/fixtures/terraform/main.tf">
resource "null_resource" "fixture" {}
</file>

<file path="tests/fixtures/vscode-extension/package.json">
{"name":"fixture-extension","engines":{"vscode":"^1.90.0"},"contributes":{}}
</file>

<file path="tests/fixtures/yarn/package.json">
{"name":"fixture-yarn","dependencies":{"left-pad":"1.3.0"}}
</file>

<file path="tests/fixtures/yarn/yarn.lock">
# fixture lockfile
</file>

<file path="tests/test_engine_external.py">
from __future__ import annotations

import contextlib
import io
import json
import sys
import tempfile
import unittest
import os
import subprocess
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
SCRIPTS = ROOT / "scripts"
sys.path.insert(0, str(SCRIPTS))

from vulnscan import ci, cli, config, discovery, engines, hygiene, inventory, orchestration, parsers, remediation, reporting, sast, sbom, secrets, supply_chain, tracker as tracker_mod  # noqa: E402


class EngineExternalExecutionTests(unittest.TestCase):
    def test_fake_gitleaks_binary_scans_current_and_history_with_sanitized_artifacts(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_gitleaks = bin_dir / "gitleaks"
            fake_gitleaks.write_text(
                "#!/usr/bin/env bash\n"
                "mode=\"$1\"\n"
                "out=''\n"
                "prev=''\n"
                "for arg in \"$@\"; do\n"
                "  if [[ \"$prev\" == '--report-path' ]]; then out=\"$arg\"; fi\n"
                "  prev=\"$arg\"\n"
                "done\n"
                "mkdir -p \"$(dirname \"$out\")\"\n"
                "if [[ \"$mode\" == 'git' ]]; then commit=',\"Commit\":\"abc\"'; line='2'; else commit=''; line='1'; fi\n"
                "printf '[{\"RuleID\":\"generic-api-key\",\"Description\":\"Generic API Key\",\"File\":\".env\",\"StartLine\":%s,\"Secret\":\"sk-secret\",\"Match\":\"API_KEY=sk-secret\"%s}]' \"$line\" \"$commit\" > \"$out\"\n",
                encoding="utf-8",
            )
            fake_gitleaks.chmod(0o755)
            repo = root / "repo"
            repo.mkdir()
            subprocess.run(["git", "init"], cwd=repo, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
            (repo / ".env").write_text("API_KEY=sk-secret\n", encoding="utf-8")
            subprocess.run(["git", "add", ".env"], cwd=repo, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
            old_path = os.environ.get("PATH", "")
            os.environ["PATH"] = f"{bin_dir}{os.pathsep}{old_path}"
            try:
                findings, stats = secrets.scan_gitleaks_git_roots(
                    [repo],
                    root,
                    {"engines": {"gitleaks": {"enabled": True, "command": "gitleaks", "timeout_seconds": 10, "scan_current": True, "scan_history": True}}},
                    root / "artifacts",
                )
                artifact_texts = [Path(command["artifact"]).read_text(encoding="utf-8") for command in stats["commands"]]
            finally:
                os.environ["PATH"] = old_path

        self.assertEqual(stats["current_ran"], 1)
        self.assertEqual(stats["history_ran"], 1)
        self.assertEqual(len(findings), 2)
        self.assertTrue(all(finding["source_engine"] == "gitleaks" for finding in findings))
        self.assertTrue(all(finding["git_tracked"] for finding in findings))
        for artifact_text in artifact_texts:
            self.assertNotIn("sk-secret", artifact_text)

    def test_fake_trufflehog_binary_scans_verified_credentials_with_sanitized_artifact(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_trufflehog = bin_dir / "trufflehog"
            fake_trufflehog.write_text(
                "#!/usr/bin/env bash\n"
                "cat <<'JSONL'\n"
                '{"DetectorName":"GitHub","Verified":false,"Raw":"ghp_unverified","SourceMetadata":{"Data":{"Git":{"file":"a.env","line":1}}}}\n'
                '{"DetectorName":"GitHub","Verified":true,"Raw":"ghp_verified","RawV2":"ghp_verified","SourceMetadata":{"Data":{"Git":{"file":"b.env","line":2,"commit":"abc"}}}}\n'
                "JSONL\n",
                encoding="utf-8",
            )
            fake_trufflehog.chmod(0o755)
            repo = root / "repo"
            repo.mkdir()
            old_path = os.environ.get("PATH", "")
            os.environ["PATH"] = f"{bin_dir}{os.pathsep}{old_path}"
            try:
                findings, stats = secrets.scan_trufflehog_git_roots(
                    [repo],
                    root,
                    {"engines": {"trufflehog": {"enabled": True, "command": "trufflehog", "timeout_seconds": 10, "only_verified": True}}},
                    root / "artifacts",
                )
                artifact_text = Path(stats["commands"][0]["artifact"]).read_text(encoding="utf-8")
            finally:
                os.environ["PATH"] = old_path

        self.assertEqual(stats["ran"], 1)
        self.assertEqual(len(findings), 1)
        self.assertEqual(findings[0]["source_engine"], "trufflehog")
        self.assertEqual(findings[0]["verification_state"], "verified")
        self.assertNotIn("ghp_verified", artifact_text)
        self.assertNotIn("ghp_unverified", artifact_text)

    def test_fake_ci_binaries_scan_workflow_project(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_zizmor = bin_dir / "zizmor"
            fake_zizmor.write_text(
                "#!/usr/bin/env bash\n"
                "cat <<'JSON'\n"
                '[{\"ident\":\"template-injection\",\"desc\":\"untrusted context\",\"determinations\":{\"confidence\":\"High\",\"severity\":\"High\"},\"locations\":[{\"symbolic\":{\"key\":{\"Local\":{\"given_path\":\".github/workflows/ci.yml\"}}},\"concrete\":{\"location\":{\"start_point\":{\"row\":4,\"column\":8}}}}]}]\n'
                "JSON\n",
                encoding="utf-8",
            )
            fake_zizmor.chmod(0o755)
            fake_actionlint = bin_dir / "actionlint"
            fake_actionlint.write_text(
                "#!/usr/bin/env bash\n"
                "cat <<'JSONL'\n"
                '{"filepath":".github/workflows/ci.yml","line":5,"column":9,"message":"github.event.head_commit.message is potentially untrusted","kind":"expression"}\n'
                "JSONL\n",
                encoding="utf-8",
            )
            fake_actionlint.chmod(0o755)
            repo = root / "repo"
            workflow_dir = repo / ".github" / "workflows"
            workflow_dir.mkdir(parents=True)
            (workflow_dir / "ci.yml").write_text("name: ci\non: push\njobs: {}\n", encoding="utf-8")
            project = discovery.ProjectRoot(path=workflow_dir, label=".github/workflows", git_root=repo, files={"ci.yml"}, target_types={"ci"})
            old_path = os.environ.get("PATH", "")
            os.environ["PATH"] = f"{bin_dir}{os.pathsep}{old_path}"
            try:
                findings_by_project, stats = ci.scan_ci_projects(
                    [project],
                    {
                        "engines": {
                            "zizmor": {"enabled": True, "command": "zizmor", "timeout_seconds": 10, "format": "json-v1", "offline": True},
                            "actionlint": {"enabled": True, "command": "actionlint", "timeout_seconds": 10, "format": "{{json .}}"},
                        }
                    },
                    root / "artifacts",
                )
                artifact_texts = [Path(command["artifact"]).read_text(encoding="utf-8") for command in stats["commands"]]
            finally:
                os.environ["PATH"] = old_path

        findings = findings_by_project[".github/workflows"]
        self.assertEqual(stats["projects"], 1)
        self.assertEqual(stats["zizmor"]["ran"], 1)
        self.assertEqual(stats["actionlint"]["ran"], 1)
        self.assertEqual({finding["source_engine"] for finding in findings}, {"zizmor", "actionlint"})
        self.assertTrue(all(finding["category"] == "workflow" for finding in findings))
        self.assertTrue(any("github.event.head_commit" in text for text in artifact_texts))

    def test_fake_semgrep_binary_scans_git_root(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_semgrep = bin_dir / "semgrep"
            fake_semgrep.write_text(
                "#!/usr/bin/env bash\n"
                "out=''\n"
                "prev=''\n"
                "for arg in \"$@\"; do\n"
                "  if [[ \"$prev\" == '--output' ]]; then out=\"$arg\"; fi\n"
                "  prev=\"$arg\"\n"
                "done\n"
                "mkdir -p \"$(dirname \"$out\")\"\n"
                "cat > \"$out\" <<'JSON'\n"
                '{"results":[{"check_id":"python.lang.security.audit.subprocess-shell-true","path":"app.py","start":{"line":4,"col":1},"extra":{"message":"subprocess call with shell=True","severity":"ERROR","fix":"avoid shell=True"}}]}\n'
                "JSON\n",
                encoding="utf-8",
            )
            fake_semgrep.chmod(0o755)
            repo = root / "repo"
            repo.mkdir()
            (repo / "app.py").write_text("print('x')\n", encoding="utf-8")
            old_path = os.environ.get("PATH", "")
            os.environ["PATH"] = f"{bin_dir}{os.pathsep}{old_path}"
            try:
                findings_by_root, stats = sast.scan_semgrep_git_roots(
                    [repo],
                    root,
                    {
                        "engines": {
                            "semgrep": {
                                "enabled": True,
                                "command": "semgrep",
                                "timeout_seconds": 10,
                                "config_auto": "auto",
                                "rule_paths": [],
                                "exclude": ["node_modules"],
                            }
                        }
                    },
                    root / "artifacts",
                )
            finally:
                os.environ["PATH"] = old_path

        self.assertEqual(stats["ran"], 1)
        self.assertEqual(stats["commands"][0]["scanner"], "semgrep")
        self.assertIn("--config", stats["commands"][0]["command"])
        self.assertEqual(findings_by_root["repo"][0]["category"], "sast")
        self.assertEqual(findings_by_root["repo"][0]["severity"], "HIGH")

    def test_fake_syft_and_grype_binaries_generate_and_scan_sbom(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_syft = bin_dir / "syft"
            fake_syft.write_text(
                "#!/usr/bin/env bash\n"
                "cat <<'JSON'\n"
                '{"bomFormat":"CycloneDX","components":[{"name":"openssl","version":"1.0.0"}]}\n'
                "JSON\n",
                encoding="utf-8",
            )
            fake_syft.chmod(0o755)
            fake_grype = bin_dir / "grype"
            fake_grype.write_text(
                "#!/usr/bin/env bash\n"
                "cat <<'JSON'\n"
                '{"matches":[{"vulnerability":{"id":"CVE-1","severity":"High","description":"bad"},"artifact":{"name":"openssl","version":"1.0.0","type":"deb","locations":[{"path":"/usr/lib"}]}}]}\n'
                "JSON\n",
                encoding="utf-8",
            )
            fake_grype.chmod(0o755)
            repo = root / "repo"
            repo.mkdir()
            old_path = os.environ.get("PATH", "")
            os.environ["PATH"] = f"{bin_dir}{os.pathsep}{old_path}"
            try:
                findings_by_root, stats = sbom.scan_sbom_git_roots(
                    [repo],
                    root,
                    {
                        "engines": {
                            "syft": {"enabled": True, "command": "syft", "timeout_seconds": 10, "output_format": "cyclonedx-json"},
                            "grype": {"enabled": True, "command": "grype", "timeout_seconds": 10, "skip_when_trivy_covers_target": True},
                        }
                    },
                    root / "artifacts",
                    vulnerability_scan_requested=True,
                )
                sbom_artifact_exists = Path(stats["syft"]["sboms"][0]["artifact"]).exists()
            finally:
                os.environ["PATH"] = old_path

        self.assertTrue(sbom_artifact_exists)
        self.assertEqual(stats["syft"]["generated"], 1)
        self.assertEqual(stats["grype"]["ran"], 1)
        self.assertEqual(findings_by_root["repo"][0]["source_engine"], "grype")
        self.assertEqual(findings_by_root["repo"][0]["package"], "openssl")

    def test_fake_scorecard_binary_scans_hygiene_explicitly(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_scorecard = bin_dir / "scorecard"
            fake_scorecard.write_text(
                "#!/usr/bin/env bash\n"
                "cat <<'JSON'\n"
                '{"score":7.2,"checks":[{"name":"Token-Permissions","score":3,"reason":"token permissions are too broad","documentation":{"url":"https://example.test","short":"tighten workflow permissions"}},{"name":"License","score":10,"reason":"ok"}]}\n'
                "JSON\n",
                encoding="utf-8",
            )
            fake_scorecard.chmod(0o755)
            repo = root / "repo"
            repo.mkdir()
            old_path = os.environ.get("PATH", "")
            os.environ["PATH"] = f"{bin_dir}{os.pathsep}{old_path}"
            try:
                findings_by_root, stats = hygiene.scan_scorecard_git_roots(
                    [repo],
                    root,
                    {
                        "engines": {
                            "scorecard": {
                                "enabled": False,
                                "command": "scorecard",
                                "timeout_seconds": 10,
                                "format": "json",
                                "show_details": True,
                                "use_local": True,
                                "minimum_check_score": 10,
                            }
                        }
                    },
                    root / "artifacts",
                    explicit_request=True,
                )
            finally:
                os.environ["PATH"] = old_path

        self.assertTrue(stats["enabled"])
        self.assertEqual(stats["ran"], 1)
        self.assertTrue(stats["commands"][0]["command"][0].endswith("scorecard"))
        self.assertEqual(stats["commands"][0]["command"][1:3], ["--format=json", "--show-details"])
        self.assertIn("--local=", stats["commands"][0]["command"][3])
        self.assertEqual(findings_by_root["repo"][0]["source_engine"], "scorecard")
        self.assertEqual(findings_by_root["repo"][0]["category"], "hygiene")

    def test_fake_guarddog_binary_scans_project_ecosystems_and_package_intake(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_guarddog = bin_dir / "guarddog"
            fake_guarddog.write_text(
                "#!/usr/bin/env bash\n"
                "ecosystem=\"$1\"\n"
                "target=\"$3\"\n"
                "if [[ \"$target\" == 'evil' ]]; then pkg='evil'; else pkg='repo-package'; fi\n"
                "cat <<JSON\n"
                "{\"issues\":[{\"rule\":\"${ecosystem}-suspicious-install\",\"message\":\"suspicious package behavior\",\"package\":\"${pkg}\",\"severity\":\"high\",\"path\":\"package.json\",\"line\":1}]}\n"
                "JSON\n",
                encoding="utf-8",
            )
            fake_guarddog.chmod(0o755)
            repo = root / "repo"
            workflow_dir = repo / ".github" / "workflows"
            workflow_dir.mkdir(parents=True)
            (repo / "package.json").write_text('{"dependencies":{"left-pad":"1.0.0"}}\n', encoding="utf-8")
            (repo / "package-lock.json").write_text("{}\n", encoding="utf-8")
            (repo / "requirements.txt").write_text("requests==2.0.0\n", encoding="utf-8")
            (repo / "go.mod").write_text("module example.test/app\n", encoding="utf-8")
            (repo / "Gemfile.lock").write_text("GEM\n", encoding="utf-8")
            (workflow_dir / "ci.yml").write_text("name: ci\n", encoding="utf-8")
            projects = [
                discovery.ProjectRoot(path=repo, label="repo", git_root=repo, files={"package.json", "package-lock.json", "requirements.txt", "go.mod", "Gemfile.lock"}),
                discovery.ProjectRoot(path=workflow_dir, label=".github/workflows", git_root=repo, files={"ci.yml"}, target_types={"ci"}),
                discovery.ProjectRoot(path=repo, label="extension", git_root=repo, files={"package.json"}, target_types={"vscode"}),
            ]
            old_path = os.environ.get("PATH", "")
            os.environ["PATH"] = f"{bin_dir}{os.pathsep}{old_path}"
            original_osv = supply_chain.run_osv_package_query
            supply_chain.run_osv_package_query = lambda *args, **kwargs: []
            try:
                findings_by_project, stats = supply_chain.scan_guarddog_projects(
                    projects,
                    {"engines": {"guarddog": {"enabled": True, "command": "guarddog", "timeout_seconds": 10}}},
                    root / "artifacts",
                )
                report, intake_stats = supply_chain.run_guarddog_package_intake(
                    "npm",
                    "evil",
                    {"engines": {"guarddog": {"enabled": True, "command": "guarddog", "timeout_seconds": 10}}},
                    root / "intake-artifacts",
                )
            finally:
                supply_chain.run_osv_package_query = original_osv
                os.environ["PATH"] = old_path

        self.assertEqual(stats["ran"], 6)
        self.assertEqual({finding["ecosystem"] for finding in findings_by_project["repo"]}, {"npm", "pypi", "go", "rubygems"})
        self.assertEqual(findings_by_project[".github/workflows"][0]["ecosystem"], "github_action")
        self.assertEqual(findings_by_project["extension"][0]["ecosystem"], "extension")
        self.assertEqual(report["decision"], "avoid")
        self.assertEqual(intake_stats["ran"], 1)

    def test_package_intake_reports_unsupported_ecosystem(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            report, stats = supply_chain.run_guarddog_package_intake(
                "maven",
                "example",
                {"engines": {"guarddog": {"enabled": True}}},
                Path(tmp) / "artifacts",
            )

        self.assertEqual(report["decision"], "blocked pending review")
        self.assertEqual(stats["setup_debt"][0]["reason"], "unsupported target")
        self.assertEqual(stats["setup_debt"][0]["unsupported_target"], "maven")

    def test_package_intake_osv_api_lookup_is_config_gated(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_guarddog = bin_dir / "guarddog"
            fake_guarddog.write_text(
                "#!/usr/bin/env bash\n"
                "printf '{\"issues\":[]}'\n",
                encoding="utf-8",
            )
            fake_guarddog.chmod(0o755)
            calls: list[str] = []
            old_path = os.environ.get("PATH", "")
            os.environ["PATH"] = f"{bin_dir}{os.pathsep}{old_path}"
            original_osv = supply_chain.run_osv_package_query
            supply_chain.run_osv_package_query = lambda ecosystem, package, *_args, **_kwargs: calls.append(f"{ecosystem}:{package}") or []
            try:
                _report, default_stats = supply_chain.run_guarddog_package_intake(
                    "npm",
                    "left-pad",
                    {"engines": {"guarddog": {"enabled": True, "command": "guarddog", "timeout_seconds": 10}}},
                    root / "default-artifacts",
                )
                _report, enabled_stats = supply_chain.run_guarddog_package_intake(
                    "npm",
                    "left-pad",
                    {
                        "package_intake": {"osv_api_enabled": True},
                        "engines": {"guarddog": {"enabled": True, "command": "guarddog", "timeout_seconds": 10}},
                    },
                    root / "enabled-artifacts",
                )
            finally:
                supply_chain.run_osv_package_query = original_osv
                os.environ["PATH"] = old_path

        self.assertEqual(calls, ["npm:left-pad"])
        self.assertNotIn("osv_api", default_stats)
        self.assertEqual(enabled_stats["ran"], 1)
</file>

<file path="tests/test_parsers.py">
from __future__ import annotations

import contextlib
import io
import json
import sys
import tempfile
import unittest
import os
import subprocess
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
SCRIPTS = ROOT / "scripts"
sys.path.insert(0, str(SCRIPTS))

from vulnscan import ci, cli, config, discovery, engines, hygiene, inventory, orchestration, parsers, remediation, reporting, sast, sbom, secrets, supply_chain, tracker as tracker_mod  # noqa: E402


class ParserTests(unittest.TestCase):
    def test_bun_clean_and_error_outputs_are_distinct(self) -> None:
        findings, err = parsers.parse_bun({})
        self.assertEqual(findings, [])
        self.assertIsNone(err)

        findings, err = parsers.parse_bun({"error": {"code": "ENOLOCK"}})
        self.assertEqual(findings, [])
        self.assertEqual(err, "bun_error:ENOLOCK")

    def test_npm_parser_extracts_direct_advisories(self) -> None:
        data = {
            "vulnerabilities": {
                "left-pad": {
                    "severity": "high",
                    "via": [{"severity": "critical", "source": 123, "title": "bad", "url": "https://example.test"}],
                }
            }
        }
        findings, err = parsers.parse_npm(data)
        self.assertIsNone(err)
        self.assertEqual(findings[0]["package"], "left-pad")
        self.assertEqual(findings[0]["severity"], "CRITICAL")

    def test_pnpm_parser_extracts_advisories(self) -> None:
        data = {"advisories": {"1": {"module_name": "minimatch", "severity": "moderate", "title": "redos"}}}
        findings, err = parsers.parse_pnpm(data)
        self.assertIsNone(err)
        self.assertEqual(findings[0]["package"], "minimatch")
        self.assertEqual(findings[0]["severity"], "MEDIUM")

    def test_osv_parser_extracts_findings(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            path = Path(tmp) / "osv.json"
            path.write_text(
                '{"results":[{"packages":[{"package":{"name":"pkg","ecosystem":"npm"},'
                '"vulnerabilities":[{"id":"OSV-1","summary":"bad","database_specific":{"severity":"HIGH"}}]}]}]}',
                encoding="utf-8",
            )
            findings, err = parsers.parse_osv(path, "repo")
        self.assertIsNone(err)
        self.assertEqual(findings[0]["package"], "pkg")
        self.assertEqual(findings[0]["severity"], "HIGH")

    def test_pip_audit_parser_extracts_findings(self) -> None:
        data = {
            "dependencies": [
                {
                    "name": "django",
                    "version": "4.2.0",
                    "vulns": [
                        {
                            "id": "PYSEC-1",
                            "aliases": ["CVE-1"],
                            "description": "bad",
                            "fix_versions": ["4.2.1"],
                        }
                    ],
                }
            ]
        }
        findings, err = parsers.parse_pip_audit(data)
        self.assertIsNone(err)
        self.assertEqual(findings[0]["source_engine"], "pip-audit")
        self.assertEqual(findings[0]["package"], "django")
        self.assertEqual(findings[0]["ecosystem"], "python")
        self.assertEqual(findings[0]["confidence"], "known_vulnerability")

    def test_cargo_audit_parser_extracts_findings(self) -> None:
        data = {
            "vulnerabilities": {
                "list": [
                    {
                        "advisory": {"id": "RUSTSEC-1", "package": "openssl", "title": "bad", "url": "https://example.test"},
                        "package": {"name": "openssl", "version": "0.10.0"},
                        "versions": {"patched": [">=0.10.1"]},
                    }
                ]
            }
        }
        findings, err = parsers.parse_cargo_audit(data)
        self.assertIsNone(err)
        self.assertEqual(findings[0]["source_engine"], "cargo-audit")
        self.assertEqual(findings[0]["package"], "openssl")
        self.assertEqual(findings[0]["ecosystem"], "rust")

    def test_trivy_parser_extracts_vuln_secret_misconfig_and_license_without_secret_value(self) -> None:
        data = {
            "Results": [
                {
                    "Target": "package-lock.json",
                    "Type": "npm",
                    "Vulnerabilities": [
                        {
                            "VulnerabilityID": "CVE-1",
                            "PkgName": "left-pad",
                            "InstalledVersion": "1.0.0",
                            "FixedVersion": "1.0.1",
                            "Severity": "HIGH",
                            "Title": "bad",
                            "PrimaryURL": "https://example.test/cve",
                        }
                    ],
                },
                {
                    "Target": ".env",
                    "Secrets": [
                        {
                            "RuleID": "aws-access-key",
                            "Severity": "CRITICAL",
                            "Title": "AWS key",
                            "StartLine": 1,
                            "Match": "AKIASECRET",
                        }
                    ],
                },
                {
                    "Target": "Dockerfile",
                    "Misconfigurations": [
                        {
                            "ID": "DS001",
                            "Severity": "MEDIUM",
                            "Title": "bad docker",
                            "Resolution": "fix it",
                            "CauseMetadata": {"StartLine": 2},
                        }
                    ],
                },
                {
                    "Target": "package-lock.json",
                    "Packages": [
                        {"Name": "pkg", "Version": "1.0.0", "Licenses": [{"Name": "GPL-3.0", "Severity": "HIGH"}]}
                    ],
                },
            ]
        }
        findings, err = parsers.parse_trivy(data, "repo")
        categories = {finding["category"] for finding in findings}
        serialized = str(findings)

        self.assertIsNone(err)
        self.assertEqual(categories, {"dependency", "secret", "misconfiguration", "license"})
        self.assertNotIn("AKIASECRET", serialized)
        redacted = str(parsers.redact_sensitive_values(data))
        self.assertNotIn("AKIASECRET", redacted)
        self.assertIn("[REDACTED]", redacted)

    def test_gitleaks_parser_outputs_metadata_only_findings(self) -> None:
        data = [
            {
                "RuleID": "generic-api-key",
                "Description": "Generic API Key",
                "File": ".env",
                "StartLine": 2,
                "Secret": "sk-secret",
                "Match": "API_KEY=sk-secret",
            }
        ]
        findings, err = parsers.parse_gitleaks(data, "repo")
        serialized = str(findings)

        self.assertIsNone(err)
        self.assertEqual(findings[0]["source_engine"], "gitleaks")
        self.assertEqual(findings[0]["category"], "secret")
        self.assertEqual(findings[0]["detector"], "generic-api-key")
        self.assertEqual(findings[0]["verification_state"], "unverified")
        self.assertNotIn("sk-secret", serialized)

    def test_trufflehog_parser_filters_unverified_and_omits_secret_values(self) -> None:
        text = "\n".join(
            [
                '{"DetectorName":"GitHub","Verified":false,"Raw":"ghp_unverified","SourceMetadata":{"Data":{"Git":{"file":"a.env","line":1}}}}',
                '{"DetectorName":"GitHub","Verified":true,"Raw":"ghp_verified","RawV2":"ghp_verified","SourceMetadata":{"Data":{"Git":{"file":"b.env","line":2,"commit":"abc"}}}}',
            ]
        )
        findings, err = parsers.parse_trufflehog_lines(text, "repo")
        serialized = str(findings)

        self.assertIsNone(err)
        self.assertEqual(len(findings), 1)
        self.assertEqual(findings[0]["source_engine"], "trufflehog")
        self.assertEqual(findings[0]["verification_state"], "verified")
        self.assertEqual(findings[0]["confidence"], "verified")
        self.assertNotIn("ghp_verified", serialized)
        self.assertNotIn("ghp_unverified", serialized)

    def test_zizmor_parser_normalizes_workflow_findings(self) -> None:
        data = [
            {
                "ident": "template-injection",
                "desc": "untrusted context in run block",
                "url": "https://docs.zizmor.sh/audits/#template-injection",
                "determinations": {"confidence": "High", "severity": "High"},
                "locations": [
                    {
                        "symbolic": {"key": {"Local": {"given_path": ".github/workflows/ci.yml"}}},
                        "concrete": {"location": {"start_point": {"row": 9, "column": 6}}},
                    }
                ],
            }
        ]
        findings, err = parsers.parse_zizmor(data, ".github/workflows")

        self.assertIsNone(err)
        self.assertEqual(findings[0]["source_engine"], "zizmor")
        self.assertEqual(findings[0]["category"], "workflow")
        self.assertEqual(findings[0]["line"], 10)
        self.assertEqual(findings[0]["workflow_issue_type"], "workflow_injection")
        self.assertEqual(findings[0]["severity"], "HIGH")

    def test_actionlint_parser_normalizes_json_lines(self) -> None:
        text = '{"filepath":".github/workflows/ci.yml","line":15,"column":41,"message":"github.event.head_commit.message is potentially untrusted","kind":"expression"}\n'
        findings, err = parsers.parse_actionlint_lines(text, ".github/workflows")

        self.assertIsNone(err)
        self.assertEqual(findings[0]["source_engine"], "actionlint")
        self.assertEqual(findings[0]["category"], "workflow")
        self.assertEqual(findings[0]["workflow_issue_type"], "workflow_injection")
        self.assertEqual(findings[0]["severity"], "HIGH")

    def test_semgrep_parser_normalizes_sast_findings(self) -> None:
        data = {
            "results": [
                {
                    "check_id": "python.lang.security.audit.subprocess-shell-true",
                    "path": "app.py",
                    "start": {"line": 12, "col": 5},
                    "extra": {
                        "message": "subprocess call with shell=True",
                        "severity": "ERROR",
                        "fix": "avoid shell=True",
                        "metadata": {"source": "https://semgrep.dev/r/python.lang.security.audit.subprocess-shell-true"},
                    },
                }
            ]
        }
        findings, err = parsers.parse_semgrep(data, "repo")

        self.assertIsNone(err)
        self.assertEqual(findings[0]["source_engine"], "semgrep")
        self.assertEqual(findings[0]["category"], "sast")
        self.assertEqual(findings[0]["severity"], "HIGH")
        self.assertEqual(findings[0]["line"], 12)
        self.assertEqual(findings[0]["remediation_hint"], "avoid shell=True")

    def test_syft_metadata_parser_summarizes_sbom_output(self) -> None:
        metadata, err = parsers.parse_syft_metadata({"bomFormat": "CycloneDX", "components": [{"name": "pkg"}]})

        self.assertIsNone(err)
        self.assertEqual(metadata["format"], "CycloneDX")
        self.assertEqual(metadata["package_count"], 1)

    def test_grype_parser_normalizes_sbom_vulnerabilities(self) -> None:
        data = {
            "matches": [
                {
                    "vulnerability": {"id": "CVE-1", "severity": "High", "description": "bad", "urls": ["https://example.test/cve"]},
                    "artifact": {"name": "openssl", "version": "1.0.0", "type": "deb", "locations": [{"path": "/usr/lib"}]},
                }
            ]
        }
        findings, err = parsers.parse_grype(data, "repo")

        self.assertIsNone(err)
        self.assertEqual(findings[0]["source_engine"], "grype")
        self.assertEqual(findings[0]["package"], "openssl")
        self.assertEqual(findings[0]["severity"], "HIGH")

    def test_scorecard_parser_treats_low_scores_as_hygiene_findings(self) -> None:
        data = {
            "score": 7.2,
            "checks": [
                {"name": "Token-Permissions", "score": 3, "reason": "token permissions are too broad", "documentation": {"url": "https://example.test", "short": "tighten workflow permissions"}},
                {"name": "License", "score": 10, "reason": "ok"},
            ],
        }
        findings, err = parsers.parse_scorecard(data, "repo", minimum_score=10)

        self.assertIsNone(err)
        self.assertEqual(len(findings), 1)
        self.assertEqual(findings[0]["source_engine"], "scorecard")
        self.assertEqual(findings[0]["category"], "hygiene")
        self.assertEqual(findings[0]["advisory_id"], "Token-Permissions")
        self.assertEqual(findings[0]["severity"], "MEDIUM")

    def test_guarddog_parser_normalizes_supply_chain_findings(self) -> None:
        data = {
            "issues": [
                {
                    "rule": "npm-exec-base64",
                    "message": "package executes base64 encoded code",
                    "package": "evil",
                    "severity": "high",
                    "path": "index.js",
                    "line": 4,
                }
            ]
        }
        findings, err = parsers.parse_guarddog(data, "evil", ecosystem="npm")

        self.assertIsNone(err)
        self.assertEqual(findings[0]["source_engine"], "guarddog")
        self.assertEqual(findings[0]["category"], "supply-chain")
        self.assertEqual(findings[0]["package"], "evil")
        self.assertEqual(findings[0]["ecosystem"], "npm")
        self.assertEqual(findings[0]["severity"], "HIGH")

    def test_osv_package_query_parser_normalizes_package_intake_findings(self) -> None:
        findings = supply_chain.parse_osv_package_query(
            {
                "vulns": [
                    {
                        "id": "GHSA-1",
                        "summary": "bad package",
                        "database_specific": {"severity": "HIGH"},
                        "references": [{"url": "https://example.test/GHSA-1"}],
                    }
                ]
            },
            "left-pad",
            "npm",
        )

        self.assertEqual(findings[0]["source_engine"], "osv-api")
        self.assertEqual(findings[0]["category"], "dependency")
        self.assertEqual(findings[0]["package"], "left-pad")
        self.assertEqual(findings[0]["severity"], "HIGH")

    def test_dedupe_findings_collapses_same_advisory_across_engines(self) -> None:
        findings = parsers.dedupe_findings(
            [
                {"source_engine": "osv-scanner", "package": "pkg", "ecosystem": "npm", "advisory_id": "GHSA-1", "title": "bad"},
                {"source_engine": "npm-audit", "package": "pkg", "ecosystem": "npm", "advisory_id": "GHSA-1", "title": "bad"},
            ]
        )
        self.assertEqual(len(findings), 1)
</file>

<file path="tests/test_tracker.py">
from __future__ import annotations

import contextlib
import io
import json
import sys
import tempfile
import unittest
import os
import subprocess
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
SCRIPTS = ROOT / "scripts"
sys.path.insert(0, str(SCRIPTS))

from vulnscan import ci, cli, config, discovery, engines, hygiene, inventory, orchestration, parsers, remediation, reporting, sast, sbom, secrets, supply_chain, tracker as tracker_mod  # noqa: E402


class TrackerTests(unittest.TestCase):
    def test_stale_unfixable_finding_retries_after_window(self) -> None:
        results = [{"label": "app", "findings": [{"package": "left-pad", "advisory_id": "GHSA-1", "title": "bad"}]}]
        tracker = {
            "entries": [
                {
                    "repo_label": "app",
                    "package": "left-pad",
                    "advisory_id": "GHSA-1",
                    "status": "unfixable",
                    "last_checked": "2026-04-01T00:00:00Z",
                    "retry_after_days": 30,
                }
            ]
        }
        actionable, skipped = tracker_mod.filter_with_tracker(results, tracker, 30)
        self.assertEqual(skipped, [])
        self.assertEqual(actionable[0]["findings"][0]["tracker_retry"]["previous_status"], "unfixable")

    def test_unfixable_retries_when_installed_version_changes(self) -> None:
        results = [{"label": "app", "findings": [{"package": "left-pad", "advisory_id": "GHSA-1", "title": "bad", "installed_version": "1.0.1"}]}]
        tracker = {
            "entries": [
                {
                    "repo_label": "app",
                    "package": "left-pad",
                    "advisory_id": "GHSA-1",
                    "status": "unfixable",
                    "installed_version": "1.0.0",
                    "last_checked": "2026-05-20T00:00:00Z",
                    "retry_after_days": 30,
                }
            ]
        }
        actionable, skipped = tracker_mod.filter_with_tracker(results, tracker, 30)

        self.assertEqual(skipped, [])
        self.assertTrue(actionable[0]["findings"][0]["tracker_retry"]["installed_version_changed"])

    def test_blocked_entire_repo_retry_is_flagged_separately(self) -> None:
        results = [{"label": "app", "findings": [{"package": "left-pad", "advisory_id": "GHSA-1", "title": "bad"}]}]
        tracker = {
            "entries": [
                {
                    "repo_label": "app",
                    "package": "left-pad",
                    "advisory_id": "GHSA-1",
                    "status": "blocked_entire_repo",
                    "last_checked": "2026-04-01T00:00:00Z",
                    "retry_after_days": 30,
                }
            ]
        }
        actionable, skipped = tracker_mod.filter_with_tracker(results, tracker, 30)

        self.assertEqual(skipped, [])
        self.assertTrue(actionable[0]["findings"][0]["tracker_retry"]["blocked_entire_repo"])

    def test_tracker_corruption_backup_and_atomic_verified_write(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            path = Path(tmp) / "tracker.json"
            path.write_text("{not-json", encoding="utf-8")

            loaded = tracker_mod.load_tracker(path)
            blocked = tracker_mod.save_tracker_atomic(path, {"version": 1, "entries": []}, same_engine_verified=False)
            written = tracker_mod.save_tracker_atomic(path, {"version": 1, "entries": []}, same_engine_verified=True)

        self.assertEqual(loaded["_tracker_recovery"]["status"], "corrupt_recovered")
        self.assertFalse(blocked["written"])
        self.assertTrue(written["written"])
</file>

<file path=".gitignore">
# OS/editor junk
.DS_Store
.vscode/
.idea/

# Secrets / env
.env
.env.*
!.env.example
*.pem
*.key

# Runtime output
*.log
/tmp/
__pycache__/
*.pyc
vuln_knowledge.json
</file>

<file path="AGENTS.md">
# Repository Instructions

- Keep source and test files under 500 lines by splitting by domain, command, parser family, or test area.
- Exceptions are allowed for generated artifacts, lockfiles, vendored code, or intentionally monolithic reference documents when splitting would reduce clarity.
</file>

<file path="repomix.config.json">
{
  "$schema": "https://repomix.com/schemas/latest/schema.json",
  "output": {
    "filePath": "repomix-output.xml",
    "style": "xml"
  },
  "include": ["**/*"],
  "ignore": {
    "useGitignore": true,
    "useDotIgnore": true,
    "useDefaultPatterns": false,
    "customPatterns": [
      ".git/**",
      ".hg/**",
      ".svn/**",
      "**/node_modules/**",
      "vendor/**",
      "**/.bundle/**",
      "**/.gradle/**",
      "**/.npm/**",
      "**/.yarn/**",
      "**/target/**",
      "dist/**",
      "build/**",
      "out/**",
      "tmp/**",
      "temp/**",
      "coverage/**",
      ".nyc_output/**",
      ".pytest_cache/**",
      ".mypy_cache/**",
      "**/__pycache__/**",
      "**/*.py[cod]",
      "**/.DS_Store",
      "**/Thumbs.db",
      ".idea/**",
      ".vscode/**",
      "**/*.swp",
      "**/*.swo",
      "**/*.bak",
      "**/*.log",
      "**/npm-debug.log*",
      "**/yarn-debug.log*",
      "**/yarn-error.log*",
      "**/repomix-output.*",
      "**/repopack-output.*",
      ".env",
      ".env.*"
    ]
  }
}
</file>

<file path="references/install-tools.md">
# Install Tools

Use this reference when preparing a host for local vulnerability scanning. The
scanner should always run `validate-tools` first and treat missing tools as
setup debt when installation is not possible.

```bash
python3 scripts/vuln-scan.py validate-tools \
  --config templates/config-starter.yaml \
  --format text
```

When validating scanner command syntax after installing or upgrading tools, run:

```bash
python3 scripts/vuln-scan.py validate-tools \
  --config templates/config-starter.yaml \
  --format text \
  --deep
```

Recommended local stack:

```bash
brew install trivy gitleaks syft grype semgrep actionlint
brew install scorecard
brew install zizmor
brew install trufflehog
pipx install guarddog
pipx install pip-audit
cargo install cargo-audit
```

OSV Scanner is the broad dependency baseline. Install it with the current
official method for the host, then verify `osv-scanner --version`.

GuardDog's upstream install docs show `pip install guarddog`. Prefer `pipx
install guarddog` for this skill so the CLI is isolated from project
environments.

Do not block the whole scan just because one tool is missing. Continue with the
engines that can produce trustworthy coverage and report the missing binary in
`setup_debt`.
</file>

<file path="references/package-intake.md">
# Package Intake

Use package intake before adding a new dependency, GitHub Action, or VS Code
extension:

```bash
python3 scripts/vuln-scan.py package-intake npm package-name \
  --output /tmp/package-intake.json \
  --artifact-dir /tmp/package-intake-artifacts \
  --format text
```

Supported ecosystems:

- `npm`
- `pypi`
- `go`
- `rubygems`
- `github_action`
- `extension`

The command returns one of:

- `allow`
- `allow with caution`
- `avoid`
- `blocked pending review`

Package intake runs GuardDog for package behavior. It stays local-first by
default. Set `package_intake.osv_api_enabled: true` to also query the public OSV
API for supported ecosystems before accepting a named package.

GuardDog findings are supply-chain behavior findings, not ordinary CVEs. Treat
them as a reason to avoid or manually review the package even when OSV-style
dependency scanners are clean.
</file>

<file path="references/parser-contract.md">
# Parser Contract

Every engine parser returns:

```text
findings, error
```

`findings` must be normalized dictionaries. `error` is `None` for valid clean or
valid finding-bearing output. Parser failures, empty output, scanner errors, and
timeouts must become setup debt in the caller rather than being reported as
clean results.

Normalized findings should include the fields that are available:

- `source_engine`
- `category`
- `severity`
- `confidence`
- `package`
- `ecosystem`
- `installed_version`
- `fixed_version` or `fixed_versions`
- `advisory_id`
- `title`
- `url`
- `file`
- `line`
- `remediation_hint`

Secret parsers must never preserve raw secret values in normalized findings or
surfaced artifacts. Keep only metadata such as detector, file, line, git-tracked
state, and verification state.

Before enabling a new parser by default, add parser fixtures and a fake-binary
integration test that proves command recording, artifact writing, setup-debt
behavior, and normalization.

## Version Floors

Do not invent minimum supported versions. A parser version floor is allowed only
after one of these is true:

- the upstream tool documents a stable output schema version
- fixture output has been captured from the minimum tool version
- `validate-tools --deep` confirms the installed version and a parser fixture
  exists for that version's output

Until then, parser compatibility is enforced by parser tests, fake-binary
integration tests, deep tool validation, and setup-debt reporting on parser
failure.
</file>

<file path="scripts/vulnscan/cli/args.py">
"""CLI argument construction and command normalization."""

from __future__ import annotations

import argparse
from pathlib import Path

from ..inventory import SCAN_MODES

COMMANDS = {"scan", "plan", "list-engines", "validate-tools", "render-report", "package-intake"}


def build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(description="Deterministic multi-repo vulnerability scanner")
    parser.add_argument("--config", type=Path, help="Config YAML/JSON path")
    parser.add_argument("--root", type=Path, help="Workspace root override")
    parser.add_argument("--output", type=Path, help="Write JSON summary to this path")
    parser.add_argument("--artifact-dir", type=Path, help="Directory for raw scanner artifacts")
    parser.add_argument("--scan-mode", choices=sorted(SCAN_MODES), default="full", help="Scan mode to run")
    parser.add_argument("--format", choices=["json", "text"], default="json", help="Console report format")
    parser.add_argument("--list-engines", action="store_true", help="List scanner engines and availability")
    parser.add_argument("--validate-tools", action="store_true", help="Validate scanner tool availability")
    parser.add_argument("--deep", action="store_true", help="With validate-tools, run version/help smoke checks for installed scanner CLIs.")
    parser.add_argument("--plan-only", action="store_true", help="Discover targets and scope without running scanners")
    parser.add_argument("--no-secrets", action="store_true", help="Disable local secret-pattern scan")
    parser.add_argument("--no-tracker", action="store_true", help="Disable vulnerability knowledge tracker filtering")
    parser.add_argument("--tracker-path", type=Path, help="Override vulnerability knowledge tracker path")
    parser.add_argument("--image-target", action="append", default=[], help="Explicit container image target for Trivy image scanning. Repeatable.")
    parser.add_argument("--include-licenses", action="store_true", help="Include license scanning in Trivy filesystem and image scans. Omitted from full by default to keep security output readable.")
    parser.add_argument("--only-engine", action="append", default=[], help="Run only named scanner engine(s). Repeatable and comma-separated. Examples: --only-engine trivy --only-engine gitleaks,semgrep")
    parser.add_argument("--auto-remediate", action="store_true", help="Opt in to bounded Codex remediation after scan findings are produced.")
    parser.add_argument("--pretty", action="store_true", help="Pretty-print JSON")
    parser.add_argument("--fail-on-findings", action="store_true", help="Exit 1 when findings are present")
    parser.add_argument("--allowed-root", action="append", type=Path, default=[], help="Allowed project root. Repeatable. Any discovered project outside these roots is a scope violation.")
    parser.add_argument("--allowed-label-prefix", action="append", default=[], help="Allowed project label prefix. Repeatable.")
    parser.add_argument("--forbidden-label-prefix", action="append", default=[], help="Forbidden project label prefix. Repeatable.")
    parser.add_argument("--fail-on-scope-violation", action="store_true", help="Exit 2 when discovered projects violate scope gates")
    return parser


def normalize_argv(argv: list[str]) -> tuple[str, list[str]]:
    if not argv or argv[0] not in COMMANDS:
        return "scan", argv
    command = argv[0]
    rest = argv[1:]
    if command == "scan":
        return command, rest
    if command == "plan":
        return command, ["--plan-only", *rest]
    if command == "list-engines":
        return command, ["--list-engines", *rest]
    if command == "validate-tools":
        return command, ["--validate-tools", *rest]
    return command, rest
</file>

<file path="scripts/vulnscan/cli/scan.py">
"""Scan command orchestration."""

from __future__ import annotations

import argparse
import json
import os
import shutil
import subprocess
import sys
import tempfile
import time
from pathlib import Path
from typing import Any

from ..common import setup_debt_item
from ..config import cfg_get, cfg_list, load_config, normalize_roots, validate_config
from ..discovery import DEFAULT_EXCLUDE_GLOBS, ProjectRoot, build_scope_report, discover_git_roots, discover_projects, relpath
from ..engines import scan_js_project, scan_python_project, scan_rust_project, scan_trivy_images
from ..inventory import MODE_IMPLEMENTATION, engine_registry
from ..orchestration import run_workspace_engines
from ..parsers import dedupe_findings
from ..remediation import build_remediation_prep, compare_same_engine_verification, run_codex_remediation
from ..reporting import build_summary
from ..secrets import scan_gitleaks_git_roots, scan_secrets, scan_trufflehog_git_roots
from ..tracker import filter_with_tracker, load_tracker
from .output import build_plan_summary, build_scope_failure_summary, filter_findings_by_severity, write_and_print_summary


def verify_after_remediation(
    *,
    original_results: list[dict[str, Any]],
    project_paths: dict[str, Path],
    args: argparse.Namespace,
    artifact_dir: Path,
    scan_mode: str,
) -> dict[str, Any]:
    affected = [result for result in original_results if result.get("findings")]
    if not affected:
        return {"enabled": False, "reason": "no affected projects"}
    scanner = Path(__file__).resolve().parents[2] / "vuln-scan.py"
    verify_dir = artifact_dir / "remediation-verification"
    verify_dir.mkdir(parents=True, exist_ok=True)
    verified_results: list[dict[str, Any]] = []
    commands: list[dict[str, Any]] = []
    for result in affected:
        label = str(result.get("label") or "")
        project_path = project_paths.get(label)
        if project_path is None:
            continue
        safe_label = label.replace("/", "_").replace(":", "_") or "root"
        output = verify_dir / f"{safe_label}.json"
        child_artifacts = verify_dir / f"{safe_label}-artifacts"
        cmd = [
            sys.executable,
            str(scanner),
            "scan",
            "--root",
            str(project_path),
            "--scan-mode",
            scan_mode,
            "--no-tracker",
            "--output",
            str(output),
            "--artifact-dir",
            str(child_artifacts),
            "--format",
            "json",
        ]
        if args.config:
            cmd.extend(["--config", str(args.config)])
        proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=1800)
        commands.append({"label": label, "command": cmd, "exit_code": proc.returncode, "output": str(output)})
        if not output.exists():
            continue
        try:
            summary = json.loads(output.read_text(encoding="utf-8"))
        except json.JSONDecodeError:
            continue
        collapsed: list[dict[str, Any]] = []
        for verified in summary.get("results", []):
            collapsed.extend(verified.get("findings", []))
        verified_results.append({"label": label, "findings": collapsed})
    comparison = compare_same_engine_verification(affected, verified_results)
    comparison.update({"enabled": True, "commands": commands})
    return comparison


def scanner_list(value: Any) -> list[str]:
    return [part.strip() for part in str(value or "").split(",") if part.strip()]


ENGINE_ALIASES = {
    "javascript-native": {"bun-audit", "npm-audit", "pnpm-audit"},
    "js-native": {"bun-audit", "npm-audit", "pnpm-audit"},
    "ci": {"zizmor", "actionlint"},
    "secrets": {"secret-patterns", "gitleaks", "trufflehog"},
    "sbom": {"syft", "grype"},
}

ENGINE_CATEGORY_GROUPS = {
    "dependencies": {"osv-scanner", "bun-audit", "npm-audit", "pnpm-audit", "pip-audit", "cargo-audit"},
    "secrets": {"secret-patterns", "gitleaks", "trufflehog"},
    "ci": {"zizmor", "actionlint"},
    "sast": {"semgrep"},
    "sbom": {"syft", "grype"},
    "hygiene": {"scorecard"},
    "supply_chain": {"guarddog"},
    "trivy": {"trivy"},
}


def parse_engine_allowlist(raw_values: list[str]) -> set[str] | None:
    requested = [part.strip() for value in raw_values for part in value.split(",") if part.strip()]
    if not requested:
        return None
    registry = engine_registry()
    selected: set[str] = set()
    unknown: list[str] = []
    for name in requested:
        if name in registry:
            selected.add(name)
        elif name in ENGINE_ALIASES:
            selected.update(ENGINE_ALIASES[name])
        else:
            unknown.append(name)
    if unknown:
        valid = sorted(set(registry) | set(ENGINE_ALIASES))
        raise SystemExit("Unknown --only-engine value(s): " + ", ".join(unknown) + "\nValid engines: " + ", ".join(valid))
    return selected


def engine_group_selected(selected: set[str] | None, group: str) -> bool:
    return selected is None or bool(selected & ENGINE_CATEGORY_GROUPS[group])


def apply_engine_allowlist(config: dict[str, Any], selected: set[str] | None) -> dict[str, Any]:
    if selected is None:
        return config
    registry = engine_registry()
    config = dict(config)
    engines_config = dict(config.get("engines") or {})
    selected_config_keys = {
        adapter.config_key
        for name, adapter in registry.items()
        if name in selected and adapter.config_key
    }
    for adapter in registry.values():
        key = adapter.config_key
        if not key or key in selected_config_keys:
            continue
        engine_config = dict(engines_config.get(key) or {})
        engine_config["enabled"] = False
        engines_config[key] = engine_config
    if "javascript" in selected_config_keys:
        javascript_config = dict(engines_config.get("javascript") or {})
        javascript_config["prefer_bun"] = "bun-audit" in selected
        javascript_config["fallback_to_npm"] = bool({"npm-audit", "pnpm-audit"} & selected)
        engines_config["javascript"] = javascript_config
    config["engines"] = engines_config
    return config


def run_scan(args: argparse.Namespace) -> int:
    started = time.time()
    config = load_config(args.config)
    selected_engines = parse_engine_allowlist(list(args.only_engine or []))
    config = apply_engine_allowlist(config, selected_engines)
    if args.include_licenses:
        config = dict(config)
        engines_config = dict(config.get("engines") or {})
        trivy_config = dict(engines_config.get("trivy") or {})
        scanners = scanner_list(trivy_config.get("scanners", "vuln,misconfig,secret"))
        image_scanners = scanner_list(trivy_config.get("image_scanners", trivy_config.get("scanners", "vuln,secret")))
        if "license" not in scanners:
            scanners.append("license")
        if "license" not in image_scanners:
            image_scanners.append("license")
        trivy_config["scanners"] = ",".join(scanners)
        trivy_config["image_scanners"] = ",".join(image_scanners)
        engines_config["trivy"] = trivy_config
        config["engines"] = engines_config
    if args.auto_remediate:
        config = dict(config)
        remediation_config = dict(config.get("remediation") or {})
        codex_config = dict(remediation_config.get("codex") or {})
        remediation_config["auto_fix"] = True
        codex_config["enabled"] = True
        remediation_config["codex"] = codex_config
        config["remediation"] = remediation_config
    if args.config:
        config_errors = validate_config(config)
        if config_errors:
            raise SystemExit("Invalid config:\n" + "\n".join(f"- {error}" for error in config_errors))

    scan_mode = args.scan_mode
    dependency_scan_enabled = scan_mode in {"full", "dependencies", "remediation-prep"} and engine_group_selected(selected_engines, "dependencies")
    secret_scan_enabled = scan_mode in {"full", "secrets", "remediation-prep"} and not args.no_secrets and engine_group_selected(selected_engines, "secrets")
    ci_scan_enabled = scan_mode in {"full", "ci", "remediation-prep"} and engine_group_selected(selected_engines, "ci")
    sast_scan_enabled = scan_mode in {"full", "sast"} and engine_group_selected(selected_engines, "sast")
    sbom_scan_enabled = scan_mode == "sbom" and engine_group_selected(selected_engines, "sbom")
    hygiene_scan_enabled = scan_mode == "hygiene" and engine_group_selected(selected_engines, "hygiene")
    supply_chain_scan_enabled = scan_mode == "supply-chain" and engine_group_selected(selected_engines, "supply_chain")
    unsupported_mode = MODE_IMPLEMENTATION[scan_mode] == "planned"
    root_value = args.root or Path(str(cfg_get(config, "projects_root", os.getcwd()))).expanduser()
    workspace_root = root_value.resolve()
    max_depth = int(cfg_get(config, "scan.max_depth", 6))
    exclude_globs = list(cfg_get(config, "filters.skip_paths", DEFAULT_EXCLUDE_GLOBS) or DEFAULT_EXCLUDE_GLOBS)
    artifact_dir = args.artifact_dir or Path(tempfile.mkdtemp(prefix="vuln-scan-"))
    artifact_dir.mkdir(parents=True, exist_ok=True)

    if not workspace_root.exists():
        raise SystemExit(f"Workspace root does not exist: {workspace_root}")

    discovery_result = discover_projects(workspace_root, max_depth=max_depth, exclude_globs=exclude_globs)
    projects = discovery_result.projects
    skipped_targets = discovery_result.skipped_targets
    allowed_roots = normalize_roots(cfg_list(config, "scope.allowed_roots") + list(args.allowed_root))
    allowed_label_prefixes = [str(value) for value in (cfg_list(config, "scope.allowed_label_prefixes") + list(args.allowed_label_prefix or []))]
    forbidden_label_prefixes = [str(value) for value in (cfg_list(config, "scope.forbidden_label_prefixes") + list(args.forbidden_label_prefix or []))]
    scope_report = build_scope_report(projects, workspace_root, allowed_roots, allowed_label_prefixes, forbidden_label_prefixes)
    if args.fail_on_scope_violation and scope_report.get("out_of_scope_count", 0):
        summary = build_scope_failure_summary(
            artifact_dir=artifact_dir,
            started=started,
            scan_mode=scan_mode,
            projects_count=len(projects),
            max_depth=max_depth,
            scope_report=scope_report,
            skipped_targets=skipped_targets,
        )
        write_and_print_summary(summary, args, config)
        return 2

    git_roots = discover_git_roots(projects, workspace_root)
    if (workspace_root / ".git").exists() and workspace_root.resolve() not in {path.resolve() for path in git_roots}:
        git_roots.append(workspace_root)
    if args.plan_only:
        summary = build_plan_summary(
            artifact_dir=artifact_dir,
            started=started,
            scan_mode=scan_mode,
            max_depth=max_depth,
            projects=projects,
            git_roots=git_roots,
            scope_report=scope_report,
            skipped_targets=skipped_targets,
        )
        write_and_print_summary(summary, args, config)
        return 0

    stats: dict[str, Any] = {
        "duration_seconds": None,
        "scan_mode": scan_mode,
        "selected_engines": sorted(selected_engines) if selected_engines else None,
        "mode_status": MODE_IMPLEMENTATION[scan_mode],
        "command": "scan",
        "commands": [],
        "project_discovery": {"projects": len(projects), "git_roots": len(git_roots), "max_depth": max_depth},
        "osv": {},
        "javascript": {"enabled": dependency_scan_enabled and bool(cfg_get(config, "engines.javascript.enabled", True)), "projects": 0, "bun_success": 0, "bun_parse_failed": 0, "bun_error": 0, "npm_success": 0, "npm_parse_failed": 0, "npm_error": 0, "pnpm_success": 0, "pnpm_parse_failed": 0, "pnpm_error": 0},
        "python": {"enabled": dependency_scan_enabled and bool(cfg_get(config, "engines.python.enabled", False)), "projects": 0, "success": 0, "missing": 0, "parse_failed": 0, "error": 0, "timeout": 0},
        "rust": {"enabled": dependency_scan_enabled and bool(cfg_get(config, "engines.rust.enabled", False)), "projects": 0, "success": 0, "missing": 0, "parse_failed": 0, "error": 0, "timeout": 0},
        "containers": {"projects": 0, "scanner_missing": False},
        "trivy": {},
        "secrets": {},
        "gitleaks": {},
        "trufflehog": {},
        "ci": {},
        "semgrep": {},
        "sbom": {},
        "scorecard": {},
        "guarddog": {},
        "mode_setup_debt": [],
        "filtered_by_severity": 0,
    }
    if unsupported_mode:
        stats["mode_setup_debt"].append(f"scan mode '{scan_mode}' is not implemented in the scanner CLI yet; use direct tools from SKILL.md")

    workspace_outputs = run_workspace_engines(
        scan_mode=scan_mode,
        projects=projects,
        git_roots=git_roots,
        workspace_root=workspace_root,
        config=config,
        artifact_dir=artifact_dir,
    )
    osv_by_git_root, stats["osv"] = workspace_outputs["osv-scanner"]
    trivy_by_git_root, stats["trivy"] = workspace_outputs["trivy"]
    ci_by_project, stats["ci"] = workspace_outputs["ci"]
    semgrep_by_git_root, stats["semgrep"] = workspace_outputs["semgrep"]
    sbom_by_git_root, stats["sbom"] = workspace_outputs["sbom"]
    scorecard_by_git_root, stats["scorecard"] = workspace_outputs["scorecard"]
    guarddog_by_project, stats["guarddog"] = workspace_outputs["guarddog"]
    for engine_stats in (
        stats["osv"],
        stats["trivy"],
        stats["ci"],
        stats["semgrep"],
        stats["sbom"],
        stats["scorecard"],
        stats["guarddog"],
    ):
        stats["commands"].extend(engine_stats.get("commands", []))
        stats["mode_setup_debt"].extend(engine_stats.get("setup_debt", []))

    if engine_group_selected(selected_engines, "trivy"):
        image_findings, image_debt, image_stats = scan_trivy_images(list(args.image_target or []), config, artifact_dir)
    else:
        image_findings, image_debt, image_stats = [], [], {"enabled": False, "ran": 0, "commands": []}
    stats["trivy_images"] = image_stats
    stats["commands"].extend(image_stats.get("commands", []))
    if image_debt:
        stats["mode_setup_debt"].extend(image_debt)

    results: list[dict[str, Any]] = []
    project_paths: dict[str, Path] = {}
    js_enabled = dependency_scan_enabled and bool(cfg_get(config, "engines.javascript.enabled", True))
    python_enabled = dependency_scan_enabled and bool(cfg_get(config, "engines.python.enabled", False))
    rust_enabled = dependency_scan_enabled and bool(cfg_get(config, "engines.rust.enabled", False))
    for project in projects:
        findings: list[dict[str, Any]] = []
        debt: list[dict[str, Any]] = []
        ecosystems = sorted(project.ecosystems)
        if "npm" in ecosystems:
            stats["javascript"]["projects"] += 1
        if "python" in ecosystems:
            stats["python"]["projects"] += 1
        if "rust" in ecosystems:
            stats["rust"]["projects"] += 1
        if "container" in ecosystems:
            stats["containers"]["projects"] += 1
        if dependency_scan_enabled and "javascript-no-lockfile" in ecosystems:
            debt.append(
                setup_debt_item(
                    scanner="javascript-native",
                    target=project.label,
                    command=None,
                    reason="unsupported target",
                    unsupported_target="package.json without lockfile",
                    suggested_next_action="Add a supported lockfile before dependency scanning: bun.lock, package-lock.json, yarn.lock, or pnpm-lock.yaml",
                )
            )

        git_label = relpath(project.git_root or project.path, workspace_root)
        for finding in osv_by_git_root.get(git_label, []):
            eco = str(finding.get("ecosystem", "")).lower()
            if eco in {"npm", "javascript", "node.js", "node"} and "npm" in ecosystems:
                findings.append(finding)
            elif eco in {"pypi", "python"} and "python" in ecosystems:
                findings.append(finding)
            elif eco in {"crates.io", "rust"} and "rust" in ecosystems:
                findings.append(finding)
            elif eco in {"go", "golang"} and "go" in ecosystems:
                findings.append(finding)
            elif eco in {"maven", "jvm"} and "jvm" in ecosystems:
                findings.append(finding)
            elif eco not in {"npm", "javascript", "node.js", "node", "pypi", "python", "crates.io", "rust", "go", "golang", "maven", "jvm"}:
                findings.append(finding)

        if js_enabled and "npm" in ecosystems:
            native, native_debt, js_stats = scan_js_project(project, artifact_dir, config)
            findings.extend(native)
            debt.extend(native_debt)
            stats["commands"].extend(js_stats.get("commands", []))
            for key, value in js_stats.items():
                if key == "commands":
                    continue
                stats["javascript"][key] += value

        if python_enabled and "python" in ecosystems:
            native, native_debt, py_stats = scan_python_project(project, artifact_dir, config)
            findings.extend(native)
            debt.extend(native_debt)
            stats["commands"].extend(py_stats.get("commands", []))
            for key, value in py_stats.items():
                if key in {"commands", "enabled"}:
                    continue
                stats["python"][key] += value

        if rust_enabled and "rust" in ecosystems:
            native, native_debt, rust_stats = scan_rust_project(project, artifact_dir, config)
            findings.extend(native)
            debt.extend(native_debt)
            stats["commands"].extend(rust_stats.get("commands", []))
            for key, value in rust_stats.items():
                if key in {"commands", "enabled"}:
                    continue
                stats["rust"][key] += value

        # Add Trivy after ecosystem-native dependency scanners so duplicate
        # dependency advisories keep the more specific native/OSV source while
        # preserving Trivy-only secret, misconfiguration, and license findings.
        findings.extend(trivy_by_git_root.get(git_label, []))
        findings.extend(ci_by_project.get(project.label, []))
        findings.extend(semgrep_by_git_root.get(git_label, []))
        findings.extend(sbom_by_git_root.get(git_label, []))
        findings.extend(scorecard_by_git_root.get(git_label, []))
        findings.extend(guarddog_by_project.get(project.label, []))

        if "container" in ecosystems and bool(cfg_get(config, "engines.containers.enabled", False)) and not shutil.which("trivy"):
            stats["containers"]["scanner_missing"] = True
            debt.append(
                setup_debt_item(
                    scanner="trivy",
                    target=project.label,
                    command=cfg_get(config, "engines.containers.command", "trivy"),
                    reason="missing binary",
                    missing_binary=str(cfg_get(config, "engines.containers.command", "trivy")),
                    suggested_next_action="Install trivy or disable engines.containers.enabled",
                )
            )

        project_paths[project.label] = project.path
        project_findings = dedupe_findings(findings)
        project_findings, filtered_count = filter_findings_by_severity(
            project_findings,
            str(cfg_get(config, "scan.severity_threshold", "low") or "low"),
        )
        stats["filtered_by_severity"] += filtered_count
        results.append(
            {
                "label": project.label,
                "git_root": git_label,
                "ecosystems": ecosystems,
                "findings": project_findings,
                "setup_debt": debt,
            }
        )

    represented_git_labels = {result["git_root"] for result in results}
    for git_root in git_roots:
        git_label = relpath(git_root, workspace_root)
        root_findings = dedupe_findings(semgrep_by_git_root.get(git_label, []) + sbom_by_git_root.get(git_label, []) + scorecard_by_git_root.get(git_label, []))
        root_findings, filtered_count = filter_findings_by_severity(
            root_findings,
            str(cfg_get(config, "scan.severity_threshold", "low") or "low"),
        )
        stats["filtered_by_severity"] += filtered_count
        if git_label in represented_git_labels or not root_findings:
            continue
        project_paths[git_label] = git_root
        results.append(
            {
                "label": git_label,
                "git_root": git_label,
                "ecosystems": ["source"],
                "findings": root_findings,
                "setup_debt": [],
            }
        )

    if not secret_scan_enabled:
        secret_findings: list[dict[str, Any]] = []
        stats["secrets"] = {"enabled": False}
    else:
        secret_projects = list(projects)
        known_secret_paths = {project.path.resolve() for project in secret_projects}
        for git_root in git_roots:
            if git_root.resolve() not in known_secret_paths:
                secret_projects.append(ProjectRoot(path=git_root, label=relpath(git_root, workspace_root), git_root=git_root, files=set()))
        secret_findings, secret_stats = scan_secrets(secret_projects, workspace_root, config)
        stats["secrets"] = secret_stats
        gitleaks_findings, gitleaks_stats = scan_gitleaks_git_roots(git_roots, workspace_root, config, artifact_dir)
        stats["gitleaks"] = gitleaks_stats
        stats["commands"].extend(gitleaks_stats.get("commands", []))
        stats["mode_setup_debt"].extend(gitleaks_stats.get("setup_debt", []))
        secret_findings.extend(gitleaks_findings)
        trufflehog_findings, trufflehog_stats = scan_trufflehog_git_roots(git_roots, workspace_root, config, artifact_dir)
        stats["trufflehog"] = trufflehog_stats
        stats["commands"].extend(trufflehog_stats.get("commands", []))
        stats["mode_setup_debt"].extend(trufflehog_stats.get("setup_debt", []))
        secret_findings.extend(trufflehog_findings)
        secret_findings = dedupe_findings(secret_findings)
        secret_findings, filtered_count = filter_findings_by_severity(
            secret_findings,
            str(cfg_get(config, "scan.severity_threshold", "low") or "low"),
        )
        stats["filtered_by_severity"] += filtered_count
    if image_findings:
        image_findings, filtered_count = filter_findings_by_severity(
            image_findings,
            str(cfg_get(config, "scan.severity_threshold", "low") or "low"),
        )
        stats["filtered_by_severity"] += filtered_count
    if image_findings:
        results.append(
            {
                "label": "__images__",
                "git_root": "__images__",
                "ecosystems": ["container-image"],
                "findings": image_findings,
                "setup_debt": [],
            }
        )

    skipped: list[dict[str, Any]] = []
    if not args.no_tracker:
        tracker_path_value = args.tracker_path or cfg_get(config, "tracker.path")
        tracker_path = Path(os.path.expandvars(str(tracker_path_value))).expanduser() if tracker_path_value else None
        tracker = load_tracker(tracker_path)
        retry_after_days = int(cfg_get(config, "tracker.retry_blocked_after_days", 30) or 30)
        results, skipped = filter_with_tracker(
            results,
            tracker,
            retry_after_days,
            skip_known_unfixable=bool(cfg_get(config, "tracker.skip_known_unfixable", True)),
        )

    stats["duration_seconds"] = round(time.time() - started, 2)
    if scan_mode == "remediation-prep":
        remediation = {"enabled": False, "skipped": "remediation-prep mode is read-only"}
        remediation_prep = build_remediation_prep(results, secret_findings)
    else:
        remediation = run_codex_remediation(results, project_paths, config, artifact_dir)
        if remediation.get("completed"):
            remediation["verification"] = verify_after_remediation(
                original_results=results,
                project_paths=project_paths,
                args=args,
                artifact_dir=artifact_dir,
                scan_mode=scan_mode,
            )
        remediation_prep = None
    summary = build_summary(
        results,
        secret_findings,
        stats,
        skipped,
        artifact_dir,
        scope_report,
        remediation,
        skipped_targets,
        requested_modes={
            "dependencies": dependency_scan_enabled,
            "secrets": secret_scan_enabled,
            "ci": ci_scan_enabled,
            "sast": sast_scan_enabled,
            "sbom": sbom_scan_enabled,
            "hygiene": hygiene_scan_enabled,
            "supply_chain": supply_chain_scan_enabled,
        },
    )
    if remediation_prep is not None:
        summary["remediation_prep"] = remediation_prep
    raw_path = artifact_dir / "summary.json"
    raw_path.write_text(json.dumps(summary, indent=2, sort_keys=True), encoding="utf-8")
    write_and_print_summary(summary, args, config)
    if args.fail_on_scope_violation and summary.get("scope", {}).get("out_of_scope_count", 0):
        return 2
    if args.fail_on_findings and summary["finding_count"]:
        return 1
    return 0
</file>

<file path="scripts/vulnscan/parsers/containers.py">
"""Container and filesystem scanner parser adapters."""

from __future__ import annotations

from typing import Any

from .secrets import normalize_secret_finding
from .utils import dedupe_findings, first_reference_url, normalize_dependency_finding, normalize_finding


def parse_trivy(data: Any, source_label: str, *, include_package_licenses: bool = True) -> tuple[list[dict[str, Any]], str | None]:
    if data is None or not isinstance(data, dict):
        return [], "parse_failed"
    results = data.get("Results") or data.get("results") or []
    if not isinstance(results, list):
        return [], "parse_failed"
    findings: list[dict[str, Any]] = []
    for result in results:
        if not isinstance(result, dict):
            continue
        target = result.get("Target") or result.get("target") or source_label
        result_class = str(result.get("Class") or result.get("class") or "").lower()
        result_type = result.get("Type") or result.get("type")

        for vuln in result.get("Vulnerabilities") or result.get("vulnerabilities") or []:
            if not isinstance(vuln, dict):
                continue
            findings.append(
                normalize_dependency_finding(
                    {
                        "source_engine": "trivy",
                        "source_label": source_label,
                        "category": "dependency",
                        "package": vuln.get("PkgName") or vuln.get("pkgName") or "unknown",
                        "ecosystem": result_type or result_class or "unknown",
                        "installed_version": vuln.get("InstalledVersion") or vuln.get("installedVersion"),
                        "fixed_version": vuln.get("FixedVersion") or vuln.get("fixedVersion"),
                        "severity": vuln.get("Severity") or vuln.get("severity"),
                        "advisory_id": vuln.get("VulnerabilityID") or vuln.get("vulnerabilityID"),
                        "title": vuln.get("Title") or vuln.get("title") or vuln.get("Description") or vuln.get("description"),
                        "url": first_reference_url(vuln),
                        "file": target,
                    }
                )
            )

        for secret in result.get("Secrets") or result.get("secrets") or []:
            if not isinstance(secret, dict):
                continue
            findings.append(
                normalize_secret_finding(
                    {
                        "source_engine": "trivy",
                        "source_label": source_label,
                        "type": secret.get("RuleID") or secret.get("ruleID") or secret.get("Category") or "secret",
                        "severity": secret.get("Severity") or secret.get("severity"),
                        "title": secret.get("Title") or secret.get("title") or secret.get("RuleID") or "Secret detected",
                        "file": target,
                        "line": secret.get("StartLine") or secret.get("startLine"),
                        "remediation_hint": "Rotate the credential if real, remove it from tracked files, and consider history cleanup.",
                    }
                )
            )

        for misconfig in result.get("Misconfigurations") or result.get("misconfigurations") or []:
            if not isinstance(misconfig, dict):
                continue
            findings.append(
                normalize_finding(
                    {
                        "source_engine": "trivy",
                        "source_label": source_label,
                        "severity": misconfig.get("Severity") or misconfig.get("severity"),
                        "advisory_id": misconfig.get("ID") or misconfig.get("id"),
                        "title": misconfig.get("Title") or misconfig.get("title") or misconfig.get("Message") or misconfig.get("message"),
                        "url": misconfig.get("PrimaryURL") or misconfig.get("primaryURL"),
                        "file": target,
                        "line": misconfig.get("CauseMetadata", {}).get("StartLine") if isinstance(misconfig.get("CauseMetadata"), dict) else None,
                        "remediation_hint": misconfig.get("Resolution") or misconfig.get("resolution"),
                    },
                    category="misconfiguration",
                    confidence="scanner_rule",
                )
            )

        if not include_package_licenses:
            continue

        for package in result.get("Packages") or result.get("packages") or []:
            if not isinstance(package, dict):
                continue
            for license_item in package.get("Licenses") or package.get("licenses") or []:
                if not isinstance(license_item, dict):
                    if isinstance(license_item, str):
                        license_item = {"Name": license_item}
                    else:
                        continue
                severity = license_item.get("Severity") or license_item.get("severity") or "UNKNOWN"
                findings.append(
                    normalize_finding(
                        {
                            "source_engine": "trivy",
                            "source_label": source_label,
                            "package": package.get("Name") or package.get("name"),
                            "installed_version": package.get("Version") or package.get("version"),
                            "severity": severity,
                            "title": license_item.get("Name") or license_item.get("name") or "License finding",
                            "advisory_id": license_item.get("Name") or license_item.get("name"),
                            "file": target,
                        },
                        category="license",
                        confidence="scanner_rule",
                    )
                )
    return dedupe_findings(findings), None
</file>

<file path="scripts/vulnscan/discovery.py">
"""Target discovery and scope gates for the vulnerability scanner."""

from __future__ import annotations

import fnmatch
import json
import os
from dataclasses import dataclass, field
from pathlib import Path

DEFAULT_EXCLUDE_GLOBS = [
    "**/.git/**",
    "**/node_modules/**",
    "**/.next/**",
    "**/.next-dev/**",
    "**/.nuxt/**",
    "**/.svelte-kit/**",
    "**/.vite/**",
    "**/.turbo/**",
    "**/.cache/**",
    "**/coverage/**",
    "**/dist/**",
    "**/build/**",
    "**/out/**",
    "**/target/**",
    "**/vendor/**",
    "**/fixtures/**",
    "**/mocks/**",
    "**/examples/**",
    "**/example/**",
    "**/docs/**",
    "**/archive/**",
    "**/archived-clones/**",
    "**/.claude/worktrees/**",
    "**/context/**",
    "**/references/**",
    "**/.developer/skills/**",
    "**/config/skills/**",
    "**/scripts/docker/**",
]

NOISE_DIR_NAMES = {
    ".git",
    "node_modules",
    ".next",
    ".next-dev",
    ".nuxt",
    ".svelte-kit",
    ".vite",
    ".turbo",
    ".cache",
    "coverage",
    "dist",
    "build",
    "out",
    "target",
    "vendor",
    "fixtures",
    "mocks",
    "examples",
    "example",
    "docs",
    "archive",
    "archived-clones",
}

JS_LOCKS = {"bun.lock", "bun.lockb", "package-lock.json", "yarn.lock", "pnpm-lock.yaml"}
PY_MANIFESTS = {"requirements.txt", "pyproject.toml", "poetry.lock", "Pipfile.lock"}
RUST_MANIFESTS = {"Cargo.toml", "Cargo.lock"}
GO_MANIFESTS = {"go.mod"}
RUBYGEMS_MANIFESTS = {"Gemfile.lock"}
JVM_MANIFESTS = {"pom.xml", "build.gradle", "build.gradle.kts"}
CONTAINER_MANIFESTS = {"Dockerfile", "Containerfile", "docker-compose.yml", "docker-compose.yaml"}
IAC_EXTENSIONS = {".tf", ".tfvars"}
IAC_FILENAMES = {"Chart.yaml", "kustomization.yaml", "kustomization.yml"}
WORKFLOW_EXTENSIONS = {".yml", ".yaml"}


@dataclass
class ProjectRoot:
    path: Path
    label: str
    git_root: Path | None
    files: set[str] = field(default_factory=set)
    target_types: set[str] = field(default_factory=set)

    @property
    def ecosystems(self) -> set[str]:
        out: set[str] = set()
        if "package.json" in self.files and (self.files & JS_LOCKS):
            out.add("npm")
        if "javascript-no-lockfile" in self.target_types:
            out.add("javascript-no-lockfile")
        if self.files & PY_MANIFESTS:
            out.add("python")
        if self.files & RUST_MANIFESTS:
            out.add("rust")
        if self.files & GO_MANIFESTS:
            out.add("go")
        if self.files & RUBYGEMS_MANIFESTS:
            out.add("rubygems")
        if self.files & JVM_MANIFESTS:
            out.add("jvm")
        if self.files & CONTAINER_MANIFESTS:
            out.add("container")
        out.update(self.target_types)
        return out


@dataclass
class DiscoveryResult:
    projects: list[ProjectRoot]
    skipped_targets: list[dict[str, str]]


def relpath(path: Path, root: Path) -> str:
    try:
        return str(path.resolve().relative_to(root.resolve()))
    except ValueError:
        return str(path)


def is_under(path: Path, root: Path) -> bool:
    try:
        path.resolve().relative_to(root.resolve())
        return True
    except ValueError:
        return False


def matches_any(path: Path, root: Path, patterns: list[str]) -> bool:
    rel = relpath(path, root)
    candidates = [rel, rel + "/", str(path)]
    return any(fnmatch.fnmatch(candidate, pattern) for candidate in candidates for pattern in patterns)


def find_git_root(path: Path, workspace_root: Path) -> Path | None:
    cur = path.resolve()
    root = workspace_root.resolve()
    while True:
        if (cur / ".git").exists():
            return cur
        if cur == root or cur.parent == cur:
            return None
        cur = cur.parent


def package_json_has_real_content(path: Path) -> bool:
    try:
        data = json.loads((path / "package.json").read_text(encoding="utf-8"))
    except Exception:
        return False
    for key in ("dependencies", "devDependencies", "peerDependencies", "optionalDependencies", "scripts"):
        value = data.get(key)
        if isinstance(value, dict) and value:
            return True
    return bool(data.get("name"))


def package_json_is_vscode_extension(path: Path) -> bool:
    try:
        data = json.loads((path / "package.json").read_text(encoding="utf-8"))
    except Exception:
        return False
    engines = data.get("engines")
    categories = data.get("categories")
    contributes = data.get("contributes")
    return (
        isinstance(engines, dict)
        and "vscode" in engines
    ) or bool(contributes) or (
        isinstance(categories, list)
        and any(str(category).lower() == "extension packs" for category in categories)
    )


def has_iac_target(files: set[str]) -> bool:
    for filename in files:
        if filename in IAC_FILENAMES:
            return True
        suffix = Path(filename).suffix.lower()
        if suffix in IAC_EXTENSIONS:
            return True
        if suffix in {".yaml", ".yml"}:
            lower = filename.lower()
            if any(token in lower for token in ("k8s", "kubernetes", "deployment", "service", "ingress", "helm")):
                return True
    return False


def has_workflow_target(path: Path, root: Path, files: set[str]) -> bool:
    rel_parts = path.resolve().relative_to(root.resolve()).parts if is_under(path, root) else path.parts
    if len(rel_parts) < 2 or rel_parts[-2:] != (".github", "workflows"):
        return False
    return any(Path(filename).suffix.lower() in WORKFLOW_EXTENSIONS for filename in files)


def discover_projects(root: Path, max_depth: int, exclude_globs: list[str] | None = None) -> DiscoveryResult:
    projects: dict[Path, ProjectRoot] = {}
    skipped: list[dict[str, str]] = []
    root = root.resolve()
    exclude_globs = exclude_globs or DEFAULT_EXCLUDE_GLOBS
    for dirpath, dirnames, filenames in os.walk(root):
        path = Path(dirpath)
        try:
            depth = len(path.relative_to(root).parts)
        except ValueError:
            depth = 0
        kept_dirnames: list[str] = []
        for dirname in dirnames:
            child = path / dirname
            if dirname in NOISE_DIR_NAMES:
                skipped.append({"target": relpath(child, root), "reason": f"noise_dir:{dirname}"})
                continue
            if matches_any(child, root, exclude_globs):
                skipped.append({"target": relpath(child, root), "reason": "excluded_by_filter"})
                continue
            kept_dirnames.append(dirname)
        dirnames[:] = kept_dirnames
        if depth > max_depth:
            skipped.append({"target": relpath(path, root), "reason": "beyond_max_depth"})
            dirnames[:] = []
            continue
        if matches_any(path, root, exclude_globs):
            skipped.append({"target": relpath(path, root), "reason": "excluded_by_filter"})
            continue
        files = set(filenames)
        has_js_manifest = "package.json" in files and package_json_has_real_content(path)
        has_js = has_js_manifest and bool(files & JS_LOCKS)
        has_js_without_lockfile = has_js_manifest and not bool(files & JS_LOCKS)
        has_vscode = "package.json" in files and package_json_is_vscode_extension(path)
        has_py = bool(files & PY_MANIFESTS)
        has_rust = bool(files & RUST_MANIFESTS)
        has_container = bool(files & CONTAINER_MANIFESTS)
        has_go = bool(files & GO_MANIFESTS)
        has_rubygems = bool(files & RUBYGEMS_MANIFESTS)
        has_jvm = bool(files & JVM_MANIFESTS)
        has_iac = has_iac_target(files)
        has_workflow = has_workflow_target(path, root, files)
        target_types: set[str] = set()
        if has_iac:
            target_types.add("iac")
        if has_workflow:
            target_types.add("ci")
        if has_vscode:
            target_types.add("vscode")
        if has_js_without_lockfile:
            target_types.add("javascript-no-lockfile")
        if not (has_js or has_js_without_lockfile or has_py or has_rust or has_container or has_go or has_rubygems or has_jvm or has_iac or has_workflow or has_vscode):
            continue
        projects[path] = ProjectRoot(
            path=path,
            label=relpath(path, root),
            git_root=find_git_root(path, root),
            files=files,
            target_types=target_types,
        )
    return DiscoveryResult(
        projects=sorted(projects.values(), key=lambda p: p.label),
        skipped_targets=sorted(skipped, key=lambda item: item["target"]),
    )


def discover_git_roots(projects: list[ProjectRoot], root: Path) -> list[Path]:
    seen: dict[Path, Path] = {}
    for project in projects:
        git_root = project.git_root or project.path
        seen[git_root.resolve()] = git_root
    return [seen[k] for k in sorted(seen, key=lambda p: relpath(p, root))]


def build_scope_report(
    projects: list[ProjectRoot],
    workspace_root: Path,
    allowed_roots: list[Path],
    allowed_label_prefixes: list[str],
    forbidden_label_prefixes: list[str],
) -> dict[str, object]:
    out_of_scope: list[dict[str, str]] = []
    for project in projects:
        reasons: list[str] = []
        if allowed_roots and not any(is_under(project.path, root) for root in allowed_roots):
            reasons.append("outside_allowed_roots")
        if allowed_label_prefixes and not any(project.label == prefix.rstrip("/") or project.label.startswith(prefix) for prefix in allowed_label_prefixes):
            reasons.append("label_missing_allowed_prefix")
        if forbidden_label_prefixes and any(project.label == prefix.rstrip("/") or project.label.startswith(prefix) for prefix in forbidden_label_prefixes):
            reasons.append("label_has_forbidden_prefix")
        if reasons:
            out_of_scope.append(
                {
                    "label": project.label,
                    "path": str(project.path),
                    "reason": ",".join(reasons),
                }
            )
    return {
        "workspace_root": str(workspace_root),
        "allowed_roots": [str(root) for root in allowed_roots],
        "allowed_label_prefixes": allowed_label_prefixes,
        "forbidden_label_prefixes": forbidden_label_prefixes,
        "out_of_scope_count": len(out_of_scope),
        "out_of_scope_projects": out_of_scope,
    }
</file>

<file path="scripts/vulnscan/secrets.py">
"""Secret scanner runners and metadata-only fallback scanning."""

from __future__ import annotations

import json
import os
import re
import shutil
import tempfile
from pathlib import Path
from typing import Any

from .common import command_record, run, setup_debt_item, stable_id
from .config import cfg_get
from .discovery import NOISE_DIR_NAMES, ProjectRoot, relpath
from .parsers import dedupe_findings, normalize_secret_finding, parse_gitleaks, parse_trufflehog_lines

SECRET_PATTERNS = [
    ("aws_access_key", re.compile(r"AKIA[0-9A-Z]{16}")),
    ("gcp_api_key", re.compile(r"AIza[0-9A-Za-z_\-]{35}")),
    ("openai_or_anthropic_key", re.compile(r"\bsk-[A-Za-z0-9][A-Za-z0-9_\-]{24,}\b")),
    ("openrouter_key", re.compile(r"\bsk-or-[A-Za-z0-9_\-]{24,}\b")),
    ("xai_key", re.compile(r"\bxai-[A-Za-z0-9_\-]{24,}\b")),
    ("github_token", re.compile(r"\bgh[pousr]_[A-Za-z0-9_]{16,}\b")),
    ("gitlab_token", re.compile(r"\bglpat-[A-Za-z0-9_\-]{20,}\b")),
    ("resend_key", re.compile(r"\bresend_[A-Za-z0-9_\-]{20,}\b")),
]

TEXT_EXTENSIONS = {
    ".env",
    ".txt",
    ".md",
    ".json",
    ".yaml",
    ".yml",
    ".toml",
    ".ini",
    ".conf",
    ".js",
    ".jsx",
    ".ts",
    ".tsx",
    ".py",
    ".rb",
    ".go",
    ".rs",
    ".java",
    ".php",
    ".sh",
    ".bash",
    ".zsh",
    ".pem",
    ".key",
    ".p12",
    ".crt",
    ".mobileprovision",
}


def tracked_by_git(path: Path, git_root: Path | None) -> bool:
    if not git_root:
        return False
    rel = relpath(path, git_root)
    result = run(["git", "ls-files", "--error-unmatch", rel], cwd=git_root, timeout=10)
    return result["code"] == 0


def classify_secret(path: Path, git_root: Path | None) -> str:
    name = path.name.lower()
    full = str(path).lower()
    tracked = tracked_by_git(path, git_root)
    if name.startswith(".env") and "example" not in name and tracked:
        return "critical"
    if any(part in full for part in ["/test/", "/tests/", "/fixture", "/fixtures/", "/mock", "/mocks/", "/example", "/examples/", "/docs/"]):
        return "review"
    if "example" in name or "sample" in name or "placeholder" in full:
        return "review"
    if tracked:
        return "high"
    return "info"


def should_secret_scan_file(path: Path) -> bool:
    if path.name.startswith(".env"):
        return True
    if path.suffix.lower() in TEXT_EXTENSIONS:
        return True
    return False


def scan_secrets(projects: list[ProjectRoot], workspace_root: Path, config: dict[str, Any]) -> tuple[list[dict[str, Any]], dict[str, Any]]:
    stats = {"enabled": bool(cfg_get(config, "engines.secrets.enabled", True)), "files_scanned": 0, "findings": 0}
    findings: list[dict[str, Any]] = []
    if not stats["enabled"]:
        return findings, stats
    scanned_files: set[Path] = set()
    for project in projects:
        for dirpath, dirnames, filenames in os.walk(project.path):
            path = Path(dirpath)
            dirnames[:] = [d for d in dirnames if d not in NOISE_DIR_NAMES]
            for filename in filenames:
                file_path = path / filename
                if file_path in scanned_files or not should_secret_scan_file(file_path):
                    continue
                scanned_files.add(file_path)
                try:
                    if file_path.stat().st_size > 512_000:
                        continue
                    text = file_path.read_text(encoding="utf-8", errors="ignore")
                except Exception:
                    continue
                stats["files_scanned"] += 1
                for line_no, line in enumerate(text.splitlines(), 1):
                    for kind, pattern in SECRET_PATTERNS:
                        if pattern.search(line):
                            git_tracked = tracked_by_git(file_path, project.git_root)
                            findings.append(
                                normalize_secret_finding(
                                    {
                                        "source_engine": "secret-patterns",
                                        "source_label": project.label,
                                        "type": kind,
                                        "severity": classify_secret(file_path, project.git_root),
                                        "title": f"{kind} pattern detected",
                                        "file": relpath(file_path, workspace_root),
                                        "line": line_no,
                                        "git_tracked": git_tracked,
                                        "verification_state": "unverified",
                                        "confidence": "detected_pattern",
                                        "remediation_hint": (
                                            "Tracked secret-like material needs human review, rotation if real, removal from tracked files, and possible history cleanup."
                                            if git_tracked
                                            else "Review the match and rotate the credential if it is real."
                                        ),
                                    }
                                )
                            )
                            break
    stats["findings"] = len(findings)
    return dedupe_findings(findings), stats


def scan_gitleaks_git_roots(git_roots: list[Path], workspace_root: Path, config: dict[str, Any], artifact_dir: Path) -> tuple[list[dict[str, Any]], dict[str, Any]]:
    stats: dict[str, Any] = {
        "enabled": bool(cfg_get(config, "engines.gitleaks.enabled", True)),
        "missing": False,
        "current_ran": 0,
        "history_ran": 0,
        "findings": 0,
        "clean": 0,
        "timeout": 0,
        "parse_failed": 0,
        "commands": [],
        "setup_debt": [],
    }
    findings: list[dict[str, Any]] = []
    if not stats["enabled"]:
        return findings, stats

    command = str(cfg_get(config, "engines.gitleaks.command", "gitleaks") or "gitleaks")
    binary = shutil.which(command)
    if not binary:
        stats["missing"] = True
        stats["setup_debt"].append(
            setup_debt_item(
                scanner="gitleaks",
                target=str(workspace_root),
                command=command,
                reason="missing binary",
                missing_binary=command,
                suggested_next_action="Install gitleaks or disable engines.gitleaks.enabled",
            )
        )
        return findings, stats

    scan_current = bool(cfg_get(config, "engines.gitleaks.scan_current", True))
    scan_history = bool(cfg_get(config, "engines.gitleaks.scan_history", True))
    timeout = int(cfg_get(config, "engines.gitleaks.timeout_seconds", 120))
    for git_root in git_roots:
        label = relpath(git_root, workspace_root)
        if scan_current:
            mode_findings = _run_gitleaks_mode(binary, "dir", git_root, label, artifact_dir, timeout, stats)
            findings.extend(mode_findings)
        if scan_history:
            mode_findings = _run_gitleaks_mode(binary, "git", git_root, label, artifact_dir, timeout, stats)
            findings.extend(mode_findings)

    stats["findings"] = len(findings)
    return dedupe_findings(findings), stats


def _run_gitleaks_mode(binary: str, mode: str, git_root: Path, label: str, artifact_dir: Path, timeout: int, stats: dict[str, Any]) -> list[dict[str, Any]]:
    safe_artifact = artifact_dir / "gitleaks" / f"{stable_id(label)}_{mode}.json"
    safe_artifact.parent.mkdir(parents=True, exist_ok=True)
    findings: list[dict[str, Any]] = []
    with tempfile.TemporaryDirectory(prefix="vuln-gitleaks-") as tmp:
        raw_artifact = Path(tmp) / "gitleaks.json"
        cmd = [binary, mode, str(git_root), "--report-format", "json", "--report-path", str(raw_artifact), "--exit-code", "0"]
        result = run(cmd, timeout=timeout)
        stats[f"{'current' if mode == 'dir' else 'history'}_ran"] += 1
        status = "completed"
        if result["code"] == 124:
            stats["timeout"] += 1
            status = "timed_out"
            stats["setup_debt"].append(
                setup_debt_item(
                    scanner="gitleaks",
                    target=label,
                    command=cmd,
                    reason="timeout",
                    timeout=timeout,
                    suggested_next_action="Retry with a higher engines.gitleaks.timeout_seconds value or run gitleaks directly",
                )
            )
        else:
            try:
                data = json.loads(raw_artifact.read_text(encoding="utf-8", errors="replace")) if raw_artifact.exists() and raw_artifact.stat().st_size else []
            except Exception as exc:
                data = {"error": f"json_decode:{exc}"}
            parsed, err = parse_gitleaks(data, label)
            for finding in parsed:
                file_value = finding.get("file")
                if mode == "git":
                    finding["git_tracked"] = True
                elif isinstance(file_value, str):
                    finding["git_tracked"] = tracked_by_git(git_root / file_value, git_root)
            safe_artifact.write_text(json.dumps(parsed, indent=2, sort_keys=True), encoding="utf-8")
            if err:
                stats["parse_failed"] += 1
                status = "parser_failed"
                stats["setup_debt"].append(
                    setup_debt_item(
                        scanner="gitleaks",
                        target=label,
                        command=cmd,
                        reason="parser failure",
                        parser_failure=err,
                        suggested_next_action="Inspect the sanitized Gitleaks artifact and update parse_gitleaks if the output format changed",
                    )
                )
            elif parsed:
                findings.extend(parsed)
            else:
                stats["clean"] += 1
        if not safe_artifact.exists():
            safe_artifact.write_text("[]\n", encoding="utf-8")
        stats["commands"].append(command_record(scanner="gitleaks", target=label, command=cmd, artifact=safe_artifact, status=status, exit_code=result["code"]))
    return findings


def scan_trufflehog_git_roots(git_roots: list[Path], workspace_root: Path, config: dict[str, Any], artifact_dir: Path) -> tuple[list[dict[str, Any]], dict[str, Any]]:
    stats: dict[str, Any] = {
        "enabled": bool(cfg_get(config, "engines.trufflehog.enabled", True)),
        "missing": False,
        "ran": 0,
        "findings": 0,
        "clean": 0,
        "timeout": 0,
        "parse_failed": 0,
        "commands": [],
        "setup_debt": [],
    }
    findings: list[dict[str, Any]] = []
    if not stats["enabled"]:
        return findings, stats

    command = str(cfg_get(config, "engines.trufflehog.command", "trufflehog") or "trufflehog")
    binary = shutil.which(command)
    if not binary:
        stats["missing"] = True
        stats["setup_debt"].append(
            setup_debt_item(
                scanner="trufflehog",
                target=str(workspace_root),
                command=command,
                reason="missing binary",
                missing_binary=command,
                suggested_next_action="Install trufflehog or disable engines.trufflehog.enabled",
            )
        )
        return findings, stats

    timeout = int(cfg_get(config, "engines.trufflehog.timeout_seconds", 300))
    only_verified = bool(cfg_get(config, "engines.trufflehog.only_verified", True))
    include_unverified = not only_verified
    for git_root in git_roots:
        label = relpath(git_root, workspace_root)
        artifact = artifact_dir / "trufflehog" / f"{stable_id(label)}.jsonl"
        cmd = [binary, "git", f"file://{git_root}", "--json"]
        if only_verified:
            cmd.append("--only-verified")
        result = run(cmd, timeout=timeout)
        stats["ran"] += 1
        status = "completed"
        if result["code"] == 124:
            stats["timeout"] += 1
            status = "timed_out"
            stats["setup_debt"].append(
                setup_debt_item(
                    scanner="trufflehog",
                    target=label,
                    command=cmd,
                    reason="timeout",
                    timeout=timeout,
                    suggested_next_action="Retry with a higher engines.trufflehog.timeout_seconds value or run trufflehog directly",
                )
            )
            artifact.parent.mkdir(parents=True, exist_ok=True)
            artifact.write_text("", encoding="utf-8")
        else:
            parsed, err = parse_trufflehog_lines(result["stdout"], label, include_unverified=include_unverified)
            artifact.parent.mkdir(parents=True, exist_ok=True)
            artifact.write_text("\n".join(json.dumps(item, sort_keys=True) for item in parsed) + ("\n" if parsed else ""), encoding="utf-8")
            if err:
                stats["parse_failed"] += 1
                status = "parser_failed"
                stats["setup_debt"].append(
                    setup_debt_item(
                        scanner="trufflehog",
                        target=label,
                        command=cmd,
                        reason="parser failure",
                        parser_failure=err,
                        suggested_next_action="Inspect the sanitized TruffleHog artifact and update parse_trufflehog_lines if the output format changed",
                    )
                )
            elif parsed:
                findings.extend(parsed)
            else:
                stats["clean"] += 1
        stats["commands"].append(command_record(scanner="trufflehog", target=label, command=cmd, artifact=artifact, status=status, exit_code=result["code"]))

    stats["findings"] = len(findings)
    return dedupe_findings(findings), stats
</file>

<file path="scripts/vulnscan/supply_chain.py">
"""Supply-chain package behavior scanner runners."""

from __future__ import annotations

import json
import shutil
import urllib.error
import urllib.request
from pathlib import Path
from typing import Any

from .common import command_record, run, setup_debt_item, stable_id
from .config import cfg_get
from .discovery import ProjectRoot
from .parsers import dedupe_findings, extract_json, parse_guarddog


GUARDDOG_ECOSYSTEMS = {"npm", "pypi", "go", "rubygems", "github_action", "extension"}
OSV_QUERY_URL = "https://api.osv.dev/v1/query"
OSV_PACKAGE_ECOSYSTEMS = {
    "npm": "npm",
    "pypi": "PyPI",
    "go": "Go",
    "rubygems": "RubyGems",
    "github_action": "GitHub Actions",
}


def scan_guarddog_projects(projects: list[ProjectRoot], config: dict[str, Any], artifact_dir: Path) -> tuple[dict[str, list[dict[str, Any]]], dict[str, Any]]:
    stats: dict[str, Any] = {
        "enabled": bool(cfg_get(config, "engines.guarddog.enabled", True)),
        "missing": False,
        "ran": 0,
        "clean": 0,
        "findings": 0,
        "timeout": 0,
        "parse_failed": 0,
        "error": 0,
        "unsupported": 0,
        "commands": [],
        "setup_debt": [],
    }
    findings_by_project: dict[str, list[dict[str, Any]]] = {}
    if not stats["enabled"]:
        return findings_by_project, stats
    command = str(cfg_get(config, "engines.guarddog.command", "guarddog") or "guarddog")
    binary = shutil.which(command)
    if not binary:
        stats["missing"] = True
        stats["setup_debt"].append(
            setup_debt_item(
                scanner="guarddog",
                target="__workspace__",
                command=command,
                reason="missing binary",
                missing_binary=command,
                suggested_next_action="Install guarddog or disable engines.guarddog.enabled",
            )
        )
        return findings_by_project, stats

    timeout = int(cfg_get(config, "engines.guarddog.timeout_seconds", 300))
    for project in projects:
        project_findings: list[dict[str, Any]] = []
        for ecosystem, target in guarddog_targets_for_project(project):
            findings = _run_guarddog(binary, ecosystem, "verify" if ecosystem != "extension" else "scan", target, project.label, config, artifact_dir, timeout, stats, cwd=project.git_root or project.path)
            project_findings.extend(findings)
        if project_findings:
            findings_by_project[project.label] = dedupe_findings(project_findings)
    return findings_by_project, stats


def guarddog_targets_for_project(project: ProjectRoot) -> list[tuple[str, Path]]:
    targets: list[tuple[str, Path]] = []
    ecosystems = project.ecosystems
    if "npm" in ecosystems and (project.path / "package.json").exists():
        targets.append(("npm", project.path / "package.json"))
    if "python" in ecosystems and (project.path / "requirements.txt").exists():
        targets.append(("pypi", project.path / "requirements.txt"))
    if "go" in ecosystems and (project.path / "go.mod").exists():
        targets.append(("go", project.path / "go.mod"))
    if "rubygems" in ecosystems and (project.path / "Gemfile.lock").exists():
        targets.append(("rubygems", project.path / "Gemfile.lock"))
    if "ci" in ecosystems:
        targets.extend(("github_action", path) for path in sorted(project.path.glob("*.yml")) + sorted(project.path.glob("*.yaml")))
    if "vscode" in ecosystems:
        targets.append(("extension", project.path))
    return targets


def run_guarddog_package_intake(
    ecosystem: str,
    package: str,
    config: dict[str, Any],
    artifact_dir: Path,
    *,
    version: str | None = None,
) -> tuple[dict[str, Any], dict[str, Any]]:
    stats: dict[str, Any] = {
        "enabled": bool(cfg_get(config, "engines.guarddog.enabled", True)),
        "missing": False,
        "ran": 0,
        "clean": 0,
        "findings": 0,
        "timeout": 0,
        "parse_failed": 0,
        "error": 0,
        "commands": [],
        "setup_debt": [],
    }
    ecosystem = ecosystem.lower()
    if ecosystem not in GUARDDOG_ECOSYSTEMS:
        stats["setup_debt"].append(
            setup_debt_item(
                scanner="guarddog",
                target=package,
                command=None,
                reason="unsupported target",
                unsupported_target=ecosystem,
                suggested_next_action=f"Use one of: {', '.join(sorted(GUARDDOG_ECOSYSTEMS))}",
            )
        )
        return package_intake_report(ecosystem, package, [], stats), stats
    if not stats["enabled"]:
        return package_intake_report(ecosystem, package, [], stats), stats
    command = str(cfg_get(config, "engines.guarddog.command", "guarddog") or "guarddog")
    binary = shutil.which(command)
    if not binary:
        stats["missing"] = True
        stats["setup_debt"].append(
            setup_debt_item(
                scanner="guarddog",
                target=package,
                command=command,
                reason="missing binary",
                missing_binary=command,
                suggested_next_action="Install guarddog before accepting new dependencies",
            )
        )
        return package_intake_report(ecosystem, package, [], stats), stats
    timeout = int(cfg_get(config, "engines.guarddog.timeout_seconds", 300))
    findings = _run_guarddog(binary, ecosystem, "scan", package, package, config, artifact_dir, timeout, stats, version=version)
    if bool(cfg_get(config, "package_intake.osv_api_enabled", False)):
        osv_findings = run_osv_package_query(ecosystem, package, artifact_dir, stats, version=version)
        findings.extend(osv_findings)
    return package_intake_report(ecosystem, package, findings, stats), stats


def run_osv_package_query(
    ecosystem: str,
    package: str,
    artifact_dir: Path,
    stats: dict[str, Any],
    *,
    version: str | None = None,
) -> list[dict[str, Any]]:
    osv_ecosystem = OSV_PACKAGE_ECOSYSTEMS.get(ecosystem)
    if not osv_ecosystem:
        stats.setdefault("setup_debt", []).append(
            setup_debt_item(
                scanner="osv-api",
                target=package,
                command=None,
                reason="unsupported target",
                unsupported_target=ecosystem,
                suggested_next_action="Run ecosystem-specific vulnerability lookup manually before accepting this package",
            )
        )
        return []

    payload: dict[str, Any] = {"package": {"name": package, "ecosystem": osv_ecosystem}}
    if version:
        payload["version"] = version
    body = json.dumps(payload).encode("utf-8")
    artifact = artifact_dir / "package-intake" / f"{stable_id('osv:' + ecosystem + ':' + package)}_osv.json"
    artifact.parent.mkdir(parents=True, exist_ok=True)
    request = urllib.request.Request(OSV_QUERY_URL, data=body, headers={"Content-Type": "application/json"}, method="POST")
    stats.setdefault("osv_api", {"ran": 0, "clean": 0, "findings": 0, "error": 0})
    stats["osv_api"]["ran"] += 1
    status = "completed"
    findings: list[dict[str, Any]] = []
    try:
        # OSV_QUERY_URL is a fixed scanner endpoint, not user-controlled input.
        with urllib.request.urlopen(request, timeout=30) as response:  # nosemgrep: python.lang.security.audit.dynamic-urllib-use-detected.dynamic-urllib-use-detected
            data = json.loads(response.read().decode("utf-8"))
    except (urllib.error.URLError, TimeoutError, json.JSONDecodeError) as exc:
        stats["osv_api"]["error"] += 1
        status = "scanner_failed"
        stats.setdefault("setup_debt", []).append(
            setup_debt_item(
                scanner="osv-api",
                target=package,
                command=f"POST {OSV_QUERY_URL}",
                reason="scanner failed",
                suggested_next_action="Retry OSV package query or run a local dependency scan after adding the package",
            )
        )
        artifact.write_text(json.dumps({"error": str(exc)}, indent=2, sort_keys=True), encoding="utf-8")
    else:
        artifact.write_text(json.dumps(data, indent=2, sort_keys=True), encoding="utf-8")
        findings = parse_osv_package_query(data, package, osv_ecosystem)
        if findings:
            stats["osv_api"]["findings"] += len(findings)
        else:
            stats["osv_api"]["clean"] += 1
    stats.setdefault("commands", []).append(
        command_record(
            scanner="osv-api",
            target=package,
            command=["POST", url],
            artifact=artifact,
            status=status,
            exit_code=0 if status == "completed" else 1,
        )
    )
    return findings


def parse_osv_package_query(data: Any, package: str, ecosystem: str) -> list[dict[str, Any]]:
    if not isinstance(data, dict):
        return []
    findings: list[dict[str, Any]] = []
    for vuln in data.get("vulns") or []:
        if not isinstance(vuln, dict):
            continue
        aliases = vuln.get("aliases") if isinstance(vuln.get("aliases"), list) else []
        references = vuln.get("references") if isinstance(vuln.get("references"), list) else []
        url = None
        for ref in references:
            if isinstance(ref, dict) and ref.get("url"):
                url = ref.get("url")
                break
        findings.append(
            {
                "source_engine": "osv-api",
                "category": "dependency",
                "severity": osv_query_severity(vuln),
                "confidence": "known_vulnerability",
                "package": package,
                "ecosystem": ecosystem,
                "advisory_id": vuln.get("id") or (aliases[0] if aliases else None),
                "title": vuln.get("summary") or vuln.get("details"),
                "url": url or (f"https://osv.dev/vulnerability/{vuln.get('id')}" if vuln.get("id") else None),
                "remediation_hint": "Review OSV advisory before accepting this package.",
            }
        )
    return findings


def osv_query_severity(vuln: dict[str, Any]) -> str:
    severities = vuln.get("severity") or []
    if isinstance(severities, list):
        for item in severities:
            if isinstance(item, dict):
                score = str(item.get("score") or "").upper()
                if score.startswith("CVSS:"):
                    continue
                for severity in ("CRITICAL", "HIGH", "MEDIUM", "LOW"):
                    if severity in score:
                        return severity
    database_specific = vuln.get("database_specific")
    if isinstance(database_specific, dict) and database_specific.get("severity"):
        text = str(database_specific.get("severity")).upper()
        if text == "MODERATE":
            return "MEDIUM"
        return text
    return "UNKNOWN"


def package_intake_report(ecosystem: str, package: str, findings: list[dict[str, Any]], stats: dict[str, Any]) -> dict[str, Any]:
    decision = "allow"
    if stats.get("setup_debt"):
        decision = "blocked pending review"
    elif any(finding.get("severity") in {"CRITICAL", "HIGH"} for finding in findings):
        decision = "avoid"
    elif findings:
        decision = "allow with caution"
    return {
        "ecosystem": ecosystem,
        "package": package,
        "decision": decision,
        "finding_count": len(findings),
        "findings": findings,
        "scanner_stats": stats,
    }


def _run_guarddog(
    binary: str,
    ecosystem: str,
    action: str,
    target: str | Path,
    label: str,
    config: dict[str, Any],
    artifact_dir: Path,
    timeout: int,
    stats: dict[str, Any],
    *,
    cwd: Path | None = None,
    version: str | None = None,
) -> list[dict[str, Any]]:
    target_text = str(target)
    artifact = artifact_dir / "supply-chain" / f"{stable_id(ecosystem + ':' + label + ':' + target_text)}_guarddog.json"
    cmd = [binary, ecosystem, action, target_text, "--output-format=json"]
    if version:
        cmd.extend(["--version", version])
    result = run(cmd, cwd=cwd, timeout=timeout, outfile=artifact)
    stats["ran"] += 1
    status = "completed"
    findings: list[dict[str, Any]] = []
    if result["code"] == 124:
        stats["timeout"] += 1
        status = "timed_out"
        stats["setup_debt"].append(
            setup_debt_item(
                scanner="guarddog",
                target=label,
                command=cmd,
                reason="timeout",
                timeout=timeout,
                suggested_next_action="Retry with a higher engines.guarddog.timeout_seconds value or run guarddog directly",
            )
        )
    else:
        data = extract_json(artifact.read_text(encoding="utf-8", errors="replace") if artifact.exists() else "")
        parsed, err = parse_guarddog(data, label, ecosystem=ecosystem)
        if err:
            stats["parse_failed"] += 1 if err == "parse_failed" else 0
            stats["error"] += 0 if err == "parse_failed" else 1
            status = "parser_failed" if err == "parse_failed" else "scanner_failed"
            stats["setup_debt"].append(
                setup_debt_item(
                    scanner="guarddog",
                    target=label,
                    command=cmd,
                    reason="parser failure" if err == "parse_failed" else "scanner failed",
                    parser_failure=err if err == "parse_failed" else None,
                    suggested_next_action="Inspect the GuardDog artifact and update parse_guarddog if the output format changed",
                )
            )
        elif parsed:
            stats["findings"] += len(parsed)
            findings = parsed
        else:
            stats["clean"] += 1
    stats["commands"].append(command_record(scanner="guarddog", target=label, command=cmd, cwd=cwd, artifact=artifact, status=status, exit_code=result["code"]))
    if findings and artifact.exists():
        artifact.write_text(json.dumps(findings, indent=2, sort_keys=True), encoding="utf-8")
    return findings
</file>

<file path="scripts/vulnscan/tracker.py">
"""Known vulnerability tracker filtering and retry rules."""

from __future__ import annotations

import json
import shutil
import tempfile
from datetime import datetime, timedelta, timezone
from pathlib import Path
from typing import Any


def load_tracker(path: Path | None) -> dict[str, Any]:
    if not path or not path.exists():
        return {"version": 1, "entries": []}
    try:
        return json.loads(path.read_text(encoding="utf-8"))
    except Exception as exc:
        backup = backup_tracker(path, "corrupt")
        return {"version": 1, "entries": [], "_tracker_recovery": {"status": "corrupt_recovered", "path": str(path), "backup": str(backup) if backup else None, "error": str(exc)}}


def backup_tracker(path: Path, label: str = "backup") -> Path | None:
    if not path.exists():
        return None
    backup = path.with_name(f"{path.name}.{label}.{datetime.now(timezone.utc).strftime('%Y%m%dT%H%M%SZ')}.bak")
    shutil.copy2(path, backup)
    return backup


def save_tracker_atomic(path: Path, tracker: dict[str, Any], *, same_engine_verified: bool) -> dict[str, Any]:
    if not same_engine_verified:
        return {"written": False, "reason": "same-engine verification required before tracker write"}
    path.parent.mkdir(parents=True, exist_ok=True)
    backup = backup_tracker(path, "prewrite")
    payload = json.dumps(tracker, indent=2, sort_keys=True) + "\n"
    with tempfile.NamedTemporaryFile("w", encoding="utf-8", dir=path.parent, delete=False) as tmp:
        tmp.write(payload)
        tmp_path = Path(tmp.name)
    tmp_path.replace(path)
    return {"written": True, "path": str(path), "backup": str(backup) if backup else None}


def parse_tracker_date(value: Any) -> datetime | None:
    if not isinstance(value, str) or not value.strip():
        return None
    text = value.strip()
    if text.endswith("Z"):
        text = text[:-1] + "+00:00"
    try:
        parsed = datetime.fromisoformat(text)
    except ValueError:
        return None
    if parsed.tzinfo is None:
        parsed = parsed.replace(tzinfo=timezone.utc)
    return parsed.astimezone(timezone.utc)


def tracker_retry_after_days(entry: dict[str, Any], default_days: int) -> int:
    value = entry.get("retry_after_days", default_days)
    try:
        days = int(value)
    except (TypeError, ValueError):
        return default_days
    return max(1, days)


def installed_version_changed(entry: dict[str, Any], finding: dict[str, Any]) -> bool:
    entry_version = entry.get("installed_version")
    finding_version = finding.get("installed_version")
    return bool(entry_version and finding_version and str(entry_version) != str(finding_version))


def tracker_entry_is_stale(entry: dict[str, Any], default_days: int, now: datetime | None = None) -> bool:
    checked = parse_tracker_date(entry.get("last_checked"))
    if checked is None:
        return True
    retry_after = tracker_retry_after_days(entry, default_days)
    now = now or datetime.now(timezone.utc)
    return checked + timedelta(days=retry_after) <= now


def tracker_match(label: str, finding: dict[str, Any], tracker: dict[str, Any]) -> dict[str, Any] | None:
    package = finding.get("package") or ""
    advisory = str(finding.get("advisory_id")) if finding.get("advisory_id") is not None else None
    title = (finding.get("title") or "").lower().strip()
    for entry in tracker.get("entries") or []:
        if entry.get("repo_label") != label or (entry.get("package") or "") != package:
            continue
        entry_advisory = str(entry.get("advisory_id")) if entry.get("advisory_id") is not None else None
        if advisory and entry_advisory and advisory == entry_advisory:
            return entry
        entry_title = (entry.get("title") or "").lower().strip()
        if title and entry_title and (title in entry_title or entry_title in title):
            return entry
    for entry in tracker.get("entries") or []:
        if entry.get("repo_label") != label or (entry.get("package") or "") != package:
            continue
        if entry.get("status") in {"fixed", "unfixable", "blocked_entire_repo"} or entry.get("blocked_entire_repo"):
            return entry
    return None


def filter_with_tracker(
    results: list[dict[str, Any]],
    tracker: dict[str, Any],
    retry_after_days: int = 30,
    *,
    skip_known_unfixable: bool = True,
) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]:
    actionable: list[dict[str, Any]] = []
    skipped: list[dict[str, Any]] = []
    for result in results:
        kept: list[dict[str, Any]] = []
        for finding in result.get("findings", []):
            match = tracker_match(result["label"], finding, tracker)
            if match and (match.get("status") in {"fixed", "unfixable", "blocked_entire_repo"} or match.get("blocked_entire_repo")):
                if match.get("status") == "unfixable" and not skip_known_unfixable:
                    kept.append(finding)
                    continue
                version_changed = installed_version_changed(match, finding)
                if version_changed or tracker_entry_is_stale(match, retry_after_days):
                    next_finding = dict(finding)
                    next_finding["tracker_retry"] = {
                        "previous_status": match.get("status") or ("blocked_entire_repo" if match.get("blocked_entire_repo") else "unknown"),
                        "last_checked": match.get("last_checked"),
                        "retry_after_days": tracker_retry_after_days(match, retry_after_days),
                        "installed_version_changed": version_changed,
                        "blocked_entire_repo": bool(match.get("blocked_entire_repo") or match.get("status") == "blocked_entire_repo"),
                    }
                    kept.append(next_finding)
                    continue
                skipped.append(
                    {
                        "repo": result["label"],
                        "package": finding.get("package"),
                        "reason": match.get("status") or "blocked_entire_repo",
                        "last_checked": match.get("last_checked"),
                        "retry_after_days": tracker_retry_after_days(match, retry_after_days),
                        "blocked_entire_repo": bool(match.get("blocked_entire_repo") or match.get("status") == "blocked_entire_repo"),
                    }
                )
                continue
            kept.append(finding)
        next_result = dict(result)
        next_result["findings"] = kept
        actionable.append(next_result)
    return actionable, skipped
</file>

<file path="scripts/validate-tools.sh">
#!/usr/bin/env bash
# validate-tools.sh - Report local scanner tool availability.
# Usage: ./scripts/validate-tools.sh [json|text] [--deep]

set -euo pipefail

FORMAT="${1:-text}"
DEEP="${2:-}"
SCRIPT_FILE="$(cd "$(dirname "$0")" && pwd)/vuln-scan.py"

if [[ "$FORMAT" != "text" && "$FORMAT" != "json" ]]; then
  echo "Usage: $0 [json|text] [--deep]" >&2
  exit 1
fi

if [[ -n "$DEEP" && "$DEEP" != "--deep" ]]; then
  echo "Usage: $0 [json|text] [--deep]" >&2
  exit 1
fi

if [[ ! -f "$SCRIPT_FILE" ]]; then
  echo "Scanner script not found: $SCRIPT_FILE" >&2
  exit 1
fi

if [[ "$DEEP" == "--deep" ]]; then
  python3 "$SCRIPT_FILE" validate-tools --format "$FORMAT" --deep
else
  python3 "$SCRIPT_FILE" validate-tools --format "$FORMAT"
fi
</file>

<file path="INSTALL.md">
# Install And Configure Vulnerability Scanning

This guide installs the local vulnerability-scanning skill for Hermes, Codex,
OpenClaw, or another agent runtime that can load a local `SKILL.md`.

The setup goal is:

- local-first scans by default
- read-only scan mode unless remediation is explicitly enabled
- artifacts and reports outside target repos
- tracker-backed nightly scans so known blocked/unfixable findings are not
  reprocessed every run
- scanner tool validation before the first real scan

## 1. Choose The Agent Runtime

Pick the skill directory for the runtime you want to use. If your runtime uses a
different skill path, replace the destination path and keep the directory name
`vulnerability-scanning`.

```bash
# Hermes
mkdir -p "$HOME/.hermes/skills/devops"
rsync -a --exclude .git ./ "$HOME/.hermes/skills/devops/vulnerability-scanning/"

# Codex
mkdir -p "$HOME/.codex/skills"
rsync -a --exclude .git ./ "$HOME/.codex/skills/vulnerability-scanning/"

# OpenClaw or another local agent runtime
mkdir -p "$HOME/.openclaw/skills"
rsync -a --exclude .git ./ "$HOME/.openclaw/skills/vulnerability-scanning/"
```

For a development checkout, you can also leave the repo in place and point the
agent directly at this directory. The important part is that the runtime can
read `SKILL.md`, `scripts/`, `templates/`, and `references/`.

## 2. Install Scanner Tools

Install the local scanner stack before running any scan:

```bash
brew install osv-scanner trivy gitleaks trufflehog semgrep actionlint syft grype zizmor scorecard
brew install pipx
pipx install --python python3.13 guarddog
pipx install pip-audit
cargo install cargo-audit
```

If Rust is not already installed, install it with `rustup` or Homebrew before
installing `cargo-audit`.

Verify OSV Scanner is on `PATH`:

```bash
osv-scanner --version
```

If GuardDog fails while building `pygit2`, install `libgit2` and retry with a
stable local Python:

```bash
brew install libgit2
pipx install --python python3.13 guarddog
```

Python and Rust scanners are optional unless you enable their engines in config.
Missing enabled tools are reported as setup debt, but the normal install target
is for enabled tools to validate cleanly.

## 3. Create Your Config

Copy the starter config to a local config path. Do not edit the template if you
want future updates to be easy to merge.

```bash
mkdir -p "$HOME/.hermes/vulnerability-scanning"
cp templates/config-starter.yaml "$HOME/.hermes/vulnerability-scanning/config.yaml"
```

For Codex or OpenClaw, the same config file can still live under
`$HOME/.hermes/vulnerability-scanning/config.yaml`. The scanner does not require
Hermes to read that file.

## 4. Answer The Setup Questions

Edit your config based on these choices.

### What workspace should be scanned?

Set `projects_root` to the broad workspace and use `scope.allowed_roots` for
the repos the agent is allowed to scan.

```yaml
projects_root: "$HOME/Developer/active"
scope:
  allowed_roots:
    - "$HOME/Developer/active"
```

For unattended scans, keep scope gates strict and run with
`--fail-on-scope-violation`.

### Do you want tracking/cache behavior?

Recommended: yes.

The tracker prevents the scanner and remediation agent from burning cycles on
the same fixed, blocked, or unfixable findings every nightly run. The default
retry window is 30 days.

```yaml
tracker:
  path: "$HOME/.hermes/vuln_knowledge.json"
  skip_known_unfixable: true
  retry_blocked_after_days: 30
```

Disable it only for one-off validation:

```bash
python3 scripts/vuln-scan.py scan ... --no-tracker
```

### Do you want Codex to auto-remediate?

Recommended default: no.

Keep scan mode read-only unless you explicitly want an agent to edit affected
repos.

```yaml
remediation:
  auto_fix: false
  codex:
    enabled: false
```

When you do want remediation, prefer an explicit command:

```bash
python3 scripts/vuln-scan.py scan \
  --config "$HOME/.hermes/vulnerability-scanning/config.yaml" \
  --root "$HOME/Developer/active" \
  --scan-mode remediation-prep \
  --format text
```

Then run with `--auto-remediate` only after reviewing the prep output:

```bash
python3 scripts/vuln-scan.py scan \
  --config "$HOME/.hermes/vulnerability-scanning/config.yaml" \
  --root "$HOME/Developer/active" \
  --scan-mode full \
  --auto-remediate \
  --artifact-dir /tmp/vuln-artifacts \
  --output /tmp/vuln-summary.json \
  --format text
```

### Do you want git-history secret scanning?

Recommended default for broad workspace scans: no.

Current-tree Gitleaks plus TruffleHog verified scans are useful in normal
`full` mode. Full history scanning can be slow on large repos, so enable it only
for deep secret audits or focused retests.

```yaml
engines:
  gitleaks:
    scan_current: true
    scan_history: false
```

Deep secret audit:

```yaml
engines:
  gitleaks:
    scan_current: true
    scan_history: true
```

### Do you want license findings?

Recommended default: no.

License findings are useful, but they should not bury vulnerability and security
findings in normal `full` output.

```yaml
engines:
  trivy:
    scanners: "vuln,misconfig,secret"
    image_scanners: "vuln,secret"
```

Use `--include-licenses` when the task is license review.

### Do you want package intake to call the OSV API?

Recommended default: no.

Package intake stays local-first unless this is enabled:

```yaml
package_intake:
  osv_api_enabled: false
```

Enable it only when public OSV API lookup is acceptable for pre-add package
review.

### Do you want Scorecard hygiene scans?

Recommended default: explicit only.

Scorecard can require network or GitHub/GitLab API behavior for complete
results. Keep it disabled in normal `full` scans and run hygiene explicitly.

```yaml
engines:
  scorecard:
    enabled: false
```

## 5. Validate Config And Tools

Run config validation:

```bash
./scripts/validate-config.sh "$HOME/.hermes/vulnerability-scanning/config.yaml"
```

The validator enforces safe remediation defaults only for
`templates/config-starter.yaml`. A copied local config may intentionally enable
`remediation.auto_fix` and `remediation.codex.enabled`; validation should warn,
not fail.

Validate installed tools:

```bash
python3 scripts/vuln-scan.py validate-tools \
  --config "$HOME/.hermes/vulnerability-scanning/config.yaml" \
  --format text
```

Run deep validation before the first real scan or after scanner upgrades:

```bash
python3 scripts/vuln-scan.py validate-tools \
  --config "$HOME/.hermes/vulnerability-scanning/config.yaml" \
  --format text \
  --deep
```

The install is ready when enabled tools are available and deep validation shows
`ok`, `built_in`, or `disabled` for every engine.

## 6. Run A Plan First

Plan mode discovers projects and scope without running scanner tools:

```bash
python3 scripts/vuln-scan.py plan \
  --config "$HOME/.hermes/vulnerability-scanning/config.yaml" \
  --root "$HOME/Developer/active" \
  --scan-mode full \
  --format text
```

Review:

- discovered project count
- git-root count
- skipped/noise paths
- scope violations
- unexpected package roots

## 7. Run The First Read-Only Scan

Write reports and artifacts outside target repos:

```bash
RUN_DIR="/tmp/vuln-scan-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$RUN_DIR"

python3 scripts/vuln-scan.py scan \
  --config "$HOME/.hermes/vulnerability-scanning/config.yaml" \
  --root "$HOME/Developer/active" \
  --allowed-root "$HOME/Developer/active" \
  --fail-on-scope-violation \
  --scan-mode full \
  --artifact-dir "$RUN_DIR/artifacts" \
  --output "$RUN_DIR/summary.json" \
  --format text
```

Use focused retests after changing one scanner or installing one tool:

```bash
python3 scripts/vuln-scan.py scan \
  --config "$HOME/.hermes/vulnerability-scanning/config.yaml" \
  --root "$HOME/Developer/active" \
  --scan-mode full \
  --only-engine trivy \
  --only-engine gitleaks,semgrep \
  --artifact-dir /tmp/vuln-focused-artifacts \
  --output /tmp/vuln-focused.json \
  --format text
```

## 8. Set Up Nightly Scans

Use the backwards-compatible wrapper for cron or launchd:

```bash
python3 scripts/nightly-vuln-scan.py scan \
  --config "$HOME/.hermes/vulnerability-scanning/config.yaml" \
  --root "$HOME/Developer/active" \
  --allowed-root "$HOME/Developer/active" \
  --fail-on-scope-violation \
  --scan-mode full \
  --artifact-dir "$HOME/.hermes/vulnerability-scanning/artifacts/nightly" \
  --output "$HOME/.hermes/vulnerability-scanning/nightly-summary.json" \
  --format text
```

For unattended nightly scans, keep:

- tracker enabled
- remediation disabled unless you intentionally want edits
- scope gates enabled
- artifact and output paths outside target repos
- Gitleaks history scanning disabled unless running a deep audit window

Clean unattended output may be exactly `[SILENT]` only when there are no
findings, no setup debt, no scope violations, and no scanner failures.

## 9. Tell Your Agent How To Use It

After installation, give your agent a task like:

```text
Use the vulnerability-scanning skill from the installed SKILL.md.
Before scanning, validate config and tools with validate-tools and --deep.
Use the local config at ~/.hermes/vulnerability-scanning/config.yaml.
Run read-only scans by default, write artifacts under /tmp or ~/.hermes/vulnerability-scanning/artifacts, and do not enable remediation unless I explicitly ask.
Use the tracker so known fixed, blocked, or unfixable findings are not repeated every nightly run.
Report findings, setup debt, coverage states, artifact paths, and the exact commands run.
```

## 10. Update Or Uninstall

To update an installed skill, sync the checkout back into the runtime skill
directory:

```bash
rsync -a --delete --exclude .git ./ "$HOME/.hermes/skills/devops/vulnerability-scanning/"
```

To uninstall, remove the copied skill directory. Keep or delete the config,
tracker, and artifacts separately depending on whether you want historical scan
state.

```bash
rm -rf "$HOME/.hermes/skills/devops/vulnerability-scanning"
```
</file>

<file path="LICENSE">
MIT License

Copyright (c) 2026 Vulnerability Scanning Skill Contributors

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
</file>

<file path="scripts/vulnscan/config.py">
"""Config loading and validation for the vulnerability scanner."""

from __future__ import annotations

import json
import os
from pathlib import Path
from typing import Any


def load_config(path: Path | None) -> dict[str, Any]:
    if not path:
        return {}
    text = path.read_text(encoding="utf-8")
    if path.suffix.lower() == ".json":
        return json.loads(text)
    try:
        import yaml  # type: ignore

        return yaml.safe_load(text) or {}
    except Exception:
        return parse_minimal_yaml(text)


def parse_minimal_yaml(text: str) -> dict[str, Any]:
    cleaned: list[tuple[int, str]] = []
    for raw in text.splitlines():
        line = raw.split("#", 1)[0].rstrip()
        if line.strip():
            cleaned.append((len(line) - len(line.lstrip(" ")), line.strip()))

    root: dict[str, Any] = {}
    stack: list[tuple[int, Any]] = [(-1, root)]

    for idx, (indent, stripped) in enumerate(cleaned):
        while stack and indent <= stack[-1][0]:
            stack.pop()
        parent = stack[-1][1]

        if stripped.startswith("- "):
            if isinstance(parent, list):
                parent.append(coerce_scalar(stripped[2:].strip()))
            continue

        if ":" not in stripped or not isinstance(parent, dict):
            continue

        key, value_raw = stripped.split(":", 1)
        key = key.strip()
        value_raw = value_raw.strip()
        if value_raw:
            parent[key] = coerce_scalar(value_raw)
            continue

        next_is_list = False
        if idx + 1 < len(cleaned):
            next_indent, next_stripped = cleaned[idx + 1]
            next_is_list = next_indent > indent and next_stripped.startswith("- ")
        value: Any = [] if next_is_list else {}
        parent[key] = value
        stack.append((indent, value))
    return root


def coerce_scalar(value: str) -> Any:
    if value.startswith("[") and value.endswith("]"):
        inner = value[1:-1].strip()
        if not inner:
            return []
        return [coerce_scalar(part.strip()) for part in inner.split(",")]
    if value in {"true", "True"}:
        return True
    if value in {"false", "False"}:
        return False
    if value in {"null", "None", "~"}:
        return None
    if (value.startswith('"') and value.endswith('"')) or (value.startswith("'") and value.endswith("'")):
        return value[1:-1]
    try:
        return int(value)
    except ValueError:
        return os.path.expandvars(value)


def cfg_get(config: dict[str, Any], path: str, default: Any = None) -> Any:
    cur: Any = config
    for part in path.split("."):
        if not isinstance(cur, dict) or part not in cur:
            return default
        cur = cur[part]
    return cur


def cfg_list(config: dict[str, Any], path: str) -> list[Any]:
    value = cfg_get(config, path, [])
    if value is None:
        return []
    if isinstance(value, list):
        return value
    return [value]


def normalize_roots(values: list[Any]) -> list[Path]:
    roots: list[Path] = []
    for value in values:
        if value is None:
            continue
        roots.append(Path(os.path.expandvars(str(value))).expanduser().resolve())
    return roots


def validate_config(config: dict[str, Any]) -> list[str]:
    errors: list[str] = []
    if not isinstance(config, dict):
        return ["config must be a mapping"]

    def require_mapping(path: str) -> None:
        value = cfg_get(config, path, {})
        if not isinstance(value, dict):
            errors.append(f"{path} must be a mapping")

    def require_bool(path: str) -> None:
        value = cfg_get(config, path)
        if value is not None and not isinstance(value, bool):
            errors.append(f"{path} must be true or false")

    def require_int(path: str, minimum: int = 0) -> None:
        value = cfg_get(config, path)
        if value is not None and (not isinstance(value, int) or value < minimum):
            errors.append(f"{path} must be an integer >= {minimum}")

    def require_string(path: str) -> None:
        value = cfg_get(config, path)
        if value is not None and not isinstance(value, str):
            errors.append(f"{path} must be a string")

    def require_list(path: str) -> list[Any]:
        value = cfg_get(config, path, [])
        if value is None:
            return []
        if not isinstance(value, list):
            errors.append(f"{path} must be a list")
            return []
        return value

    for path in ("scope", "scan", "package_intake", "engines", "filters", "tracker", "remediation"):
        require_mapping(path)

    allowed_roots = require_list("scope.allowed_roots")
    allowed_prefixes = [str(value).rstrip("/") for value in require_list("scope.allowed_label_prefixes")]
    forbidden_prefixes = [str(value).rstrip("/") for value in require_list("scope.forbidden_label_prefixes")]
    for idx, value in enumerate(allowed_roots):
        if not isinstance(value, str):
            errors.append(f"scope.allowed_roots[{idx}] must be a string path")
    for path in ("scope.allowed_label_prefixes", "scope.forbidden_label_prefixes", "filters.skip_paths"):
        for idx, value in enumerate(require_list(path)):
            if not isinstance(value, str):
                errors.append(f"{path}[{idx}] must be a string")
    overlap = sorted(set(allowed_prefixes) & set(forbidden_prefixes))
    if overlap:
        errors.append(f"scope allowed and forbidden label prefixes overlap: {', '.join(overlap)}")

    require_int("scan.max_depth", 0)
    require_bool("scan.silent_when_clean")
    threshold = cfg_get(config, "scan.severity_threshold")
    if threshold is not None and str(threshold).lower() not in {"none", "low", "medium", "high", "critical"}:
        errors.append("scan.severity_threshold must be one of none, low, medium, high, critical")
    require_bool("package_intake.osv_api_enabled")

    for engine_name in ("osv_scanner", "javascript", "python", "rust", "containers", "trivy", "secrets", "gitleaks", "trufflehog", "guarddog", "zizmor", "actionlint", "semgrep", "syft", "grype", "scorecard"):
        require_mapping(f"engines.{engine_name}")
        require_bool(f"engines.{engine_name}.enabled")
        require_int(f"engines.{engine_name}.timeout_seconds", 1)
    require_bool("engines.javascript.prefer_bun")
    require_bool("engines.javascript.fallback_to_npm")
    require_string("engines.javascript.bun_command")
    require_string("engines.javascript.npm_command")
    require_string("engines.javascript.pnpm_command")
    require_string("engines.trivy.command")
    require_string("engines.trivy.scanners")
    require_string("engines.trivy.image_scanners")
    require_string("engines.gitleaks.command")
    require_bool("engines.gitleaks.scan_current")
    require_bool("engines.gitleaks.scan_history")
    require_string("engines.trufflehog.command")
    require_bool("engines.trufflehog.only_verified")
    require_string("engines.guarddog.command")
    require_string("engines.zizmor.command")
    require_string("engines.zizmor.format")
    require_bool("engines.zizmor.offline")
    require_string("engines.actionlint.command")
    require_string("engines.actionlint.format")
    require_string("engines.semgrep.command")
    require_string("engines.semgrep.config_auto")
    for idx, value in enumerate(require_list("engines.semgrep.rule_paths")):
        if not isinstance(value, str):
            errors.append(f"engines.semgrep.rule_paths[{idx}] must be a string")
    for idx, value in enumerate(require_list("engines.semgrep.exclude")):
        if not isinstance(value, str):
            errors.append(f"engines.semgrep.exclude[{idx}] must be a string")
    require_string("engines.syft.command")
    require_string("engines.syft.output_format")
    require_string("engines.grype.command")
    require_bool("engines.grype.skip_when_trivy_covers_target")
    require_string("engines.scorecard.command")
    require_string("engines.scorecard.format")
    require_bool("engines.scorecard.show_details")
    require_bool("engines.scorecard.use_local")
    require_int("engines.scorecard.minimum_check_score", 0)

    require_bool("tracker.skip_known_unfixable")
    require_int("tracker.retry_blocked_after_days", 1)
    require_bool("remediation.auto_fix")
    require_bool("remediation.codex.enabled")
    require_int("remediation.codex.max_parallel", 1)
    require_int("remediation.codex.timeout_seconds", 60)
    require_bool("remediation.codex.skip_git_repo_check")
    return errors
</file>

<file path="scripts/vulnscan/inventory.py">
"""Scanner engine inventory and mode metadata."""

from __future__ import annotations

import json
import shutil
import subprocess
from dataclasses import dataclass
from typing import Any

from .common import now_iso
from .config import cfg_get

SCAN_MODES = {
    "full",
    "dependencies",
    "secrets",
    "ci",
    "supply-chain",
    "sast",
    "sbom",
    "hygiene",
    "remediation-prep",
}

ENGINE_CATALOG = [
    {
        "name": "osv-scanner",
        "category": "dependencies",
        "command": "osv-scanner",
        "status": "implemented",
        "notes": "Broad known-vulnerability dependency baseline.",
    },
    {
        "name": "bun-audit",
        "category": "dependencies",
        "command": "bun",
        "status": "implemented",
        "notes": "JavaScript audit for Bun package roots.",
    },
    {
        "name": "npm-audit",
        "category": "dependencies",
        "command": "npm",
        "status": "implemented",
        "notes": "JavaScript audit fallback for package-lock roots.",
    },
    {
        "name": "pnpm-audit",
        "category": "dependencies",
        "command": "pnpm",
        "status": "implemented",
        "notes": "JavaScript audit fallback for pnpm lockfile roots.",
    },
    {
        "name": "pip-audit",
        "category": "dependencies",
        "command": "pip-audit",
        "status": "implemented",
        "notes": "Python dependency vulnerability scanning.",
    },
    {
        "name": "cargo-audit",
        "category": "dependencies",
        "command": "cargo",
        "status": "implemented",
        "notes": "RustSec dependency vulnerability scanning through cargo audit.",
    },
    {
        "name": "secret-patterns",
        "category": "secrets",
        "command": None,
        "status": "implemented",
        "notes": "Local metadata-only fallback secret pattern scan.",
    },
    {
        "name": "trivy",
        "category": "broad-local",
        "command": "trivy",
        "status": "implemented",
        "notes": "Broad repo, image, IaC, secret, license, and CVE scanner.",
    },
    {
        "name": "gitleaks",
        "category": "secrets",
        "command": "gitleaks",
        "status": "implemented",
        "notes": "Fast hardcoded secret scan for tree and history.",
    },
    {
        "name": "trufflehog",
        "category": "secrets",
        "command": "trufflehog",
        "status": "implemented",
        "notes": "Verified credential scanning.",
    },
    {
        "name": "guarddog",
        "category": "supply-chain",
        "command": "guarddog",
        "status": "implemented",
        "notes": "Malicious-package behavior checks.",
    },
    {
        "name": "zizmor",
        "category": "ci",
        "command": "zizmor",
        "status": "implemented",
        "notes": "GitHub Actions security scan.",
    },
    {
        "name": "actionlint",
        "category": "ci",
        "command": "actionlint",
        "status": "implemented",
        "notes": "GitHub Actions syntax and expression linting.",
    },
    {
        "name": "semgrep",
        "category": "sast",
        "command": "semgrep",
        "status": "implemented",
        "notes": "Community-rule local SAST.",
    },
    {
        "name": "syft",
        "category": "sbom",
        "command": "syft",
        "status": "implemented",
        "notes": "SBOM generation.",
    },
    {
        "name": "grype",
        "category": "sbom",
        "command": "grype",
        "status": "implemented",
        "notes": "SBOM and filesystem vulnerability scan.",
    },
    {
        "name": "scorecard",
        "category": "hygiene",
        "command": "scorecard",
        "status": "implemented",
        "notes": "OpenSSF repository security hygiene checks.",
    },
]

MODE_IMPLEMENTATION = {
    "full": "implemented_partial",
    "dependencies": "implemented",
    "secrets": "implemented",
    "ci": "implemented",
    "supply-chain": "implemented",
    "sast": "implemented",
    "sbom": "implemented",
    "hygiene": "implemented",
    "remediation-prep": "implemented",
}


@dataclass(frozen=True)
class EngineAdapter:
    name: str
    category: str
    config_key: str | None
    default_command: str | None
    status: str
    notes: str
    target_types: tuple[str, ...] = ()
    parser: str | None = None
    artifact_subdir: str | None = None
    default_timeout_seconds: int = 60

    def enabled(self, config: dict[str, Any] | None = None) -> bool:
        if not self.config_key or config is None:
            return True
        return bool(cfg_get(config, f"engines.{self.config_key}.enabled", True))

    def command(self, config: dict[str, Any] | None = None) -> str | None:
        if self.default_command is None:
            return None
        if not self.config_key or config is None:
            return self.default_command
        return str(cfg_get(config, f"engines.{self.config_key}.command", self.default_command) or self.default_command)

    def timeout_seconds(self, config: dict[str, Any] | None = None) -> int:
        if not self.config_key or config is None:
            return self.default_timeout_seconds
        return int(cfg_get(config, f"engines.{self.config_key}.timeout_seconds", self.default_timeout_seconds) or self.default_timeout_seconds)

    def available(self, config: dict[str, Any] | None = None) -> tuple[bool, str | None]:
        command = self.command(config)
        if command is None:
            return True, None
        path = shutil.which(command)
        return path is not None, path

    def setup_debt(self, target: str, config: dict[str, Any] | None = None) -> dict[str, Any] | None:
        if not self.enabled(config):
            return None
        available, path = self.available(config)
        if available:
            return None
        command = self.command(config)
        return {
            "scanner": self.name,
            "target": target,
            "command": command,
            "reason": "missing binary",
            "missing_binary": command,
            "timeout": None,
            "parser_failure": None,
            "unsupported_target": None,
            "suggested_next_action": f"Install {command} or disable engines.{self.config_key}.enabled",
            "path": path,
        }


def engine_registry() -> dict[str, EngineAdapter]:
    adapters: dict[str, EngineAdapter] = {}
    config_keys = {
        "osv-scanner": "osv_scanner",
        "bun-audit": "javascript",
        "npm-audit": "javascript",
        "pnpm-audit": "javascript",
        "pip-audit": "python",
        "cargo-audit": "rust",
        "secret-patterns": "secrets",
        "trivy": "trivy",
        "gitleaks": "gitleaks",
        "trufflehog": "trufflehog",
        "guarddog": "guarddog",
        "zizmor": "zizmor",
        "actionlint": "actionlint",
        "semgrep": "semgrep",
        "syft": "syft",
        "grype": "grype",
        "scorecard": "scorecard",
    }
    target_types = {
        "osv-scanner": ("npm", "python", "rust", "go", "jvm"),
        "bun-audit": ("npm",),
        "npm-audit": ("npm",),
        "pnpm-audit": ("npm",),
        "pip-audit": ("python",),
        "cargo-audit": ("rust",),
        "secret-patterns": ("secrets",),
        "trivy": ("container", "iac", "filesystem"),
        "gitleaks": ("git", "secrets"),
        "trufflehog": ("git", "secrets"),
        "guarddog": ("npm", "python", "go", "rubygems", "github-actions", "vscode"),
        "zizmor": ("ci",),
        "actionlint": ("ci",),
        "semgrep": ("source",),
        "syft": ("sbom",),
        "grype": ("sbom",),
        "scorecard": ("hygiene",),
    }
    parser_names = {
        "osv-scanner": "parse_osv",
        "bun-audit": "parse_bun",
        "npm-audit": "parse_npm",
        "pnpm-audit": "parse_pnpm",
        "pip-audit": "parse_pip_audit",
        "cargo-audit": "parse_cargo_audit",
        "gitleaks": "parse_gitleaks",
        "trufflehog": "parse_trufflehog_lines",
        "zizmor": "parse_zizmor",
        "actionlint": "parse_actionlint_lines",
        "semgrep": "parse_semgrep",
        "syft": "parse_syft_metadata",
        "grype": "parse_grype",
        "scorecard": "parse_scorecard",
        "guarddog": "parse_guarddog",
    }
    for engine in ENGINE_CATALOG:
        name = str(engine["name"])
        adapters[name] = EngineAdapter(
            name=name,
            category=str(engine["category"]),
            config_key=config_keys.get(name),
            default_command=engine.get("command"),
            status=str(engine["status"]),
            notes=str(engine["notes"]),
            target_types=target_types.get(name, ()),
            parser=parser_names.get(name),
            artifact_subdir=str(engine.get("artifact_subdir") or name.replace("-", "_")),
        )
    return adapters


def engine_inventory(config: dict[str, Any] | None = None) -> list[dict[str, Any]]:
    inventory: list[dict[str, Any]] = []
    for adapter in engine_registry().values():
        command = adapter.command(config)
        available, path = adapter.available(config)
        inventory.append(
            {
                "name": adapter.name,
                "category": adapter.category,
                "config_key": adapter.config_key,
                "status": adapter.status,
                "command": command,
                "enabled": adapter.enabled(config),
                "available": available,
                "path": path,
                "target_types": list(adapter.target_types),
                "parser": adapter.parser,
                "artifact_subdir": adapter.artifact_subdir,
                "timeout_seconds": adapter.timeout_seconds(config),
                "notes": adapter.notes,
            }
        )
    return inventory


def render_engine_inventory(format_name: str, config: dict[str, Any] | None = None) -> str:
    inventory = engine_inventory(config)
    if format_name == "json":
        return json.dumps({"generated_at": now_iso(), "engines": inventory}, indent=2, sort_keys=True)
    lines = ["Scanner engines:"]
    for engine in inventory:
        state = "available" if engine["available"] else "missing"
        if engine["status"] != "implemented":
            state = f"{state}, {engine['status']}"
        command = engine["command"] or "built-in"
        lines.append(f"- {engine['name']} ({engine['category']}): {state}; command={command}")
    return "\n".join(lines)


def render_tool_validation(format_name: str, config: dict[str, Any] | None = None) -> str:
    inventory = engine_inventory(config)
    missing = [engine for engine in inventory if engine["enabled"] and not engine["available"]]
    payload = {
        "generated_at": now_iso(),
        "missing_count": len(missing),
        "engines": inventory,
    }
    if format_name == "json":
        return json.dumps(payload, indent=2, sort_keys=True)
    lines = ["Tool validation:"]
    for engine in inventory:
        state = "available" if engine["available"] else "missing"
        command = engine["command"] or "built-in"
        lines.append(f"- {engine['name']}: {state}; command={command}; status={engine['status']}")
    return "\n".join(lines)


DEEP_CHECK_ARGS = {
    "osv-scanner": ["--version"],
    "bun-audit": ["--version"],
    "npm-audit": ["--version"],
    "pnpm-audit": ["--version"],
    "pip-audit": ["--version"],
    "cargo-audit": ["audit", "--version"],
    "trivy": ["--version"],
    "gitleaks": ["version"],
    "trufflehog": ["--version"],
    "guarddog": ["--help"],
    "zizmor": ["--version"],
    "actionlint": ["--version"],
    "semgrep": ["--version"],
    "syft": ["--version"],
    "grype": ["--version"],
    "scorecard": ["--version"],
}


def deep_tool_validation(config: dict[str, Any] | None = None, timeout_seconds: int = 10) -> list[dict[str, Any]]:
    checks: list[dict[str, Any]] = []
    for adapter in engine_registry().values():
        command = adapter.command(config)
        if command is None:
            checks.append({"name": adapter.name, "command": None, "status": "built_in", "exit_code": None})
            continue
        if not adapter.enabled(config):
            checks.append({"name": adapter.name, "command": command, "status": "disabled", "exit_code": None})
            continue
        binary = shutil.which(command)
        if not binary:
            checks.append({"name": adapter.name, "command": command, "status": "missing", "exit_code": None})
            continue
        args = DEEP_CHECK_ARGS.get(adapter.name, ["--version"])
        cmd = [binary, *args]
        try:
            proc = subprocess.run(cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, timeout=timeout_seconds)
        except subprocess.TimeoutExpired:
            checks.append({"name": adapter.name, "command": cmd, "status": "timed_out", "exit_code": 124})
            continue
        output = (proc.stdout or proc.stderr or "").strip().splitlines()
        checks.append(
            {
                "name": adapter.name,
                "command": cmd,
                "status": "ok" if proc.returncode == 0 else "failed",
                "exit_code": proc.returncode,
                "output": output[0][:240] if output else "",
            }
        )
    return checks


def render_deep_tool_validation(format_name: str, config: dict[str, Any] | None = None) -> str:
    checks = deep_tool_validation(config)
    failed = [check for check in checks if check["status"] in {"missing", "timed_out", "failed"}]
    payload = {"generated_at": now_iso(), "failed_count": len(failed), "checks": checks}
    if format_name == "json":
        return json.dumps(payload, indent=2, sort_keys=True)
    lines = ["Deep tool validation:"]
    for check in checks:
        command = check.get("command")
        rendered = " ".join(str(part) for part in command) if isinstance(command, list) else str(command or "built-in")
        suffix = f"; {check.get('output')}" if check.get("output") else ""
        lines.append(f"- {check['name']}: {check['status']}; command={rendered}{suffix}")
    return "\n".join(lines)
</file>

<file path="scripts/vulnscan/remediation.py">
"""Codex remediation handoff for affected repositories."""

from __future__ import annotations

import shutil
import subprocess
import time
import re
from pathlib import Path
from typing import Any

from .common import stable_id
from .config import cfg_get


def codex_prompt_for_result(result: dict[str, Any]) -> str:
    findings = result.get("findings", [])
    lines = [
        "You are fixing dependency vulnerability findings for this single repository only.",
        "Make the smallest safe dependency/package manifest changes needed to resolve the listed findings.",
        "Do not create branches. Do not commit. Do not push. Do not delete unrelated files. Do not refactor unrelated code.",
        "Keep changes inside this repository. Prefer package manager updates/overrides over broad rewrites.",
        "Run only targeted verification/audit commands for this repository when needed.",
        "Return a concise summary of changed files, verification run, remaining findings, and anything blocked.",
        "",
        f"Repository label: {result.get('label')}",
        "Findings to resolve:",
    ]
    for finding in findings[:80]:
        parts = [
            f"- package={finding.get('package') or 'unknown'}",
            f"severity={finding.get('severity') or 'unknown'}",
            f"advisory={finding.get('advisory_id') or finding.get('id') or 'unknown'}",
            f"title={finding.get('title') or 'unknown'}",
        ]
        fixed = finding.get("fixed_version") or finding.get("fixed_versions") or finding.get("patched_versions")
        if fixed:
            parts.append(f"fixed={fixed}")
        lines.append("; ".join(parts))
    if len(findings) > 80:
        lines.append(f"- ...plus {len(findings) - 80} more findings in the scan artifact for this repo.")
    return "\n".join(lines)


def finding_fixed_versions(finding: dict[str, Any]) -> list[str]:
    value = finding.get("fixed_version") or finding.get("fixed_versions") or finding.get("patched_versions")
    if value is None:
        return []
    if isinstance(value, list):
        return [str(item) for item in value]
    return [part.strip() for part in str(value).split(",") if part.strip()]


def major_version(value: Any) -> int | None:
    if value is None:
        return None
    match = re.search(r"(\d+)", str(value))
    return int(match.group(1)) if match else None


def remediation_group_for_finding(finding: dict[str, Any]) -> str:
    category = str(finding.get("category") or "dependency")
    if category == "secret" or finding.get("git_tracked"):
        return "tracked_secret_rotation" if finding.get("git_tracked") else "manual_review"
    if category == "workflow":
        return "ci_workflow_permission_or_pinning"
    if category != "dependency":
        return "likely_unfixable_or_design_limitation"
    fixed_versions = finding_fixed_versions(finding)
    if not fixed_versions:
        return "transitive_override_candidates"
    installed_major = major_version(finding.get("installed_version"))
    fixed_major = major_version(fixed_versions[0])
    if installed_major is not None and fixed_major is not None and fixed_major > installed_major:
        return "manual_major_upgrade_candidates"
    return "direct_dependency_update_candidates"


def build_remediation_prep(results: list[dict[str, Any]], secret_findings: list[dict[str, Any]]) -> dict[str, Any]:
    groups: dict[str, list[dict[str, Any]]] = {
        "direct_dependency_update_candidates": [],
        "transitive_override_candidates": [],
        "manual_major_upgrade_candidates": [],
        "likely_unfixable_or_design_limitation": [],
        "tracked_secret_rotation": [],
        "ci_workflow_permission_or_pinning": [],
        "manual_review": [],
    }
    for result in results:
        label = str(result.get("label") or "")
        for finding in result.get("findings", []):
            item = dict(finding)
            item.setdefault("repo", label)
            groups[remediation_group_for_finding(item)].append(item)
    for finding in secret_findings:
        item = dict(finding)
        item.setdefault("repo", item.get("source_label") or "__secrets__")
        groups[remediation_group_for_finding(item)].append(item)
    return {
        "enabled": True,
        "groups": groups,
        "counts": {name: len(items) for name, items in groups.items()},
    }


def finding_identity(finding: dict[str, Any]) -> tuple[Any, ...]:
    return (
        finding.get("source_engine"),
        finding.get("category"),
        finding.get("advisory_id") or finding.get("rule_id") or finding.get("detector") or finding.get("title"),
        finding.get("package") or finding.get("file") or finding.get("type"),
        finding.get("ecosystem"),
    )


def compare_same_engine_verification(original_results: list[dict[str, Any]], verification_results: list[dict[str, Any]]) -> dict[str, Any]:
    original: dict[str, set[tuple[Any, ...]]] = {}
    verified: dict[str, set[tuple[Any, ...]]] = {}
    for result in original_results:
        original[str(result.get("label") or "")] = {finding_identity(finding) for finding in result.get("findings", [])}
    for result in verification_results:
        verified[str(result.get("label") or "")] = {finding_identity(finding) for finding in result.get("findings", [])}

    fixed = 0
    remaining = 0
    by_repo: list[dict[str, Any]] = []
    for label, identities in original.items():
        still_present = identities & verified.get(label, set())
        gone = identities - still_present
        fixed += len(gone)
        remaining += len(still_present)
        by_repo.append({"label": label, "fixed": len(gone), "remaining": len(still_present)})
    return {"same_engine": True, "fixed": fixed, "remaining": remaining, "by_repo": by_repo}


def run_codex_remediation(
    results: list[dict[str, Any]],
    project_paths: dict[str, Path],
    config: dict[str, Any],
    artifact_dir: Path,
) -> dict[str, Any]:
    enabled = bool(cfg_get(config, "remediation.auto_fix", False)) and bool(cfg_get(config, "remediation.codex.enabled", False))
    status: dict[str, Any] = {
        "enabled": enabled,
        "tool": "codex",
        "started": 0,
        "completed": 0,
        "failed": 0,
        "skipped": 0,
        "logs": [],
    }
    if not enabled:
        return status

    command = str(cfg_get(config, "remediation.codex.command", "codex") or "codex")
    if shutil.which(command) is None:
        status["failed"] = 1
        status["error"] = f"codex command not found: {command}"
        return status
    sandbox = str(cfg_get(config, "remediation.codex.sandbox", "workspace-write") or "workspace-write")
    max_parallel = max(1, int(cfg_get(config, "remediation.codex.max_parallel", 1) or 1))
    timeout_seconds = max(60, int(cfg_get(config, "remediation.codex.timeout_seconds", 1800) or 1800))
    skip_git = bool(cfg_get(config, "remediation.codex.skip_git_repo_check", True))
    log_dir = artifact_dir / "codex-remediation"
    log_dir.mkdir(parents=True, exist_ok=True)

    tasks: list[tuple[dict[str, Any], Path, Path]] = []
    for result in results:
        if not result.get("findings"):
            continue
        label = str(result.get("label") or "")
        project_path = project_paths.get(label)
        if project_path is None or not project_path.exists():
            status["skipped"] += 1
            continue
        log_path = log_dir / f"{stable_id(label)}.log"
        tasks.append((result, project_path, log_path))

    running: list[dict[str, Any]] = []

    def start_task(task: tuple[dict[str, Any], Path, Path]) -> None:
        result, project_path, log_path = task
        cmd = [command, "exec"]
        if skip_git:
            cmd.append("--skip-git-repo-check")
        cmd.extend(["--sandbox", sandbox, codex_prompt_for_result(result)])
        log_file = log_path.open("w", encoding="utf-8")
        proc = subprocess.Popen(cmd, cwd=project_path, stdout=log_file, stderr=subprocess.STDOUT, text=True)
        running.append({"proc": proc, "log_file": log_file, "log_path": log_path, "label": result.get("label"), "started_at": time.time()})
        status["started"] += 1
        status["logs"].append(str(log_path))

    while tasks or running:
        while tasks and len(running) < max_parallel:
            start_task(tasks.pop(0))
        time.sleep(2)
        still_running: list[dict[str, Any]] = []
        for item in running:
            proc = item["proc"]
            if proc.poll() is None and time.time() - item["started_at"] <= timeout_seconds:
                still_running.append(item)
                continue
            if proc.poll() is None:
                proc.kill()
                status["failed"] += 1
            elif proc.returncode == 0:
                status["completed"] += 1
            else:
                status["failed"] += 1
            item["log_file"].close()
        running = still_running
    return status
</file>

<file path="tests/test_cli.py">
from __future__ import annotations

import contextlib
import io
import json
import sys
import tempfile
import unittest
import os
import subprocess
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
SCRIPTS = ROOT / "scripts"
sys.path.insert(0, str(SCRIPTS))

from vulnscan import ci, cli, config, discovery, engines, hygiene, inventory, orchestration, parsers, remediation, reporting, sast, sbom, secrets, supply_chain, tracker as tracker_mod  # noqa: E402

TEST_OPENAI_KEY = "sk-" + "abcdefghijklmnopqrstuvwxyz123"


class CLIIntegrationTests(unittest.TestCase):
    def test_scope_violation_stops_before_scanner_execution(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            app = root / "app"
            app.mkdir()
            (app / "package.json").write_text('{"dependencies":{"left-pad":"1.0.0"}}\n', encoding="utf-8")
            (app / "package-lock.json").write_text("{}\n", encoding="utf-8")
            allowed = root / "allowed"
            output = root / "summary.json"

            with contextlib.redirect_stdout(io.StringIO()):
                code = cli.main(
                    [
                        "scan",
                        "--root",
                        str(root),
                        "--scan-mode",
                        "dependencies",
                        "--allowed-root",
                        str(allowed),
                        "--fail-on-scope-violation",
                        "--output",
                        str(output),
                        "--format",
                        "json",
                        "--no-tracker",
                    ]
                )
            summary = json.loads(output.read_text(encoding="utf-8"))

        self.assertEqual(code, 2)
        self.assertEqual(summary["scanned_projects"], 0)
        self.assertEqual(summary["scope"]["out_of_scope_count"], 1)
        self.assertEqual(summary["setup_debt"][0]["item"], "scope violation; scan not started")

    def test_clean_scan_can_emit_silent(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            stdout = io.StringIO()
            with contextlib.redirect_stdout(stdout):
                code = cli.main(
                    [
                        "scan",
                        "--config",
                        str(ROOT / "templates" / "config-starter.yaml"),
                        "--root",
                        str(root),
                        "--scan-mode",
                        "ci",
                        "--format",
                        "text",
                        "--no-tracker",
                    ]
                )

        self.assertEqual(code, 0)
        self.assertEqual(stdout.getvalue().strip(), "[SILENT]")

    def test_fail_on_findings_returns_nonzero(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            subprocess.run(["git", "init"], cwd=root, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
            (root / ".env").write_text(f"OPENAI_API_KEY={TEST_OPENAI_KEY}\n", encoding="utf-8")
            with contextlib.redirect_stdout(io.StringIO()):
                code = cli.main(
                    [
                        "scan",
                        "--root",
                        str(root),
                        "--scan-mode",
                        "secrets",
                        "--fail-on-findings",
                        "--format",
                        "json",
                        "--no-tracker",
                    ]
                )

        self.assertEqual(code, 1)

    def test_scan_does_not_remediate_without_explicit_opt_in(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            subprocess.run(["git", "init"], cwd=root, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
            (root / ".env").write_text(f"OPENAI_API_KEY={TEST_OPENAI_KEY}\n", encoding="utf-8")
            output = root / "summary.json"
            with contextlib.redirect_stdout(io.StringIO()):
                code = cli.main(
                    [
                        "scan",
                        "--root",
                        str(root),
                        "--scan-mode",
                        "secrets",
                        "--output",
                        str(output),
                        "--format",
                        "json",
                        "--no-tracker",
                    ]
                )
            summary = json.loads(output.read_text(encoding="utf-8"))

        self.assertEqual(code, 0)
        self.assertFalse(summary["remediation"]["enabled"])

    def test_package_json_without_lockfile_is_reported_as_unsupported_coverage(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            app = root / "app"
            app.mkdir()
            (app / "package.json").write_text('{"dependencies":{"left-pad":"1.0.0"}}\n', encoding="utf-8")
            output = root / "summary.json"
            with contextlib.redirect_stdout(io.StringIO()):
                code = cli.main(
                    [
                        "scan",
                        "--root",
                        str(root),
                        "--scan-mode",
                        "dependencies",
                        "--output",
                        str(output),
                        "--format",
                        "json",
                        "--no-tracker",
                    ]
                )
            summary = json.loads(output.read_text(encoding="utf-8"))

        self.assertEqual(code, 0)
        self.assertEqual(summary["results"][0]["coverage"]["dependencies"], "unsupported")
        self.assertEqual(summary["setup_debt"][0]["unsupported_target"], "package.json without lockfile")

    def test_trivy_license_scanning_requires_explicit_flag(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_trivy = bin_dir / "trivy"
            fake_trivy.write_text(
                "#!/usr/bin/env bash\n"
                "out=''\n"
                "prev=''\n"
                "for arg in \"$@\"; do\n"
                "  if [[ \"$prev\" == '--output' ]]; then out=\"$arg\"; fi\n"
                "  prev=\"$arg\"\n"
                "done\n"
                "cat > \"$out\" <<'JSON'\n"
                '{"Results":[{"Target":"package-lock.json","Packages":[{"Name":"pkg","Version":"1.0.0","Licenses":["GPL-3.0"]}]}]}\n'
                "JSON\n",
                encoding="utf-8",
            )
            fake_trivy.chmod(0o755)
            repo = root / "repo"
            repo.mkdir()
            subprocess.run(["git", "init"], cwd=repo, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
            (repo / "Dockerfile").write_text("FROM scratch\n", encoding="utf-8")
            config_path = root / "config.json"
            config_path.write_text(
                json.dumps(
                    {
                        "engines": {
                            "osv_scanner": {"enabled": False},
                            "javascript": {"enabled": False},
                            "trivy": {"enabled": True, "command": str(fake_trivy), "scanners": "vuln,misconfig,secret", "image_scanners": "vuln,secret"},
                            "zizmor": {"enabled": False},
                            "actionlint": {"enabled": False},
                            "semgrep": {"enabled": False},
                            "gitleaks": {"enabled": False},
                            "trufflehog": {"enabled": False},
                            "secrets": {"enabled": False},
                        }
                    }
                ),
                encoding="utf-8",
            )
            default_output = root / "default.json"
            license_output = root / "licenses.json"
            with contextlib.redirect_stdout(io.StringIO()):
                default_code = cli.main(
                    [
                        "scan",
                        "--root",
                        str(repo),
                        "--config",
                        str(config_path),
                        "--output",
                        str(default_output),
                        "--artifact-dir",
                        str(root / "default-artifacts"),
                        "--format",
                        "json",
                        "--no-tracker",
                    ]
                )
                license_code = cli.main(
                    [
                        "scan",
                        "--root",
                        str(repo),
                        "--config",
                        str(config_path),
                        "--include-licenses",
                        "--output",
                        str(license_output),
                        "--artifact-dir",
                        str(root / "license-artifacts"),
                        "--format",
                        "json",
                        "--no-tracker",
                    ]
                )
            default_summary = json.loads(default_output.read_text(encoding="utf-8"))
            license_summary = json.loads(license_output.read_text(encoding="utf-8"))

        self.assertEqual(default_code, 0)
        self.assertEqual(license_code, 0)
        default_trivy = next(cmd for cmd in default_summary["scanner_stats"]["commands"] if cmd["scanner"] == "trivy")
        license_trivy = next(cmd for cmd in license_summary["scanner_stats"]["commands"] if cmd["scanner"] == "trivy")
        self.assertEqual(default_trivy["command"][default_trivy["command"].index("--scanners") + 1], "vuln,misconfig,secret")
        self.assertEqual(license_trivy["command"][license_trivy["command"].index("--scanners") + 1], "vuln,misconfig,secret,license")
        self.assertNotIn("license", default_summary["category_counts"])
        self.assertEqual(license_summary["category_counts"]["license"], 1)

    def test_only_engine_limits_full_scan_to_selected_scanner(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_trivy = bin_dir / "trivy"
            fake_trivy.write_text(
                "#!/usr/bin/env bash\n"
                "out=''\n"
                "prev=''\n"
                "for arg in \"$@\"; do\n"
                "  if [[ \"$prev\" == '--output' ]]; then out=\"$arg\"; fi\n"
                "  prev=\"$arg\"\n"
                "done\n"
                "cat > \"$out\" <<'JSON'\n"
                '{"Results":[]}\n'
                "JSON\n",
                encoding="utf-8",
            )
            fake_trivy.chmod(0o755)
            repo = root / "repo"
            repo.mkdir()
            subprocess.run(["git", "init"], cwd=repo, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
            (repo / "Dockerfile").write_text("FROM scratch\n", encoding="utf-8")
            config_path = root / "config.json"
            config_path.write_text(
                json.dumps(
                    {
                        "engines": {
                            "trivy": {"enabled": True, "command": str(fake_trivy), "scanners": "vuln,misconfig,secret", "image_scanners": "vuln,secret"}
                        }
                    }
                ),
                encoding="utf-8",
            )
            output = root / "summary.json"
            with contextlib.redirect_stdout(io.StringIO()):
                code = cli.main(
                    [
                        "scan",
                        "--root",
                        str(repo),
                        "--config",
                        str(config_path),
                        "--scan-mode",
                        "full",
                        "--only-engine",
                        "trivy",
                        "--output",
                        str(output),
                        "--artifact-dir",
                        str(root / "artifacts"),
                        "--format",
                        "json",
                        "--no-tracker",
                    ]
                )
            summary = json.loads(output.read_text(encoding="utf-8"))

        self.assertEqual(code, 0)
        self.assertEqual(summary["scanner_stats"]["selected_engines"], ["trivy"])
        self.assertEqual({command["scanner"] for command in summary["commands"]}, {"trivy"})
        self.assertEqual(summary["results"][0]["coverage"]["secrets"], "not_requested")
        self.assertEqual(summary["results"][0]["coverage"]["sast"], "not_requested")

    def test_package_intake_cli_writes_decision_report(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_guarddog = bin_dir / "guarddog"
            fake_guarddog.write_text(
                "#!/usr/bin/env bash\n"
                "cat <<'JSON'\n"
                '{"issues":[{"rule":"npm-exec-base64","message":"package executes base64 encoded code","package":"evil","severity":"high"}]}\n'
                "JSON\n",
                encoding="utf-8",
            )
            fake_guarddog.chmod(0o755)
            output = root / "intake.json"
            old_path = os.environ.get("PATH", "")
            os.environ["PATH"] = f"{bin_dir}{os.pathsep}{old_path}"
            original_osv = supply_chain.run_osv_package_query
            supply_chain.run_osv_package_query = lambda *args, **kwargs: []
            try:
                with contextlib.redirect_stdout(io.StringIO()):
                    code = cli.main(
                        [
                            "package-intake",
                            "npm",
                            "evil",
                            "--output",
                            str(output),
                            "--artifact-dir",
                            str(root / "artifacts"),
                            "--format",
                            "text",
                        ]
                    )
            finally:
                supply_chain.run_osv_package_query = original_osv
                os.environ["PATH"] = old_path
            report = json.loads(output.read_text(encoding="utf-8"))

        self.assertEqual(code, 1)
        self.assertEqual(report["decision"], "avoid")
        self.assertEqual(report["findings"][0]["source_engine"], "guarddog")


class RemediationPrepTests(unittest.TestCase):
    def test_remediation_prep_groups_findings_by_fix_strategy(self) -> None:
        results = [
            {
                "label": "app",
                "findings": [
                    {"category": "dependency", "package": "a", "installed_version": "1.2.0", "fixed_version": "1.2.1"},
                    {"category": "dependency", "package": "b"},
                    {"category": "dependency", "package": "c", "installed_version": "1.2.0", "fixed_version": "2.0.0"},
                    {"category": "workflow", "rule_id": "unpinned-action"},
                    {"category": "sast", "rule_id": "dangerous-call"},
                ],
            }
        ]
        secret_findings = [{"category": "secret", "type": "aws", "git_tracked": True, "file": ".env"}]

        prep = remediation.build_remediation_prep(results, secret_findings)

        self.assertEqual(prep["counts"]["direct_dependency_update_candidates"], 1)
        self.assertEqual(prep["counts"]["transitive_override_candidates"], 1)
        self.assertEqual(prep["counts"]["manual_major_upgrade_candidates"], 1)
        self.assertEqual(prep["counts"]["ci_workflow_permission_or_pinning"], 1)
        self.assertEqual(prep["counts"]["likely_unfixable_or_design_limitation"], 1)
        self.assertEqual(prep["counts"]["tracked_secret_rotation"], 1)

    def test_same_engine_verification_compares_finding_identities(self) -> None:
        original = [{"label": "app", "findings": [{"source_engine": "osv-scanner", "category": "dependency", "advisory_id": "GHSA-1", "package": "left-pad"}]}]
        verified = [{"label": "app", "findings": []}]

        comparison = remediation.compare_same_engine_verification(original, verified)

        self.assertTrue(comparison["same_engine"])
        self.assertEqual(comparison["fixed"], 1)
        self.assertEqual(comparison["remaining"], 0)
</file>

<file path="tests/test_config_discovery_inventory.py">
from __future__ import annotations

import contextlib
import io
import json
import sys
import tempfile
import unittest
import os
import subprocess
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
SCRIPTS = ROOT / "scripts"
sys.path.insert(0, str(SCRIPTS))

from vulnscan import ci, cli, config, discovery, engines, hygiene, inventory, orchestration, parsers, remediation, reporting, sast, sbom, secrets, supply_chain, tracker as tracker_mod  # noqa: E402


class ConfigTests(unittest.TestCase):
    def test_minimal_yaml_inline_empty_list(self) -> None:
        data = config.parse_minimal_yaml("scope:\n  allowed_label_prefixes: []\n")
        self.assertEqual(data["scope"]["allowed_label_prefixes"], [])

    def test_config_validation_rejects_ambiguous_scope_prefixes(self) -> None:
        cfg = {
            "scope": {
                "allowed_roots": [],
                "allowed_label_prefixes": ["apps"],
                "forbidden_label_prefixes": ["apps"],
            },
            "scan": {"max_depth": 6, "silent_when_clean": True, "severity_threshold": "low"},
            "engines": {
                "osv_scanner": {"enabled": True, "timeout_seconds": 60},
                "javascript": {"enabled": True, "timeout_seconds": 60, "prefer_bun": True, "fallback_to_npm": True},
                "python": {"enabled": False, "timeout_seconds": 60},
                "rust": {"enabled": False, "timeout_seconds": 60},
                "containers": {"enabled": False, "timeout_seconds": 60},
                "secrets": {"enabled": True, "timeout_seconds": 60},
                "gitleaks": {"enabled": True, "command": "gitleaks", "timeout_seconds": 60, "scan_current": True, "scan_history": True},
                "trufflehog": {"enabled": True, "command": "trufflehog", "timeout_seconds": 60, "only_verified": True},
            },
            "filters": {"skip_paths": []},
            "tracker": {"skip_known_unfixable": True, "retry_blocked_after_days": 30},
            "remediation": {
                "auto_fix": True,
                "no_commits": True,
                "require_same_engine_verification": True,
                "codex": {"enabled": True, "max_parallel": 1, "timeout_seconds": 1800, "skip_git_repo_check": True},
            },
        }
        self.assertIn("scope allowed and forbidden label prefixes overlap: apps", config.validate_config(cfg))

    def test_validate_config_script_allows_local_remediation_opt_in(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            config_path = Path(tmp) / "local-remediation.yaml"
            text = (ROOT / "templates" / "config-starter.yaml").read_text(encoding="utf-8")
            text = text.replace("auto_fix: false", "auto_fix: true")
            text = text.replace(
                '    enabled: false\n    command: "codex"',
                '    enabled: true\n    command: "codex"',
            )
            config_path.write_text(text, encoding="utf-8")

            result = subprocess.run(
                [str(ROOT / "scripts" / "validate-config.sh"), str(config_path)],
                cwd=ROOT,
                text=True,
                stdout=subprocess.PIPE,
                stderr=subprocess.PIPE,
            )

        self.assertEqual(result.returncode, 0, result.stderr)
        self.assertIn("Warning: remediation is enabled", result.stdout)

    def test_validate_config_script_keeps_starter_remediation_disabled(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            template_dir = Path(tmp) / "templates"
            template_dir.mkdir()
            config_path = template_dir / "config-starter.yaml"
            text = (ROOT / "templates" / "config-starter.yaml").read_text(encoding="utf-8")
            text = text.replace("auto_fix: false", "auto_fix: true")
            config_path.write_text(text, encoding="utf-8")

            result = subprocess.run(
                [str(ROOT / "scripts" / "validate-config.sh"), str(config_path)],
                cwd=ROOT,
                text=True,
                stdout=subprocess.PIPE,
                stderr=subprocess.PIPE,
            )

        self.assertNotEqual(result.returncode, 0)
        self.assertIn("Starter config must keep remediation.auto_fix: false", result.stderr)


class DiscoveryTests(unittest.TestCase):
    def test_discovers_advertised_target_types_and_skips_noise(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            (root / "go").mkdir()
            (root / "go" / "go.mod").write_text("module example.com/app\n", encoding="utf-8")
            (root / "jvm").mkdir()
            (root / "jvm" / "build.gradle.kts").write_text("plugins {}\n", encoding="utf-8")
            (root / "ruby").mkdir()
            (root / "ruby" / "Gemfile.lock").write_text("GEM\n", encoding="utf-8")
            (root / "iac").mkdir()
            (root / "iac" / "main.tf").write_text("resource null_resource example {}\n", encoding="utf-8")
            (root / ".github" / "workflows").mkdir(parents=True)
            (root / ".github" / "workflows" / "ci.yml").write_text("name: ci\n", encoding="utf-8")
            (root / "extension").mkdir()
            (root / "extension" / "package.json").write_text('{"engines":{"vscode":"^1.0.0"}}\n', encoding="utf-8")
            (root / "node_modules").mkdir()

            result = discovery.discover_projects(root, max_depth=6)
            ecosystems = {project.label: project.ecosystems for project in result.projects}

            self.assertIn("go", ecosystems["go"])
            self.assertIn("jvm", ecosystems["jvm"])
            self.assertIn("rubygems", ecosystems["ruby"])
            self.assertIn("iac", ecosystems["iac"])
            self.assertIn("ci", ecosystems[".github/workflows"])
            self.assertIn("vscode", ecosystems["extension"])
            self.assertIn({"target": "node_modules", "reason": "noise_dir:node_modules"}, result.skipped_targets)

    def test_package_json_without_lockfile_is_setup_debt_target(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            app = root / "app"
            app.mkdir()
            (app / "package.json").write_text('{"dependencies":{"left-pad":"1.0.0"}}\n', encoding="utf-8")

            result = discovery.discover_projects(root, max_depth=6)

        self.assertEqual(result.projects[0].label, "app")
        self.assertIn("javascript-no-lockfile", result.projects[0].ecosystems)

    def test_fixture_repos_cover_supported_discovery_shapes(self) -> None:
        fixtures = ROOT / "tests" / "fixtures"
        result = discovery.discover_projects(fixtures, max_depth=6, exclude_globs=["__never_match__"])
        ecosystems = {project.label: project.ecosystems for project in result.projects}

        self.assertIn("npm", ecosystems["npm"])
        self.assertIn("npm", ecosystems["pnpm"])
        self.assertIn("npm", ecosystems["yarn"])
        self.assertIn("python", ecosystems["python"])
        self.assertIn("rust", ecosystems["rust"])
        self.assertIn("go", ecosystems["go"])
        self.assertIn("jvm", ecosystems["jvm"])
        self.assertIn("container", ecosystems["docker"])
        self.assertIn("iac", ecosystems["terraform"])
        self.assertIn("ci", ecosystems["github-actions/.github/workflows"])
        self.assertIn("vscode", ecosystems["vscode-extension"])
        self.assertIn("npm", ecosystems["monorepo/apps/web"])
        self.assertIn("python", ecosystems["monorepo/packages/api"])
        self.assertIn("javascript-no-lockfile", ecosystems["javascript-no-lock"])
        self.assertNotIn("no-manifest", ecosystems)


class InventoryTests(unittest.TestCase):
    def test_engine_registry_exposes_adapter_metadata(self) -> None:
        registry = inventory.engine_registry()
        adapter = registry["osv-scanner"]

        self.assertEqual(adapter.config_key, "osv_scanner")
        self.assertEqual(adapter.parser, "parse_osv")
        self.assertIn("npm", adapter.target_types)

    def test_engine_inventory_uses_configured_command_timeout_and_enabled_state(self) -> None:
        cfg = {"engines": {"osv_scanner": {"enabled": False, "command": "custom-osv", "timeout_seconds": 12}}}
        engines = {engine["name"]: engine for engine in inventory.engine_inventory(cfg)}

        self.assertFalse(engines["osv-scanner"]["enabled"])
        self.assertEqual(engines["osv-scanner"]["command"], "custom-osv")
        self.assertEqual(engines["osv-scanner"]["timeout_seconds"], 12)

    def test_deep_tool_validation_marks_builtin_and_disabled_without_execution(self) -> None:
        checks = inventory.deep_tool_validation({"engines": {"osv_scanner": {"enabled": False}}})
        by_name = {check["name"]: check for check in checks}

        self.assertEqual(by_name["secret-patterns"]["status"], "built_in")
        self.assertEqual(by_name["osv-scanner"]["status"], "disabled")

    def test_workspace_engine_selection_is_registry_backed(self) -> None:
        selected = orchestration.selected_workspace_engines("full", {"engines": {"semgrep": {"enabled": False}}})

        self.assertIn("osv-scanner", selected)
        self.assertIn("ci", selected)
        self.assertIn("trivy", selected)
        self.assertNotIn("semgrep", selected)


class ReportingPolicyTests(unittest.TestCase):
    def test_clean_summary_can_be_silent_only_without_actionable_debt(self) -> None:
        cfg = {"scan": {"silent_when_clean": True}}
        summary = {
            "finding_count": 0,
            "setup_debt": [],
            "scope": {"out_of_scope_count": 0},
            "scanner_stats": {"osv": {"timeout": 0, "parse_failed": 0}, "javascript": {}, "mode_setup_debt": []},
        }
        self.assertTrue(cli.summary_can_be_silent(summary, cfg))

        summary["setup_debt"] = [{"repo": "app", "item": "missing scanner"}]
        self.assertFalse(cli.summary_can_be_silent(summary, cfg))

    def test_summary_preserves_commands_and_structured_setup_debt(self) -> None:
        summary = reporting.build_summary(
            results=[{"label": "app", "findings": [], "setup_debt": [{"scanner": "npm-audit", "target": "app", "reason": "parser failure"}]}],
            secret_findings=[],
            stats={"commands": [{"scanner": "npm-audit", "target": "app", "command": ["npm", "audit"], "status": "completed"}], "mode_setup_debt": []},
            skipped=[],
            artifact_dir=Path("/tmp/artifacts"),
        )

        self.assertEqual(summary["commands"][0]["scanner"], "npm-audit")
        self.assertEqual(summary["setup_debt"][0]["reason"], "parser failure")
        self.assertIn("Commands:", reporting.render_summary_text(summary))

    def test_summary_adds_coverage_statuses(self) -> None:
        summary = reporting.build_summary(
            results=[
                {
                    "label": "app",
                    "git_root": "app",
                    "ecosystems": ["javascript-no-lockfile"],
                    "findings": [],
                    "setup_debt": [{"scanner": "javascript-native", "target": "app", "reason": "unsupported target"}],
                }
            ],
            secret_findings=[],
            stats={"commands": [], "mode_setup_debt": []},
            skipped=[],
            artifact_dir=Path("/tmp/artifacts"),
            requested_modes={"dependencies": True, "secrets": False},
        )

        self.assertEqual(summary["results"][0]["coverage"]["dependencies"], "unsupported")
        self.assertEqual(summary["results"][0]["coverage"]["secrets"], "not_requested")
        self.assertIn("Coverage:", reporting.render_summary_text(summary))

    def test_secret_coverage_uses_project_specific_scanner_debt(self) -> None:
        summary = reporting.build_summary(
            results=[
                {"label": "app-a", "git_root": "app-a", "ecosystems": ["npm"], "findings": [], "setup_debt": []},
                {"label": "app-b", "git_root": "app-b", "ecosystems": ["npm"], "findings": [], "setup_debt": []},
                {"label": "app-c", "git_root": "app-c", "ecosystems": ["npm"], "findings": [], "setup_debt": []},
            ],
            secret_findings=[{"source_engine": "gitleaks", "source_label": "app-b", "category": "secret", "severity": "HIGH"}],
            stats={
                "commands": [],
                "mode_setup_debt": [{"scanner": "gitleaks", "target": "app-a", "reason": "timeout"}],
            },
            skipped=[],
            artifact_dir=Path("/tmp/artifacts"),
            requested_modes={"secrets": True},
        )
        coverage = {result["label"]: result["coverage"]["secrets"] for result in summary["results"]}

        self.assertEqual(coverage["app-a"], "timed_out")
        self.assertEqual(coverage["app-b"], "scanned")
        self.assertEqual(coverage["app-c"], "verified_clean")
        self.assertEqual(summary["affected_projects"], 1)
        self.assertEqual(summary["top_affected"], [{"label": "app-b", "count": 1, "ecosystems": ["npm"]}])

    def test_global_missing_secret_scanner_still_taints_all_secret_coverage(self) -> None:
        summary = reporting.build_summary(
            results=[
                {"label": "app-a", "git_root": "app-a", "ecosystems": ["npm"], "findings": [], "setup_debt": []},
                {"label": "app-b", "git_root": "app-b", "ecosystems": ["npm"], "findings": [], "setup_debt": []},
            ],
            secret_findings=[],
            stats={
                "commands": [],
                "mode_setup_debt": [{"scanner": "gitleaks", "target": "/workspace", "reason": "missing binary"}],
            },
            skipped=[],
            artifact_dir=Path("/tmp/artifacts"),
            requested_modes={"secrets": True},
        )

        self.assertEqual(
            {result["coverage"]["secrets"] for result in summary["results"]},
            {"scanner_missing"},
        )
</file>

<file path="tests/test_engine_dependencies.py">
from __future__ import annotations

import contextlib
import io
import json
import sys
import tempfile
import unittest
import os
import subprocess
from pathlib import Path

ROOT = Path(__file__).resolve().parents[1]
SCRIPTS = ROOT / "scripts"
sys.path.insert(0, str(SCRIPTS))

from vulnscan import ci, cli, config, discovery, engines, hygiene, inventory, orchestration, parsers, remediation, reporting, sast, sbom, secrets, supply_chain, tracker as tracker_mod  # noqa: E402

TEST_OPENAI_KEY = "sk-" + "abcdefghijklmnopqrstuvwxyz123"


class EngineDependencyExecutionTests(unittest.TestCase):
    def test_fake_npm_binary_records_command_and_artifact(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_npm = bin_dir / "npm"
            fake_npm.write_text(
                "#!/usr/bin/env bash\n"
                "cat <<'JSON'\n"
                '{"vulnerabilities":{"left-pad":{"severity":"high","via":[{"severity":"high","source":1,"title":"bad","url":"https://example.test"}]}}}\n'
                "JSON\n",
                encoding="utf-8",
            )
            fake_npm.chmod(0o755)
            project_dir = root / "app"
            project_dir.mkdir()
            (project_dir / "package.json").write_text('{"dependencies":{"left-pad":"1.0.0"}}', encoding="utf-8")
            (project_dir / "package-lock.json").write_text("{}", encoding="utf-8")
            project = discovery.ProjectRoot(path=project_dir, label="app", git_root=None, files={"package.json", "package-lock.json"})
            old_path = os.environ.get("PATH", "")
            os.environ["PATH"] = f"{bin_dir}{os.pathsep}{old_path}"
            try:
                findings, debt, stats = engines.scan_js_project(
                    project,
                    root / "artifacts",
                    {"engines": {"javascript": {"prefer_bun": False, "fallback_to_npm": True, "timeout_seconds": 10}}},
                )
                artifact_exists = Path(stats["commands"][0]["artifact"]).exists()
            finally:
                os.environ["PATH"] = old_path

        self.assertEqual(debt, [])
        self.assertEqual(findings[0]["package"], "left-pad")
        self.assertEqual(stats["npm_success"], 1)
        self.assertEqual(stats["commands"][0]["scanner"], "npm-audit")
        self.assertTrue(artifact_exists)

    def test_missing_javascript_tools_become_setup_debt(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            project_dir = root / "app"
            project_dir.mkdir()
            project = discovery.ProjectRoot(path=project_dir, label="app", git_root=None, files={"package.json", "package-lock.json"})
            old_path = os.environ.get("PATH", "")
            os.environ["PATH"] = ""
            try:
                findings, debt, stats = engines.scan_js_project(
                    project,
                    root / "artifacts",
                    {"engines": {"javascript": {"prefer_bun": True, "fallback_to_npm": True, "timeout_seconds": 10}}},
                )
            finally:
                os.environ["PATH"] = old_path

        self.assertEqual(findings, [])
        self.assertEqual(stats["commands"], [])
        self.assertEqual(debt[0]["reason"], "missing binary")
        self.assertEqual(debt[0]["scanner"], "javascript-native")

    def test_empty_native_audit_output_after_nonzero_exit_is_scanner_debt(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_bun = bin_dir / "bun"
            fake_bun.write_text(
                "#!/usr/bin/env bash\n"
                "exit 1\n",
                encoding="utf-8",
            )
            fake_bun.chmod(0o755)
            project_dir = root / "app"
            project_dir.mkdir()
            (project_dir / "package.json").write_text('{"dependencies":{"left-pad":"1.0.0"}}\n', encoding="utf-8")
            (project_dir / "bun.lock").write_text("", encoding="utf-8")
            project = discovery.ProjectRoot(path=project_dir, label="app", git_root=None, files={"package.json", "bun.lock"})
            old_path = os.environ.get("PATH", "")
            os.environ["PATH"] = f"{bin_dir}{os.pathsep}{old_path}"
            try:
                findings, debt, stats = engines.scan_js_project(
                    project,
                    root / "artifacts",
                    {"engines": {"javascript": {"enabled": True, "prefer_bun": True, "fallback_to_npm": False, "bun_command": "bun", "timeout_seconds": 10}}},
                )
            finally:
                os.environ["PATH"] = old_path

        self.assertEqual(findings, [])
        self.assertEqual(stats["bun_error"], 1)
        self.assertEqual(stats["bun_parse_failed"], 0)
        self.assertEqual(stats["commands"][0]["status"], "scanner_failed")
        self.assertEqual(debt[0]["reason"], "scanner failed")

    def test_fake_pip_audit_binary_scans_python_project(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_pip_audit = bin_dir / "pip-audit"
            fake_pip_audit.write_text(
                "#!/usr/bin/env bash\n"
                "cat <<'JSON'\n"
                '{"dependencies":[{"name":"django","version":"4.2.0","vulns":[{"id":"PYSEC-1","description":"bad","fix_versions":["4.2.1"]}]}]}\n'
                "JSON\n",
                encoding="utf-8",
            )
            fake_pip_audit.chmod(0o755)
            project_dir = root / "app"
            project_dir.mkdir()
            (project_dir / "requirements.txt").write_text("django==4.2.0\n", encoding="utf-8")
            project = discovery.ProjectRoot(path=project_dir, label="app", git_root=None, files={"requirements.txt"})
            old_path = os.environ.get("PATH", "")
            os.environ["PATH"] = f"{bin_dir}{os.pathsep}{old_path}"
            try:
                findings, debt, stats = engines.scan_python_project(
                    project,
                    root / "artifacts",
                    {"engines": {"python": {"enabled": True, "command": "pip-audit", "timeout_seconds": 10}}},
                )
            finally:
                os.environ["PATH"] = old_path

        self.assertEqual(debt, [])
        self.assertEqual(findings[0]["package"], "django")
        self.assertEqual(stats["success"], 1)
        self.assertEqual(stats["commands"][0]["scanner"], "pip-audit")

    def test_fake_cargo_binary_scans_rust_project(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_cargo = bin_dir / "cargo"
            fake_cargo.write_text(
                "#!/usr/bin/env bash\n"
                "cat <<'JSON'\n"
                '{"vulnerabilities":{"list":[{"advisory":{"id":"RUSTSEC-1","package":"openssl","title":"bad"},"package":{"name":"openssl","version":"0.10.0"},"versions":{"patched":[">=0.10.1"]}}]}}\n'
                "JSON\n",
                encoding="utf-8",
            )
            fake_cargo.chmod(0o755)
            project_dir = root / "app"
            project_dir.mkdir()
            (project_dir / "Cargo.toml").write_text("[package]\nname='app'\n", encoding="utf-8")
            (project_dir / "Cargo.lock").write_text("", encoding="utf-8")
            project = discovery.ProjectRoot(path=project_dir, label="app", git_root=None, files={"Cargo.toml", "Cargo.lock"})
            old_path = os.environ.get("PATH", "")
            os.environ["PATH"] = f"{bin_dir}{os.pathsep}{old_path}"
            try:
                findings, debt, stats = engines.scan_rust_project(
                    project,
                    root / "artifacts",
                    {"engines": {"rust": {"enabled": True, "command": "cargo", "timeout_seconds": 10}}},
                )
            finally:
                os.environ["PATH"] = old_path

        self.assertEqual(debt, [])
        self.assertEqual(findings[0]["package"], "openssl")
        self.assertEqual(stats["success"], 1)
        self.assertEqual(stats["commands"][0]["command"][-2:], ["audit", "--json"])

    def test_fake_trivy_binary_scans_filesystem_project(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_trivy = bin_dir / "trivy"
            fake_trivy.write_text(
                "#!/usr/bin/env bash\n"
                "out=''\n"
                "prev=''\n"
                "for arg in \"$@\"; do\n"
                "  if [[ \"$prev\" == '--output' ]]; then out=\"$arg\"; fi\n"
                "  prev=\"$arg\"\n"
                "done\n"
                "cat > \"$out\" <<'JSON'\n"
                '{"Results":[{"Target":"Dockerfile","Misconfigurations":[{"ID":"DS001","Severity":"HIGH","Title":"bad"}]}]}\n'
                "JSON\n",
                encoding="utf-8",
            )
            fake_trivy.chmod(0o755)
            repo = root / "repo"
            repo.mkdir()
            (repo / "Dockerfile").write_text("FROM scratch\n", encoding="utf-8")
            old_path = os.environ.get("PATH", "")
            os.environ["PATH"] = f"{bin_dir}{os.pathsep}{old_path}"
            try:
                findings_by_root, stats = engines.scan_trivy_filesystems(
                    [repo],
                    root,
                    {"engines": {"trivy": {"enabled": True, "command": "trivy", "scanners": "vuln,misconfig,secret,license", "timeout_seconds": 10}}},
                    root / "artifacts",
                )
            finally:
                os.environ["PATH"] = old_path

        self.assertEqual(stats["ran"], 1)
        self.assertEqual(findings_by_root["repo"][0]["category"], "misconfiguration")
        self.assertEqual(stats["commands"][0]["scanner"], "trivy")
        self.assertEqual(stats["commands"][0]["status"], "completed")

    def test_fake_trivy_binary_scans_explicit_image_target(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_trivy = bin_dir / "trivy"
            fake_trivy.write_text(
                "#!/usr/bin/env bash\n"
                "out=''\n"
                "prev=''\n"
                "for arg in \"$@\"; do\n"
                "  if [[ \"$prev\" == '--output' ]]; then out=\"$arg\"; fi\n"
                "  prev=\"$arg\"\n"
                "done\n"
                "cat > \"$out\" <<'JSON'\n"
                '{"Results":[{"Target":"alpine:3.19","Vulnerabilities":[{"VulnerabilityID":"CVE-1","PkgName":"busybox","Severity":"LOW","Title":"bad"}]}]}\n'
                "JSON\n",
                encoding="utf-8",
            )
            fake_trivy.chmod(0o755)
            old_path = os.environ.get("PATH", "")
            os.environ["PATH"] = f"{bin_dir}{os.pathsep}{old_path}"
            try:
                findings, debt, stats = engines.scan_trivy_images(
                    ["alpine:3.19"],
                    {"engines": {"trivy": {"enabled": True, "command": "trivy", "image_scanners": "vuln,secret,license", "timeout_seconds": 10}}},
                    root / "artifacts",
                )
            finally:
                os.environ["PATH"] = old_path

        self.assertEqual(debt, [])
        self.assertEqual(findings[0]["package"], "busybox")
        self.assertEqual(stats["commands"][0]["command"][1], "image")
        self.assertEqual(stats["commands"][0]["status"], "completed")

    def test_trivy_missing_artifact_after_nonzero_exit_is_scanner_debt(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            bin_dir = root / "bin"
            bin_dir.mkdir()
            fake_trivy = bin_dir / "trivy"
            fake_trivy.write_text(
                "#!/usr/bin/env bash\n"
                "exit 1\n",
                encoding="utf-8",
            )
            fake_trivy.chmod(0o755)
            repo = root / "repo"
            repo.mkdir()
            old_path = os.environ.get("PATH", "")
            os.environ["PATH"] = f"{bin_dir}{os.pathsep}{old_path}"
            try:
                findings_by_root, stats = engines.scan_trivy_filesystems(
                    [repo],
                    root,
                    {"engines": {"trivy": {"enabled": True, "command": "trivy", "scanners": "vuln,misconfig,secret,license", "timeout_seconds": 10}}},
                    root / "artifacts",
                )
            finally:
                os.environ["PATH"] = old_path

        self.assertEqual(findings_by_root["repo"], [])
        self.assertEqual(stats["error"], 1)
        self.assertEqual(stats["commands"][0]["status"], "scanner_failed")
        self.assertEqual(stats["setup_debt"][0]["reason"], "scanner failed")

    def test_builtin_secret_fallback_reports_tracked_metadata_only_findings(self) -> None:
        with tempfile.TemporaryDirectory() as tmp:
            root = Path(tmp)
            subprocess.run(["git", "init"], cwd=root, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
            env_file = root / ".env"
            env_file.write_text(f"OPENAI_API_KEY={TEST_OPENAI_KEY}\n", encoding="utf-8")
            subprocess.run(["git", "add", ".env"], cwd=root, check=True, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
            project = discovery.ProjectRoot(path=root, label=".", git_root=root, files={".env"})

            findings, stats = secrets.scan_secrets([project], root, {"engines": {"secrets": {"enabled": True}}})
            serialized = str(findings)

        self.assertEqual(stats["findings"], 1)
        self.assertEqual(findings[0]["source_engine"], "secret-patterns")
        self.assertEqual(findings[0]["category"], "secret")
        self.assertEqual(findings[0]["verification_state"], "unverified")
        self.assertTrue(findings[0]["git_tracked"])
        self.assertIn("history cleanup", findings[0]["remediation_hint"])
        self.assertNotIn(TEST_OPENAI_KEY, serialized)
</file>

<file path="tests/test_scanner.py">
"""Compatibility placeholder.

The scanner suite is split by domain across test_*.py files to keep each file small.
"""
</file>

<file path="TODO.md">
# TODO

- [x] Define the target deliverable as a complete Hermes skill package: `SKILL.md`, scanner CLI, helper scripts, references, templates, and tests aligned around local codebase-aware vulnerability scanning.
- [x] Define the core goal: an agent can inspect any codebase, identify its packages and project types, select the right local scanners, run the scanner tool or direct CLI tools, and report evidence-backed findings.
- [x] Define the default stance: local-first, install required local tools first, scan read-only, no required SaaS services, no credential exposure, and explicit opt-in bounded Codex remediation per affected repo.
- [x] Define supported scan modes: full scan, dependency scan, secrets scan, CI/workflow scan, supply-chain/package-intake scan, SAST scan, SBOM scan, repo-hygiene scan, and remediation-prep scan.
- [x] Define the minimum workflow shared by `SKILL.md` and scripts: discover targets, classify codebases, select engines, run scans, normalize findings, dedupe noise, report results, and preserve artifacts.

- [x] Rewrite `SKILL.md` so it instructs the agent to use the scanner CLI first when the CLI supports the needed scan.
- [x] Rewrite `SKILL.md` so it tells the agent when to call individual scanner tools directly because the scanner CLI does not yet support that engine.
- [x] Replace the truncated generic JavaScript quick-start in `SKILL.md` with real skill-package usage.
- [x] Add a scanner selection matrix to `SKILL.md`.
- [x] Add an agent execution checklist to `SKILL.md`.
- [x] Add a setup-debt reporting contract to `SKILL.md`.
- [x] Add a final-report contract to `SKILL.md`.
- [x] Add a `[SILENT]` contract for unattended clean cron scans.
- [x] Add a safety contract covering read-only scans, secrets, scope gates, and no git mutations.
- [x] Add examples in `SKILL.md` for JavaScript, Python, monorepo, GitHub Actions, package intake, secrets-only, and SBOM scans.

- [x] Rename or redesign `scripts/nightly-vuln-scan.py` into a general scanner CLI if nightly-only semantics are no longer accurate.
- [x] Keep a backwards-compatible entrypoint for nightly cron scans.
- [x] Add CLI subcommands or modes for `scan`, `plan`, `list-engines`, `validate-tools`, and `render-report`.
- [x] Add `--scan-mode` with values for `full`, `dependencies`, `secrets`, `ci`, `supply-chain`, `sast`, `sbom`, `hygiene`, and `remediation-prep`.
- [x] Add `--root` for workspace or repo root.
- [x] Add `--config` for scanner config.
- [x] Add `--output` for normalized JSON summary.
- [x] Add `--artifact-dir` for raw scanner outputs.
- [x] Add `--allowed-root` for hard scope gating.
- [x] Add `--allowed-label-prefix` for label-based scope gating.
- [x] Add `--forbidden-label-prefix` for label exclusions.
- [x] Add `--fail-on-findings` for CI-style failure behavior.
- [x] Add `--fail-on-scope-violation` that exits before scanner execution when targets are out of scope.
- [x] Add `--no-secrets` to disable secrets engines.
- [x] Add `--no-tracker` to disable tracker filtering.
- [x] Add `--tracker-path` to override tracker location.
- [x] Add `--auto-remediate` so Codex remediation is an explicit opt-in.
- [x] Add `--pretty` for readable JSON.
- [x] Add `--format json|text` for machine-readable and human-readable reports.

- [x] Split the scanner code into modules for config loading, discovery, scope enforcement, engine registry, engine execution, parsers, normalization, tracker filtering, remediation prep, and reporting.
- [x] Extract existing scanner responsibilities into modules for shared utilities, config, discovery and scope, engine inventory, implemented engine runners, parsers, secret scanning, tracker filtering, Codex remediation, and reporting.
- [x] Define an engine adapter interface with name, category, enabled state, command detection, target selection, command construction, parser, timeout, artifact path, and setup-debt mapping.
- [x] Build an engine registry so new tools can be added without expanding the main scan loop.
- [x] Add per-engine command overrides in config.
- [x] Add per-engine timeouts in config.
- [x] Add per-engine enable/disable config.
- [x] Add per-engine artifact naming.
- [x] Add per-engine missing-tool handling.
- [x] Add per-engine parser-failure handling.
- [x] Add per-engine timeout handling.
- [x] Add per-engine unsupported-target handling.

- [x] Fix fallback YAML parsing so inline lists like `[]` parse as lists.
- [x] Decide whether to require PyYAML or maintain a tested minimal parser.
- [x] Add config validation that rejects malformed engine config.
- [x] Add config validation that rejects ambiguous scope config.
- [x] Remove starter config fields that are not enforced by code.
- [x] Implement every retained starter config field.
- [x] Document private config expectations without committing private paths, tokens, or scan results.

- [x] Expand discovery for JavaScript and TypeScript package roots using `package.json`, `bun.lock`, `bun.lockb`, `package-lock.json`, `pnpm-lock.yaml`, and `yarn.lock`.
- [x] Expand discovery for Python package roots using `requirements.txt`, `pyproject.toml`, `poetry.lock`, and `Pipfile.lock`.
- [x] Expand discovery for Rust package roots using `Cargo.toml` and `Cargo.lock`.
- [x] Expand discovery for Go package roots using `go.mod`.
- [x] Expand discovery for JVM package roots using `pom.xml`, `build.gradle`, and `build.gradle.kts`.
- [x] Expand discovery for container targets using Dockerfiles, Containerfiles, and Compose files.
- [x] Expand discovery for IaC targets using Terraform, Kubernetes YAML, and Helm charts.
- [x] Expand discovery for GitHub Actions using `.github/workflows`.
- [x] Expand discovery for VS Code extensions using extension package metadata.
- [x] Preserve monorepo subproject boundaries instead of flattening everything to one repo.
- [x] Preserve git-root boundaries separately from project-root boundaries.
- [x] Label every target with a stable relative path.
- [x] Report skipped candidate targets with a reason when useful.
- [x] Keep generated, vendored, archive, fixture, example, cache, build, and dependency directories out of normal scans.

- [x] Keep OSV Scanner as the dependency vulnerability baseline.
- [x] Add native JavaScript engine support for `bun audit`.
- [x] Add native JavaScript engine support for `npm audit`.
- [x] Add native JavaScript engine support for `pnpm audit`.
- [x] Add Python dependency support for `pip-audit`.
- [x] Add Rust dependency support for `cargo audit`.
- [x] Add Go vulnerability support through `govulncheck` or OSV.
- [x] Add JVM dependency support through OSV first and only add dedicated JVM tooling if needed.
- [x] Normalize dependency findings across OSV, Bun, npm, pnpm, pip-audit, cargo-audit, Go, and JVM sources.
- [x] Dedupe dependency findings by repo, project, package, ecosystem, advisory id, and title fallback.

- [x] Add Trivy filesystem scanning for broad local CVE, secret, misconfiguration, license, container, and IaC coverage.
- [x] Add Trivy image scanning only when an image target is explicitly provided or discovered with confidence.
- [x] Parse Trivy vulnerability findings.
- [x] Parse Trivy secret findings without exposing secret values.
- [x] Parse Trivy misconfiguration findings.
- [x] Parse Trivy license findings.
- [x] Categorize Trivy output so it complements OSV instead of duplicating dependency noise.

- [x] Add Gitleaks scanning for hardcoded secrets in current files.
- [x] Add Gitleaks scanning for git history.
- [x] Add TruffleHog scanning for verified credentials.
- [x] Add config to include or exclude unverified TruffleHog findings.
- [x] Add local regex secret-pattern scanning as a fallback when dedicated tools are missing.
- [x] Scan `.env*` git-tracking state for every git root.
- [x] Scan sensitive file extensions such as `.pem`, `.key`, `.p12`, `.crt`, and `.mobileprovision`.
- [x] Ensure all secret findings are metadata-only: file, line, detector, confidence, verification state, and git-tracked state.
- [x] Report tracked secrets as requiring human remediation decisions such as removal, rotation, and possible history cleanup.

- [x] Add GuardDog engine support for npm packages.
- [x] Add GuardDog engine support for PyPI packages.
- [x] Add GuardDog engine support for Go modules if available.
- [x] Add GuardDog engine support for RubyGems if available.
- [x] Add GuardDog engine support for GitHub Actions dependencies.
- [x] Add GuardDog engine support for VS Code extensions.
- [x] Add package-intake CLI support for scanning a named package before adding it to a repo.
- [x] Add package-intake report output with `allow`, `allow with caution`, `avoid`, or `blocked pending review`.
- [x] Document GuardDog as malicious-package behavior scanning, not normal CVE scanning.

- [x] Add zizmor engine support for GitHub Actions security issues.
- [x] Add actionlint engine support for GitHub Actions syntax and expression correctness.
- [x] Run CI/workflow engines when `.github/workflows` exists even if no dependency manifest exists.
- [x] Normalize workflow findings by workflow file, job, step, rule, severity, and remediation hint.
- [x] Add checks or reporting categories for overbroad permissions.
- [x] Add checks or reporting categories for unpinned actions.
- [x] Add checks or reporting categories for untrusted actions.
- [x] Add checks or reporting categories for `pull_request_target` and unsafe checkout patterns.
- [x] Add checks or reporting categories for workflow secret exposure.

- [x] Add Semgrep CE engine support with `--config=auto`.
- [x] Add config for custom Semgrep rule paths.
- [x] Parse Semgrep JSON output.
- [x] Normalize Semgrep findings by file, line, rule id, message, severity, confidence, and remediation hint.
- [x] Keep generated, vendored, archived, fixture, and dependency directories excluded from SAST by default.

- [x] Add Syft engine support for SBOM generation.
- [x] Add CycloneDX JSON SBOM output support.
- [x] Add Grype engine support for SBOM vulnerability scans.
- [x] Add config to skip Grype when Trivy already covers the target and SBOM output was not requested.
- [x] Store SBOM artifacts under the artifact directory.
- [x] Reference SBOM artifact paths in the final report without dumping large SBOM JSON into chat.

- [x] Add OpenSSF Scorecard engine support for repo hygiene checks.
- [x] Document Scorecard network and GitHub API requirements.
- [x] Treat Scorecard results as hygiene findings, not direct vulnerabilities.
- [x] Disable Scorecard by default for private or offline-only scans unless explicitly requested.

- [x] Define scanner priority for default full scans: OSV/native dependency checks, Trivy broad scan, Gitleaks, workflow scanners, Semgrep, then optional SBOM and hygiene engines.
- [x] Define high-value supply-chain additions as GuardDog, zizmor, Gitleaks, and TruffleHog.
- [x] Avoid adding redundant CVE scanners beyond OSV, Trivy, and optional Grype unless a clear coverage gap appears.
- [x] Document that the important non-CVE gaps are malicious package behavior, install scripts, credential theft, GitHub Actions injection, overbroad workflow permissions, untrusted actions, unsigned or unpinned dependencies, and secrets in history.

- [x] Define one normalized finding schema for all engines.
- [x] Include repo label, project label, scanner, category, severity, confidence, package, ecosystem, installed version, fixed version, advisory id, title, URL, file, line, and remediation hint.
- [x] Define one normalized setup-debt schema.
- [x] Include scanner, target, command, reason, missing binary, timeout, parser failure, unsupported target, and suggested next action.
- [x] Define one normalized skipped-target schema.
- [x] Normalize severity across tools.
- [x] Normalize confidence across tools.
- [x] Preserve raw scanner artifacts for auditability.
- [x] Redact or omit sensitive values from all normalized and raw report paths that may be surfaced to the user.

- [x] Implement text report rendering.
- [x] Implement JSON report rendering.
- [x] Include exact commands run in reports.
- [x] Include artifact paths in reports.
- [x] Distinguish verified clean, not scanned, skipped, unsupported, scanner missing, scanner failed, and scanner timed out.
- [x] Include top affected projects.
- [x] Include setup debt summary.
- [x] Include per-engine counts.
- [x] Include per-category counts.
- [x] Include per-severity counts.
- [x] Implement `[SILENT]` only when there are zero findings and zero actionable setup-debt items.

- [x] Keep the scan phase read-only by default and run bounded Codex CLI remediation only after explicit opt-in.
- [x] Add remediation-prep mode that groups findings by likely fix strategy without editing files.
- [x] Group direct dependency update candidates.
- [x] Group transitive override candidates.
- [x] Group manual major-upgrade candidates.
- [x] Group likely unfixable or design-limitation findings.
- [x] Group tracked-secret findings that require rotation.
- [x] Group CI workflow findings that require permission or pinning changes.
- [x] Require explicit remediation opt-in before Codex remediation runs when findings are present.
- [x] Re-scan affected projects after any remediation phase.
- [x] Verify fixes with the same engine that produced the finding.
- [x] Never branch, commit, push, or rewrite history from the scanner skill unless the user explicitly asks for a separate release task.

- [x] Extend vulnerability tracker matching with advisory-id matching.
- [x] Extend vulnerability tracker matching with title substring matching.
- [x] Extend vulnerability tracker matching with package-level fallback for multi-advisory packages.
- [x] Add stale retry handling for unfixable entries when installed package versions change.
- [x] Add retry handling for `blocked_entire_repo` entries after a configured interval.
- [x] Keep `blocked_entire_repo` entries out of normal fixed/unfixable update loops.
- [x] Add atomic tracker writes only after real remediation and same-engine verification.
- [x] Add tracker backup and corruption recovery.

- [x] Add `scripts/validate-config.sh` coverage for all required config sections.
- [x] Add `scripts/validate-tools.sh` to report installed and missing scanner binaries.
- [x] Add install hints for Trivy, Gitleaks, Syft, Grype, Semgrep, actionlint, Scorecard, zizmor, GuardDog, and TruffleHog.
- [x] Verify install hints before documenting them as current.
- [x] Mark install hints as install-first skill behavior with setup-debt reporting when installation fails.
- [x] Add a parser version-floor policy that blocks fake minimum versions until fixtures or upstream schemas prove them.

- [x] Add fixture repos for npm, pnpm, yarn, Python, Rust, Go, JVM, Docker, Terraform, GitHub Actions, VS Code extension, monorepo, and no-manifest cases.
- [x] Add parser tests for OSV output.
- [x] Add parser tests for Bun audit clean output.
- [x] Add parser tests for Bun audit error output.
- [x] Add parser tests for npm audit output.
- [x] Add parser tests for pnpm audit output.
- [x] Add parser tests for pip-audit output.
- [x] Add parser tests for cargo-audit output.
- [x] Add parser tests for Trivy output.
- [x] Add parser tests for Gitleaks output.
- [x] Add parser tests for TruffleHog output.
- [x] Add parser tests for GuardDog output.
- [x] Add parser tests for zizmor output.
- [x] Add parser tests for actionlint output.
- [x] Add parser tests for Semgrep output.
- [x] Add parser tests for Syft output.
- [x] Add parser tests for Grype output.
- [x] Add parser tests for Scorecard output.
- [x] Add integration tests with fake scanner binaries so engine execution can be tested without requiring every real tool.
- [x] Add integration tests proving scope violations stop before scanner execution.
- [x] Add integration tests proving missing tools become setup debt.
- [x] Add integration tests proving unsupported ecosystems are reported accurately.
- [x] Add integration tests proving clean scans can return `[SILENT]`.
- [x] Add integration tests proving `--fail-on-findings` exits nonzero when findings exist.

- [x] Update `README.md` to describe the skill package as `SKILL.md` plus scanner CLI and helper scripts.
- [x] Update `README.md` installation instructions.
- [x] Update `README.md` with local scanner stack guidance.
- [x] Update `README.md` with example CLI invocations.
- [x] Update `README.md` with artifact and report locations.
- [x] Update references so they support the actual CLI and skill behavior instead of generic scanner examples.
- [x] Add a maintenance note that external tool command syntax must be periodically verified.
- [x] Add a rule that new scanner engines require parser tests, fake-binary integration tests, setup-debt behavior, and documentation before becoming default-enabled.
</file>

<file path="scripts/vulnscan/engines.py">
"""Implemented scanner engine runners."""

from __future__ import annotations

import json
import shutil
from pathlib import Path
from typing import Any

from .common import command_record, run, setup_debt_item, stable_id
from .config import cfg_get
from .discovery import ProjectRoot, relpath
from .parsers import dedupe_findings, extract_json, parse_bun, parse_cargo_audit, parse_npm, parse_osv, parse_pip_audit, parse_pnpm, parse_trivy, redact_sensitive_values


def audit_failure_reason(err: str | None, exit_code: int, data: Any) -> tuple[str, str | None]:
    if err == "parse_failed" and exit_code != 0 and data is None:
        return "scanner failed", None
    if err == "parse_failed":
        return "parser failure", err
    return "scanner failed", None


def scan_osv_git_roots(git_roots: list[Path], workspace_root: Path, config: dict[str, Any], artifact_dir: Path) -> tuple[dict[str, list[dict[str, Any]]], dict[str, Any]]:
    stats: dict[str, Any] = {"enabled": bool(cfg_get(config, "engines.osv_scanner.enabled", True)), "missing": False, "ran": 0, "vulnerable": 0, "clean": 0, "timeout": 0, "empty": 0, "parse_failed": 0, "commands": [], "setup_debt": []}
    findings_by_git_root: dict[str, list[dict[str, Any]]] = {}
    if not stats["enabled"]:
        return findings_by_git_root, stats
    command = cfg_get(config, "engines.osv_scanner.command", "osv-scanner")
    osv = shutil.which(command)
    if not osv:
        stats["missing"] = True
        stats["setup_debt"].append(
            setup_debt_item(
                scanner="osv-scanner",
                target=str(workspace_root),
                command=str(command),
                reason="missing binary",
                missing_binary=str(command),
                suggested_next_action=f"Install {command} or disable engines.osv_scanner.enabled",
            )
        )
        return findings_by_git_root, stats
    timeout = int(cfg_get(config, "engines.osv_scanner.timeout_seconds", 60))
    for git_root in git_roots:
        label = relpath(git_root, workspace_root)
        artifact = artifact_dir / "osv" / f"{stable_id(label)}.json"
        cmd = [osv, "scan", "source", "-r", "--format", "json", str(git_root)]
        result = run(cmd, timeout=timeout, outfile=artifact)
        stats["ran"] += 1
        status = "completed"
        if result["code"] == 124:
            stats["timeout"] += 1
            status = "timed_out"
            stats["setup_debt"].append(
                setup_debt_item(
                    scanner="osv-scanner",
                    target=label,
                    command=cmd,
                    reason="timeout",
                    timeout=timeout,
                    suggested_next_action="Retry with a higher engines.osv_scanner.timeout_seconds value or scan this repo directly",
                )
            )
            findings_by_git_root[label] = []
            stats["commands"].append(command_record(scanner="osv-scanner", target=label, command=cmd, artifact=artifact, status=status, exit_code=result["code"]))
            continue
        findings, err = parse_osv(artifact, label)
        if err == "empty_output":
            stats["empty"] += 1
        elif err:
            stats["parse_failed"] += 1
            status = "parser_failed"
            stats["setup_debt"].append(
                setup_debt_item(
                    scanner="osv-scanner",
                    target=label,
                    command=cmd,
                    reason="parser failure",
                    parser_failure=err,
                    suggested_next_action="Inspect the raw OSV artifact and update parse_osv if the output format changed",
                )
            )
        elif findings:
            stats["vulnerable"] += 1
        else:
            stats["clean"] += 1
        findings_by_git_root[label] = findings
        stats["commands"].append(command_record(scanner="osv-scanner", target=label, command=cmd, artifact=artifact, status=status, exit_code=result["code"]))
    return findings_by_git_root, stats


def scan_js_project(project: ProjectRoot, artifact_dir: Path, config: dict[str, Any]) -> tuple[list[dict[str, Any]], list[dict[str, Any]], dict[str, Any]]:
    stats: dict[str, Any] = {"bun_success": 0, "bun_parse_failed": 0, "bun_error": 0, "npm_success": 0, "npm_parse_failed": 0, "npm_error": 0, "pnpm_success": 0, "pnpm_parse_failed": 0, "pnpm_error": 0, "commands": []}
    debt: list[dict[str, Any]] = []
    prefer_bun = bool(cfg_get(config, "engines.javascript.prefer_bun", True))
    fallback_npm = bool(cfg_get(config, "engines.javascript.fallback_to_npm", True))
    bun_command = str(cfg_get(config, "engines.javascript.bun_command", "bun") or "bun")
    npm_command = str(cfg_get(config, "engines.javascript.npm_command", "npm") or "npm")
    pnpm_command = str(cfg_get(config, "engines.javascript.pnpm_command", "pnpm") or "pnpm")
    bun = shutil.which(bun_command)
    npm = shutil.which(npm_command)
    pnpm = shutil.which(pnpm_command)
    files = project.files
    label_id = stable_id(project.label)

    if prefer_bun and bun:
        out = artifact_dir / "native" / f"{label_id}_bun.json"
        timeout = int(cfg_get(config, "engines.javascript.timeout_seconds", 60))
        cmd = [bun, "audit", "--json"]
        run_result = run(cmd, cwd=project.path, timeout=timeout, outfile=out)
        data = extract_json(out.read_text(encoding="utf-8", errors="replace") if out.exists() else "")
        findings, err = parse_bun(data)
        if not err:
            stats["bun_success"] += 1
            stats["commands"].append(command_record(scanner="bun-audit", target=project.label, command=cmd, cwd=project.path, artifact=out, status="completed", exit_code=run_result["code"]))
            return dedupe_findings(findings), debt, stats
        reason, parser_failure = audit_failure_reason(err, run_result["code"], data)
        if reason == "parser failure":
            stats["bun_parse_failed"] += 1
        else:
            stats["bun_error"] += 1
        stats["commands"].append(command_record(scanner="bun-audit", target=project.label, command=cmd, cwd=project.path, artifact=out, status=reason.replace(" ", "_"), exit_code=run_result["code"]))
        debt.append(
            setup_debt_item(
                scanner="bun-audit",
                target=project.label,
                command=cmd,
                reason=reason,
                parser_failure=parser_failure,
                suggested_next_action="Inspect the Bun audit artifact or fall back to npm/pnpm when a matching lockfile exists",
            )
        )

    if fallback_npm and npm and "package-lock.json" in files:
        out = artifact_dir / "native" / f"{label_id}_npm.json"
        timeout = int(cfg_get(config, "engines.javascript.timeout_seconds", 60))
        cmd = [npm, "audit", "--json"]
        run_result = run(cmd, cwd=project.path, timeout=timeout, outfile=out)
        data = extract_json(out.read_text(encoding="utf-8", errors="replace") if out.exists() else "")
        findings, err = parse_npm(data)
        if not err:
            stats["npm_success"] += 1
            stats["commands"].append(command_record(scanner="npm-audit", target=project.label, command=cmd, cwd=project.path, artifact=out, status="completed", exit_code=run_result["code"]))
            return dedupe_findings(findings), [], stats
        reason, parser_failure = audit_failure_reason(err, run_result["code"], data)
        if reason == "parser failure":
            stats["npm_parse_failed"] += 1
        else:
            stats["npm_error"] += 1
        stats["commands"].append(command_record(scanner="npm-audit", target=project.label, command=cmd, cwd=project.path, artifact=out, status=reason.replace(" ", "_"), exit_code=run_result["code"]))
        debt.append(
            setup_debt_item(
                scanner="npm-audit",
                target=project.label,
                command=cmd,
                reason=reason,
                parser_failure=parser_failure,
                suggested_next_action="Inspect the npm audit artifact and update parse_npm if the output format changed",
            )
        )
    elif fallback_npm and pnpm and "pnpm-lock.yaml" in files:
        out = artifact_dir / "native" / f"{label_id}_pnpm.json"
        timeout = int(cfg_get(config, "engines.javascript.timeout_seconds", 60))
        cmd = [pnpm, "audit", "--json"]
        run_result = run(cmd, cwd=project.path, timeout=timeout, outfile=out)
        data = extract_json(out.read_text(encoding="utf-8", errors="replace") if out.exists() else "")
        findings, err = parse_pnpm(data)
        if not err:
            stats["pnpm_success"] += 1
            stats["commands"].append(command_record(scanner="pnpm-audit", target=project.label, command=cmd, cwd=project.path, artifact=out, status="completed", exit_code=run_result["code"]))
            return dedupe_findings(findings), [], stats
        reason, parser_failure = audit_failure_reason(err, run_result["code"], data)
        if reason == "parser failure":
            stats["pnpm_parse_failed"] += 1
        else:
            stats["pnpm_error"] += 1
        stats["commands"].append(command_record(scanner="pnpm-audit", target=project.label, command=cmd, cwd=project.path, artifact=out, status=reason.replace(" ", "_"), exit_code=run_result["code"]))
        debt.append(
            setup_debt_item(
                scanner="pnpm-audit",
                target=project.label,
                command=cmd,
                reason=reason,
                parser_failure=parser_failure,
                suggested_next_action="Inspect the pnpm audit artifact and update parse_pnpm if the output format changed",
            )
        )
    elif not bun and not npm and not pnpm:
        debt.append(
            setup_debt_item(
                scanner="javascript-native",
                target=project.label,
                command=[bun_command, npm_command, pnpm_command],
                reason="missing binary",
                missing_binary=f"{bun_command}/{npm_command}/{pnpm_command}",
                suggested_next_action="Install bun, npm, or pnpm; or disable engines.javascript.enabled",
            )
        )
    elif not bun and "package-lock.json" not in files and "pnpm-lock.yaml" not in files:
        debt.append(
            setup_debt_item(
                scanner="bun-audit",
                target=project.label,
                command=bun_command,
                reason="missing binary",
                missing_binary=bun_command,
                unsupported_target="non-npm JavaScript lockfile without Bun",
                suggested_next_action="Install bun or add a package-lock/pnpm-lock file supported by fallback scanners",
            )
        )
    return [], debt, stats


def scan_python_project(project: ProjectRoot, artifact_dir: Path, config: dict[str, Any]) -> tuple[list[dict[str, Any]], list[dict[str, Any]], dict[str, Any]]:
    stats: dict[str, Any] = {"enabled": bool(cfg_get(config, "engines.python.enabled", False)), "success": 0, "missing": 0, "parse_failed": 0, "error": 0, "timeout": 0, "commands": []}
    debt: list[dict[str, Any]] = []
    if not stats["enabled"]:
        return [], debt, stats

    command = str(cfg_get(config, "engines.python.command", "pip-audit") or "pip-audit")
    binary = shutil.which(command)
    if not binary:
        stats["missing"] += 1
        debt.append(
            setup_debt_item(
                scanner="pip-audit",
                target=project.label,
                command=command,
                reason="missing binary",
                missing_binary=command,
                suggested_next_action="Install pip-audit or disable engines.python.enabled",
            )
        )
        return [], debt, stats

    label_id = stable_id(project.label)
    out = artifact_dir / "native" / f"{label_id}_pip_audit.json"
    timeout = int(cfg_get(config, "engines.python.timeout_seconds", 60))
    cmd = [binary, "-f", "json"]
    if "requirements.txt" in project.files:
        cmd.extend(["-r", "requirements.txt"])
    run_result = run(cmd, cwd=project.path, timeout=timeout, outfile=out)
    status = "completed"
    if run_result["code"] == 124:
        stats["timeout"] += 1
        status = "timed_out"
        debt.append(
            setup_debt_item(
                scanner="pip-audit",
                target=project.label,
                command=cmd,
                reason="timeout",
                timeout=timeout,
                suggested_next_action="Retry with a higher engines.python.timeout_seconds value or run pip-audit directly",
            )
        )
        stats["commands"].append(command_record(scanner="pip-audit", target=project.label, command=cmd, cwd=project.path, artifact=out, status=status, exit_code=run_result["code"]))
        return [], debt, stats

    data = extract_json(out.read_text(encoding="utf-8", errors="replace") if out.exists() else "")
    findings, err = parse_pip_audit(data)
    if err:
        reason, parser_failure = audit_failure_reason(err, run_result["code"], data)
        stats["parse_failed"] += 1 if reason == "parser failure" else 0
        stats["error"] += 0 if reason == "parser failure" else 1
        status = reason.replace(" ", "_")
        debt.append(
            setup_debt_item(
                scanner="pip-audit",
                target=project.label,
                command=cmd,
                reason=reason,
                parser_failure=parser_failure,
                suggested_next_action="Inspect the pip-audit artifact and update parse_pip_audit if the output format changed",
            )
        )
    else:
        stats["success"] += 1
    stats["commands"].append(command_record(scanner="pip-audit", target=project.label, command=cmd, cwd=project.path, artifact=out, status=status, exit_code=run_result["code"]))
    return findings, debt, stats


def scan_rust_project(project: ProjectRoot, artifact_dir: Path, config: dict[str, Any]) -> tuple[list[dict[str, Any]], list[dict[str, Any]], dict[str, Any]]:
    stats: dict[str, Any] = {"enabled": bool(cfg_get(config, "engines.rust.enabled", False)), "success": 0, "missing": 0, "parse_failed": 0, "error": 0, "timeout": 0, "commands": []}
    debt: list[dict[str, Any]] = []
    if not stats["enabled"]:
        return [], debt, stats

    command = str(cfg_get(config, "engines.rust.command", "cargo") or "cargo")
    binary = shutil.which(command)
    if not binary:
        stats["missing"] += 1
        debt.append(
            setup_debt_item(
                scanner="cargo-audit",
                target=project.label,
                command=command,
                reason="missing binary",
                missing_binary=command,
                suggested_next_action="Install cargo and cargo-audit, or disable engines.rust.enabled",
            )
        )
        return [], debt, stats

    label_id = stable_id(project.label)
    out = artifact_dir / "native" / f"{label_id}_cargo_audit.json"
    timeout = int(cfg_get(config, "engines.rust.timeout_seconds", 60))
    cmd = [binary, "audit", "--json"]
    run_result = run(cmd, cwd=project.path, timeout=timeout, outfile=out)
    status = "completed"
    if run_result["code"] == 124:
        stats["timeout"] += 1
        status = "timed_out"
        debt.append(
            setup_debt_item(
                scanner="cargo-audit",
                target=project.label,
                command=cmd,
                reason="timeout",
                timeout=timeout,
                suggested_next_action="Retry with a higher engines.rust.timeout_seconds value or run cargo audit directly",
            )
        )
        stats["commands"].append(command_record(scanner="cargo-audit", target=project.label, command=cmd, cwd=project.path, artifact=out, status=status, exit_code=run_result["code"]))
        return [], debt, stats

    data = extract_json(out.read_text(encoding="utf-8", errors="replace") if out.exists() else "")
    findings, err = parse_cargo_audit(data)
    if err:
        reason, parser_failure = audit_failure_reason(err, run_result["code"], data)
        stats["parse_failed"] += 1 if reason == "parser failure" else 0
        stats["error"] += 0 if reason == "parser failure" else 1
        status = reason.replace(" ", "_")
        debt.append(
            setup_debt_item(
                scanner="cargo-audit",
                target=project.label,
                command=cmd,
                reason=reason,
                parser_failure=parser_failure,
                suggested_next_action="Inspect the cargo-audit artifact and update parse_cargo_audit if the output format changed",
            )
        )
    else:
        stats["success"] += 1
    stats["commands"].append(command_record(scanner="cargo-audit", target=project.label, command=cmd, cwd=project.path, artifact=out, status=status, exit_code=run_result["code"]))
    return findings, debt, stats


def scan_trivy_filesystems(git_roots: list[Path], workspace_root: Path, config: dict[str, Any], artifact_dir: Path) -> tuple[dict[str, list[dict[str, Any]]], dict[str, Any]]:
    stats: dict[str, Any] = {"enabled": bool(cfg_get(config, "engines.trivy.enabled", False)), "missing": False, "ran": 0, "clean": 0, "findings": 0, "timeout": 0, "error": 0, "parse_failed": 0, "commands": [], "setup_debt": []}
    findings_by_git_root: dict[str, list[dict[str, Any]]] = {}
    if not stats["enabled"]:
        return findings_by_git_root, stats

    command = str(cfg_get(config, "engines.trivy.command", "trivy") or "trivy")
    binary = shutil.which(command)
    if not binary:
        stats["missing"] = True
        stats["setup_debt"].append(
            setup_debt_item(
                scanner="trivy",
                target=str(workspace_root),
                command=command,
                reason="missing binary",
                missing_binary=command,
                suggested_next_action="Install trivy or disable engines.trivy.enabled",
            )
        )
        return findings_by_git_root, stats

    scanners = str(cfg_get(config, "engines.trivy.scanners", "vuln,misconfig,secret") or "vuln,misconfig,secret")
    timeout = int(cfg_get(config, "engines.trivy.timeout_seconds", 300))
    for git_root in git_roots:
        label = relpath(git_root, workspace_root)
        artifact = artifact_dir / "trivy" / f"{stable_id(label)}_fs.json"
        artifact.parent.mkdir(parents=True, exist_ok=True)
        cmd = [binary, "fs", "--format", "json", "--output", str(artifact), "--scanners", scanners, str(git_root)]
        result = run(cmd, timeout=timeout)
        stats["ran"] += 1
        status = "completed"
        if result["code"] == 124:
            stats["timeout"] += 1
            status = "timed_out"
            stats["setup_debt"].append(
                setup_debt_item(
                    scanner="trivy",
                    target=label,
                    command=cmd,
                    reason="timeout",
                    timeout=timeout,
                    suggested_next_action="Retry with a higher engines.trivy.timeout_seconds value or run trivy directly",
                )
            )
            findings_by_git_root[label] = []
            stats["commands"].append(command_record(scanner="trivy", target=label, command=cmd, artifact=artifact, status=status, exit_code=result["code"]))
            continue

        if result["code"] != 0 and not artifact.exists():
            stats["error"] += 1
            status = "scanner_failed"
            stats["setup_debt"].append(
                setup_debt_item(
                    scanner="trivy",
                    target=label,
                    command=cmd,
                    reason="scanner failed",
                    suggested_next_action="Run Trivy directly and inspect stderr or retry with a narrower scanner set",
                )
            )
            findings_by_git_root[label] = []
            stats["commands"].append(command_record(scanner="trivy", target=label, command=cmd, artifact=artifact, status=status, exit_code=result["code"]))
            continue

        data = extract_json(artifact.read_text(encoding="utf-8", errors="replace") if artifact.exists() else "")
        findings, err = parse_trivy(data, label, include_package_licenses="license" in {part.strip() for part in scanners.split(",")})
        if data is not None:
            artifact.write_text(json.dumps(redact_sensitive_values(data), indent=2, sort_keys=True), encoding="utf-8")
        if err:
            stats["parse_failed"] += 1
            status = "parser_failed"
            stats["setup_debt"].append(
                setup_debt_item(
                    scanner="trivy",
                    target=label,
                    command=cmd,
                    reason="parser failure",
                    parser_failure=err,
                    suggested_next_action="Inspect the Trivy artifact and update parse_trivy if the output format changed",
                )
            )
        elif findings:
            stats["findings"] += len(findings)
        else:
            stats["clean"] += 1
        findings_by_git_root[label] = findings
        stats["commands"].append(command_record(scanner="trivy", target=label, command=cmd, artifact=artifact, status=status, exit_code=result["code"]))
    return findings_by_git_root, stats


def scan_trivy_images(image_targets: list[str], config: dict[str, Any], artifact_dir: Path) -> tuple[list[dict[str, Any]], list[dict[str, Any]], dict[str, Any]]:
    stats: dict[str, Any] = {"enabled": bool(cfg_get(config, "engines.trivy.enabled", False)), "missing": False, "ran": 0, "clean": 0, "findings": 0, "timeout": 0, "error": 0, "parse_failed": 0, "commands": []}
    debt: list[dict[str, Any]] = []
    findings: list[dict[str, Any]] = []
    if not image_targets or not stats["enabled"]:
        return findings, debt, stats

    command = str(cfg_get(config, "engines.trivy.command", "trivy") or "trivy")
    binary = shutil.which(command)
    if not binary:
        stats["missing"] = True
        debt.append(
            setup_debt_item(
                scanner="trivy",
                target=",".join(image_targets),
                command=command,
                reason="missing binary",
                missing_binary=command,
                suggested_next_action="Install trivy or disable engines.trivy.enabled",
            )
        )
        return findings, debt, stats

    scanners = str(cfg_get(config, "engines.trivy.image_scanners", cfg_get(config, "engines.trivy.scanners", "vuln,secret")) or "vuln,secret")
    timeout = int(cfg_get(config, "engines.trivy.timeout_seconds", 300))
    for image in image_targets:
        artifact = artifact_dir / "trivy" / f"{stable_id(image)}_image.json"
        artifact.parent.mkdir(parents=True, exist_ok=True)
        cmd = [binary, "image", "--format", "json", "--output", str(artifact), "--scanners", scanners, image]
        result = run(cmd, timeout=timeout)
        stats["ran"] += 1
        status = "completed"
        if result["code"] == 124:
            stats["timeout"] += 1
            status = "timed_out"
            debt.append(
                setup_debt_item(
                    scanner="trivy",
                    target=image,
                    command=cmd,
                    reason="timeout",
                    timeout=timeout,
                    suggested_next_action="Retry with a higher engines.trivy.timeout_seconds value or run trivy image directly",
                )
            )
            stats["commands"].append(command_record(scanner="trivy", target=image, command=cmd, artifact=artifact, status=status, exit_code=result["code"]))
            continue

        if result["code"] != 0 and not artifact.exists():
            stats["error"] += 1
            status = "scanner_failed"
            debt.append(
                setup_debt_item(
                    scanner="trivy",
                    target=image,
                    command=cmd,
                    reason="scanner failed",
                    suggested_next_action="Run Trivy image directly and inspect stderr or retry with a narrower scanner set",
                )
            )
            stats["commands"].append(command_record(scanner="trivy", target=image, command=cmd, artifact=artifact, status=status, exit_code=result["code"]))
            continue

        data = extract_json(artifact.read_text(encoding="utf-8", errors="replace") if artifact.exists() else "")
        parsed, err = parse_trivy(data, image, include_package_licenses="license" in {part.strip() for part in scanners.split(",")})
        if data is not None:
            artifact.write_text(json.dumps(redact_sensitive_values(data), indent=2, sort_keys=True), encoding="utf-8")
        if err:
            stats["parse_failed"] += 1
            status = "parser_failed"
            debt.append(
                setup_debt_item(
                    scanner="trivy",
                    target=image,
                    command=cmd,
                    reason="parser failure",
                    parser_failure=err,
                    suggested_next_action="Inspect the Trivy image artifact and update parse_trivy if the output format changed",
                )
            )
        elif parsed:
            stats["findings"] += len(parsed)
            findings.extend(parsed)
        else:
            stats["clean"] += 1
        stats["commands"].append(command_record(scanner="trivy", target=image, command=cmd, artifact=artifact, status=status, exit_code=result["code"]))
    return dedupe_findings(findings), debt, stats
</file>

<file path="scripts/vulnscan/reporting.py">
"""Summary builders and human-readable report rendering."""

from __future__ import annotations

from pathlib import Path
from typing import Any

from .common import now_iso


def normalize_setup_debt(repo: str, item: Any) -> dict[str, Any]:
    if isinstance(item, dict):
        out = dict(item)
        out.setdefault("repo", repo)
        return out
    return {"repo": repo, "item": item, "reason": str(item)}


def build_summary(
    results: list[dict[str, Any]],
    secret_findings: list[dict[str, Any]],
    stats: dict[str, Any],
    skipped: list[dict[str, Any]],
    artifact_dir: Path,
    scope: dict[str, Any] | None = None,
    remediation: dict[str, Any] | None = None,
    skipped_targets: list[dict[str, str]] | None = None,
    requested_modes: dict[str, bool] | None = None,
) -> dict[str, Any]:
    setup_debt = [normalize_setup_debt(r["label"], item) for r in results for item in r.get("setup_debt", [])]
    setup_debt.extend(normalize_setup_debt("__global__", item) for item in stats.get("mode_setup_debt", []))
    severity_counts: dict[str, int] = {}
    engine_counts: dict[str, int] = {}
    category_counts: dict[str, int] = {}
    for result in results:
        for finding in result.get("findings", []):
            severity_counts[finding.get("severity", "UNKNOWN")] = severity_counts.get(finding.get("severity", "UNKNOWN"), 0) + 1
            engine = finding.get("source_engine", "unknown")
            engine_counts[engine] = engine_counts.get(engine, 0) + 1
            category = finding.get("category", "unknown")
            category_counts[category] = category_counts.get(category, 0) + 1
    for finding in secret_findings:
        severity_counts[finding.get("severity", "UNKNOWN")] = severity_counts.get(finding.get("severity", "UNKNOWN"), 0) + 1
        engine = finding.get("source_engine", "secret-patterns")
        engine_counts[engine] = engine_counts.get(engine, 0) + 1
        category = finding.get("category", "secret")
        category_counts[category] = category_counts.get(category, 0) + 1
    secret_findings_by_label = group_secret_findings_by_label(secret_findings)
    affected = [r for r in results if result_finding_count(r, secret_findings_by_label)]
    modes = requested_modes or {}
    results_with_coverage = [attach_project_coverage(result, modes, stats, secret_findings_by_label) for result in results]
    coverage = coverage_summary(results_with_coverage)
    return {
        "generated_at": now_iso(),
        "artifact_dir": str(artifact_dir),
        "scanned_projects": len(results),
        "affected_projects": len(affected),
        "finding_count": sum(len(r.get("findings", [])) for r in results) + len(secret_findings),
        "severity_counts": dict(sorted(severity_counts.items())),
        "engine_counts": dict(sorted(engine_counts.items())),
        "category_counts": dict(sorted(category_counts.items())),
        "scanner_stats": stats,
        "commands": stats.get("commands", []),
        "scope": scope or {},
        "remediation": remediation or {"enabled": False},
        "setup_debt": setup_debt,
        "skipped_by_tracker": len(skipped),
        "skipped_targets": skipped_targets or [],
        "top_affected": [
            {"label": r["label"], "count": result_finding_count(r, secret_findings_by_label), "ecosystems": r.get("ecosystems", [])}
            for r in sorted(affected, key=lambda item: result_finding_count(item, secret_findings_by_label), reverse=True)[:20]
        ],
        "secret_findings": secret_findings,
        "coverage": coverage,
        "results": results_with_coverage,
    }


def setup_debt_status(items: list[dict[str, Any]]) -> str | None:
    reasons = {str(item.get("reason") or "") for item in items}
    if "timeout" in reasons:
        return "timed_out"
    if "missing binary" in reasons:
        return "scanner_missing"
    if "parser failure" in reasons or "scanner failed" in reasons:
        return "scanner_failed"
    if "unsupported target" in reasons:
        return "unsupported"
    if reasons:
        return "skipped"
    return None


def category_setup_debt(result: dict[str, Any], scanners: set[str]) -> list[dict[str, Any]]:
    return [
        item
        for item in result.get("setup_debt", [])
        if str(item.get("scanner") or "") in scanners
    ]


def group_secret_findings_by_label(secret_findings: list[dict[str, Any]]) -> dict[str, list[dict[str, Any]]]:
    grouped: dict[str, list[dict[str, Any]]] = {}
    for finding in secret_findings:
        label = finding.get("source_label")
        if not label:
            continue
        grouped.setdefault(str(label), []).append(finding)
    return grouped


def result_finding_count(result: dict[str, Any], secret_findings_by_label: dict[str, list[dict[str, Any]]]) -> int:
    labels = {str(result.get("label") or ""), str(result.get("git_root") or "")}
    secret_count = sum(len(secret_findings_by_label.get(label, [])) for label in labels)
    return len(result.get("findings", [])) + secret_count


def scanner_setup_debt_status(stats: dict[str, Any], scanners: set[str], labels: set[str]) -> str | None:
    items = [
        item
        for item in stats.get("mode_setup_debt", [])
        if isinstance(item, dict) and str(item.get("scanner") or "") in scanners
        and (str(item.get("target") or "") in labels or str(item.get("reason") or "") == "missing binary")
    ]
    return setup_debt_status(items)


def requested_status(requested: bool, applicable: bool, debt_status: str | None = None, has_findings: bool = False) -> str:
    if not requested:
        return "not_requested"
    if not applicable:
        return "not_applicable"
    if debt_status:
        return debt_status
    return "scanned" if has_findings else "verified_clean"


def attach_project_coverage(
    result: dict[str, Any],
    modes: dict[str, bool],
    stats: dict[str, Any],
    secret_findings_by_label: dict[str, list[dict[str, Any]]] | None = None,
) -> dict[str, Any]:
    ecosystems = set(result.get("ecosystems") or [])
    findings = result.get("findings") or []
    labels = {str(result.get("label") or ""), str(result.get("git_root") or "")}
    secret_findings_by_label = secret_findings_by_label or {}
    project_secret_findings = [finding for label in labels for finding in secret_findings_by_label.get(label, [])]
    has_dependency_target = bool(ecosystems & {"npm", "python", "rust", "go", "jvm", "rubygems", "javascript-no-lockfile"})
    dependency_debt = category_setup_debt(result, {"javascript-native", "bun-audit", "npm-audit", "pnpm-audit", "pip-audit", "cargo-audit"})
    dependency_status = setup_debt_status(dependency_debt) or scanner_setup_debt_status(stats, {"osv-scanner"}, labels)
    has_by_category = {
        "dependencies": any(finding.get("category") == "dependency" for finding in findings),
        "secrets": any(finding.get("category") == "secret" for finding in findings) or bool(project_secret_findings),
        "ci": any(finding.get("category") == "workflow" for finding in findings),
        "sast": any(finding.get("category") == "sast" for finding in findings),
        "sbom": any(finding.get("source_engine") == "grype" for finding in findings),
        "hygiene": any(finding.get("category") == "hygiene" for finding in findings),
        "supply_chain": any(finding.get("category") == "supply-chain" for finding in findings),
    }
    coverage = {
        "dependencies": requested_status(bool(modes.get("dependencies")), has_dependency_target, dependency_status, has_by_category["dependencies"]),
        "secrets": requested_status(bool(modes.get("secrets")), True, scanner_setup_debt_status(stats, {"gitleaks", "trufflehog"}, labels), has_by_category["secrets"]),
        "ci": requested_status(bool(modes.get("ci")), "ci" in ecosystems, scanner_setup_debt_status(stats, {"zizmor", "actionlint"}, labels), has_by_category["ci"]),
        "sast": requested_status(bool(modes.get("sast")), bool(result.get("git_root")), scanner_setup_debt_status(stats, {"semgrep"}, labels), has_by_category["sast"]),
        "sbom": requested_status(bool(modes.get("sbom")), bool(result.get("git_root")), scanner_setup_debt_status(stats, {"syft", "grype"}, labels), has_by_category["sbom"]),
        "hygiene": requested_status(bool(modes.get("hygiene")), bool(result.get("git_root")), scanner_setup_debt_status(stats, {"scorecard"}, labels), has_by_category["hygiene"]),
        "supply_chain": requested_status(bool(modes.get("supply_chain")), bool(ecosystems & {"npm", "python", "go", "rubygems", "ci", "vscode"}), scanner_setup_debt_status(stats, {"guarddog"}, labels), has_by_category["supply_chain"]),
    }
    out = dict(result)
    out["coverage"] = coverage
    return out


def coverage_summary(results: list[dict[str, Any]]) -> dict[str, Any]:
    counts: dict[str, dict[str, int]] = {}
    for result in results:
        for category, status in (result.get("coverage") or {}).items():
            bucket = counts.setdefault(category, {})
            bucket[status] = bucket.get(status, 0) + 1
    return {"counts": counts}


def render_summary_text(summary: dict[str, Any]) -> str:
    lines: list[str] = []
    lines.append(f"Generated: {summary.get('generated_at')}")
    lines.append(f"Artifact dir: {summary.get('artifact_dir')}")
    mode = summary.get("scanner_stats", {}).get("scan_mode")
    if mode:
        lines.append(f"Scan mode: {mode}")
    selected = summary.get("scanner_stats", {}).get("selected_engines")
    if selected:
        lines.append(f"Selected engines: {', '.join(selected)}")
    lines.append(
        "Summary: "
        f"{summary.get('scanned_projects', 0)} projects scanned, "
        f"{summary.get('affected_projects', 0)} affected, "
        f"{summary.get('finding_count', 0)} findings"
    )
    if summary.get("severity_counts"):
        severities = ", ".join(f"{key}={value}" for key, value in summary["severity_counts"].items())
        lines.append(f"Severity counts: {severities}")
    if summary.get("engine_counts"):
        engines = ", ".join(f"{key}={value}" for key, value in summary["engine_counts"].items())
        lines.append(f"Engine counts: {engines}")
    if summary.get("category_counts"):
        categories = ", ".join(f"{key}={value}" for key, value in summary["category_counts"].items())
        lines.append(f"Category counts: {categories}")
    coverage = ((summary.get("coverage") or {}).get("counts") or {})
    if coverage:
        lines.append("Coverage:")
        for category, counts in sorted(coverage.items()):
            rendered = ", ".join(f"{status}={count}" for status, count in sorted(counts.items()))
            lines.append(f"- {category}: {rendered}")
    commands = summary.get("commands") or []
    if commands:
        lines.append("Commands:")
        for command in commands[:40]:
            rendered = " ".join(str(part) for part in command.get("command", []))
            artifact = command.get("artifact")
            suffix = f" -> {artifact}" if artifact else ""
            lines.append(f"- {command.get('scanner')} {command.get('target')}: {command.get('status')} `{rendered}`{suffix}")
    scope = summary.get("scope") or {}
    if scope.get("out_of_scope_count"):
        lines.append(f"Scope violations: {scope['out_of_scope_count']}")
        for item in scope.get("out_of_scope_projects", [])[:20]:
            lines.append(f"- {item.get('label')}: {item.get('reason')}")
    skipped_targets = summary.get("skipped_targets") or []
    if skipped_targets:
        lines.append(f"Skipped targets: {len(skipped_targets)}")
        for item in skipped_targets[:20]:
            lines.append(f"- {item.get('target')}: {item.get('reason')}")
    setup_debt = summary.get("setup_debt") or []
    if setup_debt:
        lines.append("Setup debt:")
        for item in setup_debt[:40]:
            reason = item.get("reason") or item.get("item")
            scanner = item.get("scanner") or "unknown"
            target = item.get("target") or item.get("repo")
            lines.append(f"- {item.get('repo')}: {scanner} {target}: {reason}")
    secret_findings = summary.get("secret_findings") or []
    if secret_findings:
        lines.append("Secret findings:")
        for finding in secret_findings[:40]:
            lines.append(
                f"- {finding.get('severity')} {finding.get('type')} "
                f"{finding.get('file')}:{finding.get('line')} "
                f"tracked={finding.get('git_tracked')}"
            )
    affected = [r for r in summary.get("results", []) if r.get("findings")]
    planned = summary.get("planned_projects") or []
    if planned:
        lines.append(f"Planned projects: {len(planned)}")
        for project in planned[:20]:
            ecosystems = ", ".join(project.get("ecosystems", []))
            lines.append(f"- {project.get('label')}: {ecosystems or 'unknown'}")
    if affected:
        lines.append("Affected projects:")
        for result in affected[:20]:
            lines.append(f"- {result.get('label')}: {len(result.get('findings', []))} findings")
            for finding in result.get("findings", [])[:8]:
                package = finding.get("package") or finding.get("type") or "unknown"
                title = finding.get("title") or finding.get("advisory_id") or ""
                lines.append(
                    f"  - {finding.get('severity', 'UNKNOWN')} "
                    f"{finding.get('source_engine', 'unknown')} {package}: {title}"
                )
    if summary.get("remediation", {}).get("enabled"):
        remediation = summary["remediation"]
        lines.append(
            "Remediation: "
            f"started={remediation.get('started', 0)}, "
            f"completed={remediation.get('completed', 0)}, "
            f"failed={remediation.get('failed', 0)}"
        )
    remediation_prep = summary.get("remediation_prep")
    if remediation_prep:
        counts = ", ".join(f"{key}={value}" for key, value in remediation_prep.get("counts", {}).items() if value)
        lines.append(f"Remediation prep: {counts or 'no grouped findings'}")
    return "\n".join(lines)
</file>

<file path="scripts/nightly-vuln-scan.py">
#!/usr/bin/env python3
"""Backward-compatible entrypoint for nightly vulnerability scans."""

from __future__ import annotations

from vulnscan.cli import main


if __name__ == "__main__":
    raise SystemExit(main())
</file>

<file path="scripts/validate-config.sh">
#!/usr/bin/env bash
# validate-config.sh - Lightweight validation for vulnerability scanning config.
# Usage: ./scripts/validate-config.sh templates/config-starter.yaml

set -euo pipefail

CONFIG_FILE="${1:?Usage: $0 <config_file>}"
SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
SCRIPT_FILE="$SCRIPT_DIR/vuln-scan.py"

if [[ ! -f "$CONFIG_FILE" ]]; then
  echo "Config file not found: $CONFIG_FILE" >&2
  exit 1
fi

if [[ ! -f "$SCRIPT_FILE" ]]; then
  echo "Scanner script not found: $SCRIPT_FILE" >&2
  exit 1
fi

echo "Validating: $CONFIG_FILE"

required_patterns=(
  '^projects_root:'
  '^scan:'
  '^engines:'
  '^  osv_scanner:'
  '^  javascript:'
  '^  secrets:'
  '^  gitleaks:'
  '^  trufflehog:'
  '^  guarddog:'
  '^  zizmor:'
  '^  actionlint:'
  '^  semgrep:'
  '^  syft:'
  '^  grype:'
  '^  scorecard:'
  '^filters:'
  '^tracker:'
  '^remediation:'
)

for pattern in "${required_patterns[@]}"; do
  if ! grep -Eq "$pattern" "$CONFIG_FILE"; then
    echo "Missing required config section/pattern: $pattern" >&2
    exit 1
  fi
done

python3 -m py_compile "$SCRIPT_FILE"
python3 - "$CONFIG_FILE" "$SCRIPT_DIR" <<'PY'
import sys
from pathlib import Path
path = Path(sys.argv[1]).resolve()
scripts_dir = Path(sys.argv[2]).resolve()
sys.path.insert(0, str(scripts_dir))

from vulnscan.config import cfg_get, load_config, validate_config

text = path.read_text()
if '\t' in text:
    raise SystemExit('Config contains tabs; use spaces for YAML indentation')

config = load_config(path)
errors = validate_config(config)
if errors:
    raise SystemExit("Invalid config:\n" + "\n".join(f"- {error}" for error in errors))

starter_config = path.name == "config-starter.yaml" and path.parent.name == "templates"
if starter_config:
    if cfg_get(config, "remediation.auto_fix") is not False:
        raise SystemExit("Starter config must keep remediation.auto_fix: false")
    if cfg_get(config, "remediation.codex.enabled") is not False:
        raise SystemExit("Starter config must keep remediation.codex.enabled: false")
elif cfg_get(config, "remediation.auto_fix") or cfg_get(config, "remediation.codex.enabled"):
    print("Warning: remediation is enabled in this config. Scans can launch Codex remediation when findings are produced.")

print('Config shape and safety checks passed.')
PY

if ! python3 - <<'PY' >/dev/null 2>&1
import yaml
PY
then
  echo "Note: PyYAML is not installed. The scanner has a tiny fallback parser, but PyYAML is recommended for full YAML support."
fi

if ! command -v osv-scanner >/dev/null 2>&1; then
  echo "Note: osv-scanner is not installed or not on PATH. Scans can continue with other engines, but OSV baseline coverage will be skipped."
fi

echo "Validation complete."
</file>

<file path="templates/config-starter.yaml">
# Vulnerability scanning starter config
# Copy and adapt for your environment. Keep private paths and tokens out of public repos.

projects_root: "$HOME/projects"

# Optional hard scope gates for unattended scans.
# The scanner includes scope metadata in JSON output. If you also pass
# --fail-on-scope-violation, any discovered project outside these roots exits 2.
scope:
  allowed_roots:
    - "$HOME/projects/active"
    - "$HOME/projects/experiments"
  allowed_label_prefixes: []
  forbidden_label_prefixes:
    - "archive/"
    - "archived-clones/"

scan:
  max_depth: 6
  silent_when_clean: true
  severity_threshold: low

package_intake:
  # Keep package intake local-first by default. Enable this to query the public
  # OSV API before accepting a named package.
  osv_api_enabled: false

engines:
  osv_scanner:
    enabled: true
    command: "osv-scanner"
    timeout_seconds: 60

  javascript:
    enabled: true
    bun_command: "bun"
    npm_command: "npm"
    pnpm_command: "pnpm"
    prefer_bun: true
    fallback_to_npm: true
    timeout_seconds: 60

  python:
    enabled: false
    command: "pip-audit"

  rust:
    enabled: false
    command: "cargo"

  containers:
    enabled: false
    command: "trivy"

  trivy:
    enabled: true
    command: "trivy"
    # Keep default full-mode output focused on security findings. Add
    # --include-licenses when license review is the point of the scan.
    scanners: "vuln,misconfig,secret"
    image_scanners: "vuln,secret"
    timeout_seconds: 300

  secrets:
    enabled: true

  gitleaks:
    enabled: true
    command: "gitleaks"
    timeout_seconds: 120
    scan_current: true
    # Keep broad full scans fast enough for regular use. Enable history scans
    # for deep secret audits or focused retests.
    scan_history: false

  trufflehog:
    enabled: true
    command: "trufflehog"
    timeout_seconds: 300
    only_verified: true

  guarddog:
    enabled: true
    command: "guarddog"
    timeout_seconds: 300

  zizmor:
    enabled: true
    command: "zizmor"
    timeout_seconds: 120
    format: "json-v1"
    offline: true

  actionlint:
    enabled: true
    command: "actionlint"
    timeout_seconds: 120
    format: "{{json .}}"

  semgrep:
    enabled: true
    command: "semgrep"
    timeout_seconds: 300
    config_auto: "auto"
    rule_paths: []
    exclude:
      - "node_modules"
      - ".git"
      - "dist"
      - "build"
      - "coverage"
      - "target"
      - "vendor"
      - "fixtures"
      - "mocks"
      - "examples"
      - "archive"

  syft:
    enabled: true
    command: "syft"
    timeout_seconds: 300
    output_format: "cyclonedx-json"

  grype:
    enabled: true
    command: "grype"
    timeout_seconds: 300
    skip_when_trivy_covers_target: true

  scorecard:
    # Disabled outside explicit --scan-mode hygiene runs because Scorecard can
    # require network and GitHub/GitLab API access for complete results.
    enabled: false
    command: "scorecard"
    timeout_seconds: 300
    format: "json"
    show_details: true
    use_local: true
    minimum_check_score: 10

filters:
  skip_paths:
    - "**/.git/**"
    - "**/node_modules/**"
    - "**/.next/**"
    - "**/.next-dev/**"
    - "**/.nuxt/**"
    - "**/.svelte-kit/**"
    - "**/.vite/**"
    - "**/.turbo/**"
    - "**/.cache/**"
    - "**/coverage/**"
    - "**/dist/**"
    - "**/build/**"
    - "**/out/**"
    - "**/target/**"
    - "**/vendor/**"
    - "**/fixtures/**"
    - "**/mocks/**"
    - "**/examples/**"
    - "**/example/**"
    - "**/docs/**"
    - "**/archive/**"
    - "**/archived-clones/**"
    - "**/.claude/worktrees/**"
    - "**/context/**"
    - "**/references/**"
    - "**/.developer/skills/**"
    - "**/config/skills/**"
    - "**/scripts/docker/**"

tracker:
  path: "$HOME/.hermes/vuln_knowledge.json"
  skip_known_unfixable: true
  retry_blocked_after_days: 30

remediation:
  # Scan runs are read-only by default. To launch bounded Codex remediation,
  # pass --auto-remediate or use a separate config that explicitly enables it.
  auto_fix: false
  codex:
    enabled: false
    command: "codex"
    max_parallel: 1
    timeout_seconds: 1800
    sandbox: "workspace-write"
    skip_git_repo_check: true
</file>

<file path="SKILL.md">
---
name: vulnerability-scanning
description: >
  Local-first vulnerability and supply-chain scanning for codebases. Use when
  auditing dependencies, secrets, GitHub Actions, source security, SBOMs,
  package intake, cron monitoring, or pre-deploy security posture.
---

# Vulnerability Scanning

This skill tells an agent how to inspect a codebase, identify its packages and
project types, select the right local scanners, run the scanner CLI or direct
tools, and report evidence-backed findings.

## First Instruction: Install And Validate Required Tools First

Before attempting any scan, install or verify the local tools required for the
requested scan mode. Do not start scanner execution until tool validation has
run against the config you will use.

Local setup commands:

```bash
brew install trivy gitleaks syft grype semgrep actionlint
brew install scorecard
brew install zizmor
brew install trufflehog
pipx install guarddog
pipx install pip-audit
cargo install cargo-audit
```

Then validate the installed tools:

```bash
python3 scripts/vuln-scan.py validate-tools \
  --config templates/config-starter.yaml \
  --format text

python3 scripts/vuln-scan.py validate-tools \
  --config templates/config-starter.yaml \
  --format text \
  --deep
```

The first validation must show no missing enabled engines. The deep validation
must show `ok`, `built_in`, or `disabled` for every engine before a broad scan.
If a required tool cannot be installed, either disable that engine deliberately
for the run or report it as setup debt. Never treat a missing scanner as clean
coverage.

Use only the tools required for the requested scan mode. If package-manager
syntax has changed on the host, verify the current install command and report
the correction. GuardDog's upstream docs show `pip install guarddog`; prefer
`pipx install guarddog` for an isolated local CLI install when `pipx` is
available. If GuardDog fails while building `pygit2`, ensure `libgit2` is
installed and retry with a stable local Python, for example:

```bash
brew install libgit2
pipx install --python python3.13 guarddog
```

## Recommended Config Style

Start from `templates/config-starter.yaml` and override narrowly. For broad
local beta validation across unfamiliar repos, use this posture:

```yaml
scope:
  allowed_roots:
    - "/path/to/projects"
scan:
  max_depth: 6
  severity_threshold: "low"
package_intake:
  osv_api_enabled: false
engines:
  trivy:
    enabled: true
    scanners: "vuln,misconfig,secret"
    image_scanners: "vuln,secret"
  gitleaks:
    enabled: true
    scan_current: true
    scan_history: false
  trufflehog:
    enabled: true
    only_verified: true
  semgrep:
    enabled: true
  zizmor:
    enabled: true
    offline: true
  actionlint:
    enabled: true
  syft:
    enabled: true
  grype:
    enabled: true
  guarddog:
    enabled: true
  scorecard:
    enabled: false
remediation:
  auto_fix: false
  codex:
    enabled: false
```

Keep `full` focused on security findings. Do not include Trivy license findings
by default; add `--include-licenses` only when the task is license review. Keep
Gitleaks history scanning off for broad workspace scans; enable
`engines.gitleaks.scan_history: true` only for deep secret audits or focused
secret-history retests. Keep Scorecard disabled unless the user requests
`--scan-mode hygiene`, because it can require network/API behavior. Keep
`package_intake.osv_api_enabled: false` unless the user explicitly wants public
OSV API lookup during package intake. For multi-repo scans, always put
`--output` and `--artifact-dir` outside target repos, usually under `/tmp`.

The skill package includes:

- `SKILL.md`: agent instructions and safety rules
- `scripts/vuln-scan.py`: scanner CLI for local scans, planning, tool validation, and report rendering
- `scripts/nightly-vuln-scan.py`: backwards-compatible wrapper for existing cron runs
- `scripts/validate-config.sh`: config and scanner syntax validation
- `templates/config-starter.yaml`: starter config for local and cron scans
- `references/`: install, behavior, parser, report, remediation, and package-intake contracts

## Core Rules

- Prefer the scanner CLI when it supports the requested scan.
- Inspect the repo before choosing scanners.
- Run only scanners that match the codebase, manifests, workflows, and requested scan mode.
- Treat missing scanners, timeouts, unsupported targets, and parse failures as setup debt, not clean results.
- Never print secret values. Report only metadata such as file, line, detector, severity, confidence, and git-tracked state.
- The scan phase is read-only by default.
- Run bounded Codex CLI remediation only when the user explicitly requests remediation or the command includes `--auto-remediate`.
- Do not branch, commit, push, delete files, rotate credentials, or rewrite history during scan or Codex remediation.
- Use local tools and local artifacts by default. Do not require SaaS services for the normal path.
- Preserve scanner outputs under an artifact directory when possible, but sanitize secret-bearing artifacts before surfacing their paths.
- Final reports must distinguish verified clean, not scanned, skipped, unsupported, missing tool, failed scanner, timed out scanner, and findings present.

## When To Use

- Pre-deploy or CI vulnerability checks
- Recurring cron vulnerability monitoring
- Dependency vulnerability audits
- Secret exposure checks
- GitHub Actions and CI workflow review
- Source-code security scanning
- SBOM generation
- Package-intake review before adding a dependency
- Supply-chain review for suspicious packages, actions, or extensions
- Remediation planning after scan results exist

## Do Not Use For

- Exploit attempts or offensive testing
- Credential extraction or secret disclosure
- Production credential rotation
- Git history rewriting
- Compliance certification claims without external evidence
- Remediation unless the user explicitly requests it

## Agent Checklist

- [ ] Read the user's requested scope and scan mode.
- [ ] Identify the root path, config path, output path, and artifact directory.
- [ ] Discover project types from manifests, lockfiles, workflows, Docker/IaC files, and extension metadata.
- [ ] Apply scope gates before running scanner commands.
- [ ] Choose scanner engines from the selection matrix.
- [ ] Run `scripts/vuln-scan.py scan` when it supports the requested mode.
- [ ] Run direct scanner tools only for engines not yet covered by the CLI.
- [ ] Write large scanner outputs to artifact files instead of relying on terminal stdout.
- [ ] Normalize results across scanners.
- [ ] Dedupe obvious overlap between OSV, native package audits, Trivy, and Grype.
- [ ] Report setup debt separately from findings.
- [ ] Report exact commands run and artifact paths.
- [ ] For each affected repo, launch one Codex CLI remediation task only when remediation was explicitly requested.
- [ ] Re-scan affected repos after Codex runs and classify remaining findings as fixed, still fixable, unfixable, or retry later.

## Scanner CLI

Use the scanner CLI for normal local scans:

```bash
python3 scripts/vuln-scan.py scan \
  --config templates/config-starter.yaml \
  --root /path/to/projects \
  --scan-mode full \
  --output /tmp/vuln-summary.json \
  --artifact-dir /tmp/vuln-artifacts \
  --format text
```

For CI-style failure behavior:

```bash
python3 scripts/vuln-scan.py scan \
  --config templates/config-starter.yaml \
  --root /path/to/repo \
  --scan-mode dependencies \
  --fail-on-findings \
  --output /tmp/vuln-summary.json
```

For explicit remediation after findings are produced:

```bash
python3 scripts/vuln-scan.py scan \
  --config templates/config-starter.yaml \
  --root /path/to/repo \
  --scan-mode dependencies \
  --auto-remediate \
  --output /tmp/vuln-summary.json \
  --artifact-dir /tmp/vuln-artifacts \
  --format text
```

For focused retests after installing a scanner or changing one parser:

```bash
python3 scripts/vuln-scan.py scan \
  --config templates/config-starter.yaml \
  --root /path/to/projects \
  --scan-mode full \
  --only-engine trivy \
  --only-engine gitleaks,semgrep \
  --output /tmp/vuln-summary.json \
  --artifact-dir /tmp/vuln-artifacts \
  --format text
```

For strict unattended scans:

```bash
python3 scripts/vuln-scan.py scan \
  --config templates/config-starter.yaml \
  --root /path/to/projects \
  --allowed-root /path/to/projects/active \
  --fail-on-scope-violation \
  --output /tmp/vuln-summary.json
```

For tool availability:

```bash
python3 scripts/vuln-scan.py validate-tools --format text
```

For installed-tool smoke checks:

```bash
python3 scripts/vuln-scan.py validate-tools --format text --deep
```

For engine inventory:

```bash
python3 scripts/vuln-scan.py list-engines --format text
```

For planning without scanner execution:

```bash
python3 scripts/vuln-scan.py plan \
  --config templates/config-starter.yaml \
  --root /path/to/projects \
  --scan-mode full \
  --format text
```

For rendering an existing JSON summary:

```bash
python3 scripts/vuln-scan.py render-report /tmp/vuln-summary.json --format text
```

`scripts/nightly-vuln-scan.py` remains a backwards-compatible wrapper for
existing cron jobs.

## Examples

JavaScript dependency scan:

```bash
python3 scripts/vuln-scan.py scan \
  --root /path/to/js-repo \
  --scan-mode dependencies \
  --output /tmp/js-vuln-summary.json \
  --artifact-dir /tmp/js-vuln-artifacts \
  --format text
```

Python dependency scan:

```bash
python3 scripts/vuln-scan.py scan \
  --root /path/to/python-repo \
  --scan-mode dependencies \
  --output /tmp/python-vuln-summary.json \
  --artifact-dir /tmp/python-vuln-artifacts \
  --format text
```

Monorepo scan with scope gates:

```bash
python3 scripts/vuln-scan.py scan \
  --root /path/to/monorepo \
  --allowed-label-prefix apps/ \
  --allowed-label-prefix packages/ \
  --forbidden-label-prefix archive/ \
  --fail-on-scope-violation \
  --scan-mode full \
  --format text
```

GitHub Actions scan:

```bash
python3 scripts/vuln-scan.py scan \
  --root /path/to/repo \
  --scan-mode ci \
  --output /tmp/ci-summary.json \
  --artifact-dir /tmp/ci-artifacts \
  --format text
```

The CLI runs `zizmor --format json-v1 --offline` for workflow security and
`actionlint -format '{{json .}}'` for workflow syntax, expression, and workflow
footgun checks.

Package-intake scan:

```bash
python3 scripts/vuln-scan.py package-intake npm package-name \
  --output /tmp/package-intake.json \
  --artifact-dir /tmp/package-intake-artifacts \
  --format text
```

Use ecosystems `npm`, `pypi`, `go`, `rubygems`, `github_action`, or
`extension`. The package-intake command returns one of `allow`,
`allow with caution`, `avoid`, or `blocked pending review`.

Secrets-only scan:

```bash
python3 scripts/vuln-scan.py scan \
  --root /path/to/repo \
  --scan-mode secrets \
  --output /tmp/secrets-summary.json \
  --artifact-dir /tmp/secrets-artifacts \
  --format text
```

SBOM scan:

```bash
syft /path/to/repo -o cyclonedx-json > /tmp/sbom.cdx.json
grype sbom:/tmp/sbom.cdx.json
```

## Scan Modes

| Mode | Use |
|---|---|
| `full` | Normal local security scan across dependency, broad repo, secrets, workflow, and SAST engines; SBOM, hygiene, supply-chain, and license scanning remain explicit |
| `dependencies` | Known vulnerable dependency checks |
| `secrets` | Secret scanning and git-tracked `.env*` checks |
| `ci` | GitHub Actions and CI workflow checks |
| `supply-chain` | Package-intake and malicious-package behavior checks |
| `sast` | Source-code security scanning |
| `sbom` | SBOM generation and optional SBOM vulnerability checks |
| `hygiene` | Repo security hygiene checks |
| `remediation-prep` | Group findings by likely fix strategy without editing files |

## Scanner Selection Matrix

| Evidence in repo or request | Preferred scanners |
|---|---|
| Any supported dependency manifests or lockfiles | OSV Scanner first, then native ecosystem audit |
| `package.json` with `bun.lock` or `bun.lockb` | `bun audit --json` |
| `package.json` with `package-lock.json` | `npm audit --json` |
| `package.json` with `pnpm-lock.yaml` | `pnpm audit --json` |
| Python manifests | `pip-audit` |
| Rust manifests | `cargo audit` |
| Go modules | `govulncheck` or OSV |
| JVM manifests | OSV first; add dedicated JVM tooling only when needed |
| Dockerfile, Compose, Terraform, Kubernetes, Helm | Trivy filesystem scan |
| Image target provided by user | Trivy image scan |
| License review requested | Add `--include-licenses` to include Trivy license findings |
| Retesting only changed scanner behavior | Add repeatable `--only-engine <name>` selectors from `list-engines` |
| Secrets-only request or git repo | Gitleaks; TruffleHog when verified credentials are requested |
| Missing dedicated secret tools | Local regex secret-pattern scan as fallback |
| New npm or PyPI dependency intake | GuardDog, plus optional OSV API lookup when config enables it |
| GitHub Action intake | GuardDog, zizmor, action pinning checks |
| VS Code extension intake | GuardDog where supported |
| `.github/workflows` | zizmor and actionlint |
| Source-code security scan | Semgrep CE with `--config=auto` |
| SBOM requested | Syft, then Grype when vulnerability scan from SBOM is needed |
| Repo hygiene requested | OpenSSF Scorecard, noting any GitHub or network requirements |

## Codebase Discovery

Classify project roots from:

- JavaScript/TypeScript: `package.json`, `bun.lock`, `bun.lockb`, `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`
- Python: `requirements.txt`, `pyproject.toml`, `poetry.lock`, `Pipfile.lock`
- Rust: `Cargo.toml`, `Cargo.lock`
- Go: `go.mod`
- JVM: `pom.xml`, `build.gradle`, `build.gradle.kts`
- Containers: `Dockerfile`, `Containerfile`, Compose files
- IaC: Terraform, Kubernetes YAML, Helm charts
- CI: `.github/workflows`
- VS Code extensions: extension package metadata in `package.json`

Keep monorepo subprojects separate. Label each target by stable relative path.
Skip generated, vendored, archived, fixture, example, cache, build, and
dependency directories unless the user explicitly asks to scan them.

## Reporting Contract

Every non-silent report must include:

- Scope scanned
- Scan mode
- Commands run
- Artifact paths
- Findings grouped by repo/project
- Setup debt grouped separately
- Skipped targets when relevant
- Counts by severity, category, and scanner
- Remaining uncertainty
- Coverage status by category: `scanned`, `verified_clean`, `not_requested`, `not_applicable`, `skipped`, `unsupported`, `scanner_missing`, `scanner_failed`, or `timed_out`

Normalized finding fields should include:

- repo label
- project label
- scanner
- category
- severity
- confidence
- package and ecosystem when applicable
- installed version when available
- fixed version when available
- advisory id and URL when available
- file and line when applicable
- remediation hint

Setup debt fields should include:

- scanner
- target
- command
- reason
- missing binary, timeout, parser failure, or unsupported target
- suggested next action

## Silent Cron Contract

For unattended cron delivery, respond exactly:

```text
[SILENT]
```

Only do this when all are true:

- zero findings
- zero actionable setup-debt items
- zero scope violations
- zero parse failures
- zero scanner timeouts

Do not return `[SILENT]` if a missing tool prevented coverage.

## Direct Tool Fallback

When the scanner CLI does not yet support a needed engine, call the tool
directly and write output to an artifact file:

```bash
trivy fs --format json --output "$ARTIFACT_DIR/trivy-fs.json" --scanners vuln,misconfig,secret .
gitleaks dir . --report-format json --report-path "$ARTIFACT_DIR/gitleaks-dir.json" --exit-code 0
gitleaks git . --report-format json --report-path "$ARTIFACT_DIR/gitleaks-git.json" --exit-code 0
trufflehog git file://. --json --only-verified > "$ARTIFACT_DIR/trufflehog.jsonl"
semgrep --config=auto --json --output "$ARTIFACT_DIR/semgrep.json" .
actionlint -format '{{json .}}' .github/workflows/* > "$ARTIFACT_DIR/actionlint.json"
zizmor --format json-v1 --offline .github/workflows > "$ARTIFACT_DIR/zizmor.json"
syft . -o cyclonedx-json > "$ARTIFACT_DIR/sbom.cdx.json"
grype sbom:"$ARTIFACT_DIR/sbom.cdx.json" -o json > "$ARTIFACT_DIR/grype.json"
scorecard --local=. --format=json --show-details > "$ARTIFACT_DIR/scorecard.json"
```

Verify direct-tool command syntax against installed versions before relying on
it. If a direct tool is missing, report setup debt.

OpenSSF Scorecard is a hygiene scanner, not a direct vulnerability scanner. Run
it only when repo hygiene is explicitly requested or config enables it. Complete
results can require network access and GitHub or GitLab API tokens, especially
for branch protection, contributors, dependency update, and repository metadata
checks.

## Package Intake

For a user asking whether to add a dependency:

- Identify ecosystem and package name.
- Run `scripts/vuln-scan.py package-intake` for supported ecosystems.
- Run OSV package lookup only when `package_intake.osv_api_enabled` is true or the user explicitly asks for external vulnerability lookup.
- Check package metadata, install scripts, suspicious behavior, and maintainer risk when the tools expose it.
- Return one of: `allow`, `allow with caution`, `avoid`, or `blocked pending review`.

Do not add the dependency unless the user separately asks for implementation.

## Remediation Prep

Remediation prep groups findings by likely fix path:

- direct dependency update
- transitive override candidate
- manual major upgrade
- likely unfixable or design limitation
- tracked secret requiring rotation
- CI workflow permission or pinning change

For normal finding remediation, spawn Codex CLI once per affected repo only
after explicit remediation opt-in. Each task gets that repo's exact findings and
these guardrails:

- work only inside the affected repo
- do not branch
- do not commit
- do not push
- do not delete unrelated files
- do not rotate credentials
- do not rewrite history
- prefer package manager updates and narrow manifest changes
- rerun the scanner engine that produced the finding
- report changed files, commands run, fixed findings, remaining findings, and blocked items

When scanning multiple repos, run Codex tasks with bounded parallelism from
config. Preserve one log file per repo under the artifact directory.

## Vulnerability Tracker

Use `$HOME/.hermes/vuln_knowledge.json` or the configured tracker path to avoid
processing the same finding every run.

Tracker entries should record:

- `repo_label`
- `package`
- `advisory_id`
- `title`
- `status`: `fixed`, `fixable`, `unfixable`, `retry`, or `blocked_entire_repo`
- `reason`
- `last_checked`
- `retry_after_days`, default `30`
- `blocked_entire_repo`, when the repo cannot be safely remediated right now

Skip `fixed` and `unfixable` findings until their retry window expires. After
the retry window, include them again as retry candidates so the agent can check
whether a new package version, scanner update, or ecosystem fix made remediation
possible. Keep `blocked_entire_repo` entries out of normal fixed/unfixable
presence checks and retry them after the configured interval.

## Safety

- Never reveal secret values.
- Never bypass auth, validation, permissions, CORS, rate limits, sandboxing, or data protection as a workaround.
- Never trust a single missing scanner as proof of clean state.
- Never let broad workspace scans escape explicit scope gates.
- Never run destructive git, database, credential, or deployment commands during scan mode.
</file>

<file path="README.md">
# Vulnerability Scanning Skill

A Hermes skill package for local-first vulnerability and supply-chain scanning.

The goal is to let an agent inspect each codebase, identify its packages and
project types, choose the right scanner tools, run the scanner CLI or direct
tools, and return evidence-backed findings without requiring SaaS services for
normal repo scans. Package intake can optionally query the public OSV API when
`package_intake.osv_api_enabled` is enabled.

## Contents

- `SKILL.md`: agent instructions, scanner selection matrix, reporting contract, and safety rules
- `INSTALL.md`: install and setup guide for Hermes, Codex, OpenClaw, and other local agent runtimes
- `scripts/vuln-scan.py`: scanner CLI for deterministic local scans, planning, tool validation, and report rendering
- `scripts/nightly-vuln-scan.py`: backwards-compatible wrapper for existing cron runs
- `scripts/validate-config.sh`: starter config and Python syntax validation
- `templates/config-starter.yaml`: local scan configuration template
- `references/`: install, behavior, parser, report, remediation, and package-intake contracts

## Current Scanner CLI

Run a full local scan:

```bash
python3 scripts/vuln-scan.py scan \
  --config templates/config-starter.yaml \
  --root "$HOME/projects" \
  --scan-mode full \
  --output ./vuln-summary.json \
  --artifact-dir ./vuln-artifacts \
  --format text
```

Run dependency-only CI behavior:

```bash
python3 scripts/vuln-scan.py scan \
  --config templates/config-starter.yaml \
  --root "$PWD" \
  --scan-mode dependencies \
  --fail-on-findings \
  --output ./vuln-summary.json
```

Run explicit remediation after scan findings are produced:

```bash
python3 scripts/vuln-scan.py scan \
  --config templates/config-starter.yaml \
  --root "$PWD" \
  --scan-mode dependencies \
  --auto-remediate \
  --output ./vuln-summary.json \
  --artifact-dir ./vuln-artifacts \
  --format text
```

List scanner engines:

```bash
python3 scripts/vuln-scan.py list-engines --format text
```

Check tool availability:

```bash
python3 scripts/vuln-scan.py validate-tools --format text
```

Run installed-tool smoke checks:

```bash
python3 scripts/vuln-scan.py validate-tools --format text --deep
```

Plan a scan without running scanners:

```bash
python3 scripts/vuln-scan.py plan \
  --root "$HOME/projects" \
  --scan-mode full \
  --format text
```

Retest only specific scanners after a tool install or parser change:

```bash
python3 scripts/vuln-scan.py scan \
  --config templates/config-starter.yaml \
  --root "$HOME/projects" \
  --scan-mode full \
  --only-engine trivy \
  --only-engine gitleaks,semgrep \
  --output ./vuln-summary.json \
  --artifact-dir ./vuln-artifacts \
  --format text
```

Render a saved JSON report:

```bash
python3 scripts/vuln-scan.py render-report ./vuln-summary.json --format text
```

## Scan Modes

Supported CLI values:

- `full`
- `dependencies`
- `secrets`
- `ci`
- `supply-chain`
- `sast`
- `sbom`
- `hygiene`
- `remediation-prep`

`full` means the normal local security scan: dependency, broad repo, secrets,
workflow, and SAST engines. SBOM, repo hygiene, and GuardDog supply-chain scans
stay explicit because they can add heavier artifacts, network/API behavior, or
package-intake semantics. Trivy license scanning is also explicit; pass
`--include-licenses` when license review is part of the task.
Gitleaks history scanning is off in the starter config for broad workspace
scans; enable `engines.gitleaks.scan_history: true` for deep secret-history
audits or focused retests.

Use `--only-engine` to limit execution to specific scanner engines during
retests. The option is repeatable and comma-separated. Valid names are the
engine names from `list-engines`, plus aliases such as `ci`, `secrets`, `sbom`,
and `javascript-native`.

The current implementation covers dependency scanning through OSV, native
JavaScript audits, `pip-audit`, and `cargo audit`; broad Trivy filesystem/image
scans; and secret scanning through Gitleaks, TruffleHog, and the metadata-only
fallback scanner; GitHub Actions scanning through zizmor and actionlint;
Semgrep CE SAST through `--config=auto` or custom rule paths; and SBOM
generation/scanning through Syft plus Grype; and explicit repo-hygiene scans
through OpenSSF Scorecard; and GuardDog supply-chain/package-intake scans for
npm, PyPI, Go, RubyGems, GitHub Actions, and VS Code extensions. Package
intake stays local-first unless OSV API lookup is enabled in config. The
scanner also reports per-project coverage state so a clean finding set is not
confused with missing, skipped, unsupported, failed, or timed-out scanner
coverage. Unsupported targets, missing tools, and scanner failures are reported
as setup debt instead of being mistaken for clean coverage.
`remediation-prep` is read-only and groups findings by likely fix strategy
without launching Codex.

`scripts/nightly-vuln-scan.py` remains available for existing cron jobs and
passes through to the same CLI implementation.

## Scanner Stack Direction

The package should prioritize coverage that normal CVE scanning misses:

- malicious package behavior
- install scripts
- credential theft
- GitHub Actions injection
- overbroad workflow permissions
- untrusted or unpinned actions
- unsigned or unpinned dependencies
- secrets in git history

Highest-value tools:

- OSV Scanner for known vulnerable dependencies
- Trivy for broad local filesystem, image, IaC, and secret coverage
- Trivy license scanning through explicit `--include-licenses`
- Gitleaks for fast secret scanning
- TruffleHog for verified credential scanning
- GuardDog for malicious package behavior
- zizmor and actionlint for GitHub Actions
- Semgrep CE for local SAST
- Syft and Grype for SBOM and SBOM vulnerability scans
- OpenSSF Scorecard for repo hygiene when network/GitHub access is acceptable

Do not add redundant CVE scanners unless they cover a real gap beyond OSV,
Trivy, and optional Grype.

## Safety Defaults

- The scan phase is read-only.
- Starter `full` scans run current-tree Gitleaks by default, not full git
  history, to keep broad workspace scans usable. Turn on
  `engines.gitleaks.scan_history` for deep secret-history audits.
- Remediation is opt-in with `--auto-remediate` or a separate config that explicitly enables `remediation.auto_fix` and `remediation.codex.enabled`.
- Missing tools, timeouts, parser failures, and unsupported targets are setup debt, not clean results.
- Secret values must never be printed or summarized.
- The scanner must not branch, commit, push, delete files, rotate credentials, or rewrite history during scan mode.
- Strict unattended scans should use `--allowed-root` and `--fail-on-scope-violation`.
- Scorecard is disabled outside explicit `--scan-mode hygiene` runs because
  complete results may require network access and GitHub/GitLab API tokens.

## Vulnerability Tracker

The configured tracker path, defaulting to `$HOME/.hermes/vuln_knowledge.json`,
keeps fixed, fixable, unfixable, and blocked findings from being reprocessed
every run. Fixed, unfixable, and blocked entries are skipped until their retry
window expires. The default retry window is 30 days, after which the scanner
surfaces the finding again so Codex can retry remediation if the ecosystem has
changed.

## Install

For full setup instructions, read `INSTALL.md`.

If you want an agent to install it for you, give Hermes, Codex, OpenClaw, or
another local agent this prompt:

```text
Follow the instructions in INSTALL.md to install the vulnerability-scanning skill.
Set it up for my local agent runtime, install and validate the required scanner tools, create a local config from templates/config-starter.yaml, and ask me the setup questions from INSTALL.md before changing remediation, tracker, OSV API, license scanning, Scorecard, or Gitleaks history behavior.
Use read-only scanning by default, keep artifacts and reports outside target repos, enable tracker/cache behavior unless I decline it, and do not enable Codex auto-remediation unless I explicitly approve it.
After setup, run config validation, validate-tools, validate-tools --deep, and a plan run against the workspace I provide. Report the exact commands and results.
```

## Privacy

This repository intentionally contains no private paths, personal repo names,
tokens, scan results, or environment-specific vulnerability tracker data.

## Maintenance

External scanner command syntax changes over time. Before default-enabling a new
engine, verify current CLI flags, add parser tests, add fake-binary integration
coverage, define setup-debt behavior, and document the engine in this README and
`SKILL.md`.

## License

MIT
</file>

</files>