secure-code-agent 0.2.0__py3-none-any.whl

secure_code_audit/cli.py

@@ -0,0 +1,258 @@
+"""CLI entrypoint — `secure-code-agent` and `secure-code-audit`.
+
+Wires together: config load → scanner runs → suppressions → baseline diff →
+scoring → gate evaluation → render outputs.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import replace
+from pathlib import Path
+
+from secure_code_audit import __version__
+from secure_code_audit import baseline as baseline_mod
+from secure_code_audit import config as config_mod
+from secure_code_audit import instructions
+from secure_code_audit import remediation
+from secure_code_audit import renderers
+from secure_code_audit import sarif
+from secure_code_audit import scanners
+from secure_code_audit import suppressions
+from secure_code_audit.findings import Category, Finding, Severity
+from secure_code_audit.git_tools import find_repo_root, loc_under
+from secure_code_audit.scoring import evaluate_gates, score as score_findings
+
+
+def _parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="secure-code-agent",
+        description="Deterministic security gate + bounded AI remediation prompts.",
+    )
+    p.add_argument("paths", nargs="*", default=["."],
+                   help="Paths to scan. Defaults to the current directory.")
+    p.add_argument("--config", default="secure-code-agent.json",
+                   help="Path to config (default: secure-code-agent.json).")
+
+    p.add_argument("--output",        help="Markdown report output path.")
+    p.add_argument("--json-output",   help="Canonical JSON output path.")
+    p.add_argument("--sarif-output",  help="SARIF 2.1.0 output path.")
+    p.add_argument("--comment-output", help="PR-comment markdown output path.")
+    p.add_argument("--prompt-output", help="Remediation prompt output path.")
+    p.add_argument("--baseline",      help="Baseline file path (read).")
+    p.add_argument("--bump-baseline", action="store_true",
+                   help="Rewrite the baseline from current findings.")
+
+    p.add_argument("--fail-on-gate",  action="store_true",
+                   help="Exit nonzero if any gate trips.")
+    p.add_argument("--fail-on-new",   action="store_true",
+                   help="Exit nonzero on findings not in baseline.")
+
+    p.add_argument("--changed-only",
+                   help="Audit only files changed since REF (e.g. main...HEAD).")
+    p.add_argument("--skip-scanners",
+                   help="Comma-separated scanner names to skip.")
+    p.add_argument("--only-scanners",
+                   help="Comma-separated scanner names — only these run.")
+    p.add_argument("--severity-threshold", default="informational",
+                   choices=[s.value for s in Severity],
+                   help="Filter findings below this severity.")
+
+    p.add_argument("--sarif-import", action="append", default=[],
+                   help="Path to an external SARIF file to ingest. May be passed multiple times.")
+
+    p.add_argument("--init-agent-standards", action="store_true",
+                   help="Emit per-agent standards files instead of running an audit.")
+    p.add_argument("--target", action="append", default=[],
+                   help="Target for --init-agent-standards (codex, claude-code, cursor, copilot, windsurf, generic).")
+    p.add_argument("--instructions-output-dir", default=".",
+                   help="Output directory for --init-agent-standards.")
+
+    p.add_argument("--json", action="store_true",
+                   help="Print canonical JSON to stdout (suppresses other terminal output).")
+    p.add_argument("--version", action="version", version=f"secure-code-agent {__version__}")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+
+    if args.init_agent_standards:
+        return _do_init_standards(args)
+
+    return _do_audit(args)
+
+
+def _do_init_standards(args: argparse.Namespace) -> int:
+    targets = args.target or instructions.known_targets()
+    out_dir = Path(args.instructions_output_dir).resolve()
+    out_dir.mkdir(parents=True, exist_ok=True)
+    for t in targets:
+        path = instructions.write_for_target(t, out_dir)
+        print(f"wrote {path}")
+    return 0
+
+
+def _do_audit(args: argparse.Namespace) -> int:
+    cfg = config_mod.load(args.config)
+    target = Path(args.paths[0]).resolve()
+    root   = find_repo_root(target)
+
+    # ----- scanners -----
+    skip = set(filter(None, (args.skip_scanners or "").split(",")))
+    only = set(filter(None, (args.only_scanners or "").split(",")))
+    all_findings: list[Finding] = []
+    ran:        list[str] = []
+    unavailable: list[str] = []
+
+    for name, klass in scanners.SCANNERS.items():
+        if only and name not in only:
+            continue
+        if name in skip:
+            continue
+        sc_cfg = cfg.scanners.get(name) or config_mod.ScannerConfig()
+        if not sc_cfg.enabled:
+            continue
+        scanner = klass()
+        if not scanner.is_available():
+            unavailable.append(name)
+            all_findings.extend(scanner.run(target, cfg))   # emits tool_unavailable info
+            continue
+        ran.append(name)
+        all_findings.extend(scanner.run(target, cfg))
+
+    # ----- SARIF imports -----
+    for sarif_path_str in args.sarif_import:
+        all_findings.extend(sarif.ingest(Path(sarif_path_str)))
+
+    # ----- overrides from config -----
+    all_findings = _apply_overrides(all_findings, cfg)
+
+    # ----- suppressions -----
+    sup_rules, sup_errors = suppressions.load(Path(cfg.suppressions_file))
+    if sup_errors:
+        for err in sup_errors:
+            sys.stderr.write(f"WARN: {err}\n")
+    all_findings = suppressions.apply(all_findings, sup_rules)
+    all_findings.extend(suppressions.expired_findings(sup_rules, Path(cfg.suppressions_file)))
+
+    # ----- severity threshold filter -----
+    threshold = Severity.from_string(args.severity_threshold)
+    all_findings = [f for f in all_findings if f.severity.rank >= threshold.rank]
+
+    # ----- baseline -----
+    baseline_path = Path(args.baseline or cfg.outputs["baseline_path"])
+    baseline      = baseline_mod.load(baseline_path)
+    all_findings  = baseline_mod.mark_new(all_findings, baseline)
+
+    # ----- scoring -----
+    if cfg.loc_for_scoring:
+        loc = int(cfg.loc_for_scoring.get("value", 0))
+    else:
+        loc = loc_under(target, cfg.include_extensions, cfg.exclude_patterns)
+    score = score_findings(all_findings, loc)
+    gate  = evaluate_gates(all_findings, score, cfg.gates)
+
+    # ----- write outputs -----
+    paths = _resolve_outputs(args, cfg, root)
+
+    if paths.markdown is not None:
+        renderers.write_markdown(all_findings, score, gate, paths.markdown, ran, unavailable)
+    if paths.json_out is not None:
+        renderers.write_json(all_findings, score, gate, paths.json_out)
+    if paths.sarif is not None:
+        sarif.write(all_findings, paths.sarif)
+    if paths.comment is not None:
+        renderers.write_pr_comment(all_findings, score, gate, paths.comment)
+    if paths.prompt is not None:
+        remediation.write(all_findings, paths.prompt)
+    if args.bump_baseline:
+        baseline_mod.write(baseline_path, all_findings, baseline)
+
+    # ----- terminal output -----
+    if args.json:
+        sys.stdout.write(json.dumps(renderers.to_json(all_findings, score, gate), indent=2))
+        sys.stdout.write("\n")
+    else:
+        _print_summary(score, gate, ran, unavailable, paths)
+
+    # ----- exit code -----
+    if args.fail_on_gate and not gate.passed:
+        return 1
+    if args.fail_on_new and any(f.is_new and not f.suppressed for f in all_findings):
+        return 1
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _apply_overrides(findings: list[Finding], cfg: "config_mod.Config") -> list[Finding]:
+    """Apply config-level severity_overrides + category_overrides."""
+    if not cfg.severity_overrides and not cfg.category_overrides:
+        return findings
+    out: list[Finding] = []
+    for f in findings:
+        new_severity = f.severity
+        if f.rule_id in cfg.severity_overrides:
+            new_severity = Severity.from_string(cfg.severity_overrides[f.rule_id])
+        new_category = f.category
+        if f.rule_id in cfg.category_overrides:
+            try:
+                new_category = Category(cfg.category_overrides[f.rule_id])
+            except ValueError:
+                pass
+        out.append(replace(f, severity=new_severity, category=new_category))
+    return out
+
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class _OutputPaths:
+    markdown: Path | None
+    json_out: Path | None
+    sarif:    Path | None
+    comment:  Path | None
+    prompt:   Path | None
+
+
+def _resolve_outputs(args: argparse.Namespace, cfg: "config_mod.Config", root: Path) -> _OutputPaths:
+    """CLI flags override config defaults. A flag value of None means
+    'don't emit this format' — by default we emit Markdown only, and
+    other outputs are opt-in via CLI flag or explicit config."""
+    def _p(flag_value, default_key) -> Path | None:
+        if flag_value is not None:
+            return (root / flag_value).resolve()
+        return None
+
+    return _OutputPaths(
+        markdown=_p(args.output       or cfg.outputs.get("markdown_path"), "markdown_path"),
+        json_out=_p(args.json_output,        "json_path"),
+        sarif=   _p(args.sarif_output,       "sarif_path"),
+        comment= _p(args.comment_output,     "comment_path"),
+        prompt=  _p(args.prompt_output,      "prompt_path"),
+    )
+
+
+def _print_summary(score, gate, ran, unavailable, paths) -> None:
+    status = "PASS" if gate.passed else "FAIL"
+    print(f"secure-code-agent  ·  score {score.overall:.2f} ({score.letter})  ·  gate {status}")
+    print(f"  scanned LOC: {score.loc_scanned:,}")
+    print(f"  scanners run: {', '.join(ran) if ran else '(none)'}")
+    if unavailable:
+        print(f"  unavailable: {', '.join(unavailable)}")
+    if not gate.passed:
+        for reason in gate.reasons:
+            print(f"  ✗ {reason}")
+    written = [str(p) for p in (paths.markdown, paths.json_out, paths.sarif,
+                                paths.comment, paths.prompt) if p is not None]
+    if written:
+        print(f"  wrote: {', '.join(written)}")
+
+
+if __name__ == "__main__":
+    sys.exit(main())

secure_code_audit/config.py

@@ -0,0 +1,115 @@
+"""Config loader. Reads secure-code-agent.json (or operator-pointed path),
+validates against the schema, and exposes a Config dataclass."""
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+DEFAULT_CONFIG_PATH = Path("secure-code-agent.json")
+
+DEFAULT_EXCLUDES: tuple[str, ...] = (
+    ".git/", "node_modules/", ".venv/", "venv/", "dist/", "build/",
+    "__pycache__/", ".pytest_cache/", ".ruff_cache/", ".mypy_cache/",
+    "**/*.min.js", "**/*.lock",
+)
+
+DEFAULT_INCLUDE_EXTS: tuple[str, ...] = (
+    ".py", ".js", ".jsx", ".ts", ".tsx", ".go", ".rs", ".java", ".rb",
+    ".sh", ".yaml", ".yml", ".json", "Dockerfile",
+)
+
+DEFAULT_OUTPUTS: dict[str, str] = {
+    "markdown_path": "secure-code-report.md",
+    "json_path":     "secure-code-report.json",
+    "sarif_path":    "secure-code.sarif",
+    "comment_path":  "secure-code-pr-comment.md",
+    "prompt_path":   "secure-code-remediation-prompt.md",
+    "baseline_path": "secure-code-baseline.json",
+}
+
+
+@dataclass
+class ScannerConfig:
+    enabled:         bool          = True
+    timeout_seconds: int           = 600
+    online:          bool          = False
+    extra_args:      list[str]     = field(default_factory=list)
+
+
+@dataclass
+class Config:
+    """Parsed config. Operator-facing access is via attribute names."""
+    version:           int                                = 1
+    asvs_level:        int                                = 2
+    include_extensions: tuple[str, ...]                   = DEFAULT_INCLUDE_EXTS
+    exclude_patterns:  tuple[str, ...]                    = DEFAULT_EXCLUDES
+    scanners:          dict[str, ScannerConfig]           = field(default_factory=dict)
+    severity_overrides: dict[str, str]                    = field(default_factory=dict)
+    category_overrides: dict[str, str]                    = field(default_factory=dict)
+    gates:             dict[str, Any]                     = field(default_factory=dict)
+    outputs:           dict[str, str]                     = field(default_factory=lambda: dict(DEFAULT_OUTPUTS))
+    suppressions_file: str                                = ".scignore.yaml"
+    loc_for_scoring:   dict[str, Any] | None              = None
+    raw:               dict[str, Any]                     = field(default_factory=dict)
+
+
+def load(path: Path | str | None = None) -> Config:
+    """Load config from path. Missing file → defaults. Malformed file → ValueError."""
+    p = Path(path) if path else DEFAULT_CONFIG_PATH
+    if not p.exists():
+        return Config()
+    try:
+        raw = json.loads(p.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise ValueError(f"{p}: invalid JSON: {e}") from e
+    return _from_dict(raw)
+
+
+def _from_dict(raw: dict[str, Any]) -> Config:
+    cfg = Config(raw=raw)
+    cfg.version    = int(raw.get("version", 1))
+    cfg.asvs_level = int(raw.get("asvs_level", 2))
+    if cfg.asvs_level not in (1, 2, 3):
+        raise ValueError(f"asvs_level must be 1, 2, or 3; got {cfg.asvs_level}")
+
+    paths = raw.get("paths") or {}
+    if isinstance(paths.get("include_extensions"), list):
+        cfg.include_extensions = tuple(paths["include_extensions"])
+    if isinstance(paths.get("exclude_patterns"), list):
+        cfg.exclude_patterns = tuple(paths["exclude_patterns"])
+
+    scanners_raw = raw.get("scanners") or {}
+    for name, sc_raw in scanners_raw.items():
+        cfg.scanners[name] = ScannerConfig(
+            enabled=bool(sc_raw.get("enabled", True)),
+            timeout_seconds=int(sc_raw.get("timeout_seconds", 600)),
+            online=bool(sc_raw.get("online", False)),
+            extra_args=list(sc_raw.get("extra_args") or []),
+        )
+
+    cfg.severity_overrides = {
+        str(k): str(v).lower() for k, v in (raw.get("severity_overrides") or {}).items()
+    }
+    cfg.category_overrides = {
+        str(k): str(v).lower() for k, v in (raw.get("category_overrides") or {}).items()
+    }
+    cfg.gates = dict(raw.get("gates") or {})
+
+    outputs = raw.get("outputs") or {}
+    for k, default_v in DEFAULT_OUTPUTS.items():
+        cfg.outputs[k] = outputs.get(k, default_v)
+
+    if "suppressions_file" in raw:
+        cfg.suppressions_file = str(raw["suppressions_file"])
+
+    if "loc_for_scoring" in raw:
+        cfg.loc_for_scoring = raw["loc_for_scoring"]
+
+    return cfg
+
+
+def scanner_cfg(cfg: Config, name: str) -> ScannerConfig:
+    """Return the per-scanner config, defaulting to enabled."""
+    return cfg.scanners.get(name, ScannerConfig())

secure_code_audit/findings.py

@@ -0,0 +1,165 @@
+"""Canonical Finding type — the lingua franca between scanners, scoring, and renderers.
+
+Every scanner returns a list[Finding]. The scoring layer dedupes by `canonical_cwe`
++ `fingerprint`. Renderers consume the same dataclass — markdown, JSON, SARIF,
+PR-comment, remediation prompt all read these fields directly.
+
+See docs/design.md §4.3 for the rationale + field semantics.
+"""
+from __future__ import annotations
+
+import enum
+import hashlib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+
+class Severity(str, enum.Enum):
+    CRITICAL      = "critical"
+    HIGH          = "high"
+    MEDIUM        = "medium"
+    LOW           = "low"
+    INFORMATIONAL = "informational"
+
+    @classmethod
+    def from_string(cls, value: str) -> "Severity":
+        """Parse permissively — scanners use 'info', 'INFO', 'note', 'warning', etc."""
+        normalized = value.strip().lower()
+        return _SEVERITY_ALIASES.get(normalized, cls.INFORMATIONAL)
+
+    @property
+    def rank(self) -> int:
+        """Higher = worse. For sorting."""
+        return _SEVERITY_RANK[self]
+
+
+_SEVERITY_ALIASES: dict[str, Severity] = {
+    "critical":      Severity.CRITICAL,
+    "crit":          Severity.CRITICAL,
+    "error":         Severity.HIGH,
+    "high":          Severity.HIGH,
+    "warning":       Severity.MEDIUM,
+    "moderate":      Severity.MEDIUM,
+    "medium":        Severity.MEDIUM,
+    "med":           Severity.MEDIUM,
+    "low":           Severity.LOW,
+    "note":          Severity.LOW,
+    "info":          Severity.INFORMATIONAL,
+    "informational": Severity.INFORMATIONAL,
+    "none":          Severity.INFORMATIONAL,
+}
+
+_SEVERITY_RANK: dict[Severity, int] = {
+    Severity.CRITICAL:      5,
+    Severity.HIGH:          4,
+    Severity.MEDIUM:        3,
+    Severity.LOW:           2,
+    Severity.INFORMATIONAL: 1,
+}
+
+
+class Confidence(str, enum.Enum):
+    HIGH   = "high"
+    MEDIUM = "medium"
+    LOW    = "low"
+
+    @classmethod
+    def from_string(cls, value: str) -> "Confidence":
+        normalized = (value or "").strip().lower()
+        if normalized in ("high", "h"):
+            return cls.HIGH
+        if normalized in ("medium", "med", "m"):
+            return cls.MEDIUM
+        if normalized in ("low", "l"):
+            return cls.LOW
+        return cls.MEDIUM   # default when scanner doesn't emit confidence
+
+
+class Category(str, enum.Enum):
+    SECRETS               = "secrets"
+    DEPENDENCIES          = "dependencies"
+    CODE_VULNERABILITIES  = "code_vulnerabilities"
+    AUTH_AUTHZ            = "auth_authz"
+    CRYPTO                = "crypto"
+    SUPPLY_CHAIN          = "supply_chain"
+    CONFIG_IAC            = "config_iac"
+    LOGGING_OBSERVABILITY = "logging_observability"
+    POLICY_DOCS           = "policy_docs"
+
+
+@dataclass(frozen=True)
+class Finding:
+    """A normalized security finding."""
+
+    # --- identity ----------------------------------------------------------
+    rule_id:       str          # scanner-local id (e.g. "B608", "generic.sql.tainted")
+    scanner:       str          # which scanner emitted it
+    fingerprint:   str          # stable id for baseline + dedupe
+
+    # --- standards taxonomy (any/all may be None when unmapped) ------------
+    canonical_cwe: Optional[str]  # e.g. "CWE-89" — primary dedupe key
+    owasp_top10:   Optional[str]  # e.g. "A03:2021-Injection"
+    asvs_section:  Optional[str]  # e.g. "V5.3"
+    nist_ssdf:     Optional[str]  # e.g. "PW.5.1"
+    category:      Category
+
+    # --- severity ----------------------------------------------------------
+    severity:   Severity
+    confidence: Confidence
+
+    # --- locus -------------------------------------------------------------
+    file_path:    Path
+    line_start:   int
+    line_end:     Optional[int]
+    code_snippet: Optional[str]
+
+    # --- human-readable ----------------------------------------------------
+    message:    str
+    short_desc: Optional[str]   = None
+    full_desc:  Optional[str]   = None
+    fix_hint:   Optional[str]   = None
+    references: tuple[str, ...] = field(default_factory=tuple)
+
+    # --- lifecycle ---------------------------------------------------------
+    suppressed:       bool          = False
+    suppression_note: Optional[str] = None
+    is_new:           bool          = False   # not in baseline
+
+    # --- flags -------------------------------------------------------------
+    cwe_top25: bool = False         # set by scoring layer
+
+    # ------------------------------------------------------------------ ctor
+    @staticmethod
+    def make_fingerprint(
+        *,
+        canonical_cwe: Optional[str],
+        rule_id:       str,
+        file_path:     Path,
+        code_snippet:  Optional[str],
+    ) -> str:
+        """Stable 16-hex-char fingerprint for dedupe + baseline.
+
+        Inputs:
+          - canonical_cwe falls back to rule_id when no CWE is mapped (so
+            unmapped findings still dedupe per-rule).
+          - file_path is POSIX-normalized for cross-platform stability.
+          - code_snippet is normalized (whitespace collapsed, max 512 chars)
+            so a reformat-only edit doesn't break the fingerprint.
+        """
+        key = canonical_cwe or rule_id
+        path = file_path.as_posix()
+        snippet_norm = (
+            " ".join((code_snippet or "").split())[:512]
+        )
+        material = f"{key}|{path}|{snippet_norm}".encode()
+        return hashlib.sha256(material).hexdigest()[:16]
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def severity_at_or_above(target: Severity) -> set[Severity]:
+    """Return the set of severities >= target. Useful for gate filters."""
+    return {s for s in Severity if s.rank >= target.rank}

secure_code_audit/git_tools.py

@@ -0,0 +1,82 @@
+"""Git helpers — repo root detection, LOC count, changed-only diffing."""
+from __future__ import annotations
+
+import fnmatch
+import subprocess
+from pathlib import Path
+from typing import Iterable
+
+
+def find_repo_root(start: Path) -> Path:
+    """Walk up from `start` until a .git directory is found. Returns `start`
+    if no git repo is present (a tarball / archive run is still supported)."""
+    cur = start.resolve()
+    for parent in (cur, *cur.parents):
+        if (parent / ".git").exists():
+            return parent
+    return cur
+
+
+def changed_files(root: Path, since_ref: str) -> list[Path]:
+    """Return files changed since `since_ref` (e.g. 'main...HEAD'). Suitable
+    for `--changed-only`. Empty list on git failure."""
+    try:
+        out = subprocess.run(
+            ["git", "diff", "--name-only", since_ref],
+            cwd=str(root),
+            check=True,
+            text=True,
+            capture_output=True,
+            timeout=30,
+        )
+    except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
+        return []
+    return [root / line.strip() for line in out.stdout.splitlines() if line.strip()]
+
+
+def is_excluded(path: Path, root: Path, patterns: Iterable[str]) -> bool:
+    """Check if `path` matches any exclude glob. Patterns are tested against
+    the POSIX-relative path from `root`."""
+    try:
+        rel = path.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return False
+    for pat in patterns:
+        if pat.endswith("/"):
+            if rel.startswith(pat) or f"/{pat}" in f"/{rel}/":
+                return True
+        elif fnmatch.fnmatch(rel, pat) or fnmatch.fnmatch(path.name, pat):
+            return True
+    return False
+
+
+def in_scope(path: Path, include_exts: Iterable[str]) -> bool:
+    """Does this path match the configured include_extensions?
+    Dockerfile is matched by basename."""
+    name = path.name
+    for ext in include_exts:
+        if ext.startswith("."):
+            if name.endswith(ext):
+                return True
+        elif name == ext or name.startswith(f"{ext}."):
+            return True
+    return False
+
+
+def loc_under(root: Path, include_exts: Iterable[str], excludes: Iterable[str]) -> int:
+    """Best-effort LOC count for the scoring normalizer. Counts non-blank
+    lines across in-scope files; skips binary content."""
+    total = 0
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        if is_excluded(path, root, excludes):
+            continue
+        if not in_scope(path, include_exts):
+            continue
+        try:
+            text = path.read_text(encoding="utf-8", errors="ignore")
+        except OSError:
+            continue
+        total += sum(1 for line in text.splitlines() if line.strip())
+    return total