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

secure_code_audit/sarif.py

@@ -0,0 +1,221 @@
+"""SARIF 2.1.0 emit + ingest.
+
+Spec: https://www.oasis-open.org/standard/sarif-v2-1-0/
+SARIF JSON schema: https://github.com/oasis-tcs/sarif-spec/blob/main/sarif-2.1/schemas/sarif-schema-2.1.0.json
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Iterable
+
+from secure_code_audit import __version__
+from secure_code_audit.findings import Confidence, Finding, Severity
+from secure_code_audit.standards import cwe_url
+
+_SARIF_LEVEL = {
+    Severity.CRITICAL:      "error",
+    Severity.HIGH:          "error",
+    Severity.MEDIUM:        "warning",
+    Severity.LOW:           "note",
+    Severity.INFORMATIONAL: "none",
+}
+
+
+def emit(findings: Iterable[Finding]) -> dict:
+    """Build a SARIF 2.1.0 document from canonical findings."""
+    findings = list(findings)
+
+    # Build the rules array per-canonical-rule (rule_id is local; dedupe).
+    rule_meta: dict[str, dict] = {}
+    results: list[dict] = []
+
+    for f in findings:
+        rid = f.rule_id
+        if rid not in rule_meta:
+            rule_meta[rid] = _rule(f)
+        results.append(_result(f))
+
+    return {
+        "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schemas/sarif-schema-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [{
+            "tool": {
+                "driver": {
+                    "name":            "secure-code-agent",
+                    "informationUri":  "https://github.com/marshallguillory86/secure-code-agent",
+                    "version":         __version__,
+                    "rules":           list(rule_meta.values()),
+                }
+            },
+            "results": results,
+        }],
+    }
+
+
+def _rule(f: Finding) -> dict:
+    rule: dict = {
+        "id":   f.rule_id,
+        "name": f.rule_id,
+        "shortDescription": {"text": f.short_desc or f.message[:120]},
+        "defaultConfiguration": {"level": _SARIF_LEVEL[f.severity]},
+        "properties": {
+            "category":    f.category.value,
+            "scanner":     f.scanner,
+            "owasp_top10": f.owasp_top10,
+            "asvs":        f.asvs_section,
+            "nist_ssdf":   f.nist_ssdf,
+            "cwe_top25":   f.cwe_top25,
+        },
+    }
+    if f.canonical_cwe:
+        rule["properties"]["cwe"] = [f.canonical_cwe]
+        rule["helpUri"] = cwe_url(f.canonical_cwe)
+    return rule
+
+
+def _result(f: Finding) -> dict:
+    region: dict = {"startLine": max(1, f.line_start)}
+    if f.line_end and f.line_end != f.line_start:
+        region["endLine"] = f.line_end
+    if f.code_snippet:
+        region["snippet"] = {"text": f.code_snippet}
+
+    return {
+        "ruleId":          f.rule_id,
+        "level":           _SARIF_LEVEL[f.severity],
+        "message":         {"text": f.message},
+        "fingerprints":    {"secure-code-agent/v1": f.fingerprint},
+        "properties":      {
+            "confidence":  f.confidence.value,
+            "category":    f.category.value,
+            "is_new":      f.is_new,
+            "suppressed":  f.suppressed,
+        },
+        "locations": [{
+            "physicalLocation": {
+                "artifactLocation": {"uri": f.file_path.as_posix()},
+                "region":            region,
+            }
+        }],
+    }
+
+
+def write(findings: Iterable[Finding], output: Path) -> None:
+    output.write_text(json.dumps(emit(findings), indent=2), encoding="utf-8")
+
+
+# ----- ingest -------------------------------------------------------------
+
+_SARIF_LEVEL_TO_SEVERITY: dict[str, Severity] = {
+    "error":   Severity.HIGH,
+    "warning": Severity.MEDIUM,
+    "note":    Severity.LOW,
+    "none":    Severity.INFORMATIONAL,
+}
+
+
+def ingest(sarif_path: Path, default_scanner: str = "external_sarif") -> list[Finding]:
+    """Parse an external SARIF file (CodeQL, Snyk, Trivy, etc.) into canonical
+    Findings. We trust the SARIF's own rule metadata for severity + CWE;
+    standards.lookup() may still enhance via the local map."""
+    payload = _read_sarif(sarif_path)
+    if payload is None:
+        return []
+
+    out: list[Finding] = []
+    for run in payload.get("runs", []):
+        out.extend(_findings_from_run(run, default_scanner))
+    return out
+
+
+def _read_sarif(path: Path) -> dict | None:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def _findings_from_run(run: dict, default_scanner: str) -> list[Finding]:
+    driver  = (run.get("tool") or {}).get("driver") or {}
+    scanner = (driver.get("name") or default_scanner).lower().replace(" ", "_")
+    rules   = {r.get("id"): r for r in (driver.get("rules") or [])}
+
+    findings: list[Finding] = []
+    for result in run.get("results", []):
+        findings.append(_finding_from_result(result, rules, scanner))
+    return findings
+
+
+def _finding_from_result(result: dict, rules: dict, scanner: str) -> Finding:
+    from secure_code_audit.findings import Category
+    from secure_code_audit.standards import is_top25, lookup
+
+    rule_id = result.get("ruleId") or "unknown"
+    rule    = rules.get(rule_id, {})
+    msg     = (result.get("message") or {}).get("text") or rule_id
+
+    severity = _severity_from_result(result, rule)
+    cwe      = _cwe_from_rule(rule)
+    file_path, line_start, line_end, snippet = _location_from_result(result)
+
+    entry = lookup(scanner, rule_id)
+    canonical_cwe = cwe or (entry.canonical_cwe if entry else None)
+
+    fingerprint = Finding.make_fingerprint(
+        canonical_cwe=canonical_cwe,
+        rule_id=rule_id,
+        file_path=file_path,
+        code_snippet=snippet,
+    )
+    return Finding(
+        rule_id=rule_id,
+        scanner=scanner,
+        fingerprint=fingerprint,
+        canonical_cwe=canonical_cwe,
+        owasp_top10=entry.owasp_top10 if entry else None,
+        asvs_section=entry.asvs_section if entry else None,
+        nist_ssdf=entry.nist_ssdf if entry else None,
+        category=entry.category if entry else Category.CODE_VULNERABILITIES,
+        severity=severity,
+        confidence=Confidence.MEDIUM,
+        file_path=file_path,
+        line_start=line_start,
+        line_end=line_end if line_end and line_end != line_start else None,
+        code_snippet=snippet,
+        message=msg,
+        short_desc=entry.short_desc if entry else None,
+        fix_hint=entry.fix_hint if entry else None,
+        cwe_top25=is_top25(canonical_cwe),
+    )
+
+
+def _severity_from_result(result: dict, rule: dict) -> Severity:
+    level = (
+        result.get("level")
+        or rule.get("defaultConfiguration", {}).get("level")
+        or "warning"
+    )
+    return _SARIF_LEVEL_TO_SEVERITY.get(level, Severity.MEDIUM)
+
+
+def _cwe_from_rule(rule: dict) -> str | None:
+    props = rule.get("properties") or {}
+    cwe   = props.get("cwe")
+    if isinstance(cwe, list) and cwe:
+        return cwe[0]
+    if isinstance(cwe, str):
+        return cwe
+    return None
+
+
+def _location_from_result(result: dict) -> tuple[Path, int, int | None, str | None]:
+    locs = result.get("locations") or [{}]
+    phys = (locs[0].get("physicalLocation") or {}) if locs else {}
+    file_uri   = (phys.get("artifactLocation") or {}).get("uri") or ""
+    region     = phys.get("region") or {}
+    line_start = int(region.get("startLine") or 0)
+    line_end   = int(region.get("endLine") or line_start) if region else None
+    snippet    = (region.get("snippet") or {}).get("text")
+    file_path  = Path(file_uri) if file_uri else Path(".")
+    return file_path, line_start, line_end, snippet

secure_code_audit/scanners/__init__.py

@@ -0,0 +1,50 @@
+"""Scanner subprocesses. Each module is a single-purpose adapter:
+  in:  scanner invocation + target path
+  out: list[Finding] in the canonical schema (see secure_code_audit.findings).
+
+The registry below is the lookup the CLI uses to enumerate active scanners.
+"""
+from __future__ import annotations
+
+from typing import Callable, Iterable
+
+from secure_code_audit.findings import Finding
+
+from secure_code_audit.scanners.base import Scanner
+from secure_code_audit.scanners.bandit_scanner     import BanditScanner
+from secure_code_audit.scanners.builtin_rules      import BuiltinRulesScanner
+from secure_code_audit.scanners.checkov_scanner    import CheckovScanner
+from secure_code_audit.scanners.gitleaks_scanner   import GitleaksScanner
+from secure_code_audit.scanners.hadolint_scanner   import HadolintScanner
+from secure_code_audit.scanners.npm_audit_scanner  import NpmAuditScanner
+from secure_code_audit.scanners.osv_scanner        import OsvScanner
+from secure_code_audit.scanners.pip_audit_scanner  import PipAuditScanner
+from secure_code_audit.scanners.scorecard_scanner  import ScorecardScanner
+from secure_code_audit.scanners.semgrep_scanner    import SemgrepScanner
+from secure_code_audit.scanners.trivy_scanner      import TrivyScanner
+from secure_code_audit.scanners.trufflehog_scanner import TruffleHogScanner
+
+SCANNERS: dict[str, type[Scanner]] = {
+    # Tier-1 — Python / Node / secrets / SAST
+    "bandit":         BanditScanner,
+    "builtin_rules":  BuiltinRulesScanner,
+    "gitleaks":       GitleaksScanner,
+    "npm_audit":      NpmAuditScanner,
+    "pip_audit":      PipAuditScanner,
+    "semgrep":        SemgrepScanner,
+    # Tier-2 — IaC / containers / supply chain / multi-ecosystem SCA / verified secrets
+    "checkov":        CheckovScanner,
+    "hadolint":       HadolintScanner,
+    "osv_scanner":    OsvScanner,
+    "scorecard":      ScorecardScanner,
+    "trivy":          TrivyScanner,
+    "trufflehog":     TruffleHogScanner,
+}
+
+
+def all_scanner_names() -> list[str]:
+    return list(SCANNERS.keys())
+
+
+def get(name: str) -> type[Scanner] | None:
+    return SCANNERS.get(name)

secure_code_audit/scanners/bandit_scanner.py

@@ -0,0 +1,83 @@
+"""Bandit — Python SAST.
+
+Invocation:
+  bandit -r <target> -f json -ll -ii [--exclude <pattern>]
+
+Output: JSON with results[] array. Each result has filename, line_number,
+test_id (B102, B608, ...), issue_text, issue_severity, issue_confidence,
+and code (the offending snippet).
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from secure_code_audit.config import Config
+from secure_code_audit.findings import Confidence, Finding, Severity
+from secure_code_audit.scanners.base import Scanner
+
+
+class BanditScanner(Scanner):
+    name   = "bandit"
+    binary = "bandit"
+
+    def run(self, target: Path, config: Config) -> list[Finding]:
+        if not self.is_available():
+            return [self._unavailable_finding(target)]
+
+        sc_cfg = self.cfg(config)
+        args = [
+            self.binary, "-r", str(target),
+            "-f", "json",
+            "--severity-level", "low",
+            "--confidence-level", "low",
+        ]
+        for pat in config.exclude_patterns:
+            args.extend(["--exclude", pat])
+        args.extend(sc_cfg.extra_args)
+
+        # Bandit exits nonzero on findings — accept 0 + 1.
+        r = self._exec(args, cwd=target, timeout_seconds=sc_cfg.timeout_seconds,
+                       allowed_exits=(0, 1))
+        if r.returncode == 124:
+            return [self._timeout_finding(target, r.stderr)]
+        if not r.stdout.strip():
+            return [self._error_finding(target, "bandit emitted no output")]
+
+        try:
+            payload = json.loads(r.stdout)
+        except json.JSONDecodeError as e:
+            return [self._error_finding(target, f"bandit JSON parse failure: {e}")]
+
+        findings: list[Finding] = []
+        for result in payload.get("results", []):
+            rule_id = result.get("test_id") or result.get("test_name") or "unknown"
+            findings.append(self._make_finding(
+                rule_id=rule_id,
+                message=str(result.get("issue_text") or "").strip(),
+                file_path=Path(result.get("filename", "")),
+                line_start=int(result.get("line_number") or 0),
+                line_end=int(result.get("line_range", [0])[-1] or 0)
+                    if isinstance(result.get("line_range"), list)
+                    else None,
+                code_snippet=str(result.get("code") or "").strip() or None,
+                severity=Severity.from_string(result.get("issue_severity", "")),
+                confidence=Confidence.from_string(result.get("issue_confidence", "")),
+            ))
+        return findings
+
+    def _timeout_finding(self, target: Path, stderr: str) -> Finding:
+        return self._make_finding(
+            rule_id=f"{self.name}.tool_timeout",
+            message=f"bandit timed out: {stderr}",
+            file_path=target, line_start=0, line_end=None, code_snippet=None,
+            severity=Severity.INFORMATIONAL, confidence=Confidence.HIGH,
+        )
+
+    def _error_finding(self, target: Path, message: str) -> Finding:
+        return self._make_finding(
+            rule_id=f"{self.name}.tool_error",
+            message=message,
+            file_path=target, line_start=0, line_end=None, code_snippet=None,
+            severity=Severity.INFORMATIONAL, confidence=Confidence.HIGH,
+        )

secure_code_audit/scanners/base.py

@@ -0,0 +1,194 @@
+"""Scanner protocol + subprocess helpers."""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from abc import ABC, abstractmethod
+from pathlib import Path
+from typing import Optional
+
+from secure_code_audit.config import Config, scanner_cfg
+from secure_code_audit.findings import Category, Confidence, Finding, Severity
+from secure_code_audit.standards import StandardsEntry, is_top25, lookup
+
+
+class Scanner(ABC):
+    """Base class for all scanner adapters.
+
+    Subclasses implement `_run_subprocess()` and `_parse_output()` (or
+    override `run()` entirely for built-in / in-process scanners).
+    """
+
+    name:         str   # canonical id used in config + reports
+    binary:       str   # name of the executable on PATH
+    version_flag: str   = "--version"
+    default_category: Category = Category.CODE_VULNERABILITIES
+
+    # ----- availability ----------------------------------------------------
+
+    def is_available(self) -> bool:
+        return shutil.which(self.binary) is not None
+
+    def binary_version(self) -> Optional[str]:
+        if not self.is_available():
+            return None
+        try:
+            r = subprocess.run(
+                [self.binary, self.version_flag],
+                check=False, capture_output=True, text=True, timeout=10,
+            )
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            return None
+        out = (r.stdout or r.stderr or "").strip().splitlines()
+        return out[0] if out else None
+
+    # ----- main entrypoint ------------------------------------------------
+
+    @abstractmethod
+    def run(self, target: Path, config: Config) -> list[Finding]:
+        """Execute the scanner against target. MUST NOT raise.
+
+        Errors are converted to a single informational finding so the
+        audit pipeline never dies on a single scanner failing.
+        """
+        ...
+
+    # ----- subprocess helpers ---------------------------------------------
+
+    def _exec(
+        self,
+        args: list[str],
+        cwd:  Path,
+        timeout_seconds: int,
+        allowed_exits: tuple[int, ...] = (0,),
+    ) -> subprocess.CompletedProcess:
+        """Run a scanner subprocess with sanitized env, no shell.
+
+        Some scanners (npm audit, pip-audit) exit nonzero on findings; pass
+        `allowed_exits` to mark those as success."""
+        env = self._sanitized_env()
+        try:
+            r = subprocess.run(
+                args,
+                cwd=str(cwd),
+                env=env,
+                shell=False,
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=timeout_seconds,
+            )
+        except subprocess.TimeoutExpired as exc:
+            return subprocess.CompletedProcess(
+                args=exc.cmd or args,
+                returncode=124,
+                stdout="",
+                stderr=f"timeout after {timeout_seconds}s",
+            )
+        if r.returncode not in allowed_exits and r.returncode != 0:
+            return r  # caller decides how to handle
+        return r
+
+    @staticmethod
+    def _sanitized_env() -> dict[str, str]:
+        """A minimal env for subprocesses — keep PATH and locale, drop the rest.
+        Prevents accidental secret-leak into the scanner process via env."""
+        keep = ("PATH", "HOME", "LANG", "LC_ALL", "TMPDIR", "TEMP", "TMP")
+        return {k: v for k, v in os.environ.items() if k in keep}
+
+    # ----- finding construction helper ------------------------------------
+
+    def _make_finding(
+        self,
+        *,
+        rule_id:    str,
+        message:    str,
+        file_path:  Path,
+        line_start: int,
+        line_end:   Optional[int],
+        code_snippet: Optional[str],
+        severity:   Optional[Severity]   = None,
+        confidence: Optional[Confidence] = None,
+        category:   Optional[Category]   = None,
+        cwe_override: Optional[str]      = None,
+        scanner_name: Optional[str]      = None,
+    ) -> Finding:
+        """Construct a canonical Finding from scanner-emitted bits, layering
+        in the standards mapping. Scanner-emitted severity wins over the
+        map's default; confidence falls back to the map; category is set
+        per the map unless explicitly overridden."""
+
+        scanner_label = scanner_name or self.name
+        entry: Optional[StandardsEntry] = lookup(scanner_label, rule_id)
+
+        # Mapping fallback to wildcard (handled inside lookup).
+        canonical_cwe = cwe_override or (entry.canonical_cwe if entry else None)
+        owasp_top10   = entry.owasp_top10 if entry else None
+        asvs_section  = entry.asvs_section if entry else None
+        nist_ssdf     = entry.nist_ssdf    if entry else None
+        chosen_cat    = category or (entry.category if entry else self.default_category)
+        chosen_sev    = severity or (entry.severity if entry else Severity.MEDIUM)
+        chosen_conf   = confidence or (entry.confidence if entry else Confidence.MEDIUM)
+        short_desc    = entry.short_desc if entry else None
+        fix_hint      = entry.fix_hint  if entry else None
+
+        fingerprint = Finding.make_fingerprint(
+            canonical_cwe=canonical_cwe,
+            rule_id=rule_id,
+            file_path=file_path,
+            code_snippet=code_snippet,
+        )
+
+        return Finding(
+            rule_id=rule_id,
+            scanner=scanner_label,
+            fingerprint=fingerprint,
+            canonical_cwe=canonical_cwe,
+            owasp_top10=owasp_top10,
+            asvs_section=asvs_section,
+            nist_ssdf=nist_ssdf,
+            category=chosen_cat,
+            severity=chosen_sev,
+            confidence=chosen_conf,
+            file_path=file_path,
+            line_start=line_start,
+            line_end=line_end,
+            code_snippet=code_snippet,
+            message=message,
+            short_desc=short_desc,
+            fix_hint=fix_hint,
+            cwe_top25=is_top25(canonical_cwe),
+        )
+
+    def _unavailable_finding(self, target: Path) -> Finding:
+        """Informational finding emitted when the binary isn't on PATH."""
+        return Finding(
+            rule_id=f"{self.name}.tool_unavailable",
+            scanner=self.name,
+            fingerprint=f"unavailable.{self.name}",
+            canonical_cwe=None,
+            owasp_top10=None,
+            asvs_section=None,
+            nist_ssdf=None,
+            category=Category.POLICY_DOCS,
+            severity=Severity.INFORMATIONAL,
+            confidence=Confidence.HIGH,
+            file_path=target,
+            line_start=0,
+            line_end=None,
+            code_snippet=None,
+            message=f"{self.binary} not on PATH; {self.name} scan skipped.",
+            short_desc=None,
+            fix_hint=f"Install {self.binary} to enable {self.name} coverage.",
+        )
+
+    # ----- shared utility -------------------------------------------------
+
+    def cfg(self, config: Config) -> "ScannerConfig":
+        """Convenience accessor."""
+        return scanner_cfg(config, self.name)
+
+
+# Re-export so the registry import in __init__.py is clean.
+from secure_code_audit.config import ScannerConfig  # noqa: E402