cernus-plugins 0.1.0__py3-none-any.whl

cernus_plugins/sarif.py

@@ -0,0 +1,158 @@
+"""SARIF 2.1.0 — connector (semgrep, CodeQL, bandit, genesis-cli …) and exporter."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+from cernus_core.model import Finding, IngestBatch, Severity, Source, new_id, now_iso
+from cernus_core.plugins import Connector, Exporter, register_connector, register_exporter
+
+_LEVEL_TO_SEV = {"error": "high", "warning": "medium", "note": "low", "none": "info"}
+_SEV_TO_LEVEL = {
+    "critical": "error",
+    "high": "error",
+    "medium": "warning",
+    "low": "note",
+    "info": "none",
+}
+
+
+@register_connector
+class SarifConnector(Connector):
+    name = "sarif"
+    description = "SARIF 2.1.0 static-analysis logs"
+    tools = ("semgrep", "codeql", "bandit", "genesis-cli")
+
+    def detect(self, path: Path, document: dict[str, Any] | None = None) -> bool:
+        return bool(document) and document.get("version") == "2.1.0" and "runs" in document
+
+    def ingest(
+        self, path: Path, document: dict[str, Any] | None = None, **context: Any
+    ) -> IngestBatch:
+        doc = document if document is not None else json.loads(path.read_text())
+        batch = IngestBatch(source=Source(tool="sarif", connector=self.name))
+        seen = now_iso()
+        for run in doc.get("runs") or []:
+            driver = (run.get("tool") or {}).get("driver") or {}
+            source = Source(
+                tool=driver.get("name", "sarif").lower(),
+                version=driver.get("version"),
+                connector=self.name,
+            )
+            rules = {r.get("id"): r for r in driver.get("rules") or []}
+            for res in run.get("results") or []:
+                rule_id = res.get("ruleId") or "unknown"
+                rule = rules.get(rule_id, {})
+                sev = _severity(res, rule)
+                loc = _location(res)
+                batch.findings.append(
+                    Finding(
+                        id=new_id("fnd"),
+                        title=(rule.get("shortDescription") or {}).get("text") or rule_id,
+                        severity=sev,
+                        source=source,
+                        source_ref=rule_id,
+                        category="sast",
+                        detail=(res.get("message") or {}).get("text"),
+                        location=loc,
+                        remediation=(rule.get("help") or {}).get("text"),
+                        asset_id=context.get("asset_id"),
+                        deployment_id=context.get("deployment_id"),
+                        system_id=context.get("system_id"),
+                        first_seen=seen,
+                        last_seen=seen,
+                        tags=[
+                            t
+                            for t in (rule.get("properties") or {}).get("tags", [])
+                            if isinstance(t, str)
+                        ][:10],
+                        raw=res,
+                    )
+                )
+        if batch.findings:
+            batch.source = batch.findings[0].source
+        return batch
+
+
+def _severity(res: dict, rule: dict) -> str:
+    props = rule.get("properties") or {}
+    if "security-severity" in props:  # GitHub convention: CVSS-like 0–10 string
+        try:
+            s = float(props["security-severity"])
+            return "critical" if s >= 9 else "high" if s >= 7 else "medium" if s >= 4 else "low"
+        except ValueError:
+            pass
+    level = res.get("level") or (rule.get("defaultConfiguration") or {}).get("level") or "warning"
+    return _LEVEL_TO_SEV.get(level, "medium")
+
+
+def _location(res: dict) -> str | None:
+    for loc in res.get("locations") or []:
+        phys = loc.get("physicalLocation") or {}
+        uri = (phys.get("artifactLocation") or {}).get("uri")
+        line = (phys.get("region") or {}).get("startLine")
+        if uri:
+            return f"{uri}:{line}" if line else uri
+    return None
+
+
+@register_exporter
+class SarifExporter(Exporter):
+    name = "sarif"
+    description = "Write findings as SARIF 2.1.0 (one run per source tool)"
+    formats = ("sarif",)
+
+    def export(self, fmt: str, batch: IngestBatch, out: Path, **options: Any) -> Path:
+        by_tool: dict[str, list[Finding]] = {}
+        for f in batch.findings:
+            by_tool.setdefault(f.source.tool, []).append(f)
+        runs = []
+        for tool, findings in by_tool.items():
+            rules: dict[str, dict] = {}
+            results = []
+            for f in findings:
+                rid = f.source_ref or f.fingerprint[:12]
+                rules.setdefault(rid, {"id": rid, "shortDescription": {"text": f.title}})
+                result: dict[str, Any] = {
+                    "ruleId": rid,
+                    "level": _SEV_TO_LEVEL[f.severity.value],
+                    "message": {"text": f.detail or f.title},
+                    "fingerprints": {"cernus/v1": f.fingerprint},
+                    "properties": {
+                        "cernus": {
+                            "id": f.id,
+                            "severity": f.severity.value,
+                            "status": f.status.value,
+                        }
+                    },
+                }
+                if f.location:
+                    uri, _, line = f.location.partition(":")
+                    region = {"startLine": int(line)} if line.isdigit() else {}
+                    result["locations"] = [
+                        {
+                            "physicalLocation": {
+                                "artifactLocation": {"uri": uri},
+                                **({"region": region} if region else {}),
+                            }
+                        }
+                    ]
+                results.append(result)
+            runs.append(
+                {
+                    "tool": {"driver": {"name": tool, "rules": list(rules.values())}},
+                    "results": results,
+                }
+            )
+        doc = {
+            "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/sarif-2.1.0.json",
+            "version": "2.1.0",
+            "runs": runs,
+        }
+        out.write_text(json.dumps(doc, indent=2))
+        return out
+
+
+__all__ = ["SarifConnector", "SarifExporter", "Severity"]

cernus_plugins/syft.py

@@ -0,0 +1,50 @@
+"""Syft scanner wrapper: produce a CycloneDX SBOM for an image or directory.
+
+Normalization of the SBOM itself is the :mod:`cyclonedx` connector's job.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+from cernus_core.plugins import Scanner, ScanResult, register_scanner
+
+
+@register_scanner
+class SyftScanner(Scanner):
+    name = "syft"
+    description = "Generate a CycloneDX SBOM with syft"
+    binary = "syft"
+    targets = ("image", "fs")
+
+    def version(self) -> str | None:
+        try:
+            out = subprocess.run(
+                [self.binary, "version", "-o", "raw"],
+                capture_output=True,
+                text=True,
+                timeout=20,
+                check=False,
+            ).stdout
+            return out.strip() or None
+        except (OSError, subprocess.TimeoutExpired):
+            return None
+
+    def scan(self, target_kind: str, target: str, workdir: Path) -> ScanResult:
+        if target_kind not in self.targets:
+            raise ValueError(f"syft scanner does not support target kind {target_kind!r}")
+        workdir.mkdir(parents=True, exist_ok=True)
+        slug = "".join(c if c.isalnum() else "-" for c in target).strip("-")[:80]
+        out = workdir / f"syft-{slug}.cdx.json"
+        src = target if target_kind == "image" else f"dir:{target}"
+        argv = [self.binary, src, "-o", f"cyclonedx-json={out}", "-q"]
+        proc = subprocess.run(argv, capture_output=True, text=True, check=False, timeout=1800)
+        return ScanResult(
+            tool="syft",
+            output_path=out if out.exists() else None,
+            connector="cyclonedx",
+            argv=argv,
+            returncode=proc.returncode,
+            stderr=proc.stderr[-4000:],
+        )

cernus_plugins/trivy.py

@@ -0,0 +1,294 @@
+"""Trivy — connector for `trivy … --format json` output, and a scanner wrapper.
+
+Covers image scans (``ArtifactType: container_image``), filesystem scans, and
+SBOM scans (``trivy sbom``). Misconfiguration and secret results are mapped to
+their own categories when present.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from pathlib import Path
+from typing import Any
+
+from cernus_core.model import (
+    Asset,
+    Component,
+    EvidenceRecord,
+    Finding,
+    IngestBatch,
+    Source,
+    Vuln,
+    new_id,
+    now_iso,
+)
+from cernus_core.plugins import Connector, Scanner, ScanResult, register_connector, register_scanner
+
+_KIND_BY_ARTIFACT = {
+    "container_image": "container_image",
+    "filesystem": "repository",
+    "repository": "repository",
+    "cyclonedx": "container_image",
+    "spdx": "container_image",
+}
+
+
+@register_connector
+class TrivyConnector(Connector):
+    name = "trivy"
+    description = (
+        "Trivy JSON reports (image, fs, sbom): vulnerabilities, misconfigurations, secrets"
+    )
+    tools = ("trivy",)
+
+    def detect(self, path: Path, document: dict[str, Any] | None = None) -> bool:
+        return (
+            bool(document)
+            and "SchemaVersion" in document
+            and "Results" in document
+            and ("ArtifactName" in document or "ArtifactType" in document)
+        )
+
+    def ingest(
+        self, path: Path, document: dict[str, Any] | None = None, **context: Any
+    ) -> IngestBatch:
+        doc = document if document is not None else json.loads(path.read_text())
+        version = (doc.get("Trivy") or {}).get("Version")
+        source = Source(tool="trivy", version=version, connector=self.name)
+        batch = IngestBatch(source=source)
+
+        artifact = doc.get("ArtifactName") or path.stem
+        artifact_type = doc.get("ArtifactType", "container_image")
+        meta = doc.get("Metadata") or {}
+        digest = (meta.get("RepoDigests") or [None])[0]
+        image_id = meta.get("ImageID")
+
+        asset_id = context.get("asset_id")
+        if asset_id is None:
+            # Identity facet is the image *reference* (name:tag) so that trivy,
+            # syft, and the Genesis deployment record reconcile to one asset;
+            # the digest rides along as an identifier for exact matching.
+            asset_id = Asset.id_for(
+                _KIND_BY_ARTIFACT.get(artifact_type, "other"), normalize_ref(artifact)
+            )
+            identifiers = {"image_ref": artifact}
+            if digest:
+                identifiers["digest"] = digest.split("@")[-1]
+            elif image_id:
+                identifiers["digest"] = image_id
+            batch.assets.append(
+                Asset(
+                    id=asset_id,
+                    asset_kind=_KIND_BY_ARTIFACT.get(artifact_type, "other"),
+                    name=artifact,
+                    identifiers=identifiers,
+                    system_id=context.get("system_id"),
+                    deployment_id=context.get("deployment_id"),
+                    environment=context.get("environment", "unknown"),
+                    source=source,
+                )
+            )
+
+        seen = now_iso()
+        context = {**context, "scan_scope": artifact_type}
+        for result in doc.get("Results") or []:
+            target = result.get("Target")
+            for v in result.get("Vulnerabilities") or []:
+                batch.findings.append(self._vuln(v, target, asset_id, source, seen, context))
+            for m in result.get("Misconfigurations") or []:
+                batch.findings.append(self._misconf(m, target, asset_id, source, seen, context))
+            for s in result.get("Secrets") or []:
+                batch.findings.append(self._secret(s, target, asset_id, source, seen, context))
+
+        batch.evidence.append(
+            EvidenceRecord(
+                id=new_id("ev"),
+                record_kind="scan",
+                subject_kind="asset",
+                subject_id=asset_id,
+                produced_by=f"trivy {version or ''}".strip(),
+                summary=f"trivy scan of {artifact}: {len(batch.findings)} findings",
+                payload={
+                    "artifact": artifact,
+                    "artifact_type": artifact_type,
+                    "created_at": doc.get("CreatedAt"),
+                    "report_id": doc.get("ReportID"),
+                    "os": meta.get("OS"),
+                    "counts": _counts(batch.findings),
+                },
+            )
+        )
+        return batch
+
+    @staticmethod
+    def _vuln(
+        v: dict, target: str | None, asset_id: str, source: Source, seen: str, ctx: dict
+    ) -> Finding:
+        cvss_block = v.get("CVSS") or {}
+        score, vector = None, None
+        # Prefer NVD v3, then any v3, then v2.
+        for key in ("nvd", *sorted(k for k in cvss_block if k != "nvd")):
+            c = cvss_block.get(key) or {}
+            if c.get("V3Score") is not None:
+                score, vector = c["V3Score"], c.get("V3Vector")
+                break
+        if score is None:
+            for c in cvss_block.values():
+                if c.get("V2Score") is not None:
+                    score, vector = c["V2Score"], c.get("V2Vector")
+                    break
+        purl = (v.get("PkgIdentifier") or {}).get("PURL")
+        return Finding(
+            id=new_id("fnd"),
+            title=v.get("Title") or f"{v.get('VulnerabilityID')} in {v.get('PkgName')}",
+            severity=v.get("Severity"),
+            source=source,
+            source_ref=v.get("VulnerabilityID"),
+            category="vulnerability",
+            detail=v.get("Description"),
+            location=target,
+            remediation=(
+                f"Upgrade {v.get('PkgName')} to {v['FixedVersion']}"
+                if v.get("FixedVersion")
+                else None
+            ),
+            vuln=Vuln(
+                id=v.get("VulnerabilityID", ""),
+                cwe=list(v.get("CweIDs") or []),
+                cvss=score,
+                cvss_vector=vector,
+                published=v.get("PublishedDate"),
+                references=list(v.get("References") or [])[:5],
+            ),
+            component=Component(
+                name=v.get("PkgName", ""),
+                purl=purl,
+                version=v.get("InstalledVersion"),
+                fixed_version=v.get("FixedVersion"),
+                type=(purl.split(":")[1].split("/")[0] if purl else None),
+            ),
+            asset_id=asset_id,
+            deployment_id=ctx.get("deployment_id"),
+            system_id=ctx.get("system_id"),
+            scan_scope=ctx.get("scan_scope"),
+            first_seen=seen,
+            last_seen=seen,
+            tags=[t for t in (v.get("Status"),) if t],
+            raw=v,
+        )
+
+    @staticmethod
+    def _misconf(
+        m: dict, target: str | None, asset_id: str, source: Source, seen: str, ctx: dict
+    ) -> Finding:
+        return Finding(
+            id=new_id("fnd"),
+            title=m.get("Title") or m.get("ID", "misconfiguration"),
+            severity=m.get("Severity"),
+            source=source,
+            source_ref=m.get("ID") or m.get("AVDID"),
+            category="misconfiguration",
+            detail=m.get("Description") or m.get("Message"),
+            location=target,
+            remediation=m.get("Resolution"),
+            asset_id=asset_id,
+            deployment_id=ctx.get("deployment_id"),
+            system_id=ctx.get("system_id"),
+            scan_scope=ctx.get("scan_scope"),
+            first_seen=seen,
+            last_seen=seen,
+            raw=m,
+        )
+
+    @staticmethod
+    def _secret(
+        s: dict, target: str | None, asset_id: str, source: Source, seen: str, ctx: dict
+    ) -> Finding:
+        return Finding(
+            id=new_id("fnd"),
+            title=s.get("Title") or f"Secret: {s.get('RuleID')}",
+            severity=s.get("Severity"),
+            source=source,
+            source_ref=s.get("RuleID"),
+            category="secret",
+            detail=s.get("Match"),
+            location=f"{target}:{s.get('StartLine')}" if s.get("StartLine") else target,
+            remediation="Remove the secret from the artifact and rotate it.",
+            asset_id=asset_id,
+            deployment_id=ctx.get("deployment_id"),
+            system_id=ctx.get("system_id"),
+            scan_scope=ctx.get("scan_scope"),
+            first_seen=seen,
+            last_seen=seen,
+            raw={k: v for k, v in s.items() if k != "Match"},  # never persist the matched secret
+        )
+
+
+def _counts(findings: list[Finding]) -> dict[str, int]:
+    out: dict[str, int] = {}
+    for f in findings:
+        out[f.severity.value] = out.get(f.severity.value, 0) + 1
+    return out
+
+
+@register_scanner
+class TrivyScanner(Scanner):
+    name = "trivy"
+    description = "Run trivy against an image, directory, or SBOM"
+    binary = "trivy"
+    targets = ("image", "fs", "sbom")
+
+    def version(self) -> str | None:
+        try:
+            out = subprocess.run(
+                [self.binary, "--version"], capture_output=True, text=True, timeout=20, check=False
+            ).stdout
+            return out.strip().splitlines()[0].replace("Version:", "").strip() or None
+        except (OSError, subprocess.TimeoutExpired):
+            return None
+
+    def scan(self, target_kind: str, target: str, workdir: Path) -> ScanResult:
+        if target_kind not in self.targets:
+            raise ValueError(f"trivy scanner does not support target kind {target_kind!r}")
+        workdir.mkdir(parents=True, exist_ok=True)
+        out = workdir / f"trivy-{target_kind}-{_slug(target)}.json"
+        argv = [
+            self.binary,
+            target_kind,
+            "--skip-version-check",
+            "--format",
+            "json",
+            "--output",
+            str(out),
+            target,
+        ]
+        if target_kind == "image":
+            argv[2:2] = ["--scanners", "vuln,secret"]
+        proc = subprocess.run(argv, capture_output=True, text=True, check=False, timeout=1800)
+        return ScanResult(
+            tool="trivy",
+            output_path=out if out.exists() else None,
+            connector="trivy",
+            argv=argv,
+            returncode=proc.returncode,
+            stderr=proc.stderr[-4000:],
+        )
+
+
+def normalize_ref(ref: str) -> str:
+    """``docker.io/library/python:3.11-slim`` and ``python:3.11-slim`` are one asset."""
+    ref = ref.split("@")[0]
+    for prefix in (
+        "docker.io/library/",
+        "docker.io/",
+        "index.docker.io/library/",
+        "index.docker.io/",
+    ):
+        if ref.startswith(prefix):
+            ref = ref[len(prefix) :]
+    return ref if ":" in ref.rsplit("/", 1)[-1] else f"{ref}:latest"
+
+
+def _slug(s: str) -> str:
+    return "".join(c if c.isalnum() else "-" for c in s).strip("-")[:80]

cernus_plugins-0.1.0.dist-info/METADATA

@@ -0,0 +1,35 @@
+Metadata-Version: 2.5
+Name: cernus-plugins
+Version: 0.1.0
+Summary: First-party Cernus connectors, scanners, and exporters: Genesis, Trivy, Syft/CycloneDX, SARIF, OSCAL.
+Project-URL: Homepage, https://github.com/Inceptium-ai/cernus-framework
+Project-URL: Repository, https://github.com/Inceptium-ai/cernus-framework
+Author-email: Inceptium <opensource@inceptium.ai>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Requires-Python: >=3.12
+Requires-Dist: cernus-core>=0.1.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# cernus-plugins
+
+First-party plugins for [Cernus](https://github.com/Inceptium-ai/cernus-framework).
+Each one wraps a tool you already run; none re-implements a scanner.
+
+| Plugin | Kind | What it does |
+|---|---|---|
+| `genesis` | connector | Genesis `EvidencePackage` + `DeliveryManifest` → System, Deployment, Findings |
+| `trivy` | connector + scanner | `trivy image/sbom --format json` → Findings with CVE/CVSS/purl; runs trivy |
+| `syft` | scanner | `syft <image> -o cyclonedx-json` → SBOM |
+| `cyclonedx` | connector | CycloneDX SBOM → Sbom + component Assets |
+| `sarif` | connector + exporter | SARIF 2.1.0 in (semgrep, CodeQL, …) and out |
+| `oscal` | exporter | Findings → OSCAL 1.1 POA&M (minimal, schema-shaped) |
+
+Plugins register through entry points (`cernus.connectors`, `cernus.scanners`,
+`cernus.exporters`). Write your own the same way — see `cernus_core.plugins`.

cernus_plugins-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+cernus_plugins/__init__.py,sha256=2QAXxvntSldkQujJ4fSWYPyvcOTnaz56Tq968CSfcG8,175
+cernus_plugins/cyclonedx.py,sha256=pj3lOW_wp6CD6qOLl-66s7EJHnAiymUpm5hvJdWwxLU,4306
+cernus_plugins/genesis.py,sha256=zsuMkPd_gAIMUiR-pAmCBxbapIWDlKWVOu4doVds5v4,12444
+cernus_plugins/oscal.py,sha256=riAe7wYectYHqHwST2v_OaJQEGwF5ppzHW94PKMpeRk,10035
+cernus_plugins/sarif.py,sha256=y91Cw8aTGyj8PiPehfMMSXatlgHnAE_ZPlFu9Eqw_wg,6250
+cernus_plugins/syft.py,sha256=mQsyEAdbFTBICDEInaSc7BdfT8-05-7ST_fIOo3koxA,1763
+cernus_plugins/trivy.py,sha256=d4V_VotAHmyH8XDa_azRK9U75hCKbycgsmiChRPQGfU,10833
+cernus_plugins-0.1.0.dist-info/METADATA,sha256=MXvyEtZ1L1rvVSuFQTom_4scDAFkEPPmDQG3sCb53pc,1683
+cernus_plugins-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+cernus_plugins-0.1.0.dist-info/entry_points.txt,sha256=i9x-BMBZc_BUHQU9jBiQSpoqI5OojZhXhfPSi5cOnZg,420
+cernus_plugins-0.1.0.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+cernus_plugins-0.1.0.dist-info/RECORD,,

cernus_plugins-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

cernus_plugins-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,13 @@
+[cernus.connectors]
+cyclonedx = cernus_plugins.cyclonedx:CycloneDXConnector
+genesis = cernus_plugins.genesis:GenesisConnector
+sarif = cernus_plugins.sarif:SarifConnector
+trivy = cernus_plugins.trivy:TrivyConnector
+
+[cernus.exporters]
+oscal = cernus_plugins.oscal:OscalExporter
+sarif = cernus_plugins.sarif:SarifExporter
+
+[cernus.scanners]
+syft = cernus_plugins.syft:SyftScanner
+trivy = cernus_plugins.trivy:TrivyScanner