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

secure_code_audit/scanners/builtin_rules.py

@@ -0,0 +1,183 @@
+"""Built-in regex rules — high-confidence, low-false-positive patterns that
+catch what the big scanners miss or that we want to ship even when no
+external scanner is installed.
+
+The rules are opinionated and SMALL. We are not building a parallel
+Semgrep. Each rule:
+  · targets a single CWE
+  · is documented inline (when it's useful + when it false-positives)
+  · is covered by at least one true-positive and one false-positive fixture
+    in tests/fixtures/builtin_rules/
+"""
+from __future__ import annotations
+
+import re
+from pathlib import Path
+from typing import NamedTuple
+
+from secure_code_audit.config import Config
+from secure_code_audit.findings import Confidence, Finding, Severity
+from secure_code_audit.git_tools import in_scope, is_excluded
+from secure_code_audit.scanners.base import Scanner
+
+
+class _Rule(NamedTuple):
+    rule_id:     str
+    pattern:     re.Pattern[str]
+    file_globs:  tuple[str, ...]   # restrict to certain languages (e.g. ".py")
+    description: str
+
+
+# --- the rule set ---------------------------------------------------------
+# Each pattern is tuned for ≥90% precision on real-world code. Update with
+# a counter-example in tests/fixtures/ if you tighten or loosen.
+
+_RULES: tuple[_Rule, ...] = (
+    _Rule(
+        rule_id="sca.python.eval",
+        # eval/exec with a non-string-literal first arg. Allow eval('lit').
+        pattern=re.compile(
+            r"\b(?:eval|exec)\s*\(\s*(?!['\"][^'\"]*['\"]\s*\))",
+            re.MULTILINE,
+        ),
+        file_globs=(".py",),
+        description="eval()/exec() with non-literal input — arbitrary code execution.",
+    ),
+    _Rule(
+        rule_id="sca.python.yaml.unsafe_load",
+        pattern=re.compile(
+            r"\byaml\.load\s*\(\s*(?!.*Loader\s*=\s*(?:yaml\.)?SafeLoader)",
+            re.MULTILINE,
+        ),
+        file_globs=(".py",),
+        description="yaml.load() without SafeLoader — unsafe deserialization.",
+    ),
+    _Rule(
+        rule_id="sca.python.requests.verify_false",
+        pattern=re.compile(
+            r"\brequests\.(?:get|post|put|patch|delete|head|options|request)\s*\([^)]*verify\s*=\s*False",
+            re.MULTILINE | re.DOTALL,
+        ),
+        file_globs=(".py",),
+        description="requests.* called with verify=False — TLS cert validation disabled.",
+    ),
+    _Rule(
+        rule_id="sca.python.subprocess.shell_true",
+        pattern=re.compile(
+            r"\bsubprocess\.(?:run|call|check_call|check_output|Popen)\s*\([^)]*shell\s*=\s*True",
+            re.MULTILINE | re.DOTALL,
+        ),
+        file_globs=(".py",),
+        description="subprocess with shell=True — command-injection risk.",
+    ),
+    _Rule(
+        rule_id="sca.python.fstring_sql",
+        # Look for f-strings containing SELECT/INSERT/UPDATE/DELETE
+        # interpolated into .execute( / .executemany(. We require both the
+        # f-string AND the execute-call to be within ~200 chars to keep
+        # false positives down.
+        pattern=re.compile(
+            r"\.(?:execute|executemany)\s*\(\s*f['\"](?:[^'\"]*?\b(?:SELECT|INSERT|UPDATE|DELETE|MERGE)\b[^'\"]*?\{[^}]+\})",
+            re.IGNORECASE | re.MULTILINE,
+        ),
+        file_globs=(".py",),
+        description="f-string SQL in .execute()/.executemany() — possible SQL injection.",
+    ),
+    _Rule(
+        rule_id="sca.python.hashlib.md5_sha1_security",
+        # MD5/SHA-1 — false-positives in non-security use are common. We
+        # only flag when usedforsecurity is not explicitly False.
+        pattern=re.compile(
+            r"\bhashlib\.(?:md5|sha1)\s*\((?![^)]*usedforsecurity\s*=\s*False)",
+            re.MULTILINE,
+        ),
+        file_globs=(".py",),
+        description="MD5/SHA-1 without usedforsecurity=False — weak hash for security context.",
+    ),
+    _Rule(
+        rule_id="sca.web.dangerously_set_inner_html",
+        pattern=re.compile(
+            r"dangerouslySetInnerHTML\s*=\s*\{\{\s*__html\s*:",
+            re.MULTILINE,
+        ),
+        file_globs=(".tsx", ".jsx", ".ts", ".js"),
+        description="React dangerouslySetInnerHTML — XSS surface unless input is trusted/sanitized.",
+    ),
+    _Rule(
+        rule_id="sca.web.cors_wildcard",
+        # Headers/middleware setting Allow-Origin '*'. Pair with
+        # Allow-Credentials: true → spec violation + XSCSRF surface.
+        pattern=re.compile(
+            r"(?i)Access-Control-Allow-Origin\s*['\"]?\s*[:=]\s*['\"]?\*",
+        ),
+        file_globs=(".py", ".js", ".ts", ".tsx", ".go", ".rb", ".java"),
+        description="CORS Allow-Origin: * — review for credentialed-cookies exposure.",
+    ),
+    _Rule(
+        rule_id="sca.shell.curl_pipe_sh",
+        pattern=re.compile(
+            r"\bcurl\b[^|;\n]+\|\s*(?:bash|sh|zsh)\b",
+            re.MULTILINE,
+        ),
+        file_globs=(".sh", "Dockerfile"),
+        description="curl ... | sh — unauthenticated remote-script execution.",
+    ),
+)
+
+
+class BuiltinRulesScanner(Scanner):
+    name   = "builtin_rules"
+    binary = ""   # in-process scanner
+
+    def is_available(self) -> bool:
+        return True   # no external binary needed
+
+    def binary_version(self) -> str | None:
+        from secure_code_audit import __version__
+        return f"builtin/{__version__}"
+
+    def run(self, target: Path, config: Config) -> list[Finding]:
+        findings: list[Finding] = []
+        for path in self._candidate_files(target, config):
+            try:
+                text = path.read_text(encoding="utf-8", errors="ignore")
+            except OSError:
+                continue
+            for rule in _RULES:
+                if not self._applies_to(path, rule):
+                    continue
+                for m in rule.pattern.finditer(text):
+                    line_start = text.count("\n", 0, m.start()) + 1
+                    line_end   = text.count("\n", 0, m.end()) + 1
+                    snippet    = m.group(0)[:200]
+                    findings.append(self._make_finding(
+                        rule_id=rule.rule_id,
+                        message=rule.description,
+                        file_path=path,
+                        line_start=line_start,
+                        line_end=line_end if line_end != line_start else None,
+                        code_snippet=snippet,
+                        severity=Severity.HIGH,
+                        confidence=Confidence.MEDIUM,
+                    ))
+        return findings
+
+    def _applies_to(self, path: Path, rule: _Rule) -> bool:
+        name = path.name
+        for glob in rule.file_globs:
+            if glob.startswith("."):
+                if name.endswith(glob):
+                    return True
+            elif name == glob:
+                return True
+        return False
+
+    def _candidate_files(self, target: Path, config: Config):
+        for path in target.rglob("*"):
+            if not path.is_file():
+                continue
+            if is_excluded(path, target, config.exclude_patterns):
+                continue
+            if not in_scope(path, config.include_extensions):
+                continue
+            yield path

secure_code_audit/scanners/checkov_scanner.py

@@ -0,0 +1,69 @@
+"""Checkov — IaC scanning (Terraform / CloudFormation / Helm / k8s / Dockerfile).
+
+Invocation:
+  checkov -d <target> --output sarif --output-file-path <tmp> --quiet --soft-fail
+
+`--soft-fail` makes checkov exit 0 even on findings; we want our own
+gate logic to drive exit codes, not checkov's. SARIF goes through the
+canonical ingest.
+"""
+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 CheckovScanner(Scanner):
+    name   = "checkov"
+    binary = "checkov"
+    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)
+        # Checkov writes to a directory and names the file itself.
+        # Use a temp directory so cleanup is straightforward.
+        with tempfile.TemporaryDirectory() as tmpdir:
+            tmpdir_path = Path(tmpdir)
+            args = [
+                self.binary, "-d", str(target),
+                "--output", "sarif",
+                "--output-file-path", str(tmpdir_path),
+                "--quiet", "--soft-fail",
+            ]
+            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"checkov timed out: {r.stderr[:200]}",
+                    file_path=target, line_start=0, line_end=None, code_snippet=None,
+                    severity=Severity.INFORMATIONAL, confidence=Confidence.HIGH,
+                )]
+
+            # Checkov writes results.sarif into the output directory.
+            sarif_path = tmpdir_path / "results_sarif.sarif"
+            if not sarif_path.exists():
+                # Older versions write `results.sarif` instead.
+                alt = tmpdir_path / "results.sarif"
+                sarif_path = alt if alt.exists() else sarif_path
+            if not sarif_path.exists():
+                return []
+
+            ingested = sarif_ingest(sarif_path, default_scanner="checkov")
+            # All checkov findings are config_iac by rule family. Pin
+            # the scanner field for cross-scanner dedupe clarity.
+            return [
+                replace(f, scanner="checkov", category=Category.CONFIG_IAC)
+                for f in ingested
+            ]

secure_code_audit/scanners/gitleaks_scanner.py

@@ -0,0 +1,86 @@
+"""Gitleaks — history-aware secret scanning.
+
+Invocation:
+  gitleaks detect --source=<target> --no-banner \
+      --redact --report-format=json --report-path=<tmp>
+
+We always pass --redact so the raw secret never reaches the report JSON.
+The fingerprint hashes the raw match site so dedupe still works.
+"""
+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 GitleaksScanner(Scanner):
+    name   = "gitleaks"
+    binary = "gitleaks"
+    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)
+        with tempfile.NamedTemporaryFile(suffix=".json", delete=False) as tmp:
+            report_path = Path(tmp.name)
+        try:
+            args = [
+                self.binary, "detect",
+                "--source", str(target),
+                "--no-banner",
+                "--redact",
+                "--report-format", "json",
+                "--report-path", str(report_path),
+            ]
+            args.extend(sc_cfg.extra_args)
+            # Gitleaks exits 1 when findings exist; 0 = clean; >1 = error.
+            r = self._exec(args, cwd=target, timeout_seconds=sc_cfg.timeout_seconds,
+                           allowed_exits=(0, 1))
+            if r.returncode not in (0, 1):
+                return [self._make_finding(
+                    rule_id=f"{self.name}.tool_error",
+                    message=f"gitleaks failed: {r.stderr[:300]}",
+                    file_path=target, line_start=0, line_end=None, code_snippet=None,
+                    severity=Severity.INFORMATIONAL, confidence=Confidence.HIGH,
+                )]
+            if not report_path.exists() or report_path.stat().st_size == 0:
+                return []
+            try:
+                payload = json.loads(report_path.read_text(encoding="utf-8"))
+            except json.JSONDecodeError:
+                return []
+            return self._parse(payload, target)
+        finally:
+            report_path.unlink(missing_ok=True)
+
+    def _parse(self, payload: list[dict], target: Path) -> list[Finding]:
+        if not isinstance(payload, list):
+            return []
+        findings: list[Finding] = []
+        for hit in payload:
+            rule_id = str(hit.get("RuleID") or hit.get("Rule") or "unknown")
+            file_path = Path(hit.get("File") or "")
+            line = int(hit.get("StartLine") or 0)
+            redacted_match = str(hit.get("Match") or hit.get("Secret") or "").strip()
+            # Gitleaks --redact returns the match string with the secret
+            # replaced by REDACTED — we surface that exact string in the
+            # report.
+            findings.append(self._make_finding(
+                rule_id=f"gitleaks.{rule_id}",
+                message=f"{hit.get('Description') or rule_id}: {redacted_match}".strip(),
+                file_path=file_path,
+                line_start=line,
+                line_end=int(hit.get("EndLine") or line) if hit.get("EndLine") else None,
+                code_snippet=redacted_match[:200] or None,
+                severity=Severity.CRITICAL,
+                confidence=Confidence.HIGH,
+                category=Category.SECRETS,
+            ))
+        return findings

secure_code_audit/scanners/hadolint_scanner.py

@@ -0,0 +1,107 @@
+"""Hadolint — Dockerfile linter.
+
+Invocation:
+  hadolint --no-fail --format json <Dockerfile> [<Dockerfile> ...]
+
+Hadolint emits a JSON array — one entry per finding with file/line/code
+(rule id like DL3001) / level / message. We walk the target tree for
+Dockerfiles and pass them all to one hadolint invocation.
+
+Only a subset of DL/SC rules have security implications; we map those
+in standards.py (see SECURITY_RELEVANT_RULES). Style-only rules
+(DL3007, DL3008 unpinned-apt) are tagged config_iac at LOW severity.
+"""
+from __future__ import annotations
+
+import json
+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.git_tools import is_excluded
+from secure_code_audit.scanners.base import Scanner
+
+
+# Hadolint rule ids whose semantics are security-relevant. The category
+# stays config_iac but severity is bumped over the default LOW.
+_HIGH_SECURITY: dict[str, Severity] = {
+    "DL3002":  Severity.HIGH,    # USER root
+    "DL3004":  Severity.MEDIUM,  # do not use sudo
+    "DL3025":  Severity.MEDIUM,  # use JSON form for CMD/ENTRYPOINT (shell injection surface)
+    "DL4006":  Severity.MEDIUM,  # set SHELL with pipefail
+    "SC2086":  Severity.MEDIUM,  # unquoted variable (shell-injection)
+    "SC2046":  Severity.MEDIUM,  # unquoted command substitution
+    "DL3023":  Severity.MEDIUM,  # COPY --from points to its own FROM alias
+    "DL3033":  Severity.MEDIUM,  # specify version with yum install -y
+    "DL3008":  Severity.LOW,     # pin apt versions
+    "DL3009":  Severity.LOW,     # delete apt lists after install
+    "DL3015":  Severity.LOW,     # use --no-install-recommends
+    "DL3018":  Severity.LOW,     # pin apk versions
+}
+
+
+class HadolintScanner(Scanner):
+    name   = "hadolint"
+    binary = "hadolint"
+    default_category = Category.CONFIG_IAC
+
+    def run(self, target: Path, config: Config) -> list[Finding]:
+        if not self.is_available():
+            return [self._unavailable_finding(target)]
+
+        dockerfiles = self._find_dockerfiles(target, config.exclude_patterns)
+        if not dockerfiles:
+            return []
+
+        sc_cfg = self.cfg(config)
+        args = [self.binary, "--no-fail", "--format", "json"]
+        args.extend(str(p) for p in dockerfiles)
+        args.extend(sc_cfg.extra_args)
+
+        r = self._exec(args, cwd=target, timeout_seconds=sc_cfg.timeout_seconds,
+                       allowed_exits=(0,))
+        if r.returncode == 124:
+            return [self._make_finding(
+                rule_id=f"{self.name}.tool_timeout",
+                message=f"hadolint 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 []
+        if not isinstance(payload, list):
+            return []
+
+        return [self._parse_one(item) for item in payload if isinstance(item, dict)]
+
+    def _find_dockerfiles(self, target: Path, excludes) -> list[Path]:
+        out: list[Path] = []
+        for path in target.rglob("Dockerfile*"):
+            if not path.is_file():
+                continue
+            if is_excluded(path, target, excludes):
+                continue
+            out.append(path)
+        return out
+
+    def _parse_one(self, item: dict) -> Finding:
+        code = str(item.get("code") or "unknown")
+        severity = _HIGH_SECURITY.get(code, Severity.LOW)
+        finding = self._make_finding(
+            rule_id=f"hadolint.{code}",
+            message=str(item.get("message") or code),
+            file_path=Path(item.get("file") or ""),
+            line_start=int(item.get("line") or 0),
+            line_end=None,
+            code_snippet=None,
+            severity=severity,
+            confidence=Confidence.HIGH,
+            category=Category.CONFIG_IAC,
+        )
+        return finding

secure_code_audit/scanners/npm_audit_scanner.py

@@ -0,0 +1,101 @@
+"""npm audit — Node SCA.
+
+Invocation:
+  npm audit --json --omit=dev [--audit-level=low]
+
+npm audit exits nonzero when findings exist; we accept 0+1.
+"""
+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
+
+
+_NPM_SEVERITY: dict[str, Severity] = {
+    "critical": Severity.CRITICAL,
+    "high":     Severity.HIGH,
+    "moderate": Severity.MEDIUM,
+    "low":      Severity.LOW,
+    "info":     Severity.INFORMATIONAL,
+}
+
+
+class NpmAuditScanner(Scanner):
+    name   = "npm_audit"
+    binary = "npm"
+    default_category = Category.DEPENDENCIES
+
+    def run(self, target: Path, config: Config) -> list[Finding]:
+        if not self.is_available():
+            return [self._unavailable_finding(target)]
+
+        pkg_dirs = self._discover_package_dirs(target, config.exclude_patterns)
+        if not pkg_dirs:
+            return [self._make_finding(
+                rule_id=f"{self.name}.no_package_lock",
+                message="No package-lock.json found in scope; npm 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 pkg_dir in pkg_dirs:
+            args = [self.binary, "audit", "--json", "--omit=dev"]
+            args.extend(sc_cfg.extra_args)
+            r = self._exec(args, cwd=pkg_dir, timeout_seconds=sc_cfg.timeout_seconds,
+                           allowed_exits=(0, 1))
+            if r.returncode == 124 or not r.stdout.strip():
+                continue
+            try:
+                payload = json.loads(r.stdout)
+            except json.JSONDecodeError:
+                continue
+            findings.extend(self._parse(payload, pkg_dir))
+        return findings
+
+    def _discover_package_dirs(self, root: Path, excludes: tuple[str, ...]) -> list[Path]:
+        out: list[Path] = []
+        for path in root.rglob("package-lock.json"):
+            rel = str(path.relative_to(root).as_posix())
+            if any(rel.startswith(e) or f"/{e}" in f"/{rel}" for e in excludes):
+                continue
+            out.append(path.parent)
+        return out
+
+    def _parse(self, payload: dict, pkg_dir: Path) -> list[Finding]:
+        findings: list[Finding] = []
+        vulns = payload.get("vulnerabilities") or {}
+        manifest = pkg_dir / "package-lock.json"
+        for pkg_name, info in vulns.items():
+            severity_str = (info.get("severity") or "moderate").lower()
+            severity     = _NPM_SEVERITY.get(severity_str, Severity.MEDIUM)
+            via          = info.get("via") or []
+            advisories   = [v for v in via if isinstance(v, dict)]
+            if not advisories:
+                # Indirect-only entry; collapse to a single finding.
+                findings.append(self._make_finding(
+                    rule_id=f"npm_audit.{pkg_name}.indirect",
+                    message=f"{pkg_name}: vulnerable via transitive dep.",
+                    file_path=manifest, line_start=0, line_end=None, code_snippet=None,
+                    severity=severity, confidence=Confidence.HIGH,
+                    category=Category.DEPENDENCIES,
+                ))
+                continue
+            for adv in advisories:
+                rule_id = f"npm_audit.{adv.get('source') or adv.get('name') or pkg_name}"
+                msg     = adv.get("title") or adv.get("name") or pkg_name
+                url     = adv.get("url") or ""
+                findings.append(self._make_finding(
+                    rule_id=rule_id,
+                    message=f"{pkg_name}: {msg} {url}".strip(),
+                    file_path=manifest, line_start=0, line_end=None, code_snippet=None,
+                    severity=severity, confidence=Confidence.HIGH,
+                    category=Category.DEPENDENCIES,
+                ))
+        return findings

secure_code_audit/scanners/osv_scanner.py

@@ -0,0 +1,108 @@
+"""OSV-Scanner — multi-ecosystem SCA via osv.dev.
+
+Invocation:
+  osv-scanner --format=json --recursive <target>
+
+Output: JSON with `results[].packages[].vulnerabilities[]` each carrying
+id (CVE / GHSA / OSV-), severity, summary, references.
+
+Overlaps with pip-audit + npm-audit by design; the fingerprint dedupe
+across `(canonical_cwe, file_path, code_snippet)` ensures we don't
+double-count the same upstream advisory.
+"""
+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
+
+
+_OSV_SEVERITY: dict[str, Severity] = {
+    "CRITICAL": Severity.CRITICAL,
+    "HIGH":     Severity.HIGH,
+    "MODERATE": Severity.MEDIUM,
+    "MEDIUM":   Severity.MEDIUM,
+    "LOW":      Severity.LOW,
+    "UNKNOWN":  Severity.MEDIUM,
+}
+
+
+class OsvScanner(Scanner):
+    name   = "osv_scanner"
+    binary = "osv-scanner"
+    default_category = Category.DEPENDENCIES
+
+    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,
+            "--format=json", "--recursive",
+            str(target),
+        ]
+        args.extend(sc_cfg.extra_args)
+
+        # osv-scanner exits 1 on findings, 0 on clean, 127 on bad usage,
+        # 128 on internal error.
+        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"osv-scanner 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 _parse(self, payload: dict, target: Path) -> list[Finding]:
+        out: list[Finding] = []
+        for result in payload.get("results", []):
+            source = (result.get("source") or {}).get("path") or ""
+            file_path = Path(source) if source else target
+            for pkg_block in result.get("packages", []):
+                pkg = pkg_block.get("package") or {}
+                pkg_name = pkg.get("name", "?")
+                pkg_ver  = pkg.get("version", "?")
+                for vuln in pkg_block.get("vulnerabilities", []) or []:
+                    vid = str(vuln.get("id") or "UNKNOWN")
+                    summary = (vuln.get("summary") or "").strip()[:300]
+                    severity_str = self._extract_severity(vuln)
+                    severity = _OSV_SEVERITY.get(severity_str, Severity.MEDIUM)
+                    out.append(self._make_finding(
+                        rule_id=f"osv_scanner.{vid}",
+                        message=f"{pkg_name} {pkg_ver} — {vid}: {summary}",
+                        file_path=file_path,
+                        line_start=0, line_end=None, code_snippet=None,
+                        severity=severity,
+                        confidence=Confidence.HIGH,
+                        category=Category.DEPENDENCIES,
+                    ))
+        return out
+
+    def _extract_severity(self, vuln: dict) -> str:
+        """OSV format puts severity in two places: a top-level
+        `database_specific.severity` (string) and a `severity[]` array
+        with CVSS vectors. Prefer the string when present."""
+        ds = (vuln.get("database_specific") or {}).get("severity")
+        if isinstance(ds, str):
+            return ds.upper()
+        sev_arr = vuln.get("severity") or []
+        if isinstance(sev_arr, list) and sev_arr:
+            # CVSS string in score; we don't parse the vector — fall back
+            # to MEDIUM as a safe default.
+            return "MEDIUM"
+        return "UNKNOWN"