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

secure_code_audit/scanners/pip_audit_scanner.py

@@ -0,0 +1,83 @@
+"""pip-audit — Python SCA via PyPI Advisory DB / OSV.
+
+Invocation:
+  pip-audit -r requirements.txt --format=json
+
+Output: JSON with dependencies[] each having vulns[] with id, fix_versions,
+description.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from secure_code_audit.config import Config
+from secure_code_audit.findings import Category, Confidence, Finding, Severity
+from secure_code_audit.scanners.base import Scanner
+
+
+_REQ_NAMES: tuple[str, ...] = (
+    "requirements.txt",
+    "requirements-dev.txt",
+    "requirements/base.txt",
+)
+
+
+class PipAuditScanner(Scanner):
+    name   = "pip_audit"
+    binary = "pip-audit"
+    default_category = Category.DEPENDENCIES
+
+    def run(self, target: Path, config: Config) -> list[Finding]:
+        if not self.is_available():
+            return [self._unavailable_finding(target)]
+
+        req_files = [target / r for r in _REQ_NAMES if (target / r).exists()]
+        if not req_files:
+            return [self._make_finding(
+                rule_id=f"{self.name}.no_requirements",
+                message="No requirements.txt found at target root; pip-audit skipped.",
+                file_path=target, line_start=0, line_end=None, code_snippet=None,
+                severity=Severity.INFORMATIONAL, confidence=Confidence.HIGH,
+                category=Category.DEPENDENCIES,
+            )]
+
+        sc_cfg = self.cfg(config)
+        findings: list[Finding] = []
+        for req in req_files:
+            args = [self.binary, "-r", str(req), "--format=json"]
+            args.extend(sc_cfg.extra_args)
+            r = self._exec(args, cwd=target, timeout_seconds=sc_cfg.timeout_seconds,
+                           allowed_exits=(0, 1))
+            if r.returncode == 124:
+                findings.append(self._make_finding(
+                    rule_id=f"{self.name}.tool_timeout",
+                    message=f"pip-audit timed out on {req.name}: {r.stderr}",
+                    file_path=req, line_start=0, line_end=None, code_snippet=None,
+                    severity=Severity.INFORMATIONAL, confidence=Confidence.HIGH,
+                ))
+                continue
+            if not r.stdout.strip():
+                continue
+            try:
+                payload = json.loads(r.stdout)
+            except json.JSONDecodeError:
+                continue
+
+            deps = payload.get("dependencies", payload if isinstance(payload, list) else [])
+            for dep in deps:
+                name    = dep.get("name", "?")
+                version = dep.get("version", "?")
+                for vuln in dep.get("vulns", []) or []:
+                    vuln_id  = vuln.get("id", "UNKNOWN")
+                    fixes    = vuln.get("fix_versions") or []
+                    desc     = (vuln.get("description") or "").strip()
+                    fix_note = f" Fix in: {', '.join(fixes)}" if fixes else " No fix available."
+                    findings.append(self._make_finding(
+                        rule_id=f"pip_audit.{vuln_id}",
+                        message=f"{name} {version} — {vuln_id}: {desc[:200]}{fix_note}",
+                        file_path=req, line_start=0, line_end=None, code_snippet=None,
+                        severity=Severity.HIGH, confidence=Confidence.HIGH,
+                        category=Category.DEPENDENCIES,
+                    ))
+        return findings

secure_code_audit/scanners/scorecard_scanner.py

@@ -0,0 +1,156 @@
+"""OpenSSF Scorecard — repo + supply-chain hygiene.
+
+Special case among scanners:
+  · Operates on a REMOTE repo URL, not a local path.
+  · Needs the GH_TOKEN env var (or equivalent) to query GitHub APIs.
+  · Best run on the repo root, not on a subdirectory.
+
+Invocation:
+  scorecard --repo=<github-url> --format=json --show-details
+
+Output: JSON with `checks[]` array, each having `name`, `score` (0-10
+or -1 for inconclusive), `reason`, `details[]`, and `documentation.url`.
+
+We map each Scorecard check into `supply_chain` (or `policy_docs` for
+documentation-style checks). Score → severity mapping:
+  · score < 0       → INFORMATIONAL (inconclusive — check couldn't run)
+  · score < 3       → HIGH          (clearly failing)
+  · score < 7       → MEDIUM        (warning)
+  · score < 10      → LOW           (acceptable but not perfect)
+  · score == 10     → no finding emitted (passed cleanly)
+"""
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+
+from secure_code_audit.config import Config
+from secure_code_audit.findings import Category, Confidence, Finding, Severity
+from secure_code_audit.scanners.base import Scanner
+
+
+# Checks whose semantics are "documentation present" rather than
+# supply-chain integrity.
+_POLICY_DOCS_CHECKS = {"Security-Policy", "License", "CII-Best-Practices"}
+
+
+class ScorecardScanner(Scanner):
+    name   = "scorecard"
+    binary = "scorecard"
+    default_category = Category.SUPPLY_CHAIN
+
+    def run(self, target: Path, config: Config) -> list[Finding]:
+        if not self.is_available():
+            return [self._unavailable_finding(target)]
+
+        repo_url = self._infer_repo_url(target)
+        if repo_url is None:
+            return [self._make_finding(
+                rule_id=f"{self.name}.no_remote",
+                message="Scorecard requires a remote GitHub URL (origin remote not found).",
+                file_path=target, line_start=0, line_end=None, code_snippet=None,
+                severity=Severity.INFORMATIONAL, confidence=Confidence.HIGH,
+                category=Category.SUPPLY_CHAIN,
+            )]
+
+        sc_cfg = self.cfg(config)
+        args = [
+            self.binary,
+            f"--repo={repo_url}",
+            "--format=json", "--show-details",
+        ]
+        args.extend(sc_cfg.extra_args)
+
+        r = self._exec(args, cwd=target, timeout_seconds=sc_cfg.timeout_seconds,
+                       allowed_exits=(0, 1, 2))
+        if r.returncode == 124:
+            return [self._make_finding(
+                rule_id=f"{self.name}.tool_timeout",
+                message=f"scorecard timed out: {r.stderr[:200]}",
+                file_path=target, line_start=0, line_end=None, code_snippet=None,
+                severity=Severity.INFORMATIONAL, confidence=Confidence.HIGH,
+            )]
+        if not r.stdout.strip():
+            return []
+
+        try:
+            payload = json.loads(r.stdout)
+        except json.JSONDecodeError:
+            return []
+
+        return self._parse(payload, target)
+
+    def _infer_repo_url(self, target: Path) -> str | None:
+        """Run `git remote get-url origin` in target. Returns the URL
+        normalized to https://github.com/<owner>/<repo> form, or None
+        if no GitHub origin is present."""
+        try:
+            r = subprocess.run(
+                ["git", "remote", "get-url", "origin"],
+                cwd=str(target),
+                check=False, capture_output=True, text=True, timeout=5,
+            )
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            return None
+        url = (r.stdout or "").strip()
+        if not url:
+            return None
+        # Normalize SSH form to HTTPS form so scorecard accepts it.
+        if url.startswith("git@github.com:"):
+            url = "https://github.com/" + url[len("git@github.com:"):]
+        if url.endswith(".git"):
+            url = url[:-4]
+        if not url.startswith("https://github.com/"):
+            return None
+        return url
+
+    def _parse(self, payload: dict, target: Path) -> list[Finding]:
+        out: list[Finding] = []
+        for check in payload.get("checks", []):
+            name   = str(check.get("name") or "Unknown")
+            score  = check.get("score")
+            reason = (check.get("reason") or "").strip()
+            doc    = (check.get("documentation") or {}).get("url") or ""
+
+            severity = self._score_to_severity(score)
+            if severity is None:
+                continue  # passed cleanly, no finding
+
+            category = (Category.POLICY_DOCS
+                        if name in _POLICY_DOCS_CHECKS
+                        else Category.SUPPLY_CHAIN)
+            msg = f"OpenSSF Scorecard `{name}` scored {score}/10: {reason}"
+            if doc:
+                msg = f"{msg} [{doc}]"
+
+            out.append(self._make_finding(
+                rule_id=f"scorecard.{name}",
+                message=msg,
+                file_path=target,
+                line_start=0,
+                line_end=None,
+                code_snippet=None,
+                severity=severity,
+                confidence=Confidence.HIGH,
+                category=category,
+            ))
+        return out
+
+    @staticmethod
+    def _score_to_severity(score) -> Severity | None:
+        if score is None:
+            return None
+        try:
+            s = int(score)
+        except (TypeError, ValueError):
+            return None
+        if s < 0:
+            return Severity.INFORMATIONAL
+        if s == 10:
+            return None
+        if s < 3:
+            return Severity.HIGH
+        if s < 7:
+            return Severity.MEDIUM
+        return Severity.LOW

secure_code_audit/scanners/semgrep_scanner.py

@@ -0,0 +1,119 @@
+"""Semgrep — multi-language SAST.
+
+Invocation:
+  semgrep --config=auto --sarif --metrics=off --error <target>
+
+Output: SARIF 2.1.0. We piggyback the canonical SARIF parser since other
+scanners (CodeQL, Snyk, Trivy) emit the same format.
+"""
+from __future__ import annotations
+
+import json
+import tempfile
+from pathlib import Path
+
+from secure_code_audit.config import Config
+from secure_code_audit.findings import Category, Confidence, Finding, Severity
+from secure_code_audit.scanners.base import Scanner
+
+
+class SemgrepScanner(Scanner):
+    name   = "semgrep"
+    binary = "semgrep"
+    default_category = Category.CODE_VULNERABILITIES
+
+    def run(self, target: Path, config: Config) -> list[Finding]:
+        if not self.is_available():
+            return [self._unavailable_finding(target)]
+
+        sc_cfg = self.cfg(config)
+        config_arg = "auto"   # registry-curated pack
+        if not sc_cfg.online:
+            # Operator opted out of online registry — fall back to bundled
+            # rules. Semgrep ships a small offline set under p/python +
+            # p/javascript when --config points to those names.
+            config_arg = "p/security-audit"
+
+        with tempfile.NamedTemporaryFile(suffix=".sarif", delete=False) as tmp:
+            sarif_path = Path(tmp.name)
+        try:
+            args = [
+                self.binary,
+                "--config", config_arg,
+                "--sarif", "--metrics=off",
+                "--output", str(sarif_path),
+                str(target),
+            ]
+            args.extend(sc_cfg.extra_args)
+            r = self._exec(args, cwd=target, timeout_seconds=sc_cfg.timeout_seconds,
+                           allowed_exits=(0, 1))
+            if r.returncode == 124:
+                return [self._make_finding(
+                    rule_id=f"{self.name}.tool_timeout",
+                    message=f"semgrep timed out: {r.stderr[:200]}",
+                    file_path=target, line_start=0, line_end=None, code_snippet=None,
+                    severity=Severity.INFORMATIONAL, confidence=Confidence.HIGH,
+                )]
+            if not sarif_path.exists():
+                return []
+            try:
+                payload = json.loads(sarif_path.read_text(encoding="utf-8"))
+            except json.JSONDecodeError:
+                return []
+            return self._parse_sarif(payload, target)
+        finally:
+            sarif_path.unlink(missing_ok=True)
+
+    # -- minimal SARIF parser; a fuller one lives in sarif.py for ingest --
+    def _parse_sarif(self, payload: dict, target: Path) -> list[Finding]:
+        findings: list[Finding] = []
+        for run in payload.get("runs", []):
+            rules = {
+                r.get("id"): r
+                for r in (run.get("tool", {}).get("driver", {}).get("rules", []) or [])
+            }
+            for result in run.get("results", []):
+                rule_id = result.get("ruleId") or "unknown"
+                rule    = rules.get(rule_id, {})
+                level   = result.get("level") or rule.get("defaultConfiguration", {}).get("level") or "warning"
+                msg     = (result.get("message") or {}).get("text") or rule.get("shortDescription", {}).get("text") or rule_id
+
+                locs = result.get("locations") or []
+                if not locs:
+                    continue
+                loc        = locs[0]
+                phys       = loc.get("physicalLocation") or {}
+                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)
+                snippet    = (region.get("snippet") or {}).get("text")
+
+                # SARIF severity: "error" → HIGH, "warning" → MEDIUM, "note" → LOW.
+                if level == "error":
+                    severity = Severity.HIGH
+                elif level == "note":
+                    severity = Severity.LOW
+                else:
+                    severity = Severity.MEDIUM
+
+                # Pull CWE from rule properties.cwe if present.
+                cwe = None
+                props = rule.get("properties") or {}
+                if isinstance(props.get("cwe"), list) and props["cwe"]:
+                    cwe = props["cwe"][0]
+                elif isinstance(props.get("cwe"), str):
+                    cwe = props["cwe"]
+
+                findings.append(self._make_finding(
+                    rule_id=rule_id,
+                    message=msg,
+                    file_path=Path(file_uri) if file_uri else target,
+                    line_start=line_start,
+                    line_end=line_end if line_end != line_start else None,
+                    code_snippet=snippet,
+                    severity=severity,
+                    confidence=Confidence.MEDIUM,
+                    cwe_override=cwe,
+                ))
+        return findings

secure_code_audit/scanners/trivy_scanner.py

@@ -0,0 +1,87 @@
+"""Trivy — containers / filesystem / IaC / Kubernetes scanner.
+
+Invocation:
+  trivy fs --format sarif --output <tmp> --quiet --no-progress <target>
+
+Trivy's `fs` subcommand covers filesystem scanning for vulnerable deps
+(via its own DB ingest of OSV/GHSA/NVD), secrets, misconfigurations
+(Terraform / CloudFormation / Dockerfile / Helm / k8s), and license
+issues. We focus on the security-relevant categories: vulnerabilities,
+misconfigs, secrets.
+
+SARIF output goes through `secure_code_audit.sarif.ingest()` so we get
+canonical Findings with the same normalization as every other SARIF
+source.
+
+Trivy emits a single SARIF file per scan with results across all
+categories — the standards mapping table routes findings into the
+right `Category` based on rule properties.
+"""
+from __future__ import annotations
+
+import tempfile
+from dataclasses import replace
+from pathlib import Path
+
+from secure_code_audit.config import Config
+from secure_code_audit.findings import Category, Confidence, Finding, Severity
+from secure_code_audit.sarif import ingest as sarif_ingest
+from secure_code_audit.scanners.base import Scanner
+
+
+class TrivyScanner(Scanner):
+    name   = "trivy"
+    binary = "trivy"
+    default_category = Category.CONFIG_IAC
+
+    def run(self, target: Path, config: Config) -> list[Finding]:
+        if not self.is_available():
+            return [self._unavailable_finding(target)]
+
+        sc_cfg = self.cfg(config)
+        with tempfile.NamedTemporaryFile(suffix=".sarif", delete=False) as tmp:
+            sarif_path = Path(tmp.name)
+        try:
+            args = [
+                self.binary, "fs",
+                "--format", "sarif",
+                "--output", str(sarif_path),
+                "--quiet", "--no-progress",
+                # Skip license findings — we focus on security only.
+                "--scanners", "vuln,secret,misconfig",
+                str(target),
+            ]
+            args.extend(sc_cfg.extra_args)
+
+            r = self._exec(args, cwd=target, timeout_seconds=sc_cfg.timeout_seconds,
+                           allowed_exits=(0, 1))
+            if r.returncode == 124:
+                return [self._make_finding(
+                    rule_id=f"{self.name}.tool_timeout",
+                    message=f"trivy timed out: {r.stderr[:200]}",
+                    file_path=target, line_start=0, line_end=None, code_snippet=None,
+                    severity=Severity.INFORMATIONAL, confidence=Confidence.HIGH,
+                )]
+            if not sarif_path.exists() or sarif_path.stat().st_size == 0:
+                return []
+
+            ingested = sarif_ingest(sarif_path, default_scanner="trivy")
+            # Trivy tags its rules with a category prefix (CVE-, AVD-, etc.);
+            # route them into the right Category bucket.
+            return [self._route_category(f) for f in ingested]
+        finally:
+            sarif_path.unlink(missing_ok=True)
+
+    def _route_category(self, f: Finding) -> Finding:
+        """Trivy bundles three rule families into one SARIF output.
+        Route by rule_id prefix so the scoring layer puts them in the
+        right category."""
+        rid = f.rule_id.upper()
+        if rid.startswith("CVE-") or rid.startswith("GHSA-"):
+            return replace(f, category=Category.DEPENDENCIES, scanner="trivy")
+        if rid.startswith("AVD-") or "MISCONFIG" in rid:
+            return replace(f, category=Category.CONFIG_IAC, scanner="trivy")
+        if "SECRET" in rid or rid.startswith("AWS") or rid.startswith("PRIVATE-KEY"):
+            return replace(f, category=Category.SECRETS, scanner="trivy",
+                           severity=Severity.CRITICAL)
+        return replace(f, scanner="trivy")

secure_code_audit/scanners/trufflehog_scanner.py

@@ -0,0 +1,91 @@
+"""TruffleHog — secret scanning with verifiers.
+
+Invocation:
+  trufflehog filesystem --json --no-update --only-verified <target>
+
+`--only-verified` is the default — high-precision matches where
+TruffleHog's verifier confirmed the secret is currently live against
+the upstream service. Operators can opt into unverified findings via
+`scanners.trufflehog.extra_args: ["--no-only-verified"]` in config.
+
+Output: JSONL (one JSON object per line) — distinct from gitleaks
+which writes a single JSON array.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from secure_code_audit.config import Config
+from secure_code_audit.findings import Category, Confidence, Finding, Severity
+from secure_code_audit.scanners.base import Scanner
+
+
+class TruffleHogScanner(Scanner):
+    name   = "trufflehog"
+    binary = "trufflehog"
+    default_category = Category.SECRETS
+
+    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, "filesystem",
+            "--json", "--no-update",
+            "--only-verified",
+            str(target),
+        ]
+        args.extend(sc_cfg.extra_args)
+
+        r = self._exec(args, cwd=target, timeout_seconds=sc_cfg.timeout_seconds,
+                       allowed_exits=(0, 183))   # 183 = findings present
+        if r.returncode == 124:
+            return [self._make_finding(
+                rule_id=f"{self.name}.tool_timeout",
+                message=f"trufflehog timed out: {r.stderr[:200]}",
+                file_path=target, line_start=0, line_end=None, code_snippet=None,
+                severity=Severity.INFORMATIONAL, confidence=Confidence.HIGH,
+            )]
+        if not r.stdout.strip():
+            return []
+
+        out: list[Finding] = []
+        for line in r.stdout.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                hit = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            out.append(self._parse_one(hit))
+        return out
+
+    def _parse_one(self, hit: dict) -> Finding:
+        detector = str(hit.get("DetectorName") or hit.get("Detector") or "unknown")
+        # SourceMetadata.Data.Filesystem.file / line
+        meta = (((hit.get("SourceMetadata") or {}).get("Data") or {}).get("Filesystem") or {})
+        file_path = Path(meta.get("file") or "")
+        line      = int(meta.get("line") or 0)
+        verified  = bool(hit.get("Verified"))
+        # The redacted match is what TruffleHog emits when --only-verified
+        # is on — it strips the raw secret bytes.
+        match = str(hit.get("Redacted") or "<verified>").strip()
+
+        # Verified secrets are CRITICAL; unverified (if operator opted in
+        # via --no-only-verified in extra_args) are HIGH.
+        severity = Severity.CRITICAL if verified else Severity.HIGH
+
+        return self._make_finding(
+            rule_id=f"trufflehog.{detector}",
+            message=f"{detector}: {match}".strip(),
+            file_path=file_path,
+            line_start=line,
+            line_end=None,
+            code_snippet=match[:200],
+            severity=severity,
+            confidence=Confidence.HIGH,
+            category=Category.SECRETS,
+        )