dockerdna 1.0.2__py3-none-any.whl

dockerdna/reports/sarif.py

@@ -0,0 +1,139 @@
+"""
+SARIF 2.1.0 output for GitHub Advanced Security integration.
+
+DockerDNA ships with full SARIF support out of the box, enabling
+GitHub Security tab annotations on pull requests.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+_TOOL = {
+    "driver": {
+        "name": "DockerDNA",
+        "version": "1.0.2",
+        "informationUri": "https://github.com/sunilgentyala/DockerDNA",
+        "rules": [],
+    }
+}
+
+_SEVERITY_MAP = {
+    "CRITICAL": "error",
+    "HIGH": "error",
+    "MEDIUM": "warning",
+    "LOW": "note",
+}
+
+
+def generate_sarif(
+    dockerfile_findings: list[Any],
+    compose_findings: list[Any],
+    secret_findings: list[Any],
+    supply_chain_findings: list[Any],
+    base_path: str = "",
+) -> dict:
+    rules: dict[str, dict] = {}
+    results: list[dict] = []
+
+    def _add_rule(rule_id: str, name: str, description: str, severity: str):
+        if rule_id not in rules:
+            rules[rule_id] = {
+                "id": rule_id,
+                "name": name,
+                "shortDescription": {"text": name},
+                "fullDescription": {"text": description},
+                "defaultConfiguration": {
+                    "level": _SEVERITY_MAP.get(severity, "warning")
+                },
+                "helpUri": f"https://github.com/sunilgentyala/DockerDNA/wiki/{rule_id}",
+            }
+
+    def _add_result(
+        rule_id: str, message: str, filepath: str, line: int, severity: str
+    ):
+        uri = Path(filepath).as_posix() if filepath else "unknown"
+        if base_path:
+            try:
+                uri = Path(filepath).relative_to(base_path).as_posix()
+            except ValueError:
+                pass
+        results.append(
+            {
+                "ruleId": rule_id,
+                "level": _SEVERITY_MAP.get(severity, "warning"),
+                "message": {"text": message},
+                "locations": [
+                    {
+                        "physicalLocation": {
+                            "artifactLocation": {"uri": uri, "uriBaseId": "%SRCROOT%"},
+                            "region": {"startLine": max(1, line)},
+                        }
+                    }
+                ],
+            }
+        )
+
+    # Dockerfile findings
+    for f in dockerfile_findings:
+        _add_rule(f.cis_id, f.title, f.remediation, f.severity)
+        _add_result(f.cis_id, f.detail, "Dockerfile", f.line_number, f.severity)
+
+    # Compose findings
+    for f in compose_findings:
+        _add_rule(f.cis_id, f.title, f.remediation, f.severity)
+        _add_result(
+            f.cis_id,
+            f"{f.service}: {f.detail}",
+            "docker-compose.yml",
+            f.line_hint or 1,
+            f.severity,
+        )
+
+    # Secret findings
+    for f in secret_findings:
+        _add_rule(f.cis_id, f"Secret: {f.secret_type}", f.remediation, f.severity)
+        _add_result(
+            f.cis_id,
+            f"{f.secret_type} detected (method: {f.detection_method})",
+            f.file,
+            f.line_number,
+            f.severity,
+        )
+
+    # Supply chain findings
+    for f in supply_chain_findings:
+        if f.risk_score >= 15:
+            rule_id = f"{f.cis_id}-SUPPLY-CHAIN"
+            _add_rule(
+                rule_id, f"Supply chain risk: {f.image}", f.remediation, f.severity
+            )
+            _add_result(
+                rule_id,
+                f"Risk score {f.risk_score}/100 — {'; '.join(f.factors)}",
+                "Dockerfile",
+                1,
+                f.severity,
+            )
+
+    tool = dict(_TOOL)
+    tool["driver"]["rules"] = list(rules.values())
+
+    return {
+        "$schema": "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/master/Schemata/sarif-schema-2.1.0.json",
+        "version": "2.1.0",
+        "runs": [
+            {
+                "tool": tool,
+                "results": results,
+                "invocations": [
+                    {
+                        "executionSuccessful": True,
+                        "endTimeUtc": datetime.now(timezone.utc).isoformat(),
+                    }
+                ],
+            }
+        ],
+    }

dockerdna/reports/sbom.py

@@ -0,0 +1,176 @@
+"""
+CycloneDX SBOM (Software Bill of Materials) generator.
+
+Parses Dockerfile package install instructions to produce a
+CycloneDX 1.5 JSON SBOM documenting what is installed in each layer,
+enabling supply-chain transparency and NTIA minimum-elements compliance.
+"""
+
+from __future__ import annotations
+
+import re
+import uuid
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any
+
+
+@dataclass
+class Component:
+    name: str
+    version: str
+    pkg_type: str  # "deb" | "rpm" | "apk" | "pip" | "npm" | "gem" | "unknown"
+    source_layer: int
+    stage: str
+    purl: str = ""
+
+    def to_cyclonedx(self) -> dict:
+        comp: dict = {
+            "type": "library",
+            "name": self.name,
+            "version": self.version or "unknown",
+            "properties": [
+                {"name": "dockerdna:layer", "value": str(self.source_layer)},
+                {"name": "dockerdna:stage", "value": self.stage},
+                {"name": "dockerdna:pkg_type", "value": self.pkg_type},
+            ],
+        }
+        if self.purl:
+            comp["purl"] = self.purl
+        return comp
+
+
+# Package manager install patterns
+_INSTALLERS: list[tuple[str, str, re.Pattern]] = [
+    (
+        "deb",
+        "apt",
+        re.compile(
+            r"apt(?:-get)?\s+install\s+(?:-[^\s]+\s+)*(.+?)(?:\s*&&|\s*$|\s*\\)",
+            re.DOTALL,
+        ),
+    ),
+    (
+        "apk",
+        "apk",
+        re.compile(r"apk\s+add\s+(?:--[^\s]+\s+)*(.+?)(?:\s*&&|\s*$|\s*\\)", re.DOTALL),
+    ),
+    (
+        "rpm",
+        "yum",
+        re.compile(
+            r"yum\s+install\s+(?:-[^\s]+\s+)*(.+?)(?:\s*&&|\s*$|\s*\\)", re.DOTALL
+        ),
+    ),
+    (
+        "rpm",
+        "dnf",
+        re.compile(
+            r"dnf\s+install\s+(?:-[^\s]+\s+)*(.+?)(?:\s*&&|\s*$|\s*\\)", re.DOTALL
+        ),
+    ),
+    (
+        "pip",
+        "pip",
+        re.compile(
+            r"pip(?:3)?\s+install\s+(?:--[^\s]+\s+)*(.+?)(?:\s*&&|\s*$|\s*\\)",
+            re.DOTALL,
+        ),
+    ),
+    (
+        "npm",
+        "npm",
+        re.compile(
+            r"npm\s+install\s+(?:-[^\s]+\s+)*(.+?)(?:\s*&&|\s*$|\s*\\)", re.DOTALL
+        ),
+    ),
+    (
+        "gem",
+        "gem",
+        re.compile(
+            r"gem\s+install\s+(?:--[^\s]+\s+)*(.+?)(?:\s*&&|\s*$|\s*\\)", re.DOTALL
+        ),
+    ),
+]
+
+_PKG_TOKEN = re.compile(r"[A-Za-z0-9_\-\.]+(?:=[^\s]+)?")
+_VERSION_SEP = re.compile(r"[=><~!]+")
+
+
+def _parse_pkg(token: str, pkg_type: str) -> tuple[str, str]:
+    """Split 'pkg=1.2.3' into (name, version)."""
+    parts = _VERSION_SEP.split(token, maxsplit=1)
+    name = parts[0].strip()
+    version = parts[1].strip() if len(parts) > 1 else ""
+    return name, version
+
+
+def _make_purl(pkg_type: str, name: str, version: str) -> str:
+    if not name:
+        return ""
+    v = f"@{version}" if version else ""
+    return f"pkg:{pkg_type}/{name}{v}"
+
+
+def extract_components(layers: list[Any]) -> list[Component]:
+    components: list[Component] = []
+    for layer in layers:
+        if layer.instruction != "RUN":
+            continue
+        args = layer.arguments
+        for pkg_type, _, pattern in _INSTALLERS:
+            for match in pattern.finditer(args):
+                raw_pkgs = match.group(1)
+                for token in _PKG_TOKEN.findall(raw_pkgs):
+                    if token.startswith("-"):
+                        continue
+                    name, version = _parse_pkg(token, pkg_type)
+                    if len(name) < 2:
+                        continue
+                    components.append(
+                        Component(
+                            name=name,
+                            version=version,
+                            pkg_type=pkg_type,
+                            source_layer=layer.index,
+                            stage=layer.stage,
+                            purl=_make_purl(pkg_type, name, version),
+                        )
+                    )
+    return components
+
+
+def generate_cyclonedx(
+    components: list[Component],
+    image_name: str = "unknown",
+    dockerfile_path: str = "Dockerfile",
+) -> dict:
+    """Return a CycloneDX 1.5 BOM as a Python dict (serialise to JSON)."""
+    now = datetime.now(timezone.utc).isoformat()
+    bom_ref = str(uuid.uuid4())
+
+    return {
+        "bomFormat": "CycloneDX",
+        "specVersion": "1.5",
+        "serialNumber": f"urn:uuid:{bom_ref}",
+        "version": 1,
+        "metadata": {
+            "timestamp": now,
+            "tools": [
+                {
+                    "vendor": "DockerDNA",
+                    "name": "DockerDNA SBOM Generator",
+                    "version": "1.0.2",
+                }
+            ],
+            "component": {
+                "type": "container",
+                "name": image_name,
+                "version": "unknown",
+                "properties": [
+                    {"name": "dockerdna:dockerfile", "value": dockerfile_path}
+                ],
+            },
+        },
+        "components": [c.to_cyclonedx() for c in components],
+    }

dockerdna/scanner.py

@@ -0,0 +1,234 @@
+"""
+DockerDNA main orchestrator.
+
+Runs all sub-scanners and assembles a unified report.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+from typing import Optional
+
+from dockerdna.reports.html import generate_html
+from dockerdna.reports.json_report import generate_json_report
+from dockerdna.reports.sarif import generate_sarif
+from dockerdna.reports.sbom import extract_components, generate_cyclonedx
+from dockerdna.scanners.compliance import ComplianceMapper
+from dockerdna.scanners.compose import ComposeScanner
+from dockerdna.scanners.dockerfile import DockerfileScanner
+from dockerdna.scanners.secrets import SecretsScanner
+from dockerdna.scanners.supply_chain import SupplyChainScanner
+
+
+def scan(
+    dockerfile: Optional[str] = None,
+    compose_file: Optional[str] = None,
+    extra_files: Optional[list[str]] = None,
+    scan_directory: Optional[str] = None,
+    ai_remediation: bool = False,
+    ai_model: str = "claude-sonnet-4-6",
+    output_dir: str = "dockerdna-results",
+    formats: list[str] | None = None,
+    threshold: Optional[str] = None,  # CRITICAL | HIGH | MEDIUM | LOW
+    redact_secrets: bool = True,
+    verbose: bool = False,
+) -> dict:
+    """
+    Run all DockerDNA scanners and write reports.
+
+    Returns the full report dict. Raises SystemExit with code 1 if
+    ``threshold`` is set and findings at that severity or above are found.
+    """
+    if formats is None:
+        formats = ["json", "html"]
+
+    # ------------------------------------------------------------------ #
+    # Auto-discover files
+    # ------------------------------------------------------------------ #
+    search_roots: list[Path] = []
+    if scan_directory:
+        search_roots.append(Path(scan_directory))
+    if dockerfile:
+        search_roots.append(Path(dockerfile).parent)
+
+    if dockerfile is None and scan_directory:
+        for candidate in ["Dockerfile", "dockerfile"]:
+            p = Path(scan_directory) / candidate
+            if p.exists():
+                dockerfile = str(p)
+                break
+
+    if compose_file is None and scan_directory:
+        for candidate in [
+            "docker-compose.yml",
+            "docker-compose.yaml",
+            "compose.yml",
+            "compose.yaml",
+        ]:
+            p = Path(scan_directory) / candidate
+            if p.exists():
+                compose_file = str(p)
+                break
+
+    # ------------------------------------------------------------------ #
+    # Run scanners
+    # ------------------------------------------------------------------ #
+    secrets_scanner = SecretsScanner(redact=redact_secrets)
+    compose_scanner = ComposeScanner()
+    dockerfile_scanner = DockerfileScanner(redact=redact_secrets)
+    supply_chain_scanner = SupplyChainScanner()
+    compliance_mapper = ComplianceMapper()
+
+    # Secrets
+    secret_findings = []
+    if dockerfile:
+        secret_findings.extend(secrets_scanner.scan_file(dockerfile))
+    if compose_file:
+        secret_findings.extend(secrets_scanner.scan_file(compose_file))
+    if scan_directory:
+        secret_findings.extend(secrets_scanner.scan_directory(scan_directory))
+    if extra_files:
+        for ef in extra_files:
+            secret_findings.extend(secrets_scanner.scan_file(ef))
+
+    # Deduplicate secrets by (file, line)
+    seen_secrets: set[tuple[str, int]] = set()
+    deduped_secrets = []
+    for sf in secret_findings:
+        key = (sf.file, sf.line_number)
+        if key not in seen_secrets:
+            seen_secrets.add(key)
+            deduped_secrets.append(sf)
+    secret_findings = deduped_secrets
+
+    # Compose
+    compose_findings = []
+    if compose_file:
+        compose_findings = compose_scanner.scan(compose_file)
+
+    # Dockerfile + layers
+    layers: list = []
+    dockerfile_findings = []
+    if dockerfile:
+        layers, dockerfile_findings = dockerfile_scanner.scan(dockerfile)
+
+    # Supply chain
+    supply_chain_findings = supply_chain_scanner.analyze_base_images(layers)
+
+    # Compliance
+    compliance_report = compliance_mapper.generate(
+        dockerfile_findings,
+        compose_findings,
+        secret_findings,
+        supply_chain_findings,
+    )
+
+    # SBOM
+    components = extract_components(layers)
+    image_name = Path(dockerfile).stem if dockerfile else "unknown"
+    sbom = generate_cyclonedx(components, image_name, dockerfile or "Dockerfile")
+
+    # Metadata
+    metadata = {
+        "scanned_path": dockerfile or scan_directory or ".",
+        "compose_file": compose_file or "",
+        "dockerfile": dockerfile or "",
+        "files_scanned": (
+            ([dockerfile] if dockerfile else [])
+            + ([compose_file] if compose_file else [])
+            + (extra_files or [])
+        ),
+    }
+
+    # ------------------------------------------------------------------ #
+    # Assemble report
+    # ------------------------------------------------------------------ #
+    report = generate_json_report(
+        dockerfile_findings,
+        compose_findings,
+        secret_findings,
+        supply_chain_findings,
+        compliance_report,
+        sbom,
+        metadata,
+    )
+
+    # ------------------------------------------------------------------ #
+    # AI remediation (optional)
+    # ------------------------------------------------------------------ #
+    if ai_remediation:
+        from dockerdna.ai.remediation import get_ai_remediation
+
+        ai_result = get_ai_remediation(
+            dockerfile,
+            compose_file,
+            dockerfile_findings,
+            compose_findings,
+            secret_findings,
+            supply_chain_findings,
+            compliance_report.score,
+            model=ai_model,
+        )
+        report["ai_remediation"] = ai_result
+
+    # ------------------------------------------------------------------ #
+    # Write outputs
+    # ------------------------------------------------------------------ #
+    out = Path(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+
+    if "json" in formats:
+        json_path = out / "report.json"
+        json_path.write_text(
+            json.dumps(report, indent=2, default=str), encoding="utf-8"
+        )
+        if verbose:
+            print(f"[DockerDNA] JSON report: {json_path}")
+
+    if "html" in formats:
+        html_path = out / "report.html"
+        html_path.write_text(generate_html(report), encoding="utf-8")
+        if verbose:
+            print(f"[DockerDNA] HTML report: {html_path}")
+
+    if "sarif" in formats:
+        sarif_data = generate_sarif(
+            dockerfile_findings,
+            compose_findings,
+            secret_findings,
+            supply_chain_findings,
+            base_path=str(Path(dockerfile).parent) if dockerfile else "",
+        )
+        sarif_path = out / "report.sarif"
+        sarif_path.write_text(json.dumps(sarif_data, indent=2), encoding="utf-8")
+        if verbose:
+            print(f"[DockerDNA] SARIF report: {sarif_path}")
+
+    if "sbom" in formats:
+        sbom_path = out / "sbom.cyclonedx.json"
+        sbom_path.write_text(json.dumps(sbom, indent=2), encoding="utf-8")
+        if verbose:
+            print(f"[DockerDNA] SBOM: {sbom_path}")
+
+    # ------------------------------------------------------------------ #
+    # Threshold gate (CI/CD)
+    # ------------------------------------------------------------------ #
+    if threshold:
+        order = {"CRITICAL": 0, "HIGH": 1, "MEDIUM": 2, "LOW": 3}
+        threshold_level = order.get(threshold.upper(), 3)
+        by_sev = report["summary"]["by_severity"]
+        should_fail = any(
+            count > 0
+            for sev, count in by_sev.items()
+            if order.get(sev, 99) <= threshold_level
+        )
+        if should_fail:
+            print(
+                f"[DockerDNA] FAIL: findings at or above {threshold} severity detected.",
+                file=sys.stderr,
+            )
+            sys.exit(1)
+
+    return report

dockerdna/scanners/compliance.py

@@ -0,0 +1,149 @@
+"""
+CIS Docker Benchmark v1.6 compliance report generator.
+
+Aggregates findings from all scanners and maps them to specific CIS Docker
+Benchmark control IDs, producing a structured pass/fail/not-checked scorecard.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from dockerdna.utils.patterns import CIS_RULES, CISRule
+
+
+@dataclass
+class ControlResult:
+    rule: CISRule
+    status: str  # PASS | FAIL | NOT_CHECKED
+    findings: list[dict] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.rule.id,
+            "level": self.rule.level,
+            "title": self.rule.title,
+            "severity": self.rule.severity,
+            "status": self.status,
+            "findings_count": len(self.findings),
+            "remediation": self.rule.remediation if self.status == "FAIL" else "",
+        }
+
+
+@dataclass
+class ComplianceReport:
+    total: int
+    passed: int
+    failed: int
+    not_checked: int
+    score: float  # 0–100 compliance score
+    controls: list[ControlResult]
+
+    def to_dict(self) -> dict:
+        return {
+            "summary": {
+                "total_controls": self.total,
+                "passed": self.passed,
+                "failed": self.failed,
+                "not_checked": self.not_checked,
+                "compliance_score": round(self.score, 1),
+            },
+            "controls": [c.to_dict() for c in self.controls],
+        }
+
+
+class ComplianceMapper:
+    """Map raw findings to CIS Docker Benchmark controls."""
+
+    def generate(
+        self,
+        dockerfile_findings: list[Any],
+        compose_findings: list[Any],
+        secret_findings: list[Any],
+        supply_chain_findings: list[Any],
+    ) -> ComplianceReport:
+
+        # Build a map: check_key -> list of findings
+        hit_map: dict[str, list[dict]] = {}
+
+        for f in dockerfile_findings:
+            hit_map.setdefault(f.check_key, []).append(f.to_dict())
+
+        for f in compose_findings:
+            hit_map.setdefault(f.check_key, []).append(f.to_dict())
+
+        for f in secret_findings:
+            # map secret type to a check_key
+            key = (
+                "hardcoded_secret" if f.detection_method == "pattern" else "env_secret"
+            )
+            hit_map.setdefault(key, []).append(f.to_dict())
+
+        for f in supply_chain_findings:
+            if f.risk_score >= 15:
+                hit_map.setdefault("no_content_trust", []).append(f.to_dict())
+
+        results: list[ControlResult] = []
+        passed = failed = not_checked = 0
+
+        for rule in CIS_RULES:
+            findings_for_rule = hit_map.get(rule.check_key, [])
+            if findings_for_rule:
+                status = "FAIL"
+                failed += 1
+            else:
+                # We only mark PASS for checks we actually ran
+                if rule.check_key in self._checked_keys():
+                    status = "PASS"
+                    passed += 1
+                else:
+                    status = "NOT_CHECKED"
+                    not_checked += 1
+
+            results.append(
+                ControlResult(
+                    rule=rule,
+                    status=status,
+                    findings=findings_for_rule,
+                )
+            )
+
+        total = len(CIS_RULES)
+        checkable = passed + failed
+        score = (passed / checkable * 100) if checkable else 0.0
+
+        return ComplianceReport(
+            total=total,
+            passed=passed,
+            failed=failed,
+            not_checked=not_checked,
+            score=score,
+            controls=results,
+        )
+
+    @staticmethod
+    def _checked_keys() -> set[str]:
+        """The set of check_keys that DockerDNA actually evaluates."""
+        return {
+            "no_user",
+            "latest_tag",
+            "unnecessary_packages",
+            "no_healthcheck",
+            "update_without_install",
+            "env_secret",
+            "hardcoded_secret",
+            "no_content_trust",
+            "privileged",
+            "excess_capabilities",
+            "sensitive_mount",
+            "docker_socket",
+            "host_network",
+            "no_memory_limit",
+            "no_cpu_limit",
+            "no_readonly_fs",
+            "no_new_privileges",
+            "privileged_ports",
+            "no_apparmor",
+            "ssh_in_container",
+        }