audit-packs-mapping 0.1.1__tar.gz

audit_packs_mapping-0.1.1/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: audit-packs-mapping
+Version: 0.1.1
+Summary: Compliance mapping, coverage, and OSCAL export for audit-packs
+License: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: audit-packs-core>=0.1.1
+Requires-Dist: PyYAML>=6.0
+
+# audit-packs-mapping
+
+[![PyPI version](https://img.shields.io/pypi/v/audit-packs-mapping.svg)](https://pypi.org/project/audit-packs-mapping/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE)
+
+`audit-packs-mapping` is the compliance framework mapping and coverage calculation engine for the `audit-packs` ecosystem. It evaluates raw security scanner findings and maps them to control requirements in GRC frameworks (such as SOC 2, NIST 800-53, GDPR, HIPAA, and ISO 27001).
+
+## Installation
+
+```bash
+pip install audit-packs-mapping
+```
+
+## Features
+
+- **Framework Control Mapping**: Resolves raw scanner rule IDs (e.g. Checkov `CKV_AWS_19`, Semgrep rules) to specific compliance controls.
+- **Coverage Engine**: Computes compliance pass/fail/manual rates across active control frameworks based on finding states.
+- **OSCAL Export**: Generates NIST Open Security Controls Assessment Language (OSCAL) JSON representation of compliance postures.
+- **Pack Registry Support**: Loads, validates, and installs compliance packs containing control-to-rule mappings.
+
+## Learn More
+
+This library is part of the larger `audit-packs` Compliance Intelligence Engine. For the main command-line interface, GitHub Action integration, and framework mappings, see the [main repository](https://github.com/prakharsingh/audit-packs).

audit_packs_mapping-0.1.1/README.md

@@ -0,0 +1,23 @@
+# audit-packs-mapping
+
+[![PyPI version](https://img.shields.io/pypi/v/audit-packs-mapping.svg)](https://pypi.org/project/audit-packs-mapping/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE)
+
+`audit-packs-mapping` is the compliance framework mapping and coverage calculation engine for the `audit-packs` ecosystem. It evaluates raw security scanner findings and maps them to control requirements in GRC frameworks (such as SOC 2, NIST 800-53, GDPR, HIPAA, and ISO 27001).
+
+## Installation
+
+```bash
+pip install audit-packs-mapping
+```
+
+## Features
+
+- **Framework Control Mapping**: Resolves raw scanner rule IDs (e.g. Checkov `CKV_AWS_19`, Semgrep rules) to specific compliance controls.
+- **Coverage Engine**: Computes compliance pass/fail/manual rates across active control frameworks based on finding states.
+- **OSCAL Export**: Generates NIST Open Security Controls Assessment Language (OSCAL) JSON representation of compliance postures.
+- **Pack Registry Support**: Loads, validates, and installs compliance packs containing control-to-rule mappings.
+
+## Learn More
+
+This library is part of the larger `audit-packs` Compliance Intelligence Engine. For the main command-line interface, GitHub Action integration, and framework mappings, see the [main repository](https://github.com/prakharsingh/audit-packs).

audit_packs_mapping-0.1.1/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "audit-packs-mapping"
+version = "0.1.1"
+description = "Compliance mapping, coverage, and OSCAL export for audit-packs"
+readme = "README.md"
+license = { text = "Apache-2.0" }
+requires-python = ">=3.11"
+dependencies = ["audit-packs-core>=0.1.1", "PyYAML>=6.0"]
+
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]

audit_packs_mapping-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

audit_packs_mapping-0.1.1/src/audit_packs_mapping/coverage.py

@@ -0,0 +1,60 @@
+"""coverage.py — compute ControlStatus for every framework control.
+
+Pure logic: no subprocess, no HTTP. Takes ControlFinding instances (already
+mapped by packs.map_findings) and the pack directory, and returns a
+ControlStatus per control — pass, fail, manual, or not_applicable.
+"""
+
+from audit_packs_core.models import ControlFinding, ControlStatus, AssessmentStatus
+from audit_packs_mapping.packs import iter_controls
+
+
+def compute_coverage(
+    control_findings: list[ControlFinding],
+    packs_dir: str,
+    frameworks: list[str],
+) -> list[ControlStatus]:
+    """Compute a ControlStatus for every control in *frameworks*.
+
+    Args:
+        control_findings: All ControlFinding instances from map_findings()
+                          (may come from diff-only or full-repo scan).
+        packs_dir:        Path to the directory containing pack YAML files.
+        frameworks:       List of framework ids (e.g. ["nist-800-53", "soc2"]).
+
+    Returns:
+        One ControlStatus per (framework, control_id) pair.
+    """
+    # Index findings by (framework, control_id) for O(1) lookup
+    findings_by_key: dict[tuple[str, str], list[ControlFinding]] = {}
+    for cf in control_findings:
+        key = (cf.framework, cf.control_id)
+        findings_by_key.setdefault(key, []).append(cf)
+
+    statuses: list[ControlStatus] = []
+    for fw in frameworks:
+        for ctrl in iter_controls(packs_dir, fw):
+            key = (fw, ctrl["id"])
+            matched = findings_by_key.get(key, [])
+            assessment_hint = ctrl.get("assessment")
+
+            if assessment_hint == "manual":
+                status = AssessmentStatus.MANUAL
+            elif matched:
+                status = AssessmentStatus.FAIL
+            else:
+                status = AssessmentStatus.PASS
+
+            statuses.append(
+                ControlStatus(
+                    framework=fw,
+                    control_id=ctrl["id"],
+                    control_title=ctrl["title"],
+                    status=status,
+                    check_ids=tuple(ctrl["check_ids"]),
+                    findings=tuple(matched),
+                    evidence=tuple(cf.finding.evidence for cf in matched),
+                )
+            )
+
+    return statuses

audit_packs_mapping-0.1.1/src/audit_packs_mapping/oscal.py

@@ -0,0 +1,144 @@
+"""oscal.py — Emit NIST OSCAL assessment-results from ControlStatus objects.
+
+Produces a JSON-serialisable dict that conforms to the OSCAL assessment-results
+model (https://pages.nist.gov/OSCAL/). Uses stdlib only (no new dependencies).
+
+Supports:
+  - One result entry per framework
+  - reviewed-controls with all assessed controls
+  - findings for FAIL controls with evidence links
+  - Manual controls flagged with state "not-satisfied" (human evidence required)
+"""
+
+import uuid
+from collections import defaultdict
+from datetime import datetime, timezone
+
+from audit_packs_core.models import AssessmentStatus, ControlStatus
+
+
+def _now_iso() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+
+def _uuid() -> str:
+    return str(uuid.uuid4())
+
+
+def to_assessment_results(control_statuses: list[ControlStatus]) -> dict:
+    """Convert a list of ControlStatus objects to an OSCAL assessment-results dict.
+
+    Returns a JSON-serialisable dict with the OSCAL top-level structure:
+      {"assessment-results": {"uuid": ..., "metadata": ..., "results": [...]}}
+    """
+    if not control_statuses:
+        return {
+            "assessment-results": {
+                "uuid": _uuid(),
+                "metadata": _metadata(),
+                "results": [],
+            }
+        }
+
+    # Group by framework
+    by_framework: dict[str, list[ControlStatus]] = defaultdict(list)
+    for cs in control_statuses:
+        by_framework[cs.framework].append(cs)
+
+    results = []
+    for framework, statuses in by_framework.items():
+        results.append(_build_result(framework, statuses))
+
+    return {
+        "assessment-results": {
+            "uuid": _uuid(),
+            "metadata": _metadata(),
+            "results": results,
+        }
+    }
+
+
+def _metadata() -> dict:
+    return {
+        "title": "audit-packs SOC 2 / NIST 800-53 Assessment Results",
+        "last-modified": _now_iso(),
+        "version": "1.0",
+        "oscal-version": "1.1.2",
+        "remarks": (
+            "Generated by audit-packs (https://github.com/prakharsingh/audit-packs). "
+            "Code-observable controls are assessed automatically; controls marked "
+            "assessment:manual require human evidence for SOC 2 attestation."
+        ),
+    }
+
+
+def _build_result(framework: str, statuses: list[ControlStatus]) -> dict:
+    findings = []
+    control_selections: list[dict] = []
+
+    # Separate by status to build both the reviewed-controls list and findings
+    include_all = [{"control-id": s.control_id} for s in statuses]
+    if include_all:
+        control_selections.append({"include-controls": include_all})
+
+    for cs in statuses:
+        if cs.status == AssessmentStatus.FAIL:
+            for cf in cs.findings:
+                findings.append(
+                    {
+                        "uuid": _uuid(),
+                        "title": f"[{cs.framework}] {cs.control_id} — {cs.control_title}",
+                        "description": cf.finding.message,
+                        "target": {
+                            "type": "statement-id",
+                            "target-id": cs.control_id,
+                            "status": {
+                                "state": "not-satisfied",
+                                "reason": "fail",
+                            },
+                        },
+                        "related-observations": [
+                            {
+                                "observation-uuid": _uuid(),
+                                "description": (
+                                    f"Engine: {cf.finding.engine} ({cf.finding.check_id}) "
+                                    f"— {cf.finding.file}:{cf.finding.line}"
+                                ),
+                                "evidence": cf.finding.evidence,
+                                "severity": cf.finding.severity,
+                            }
+                        ],
+                    }
+                )
+        elif cs.status == AssessmentStatus.MANUAL:
+            # Manual controls appear in findings with state "not-satisfied" and
+            # a note that human evidence is required.
+            findings.append(
+                {
+                    "uuid": _uuid(),
+                    "title": f"[{cs.framework}] {cs.control_id} — {cs.control_title}",
+                    "description": (
+                        "This control requires manual attestation. "
+                        "No automated checks are available for this criterion."
+                    ),
+                    "target": {
+                        "type": "statement-id",
+                        "target-id": cs.control_id,
+                        "status": {
+                            "state": "not-satisfied",
+                            "reason": "manual-evidence-required",
+                        },
+                    },
+                    "related-observations": [],
+                }
+            )
+
+    return {
+        "uuid": _uuid(),
+        "title": framework,
+        "description": f"Assessment results for {framework}",
+        "reviewed-controls": {
+            "control-selections": control_selections,
+        },
+        "findings": findings,
+    }

audit_packs_mapping-0.1.1/src/audit_packs_mapping/packs.py

@@ -0,0 +1,160 @@
+import os
+import yaml
+from audit_packs_core.models import Finding, ControlFinding
+
+
+def load_pack(path: str) -> dict | None:
+    """Load a pack YAML.  Returns None (instead of raising) when the file is missing."""
+    if not os.path.exists(path):
+        return None
+    with open(path) as fh:
+        data = yaml.safe_load(fh) or {}
+    framework_key = data.get("framework") or data.get("id")
+    if not framework_key or "controls" not in data:
+        raise ValueError(f"pack {path} missing required keys 'framework'/'controls'")
+    return data
+
+
+def _pack_path(packs_dir: str, pack_id: str) -> str:
+    # 1. Check if packs_dir/pack_id exists
+    local_path = os.path.join(packs_dir, pack_id, "controls.yaml")
+    if os.path.exists(local_path):
+        return local_path
+
+    # 2. Check if it's installed in the user's home folder registry cache
+    installed_path = os.path.join(
+        os.path.expanduser("~"), ".audit-packs", "installed", pack_id, "controls.yaml"
+    )
+    if os.path.exists(installed_path):
+        return installed_path
+
+    return local_path
+
+
+def _canonical_index(pack: dict) -> dict[tuple[str, str], list[tuple[str, str, tuple]]]:
+    """(engine, check_id) -> [(control_id, control_title, evidence_requirements), ...]"""
+    index: dict[tuple[str, str], list[tuple[str, str, tuple]]] = {}
+    for control in pack["controls"]:
+        ev_reqs: tuple = tuple(control.get("evidence_requirements", []))
+        for m in control.get("mappings", []):
+            key = (m["engine"], m["check_id"])
+            index.setdefault(key, []).append(
+                (
+                    control["id"],
+                    control.get("title", control["id"]),
+                    ev_reqs,
+                )
+            )
+    return index
+
+
+def _canonical_check_ids(pack: dict) -> dict[str, list[tuple[str, str]]]:
+    """control_id -> [(engine, check_id), ...]"""
+    result: dict[str, list[tuple[str, str]]] = {}
+    for control in pack["controls"]:
+        pairs = [(m["engine"], m["check_id"]) for m in control.get("mappings", [])]
+        result[control["id"]] = pairs
+    return result
+
+
+def iter_controls(packs_dir: str, framework: str) -> list[dict]:
+    """Return every control in *framework* with its resolved check_ids."""
+    pack = load_pack(_pack_path(packs_dir, framework))
+    if pack is None:
+        return []
+    crosswalk_id = pack.get("crosswalk")
+
+    if crosswalk_id:
+        canonical = load_pack(_pack_path(packs_dir, crosswalk_id))
+        canon_checks = _canonical_check_ids(canonical)
+        result = []
+        for control in pack["controls"]:
+            maps_to = control.get("maps_to", [])
+            assessment = control.get("assessment", None)
+            check_ids: list[tuple[str, str]] = []
+            for nist_id in maps_to:
+                check_ids.extend(canon_checks.get(nist_id, []))
+            result.append(
+                {
+                    "id": control["id"],
+                    "title": control.get("title", control["id"]),
+                    "assessment": assessment,
+                    "check_ids": check_ids,
+                    "maps_to": maps_to,
+                }
+            )
+        return result
+    else:
+        canon_checks = _canonical_check_ids(pack)
+        return [
+            {
+                "id": control["id"],
+                "title": control.get("title", control["id"]),
+                "assessment": None,
+                "check_ids": canon_checks.get(control["id"], []),
+                "maps_to": [],
+            }
+            for control in pack["controls"]
+        ]
+
+
+def map_findings(
+    findings: list[Finding], packs_dir: str, frameworks: list[str]
+) -> list[ControlFinding]:
+    import sys
+
+    results: list[ControlFinding] = []
+    for fw in frameworks:
+        pack = load_pack(_pack_path(packs_dir, fw))
+        if pack is None:
+            print(
+                f"\n⚠️  pack not found for framework '{fw}' in {packs_dir!r} — skipping mapping.\n"
+                f"   Install with: audit-packs pack install <source>  "
+                f"or point --packs-dir at your packs directory.",
+                file=sys.stderr,
+            )
+            continue
+        crosswalk_id = pack.get("crosswalk")
+        canonical = (
+            load_pack(_pack_path(packs_dir, crosswalk_id)) if crosswalk_id else pack
+        )
+        if canonical is None:
+            print(
+                f"\n⚠️  crosswalk pack '{crosswalk_id}' not found for '{fw}' — skipping mapping.",
+                file=sys.stderr,
+            )
+            continue
+        check_index = _canonical_index(canonical)
+
+        if crosswalk_id:
+            cw: dict[str, list[tuple[str, str, tuple]]] = {}
+            for control in pack["controls"]:
+                ev_reqs: tuple = tuple(control.get("evidence_requirements", []))
+                for mapped in control.get("maps_to", []):
+                    cw.setdefault(mapped, []).append(
+                        (control["id"], control.get("title", control["id"]), ev_reqs)
+                    )
+            has_manual = any(c.get("assessment") == "manual" for c in pack["controls"])
+            if not cw and not has_manual:
+                raise ValueError(
+                    f"crosswalk pack '{fw}' has no 'maps_to' entries in any control; "
+                    f"check that controls use 'maps_to' (not 'nist_ids' or similar)"
+                )
+
+        for f in findings:
+            hits = check_index.get((f.engine, f.check_id), [])
+            for canonical_control_id, canonical_title, canon_ev_reqs in hits:
+                if crosswalk_id:
+                    for control_id, title, fw_ev_reqs in cw.get(
+                        canonical_control_id, []
+                    ):
+                        results.append(
+                            ControlFinding(f, fw, control_id, title, fw_ev_reqs)
+                        )
+                else:
+                    results.append(
+                        ControlFinding(
+                            f, fw, canonical_control_id, canonical_title, canon_ev_reqs
+                        )
+                    )
+    return results

audit_packs_mapping-0.1.1/src/audit_packs_mapping.egg-info/PKG-INFO

@@ -0,0 +1,33 @@
+Metadata-Version: 2.4
+Name: audit-packs-mapping
+Version: 0.1.1
+Summary: Compliance mapping, coverage, and OSCAL export for audit-packs
+License: Apache-2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: audit-packs-core>=0.1.1
+Requires-Dist: PyYAML>=6.0
+
+# audit-packs-mapping
+
+[![PyPI version](https://img.shields.io/pypi/v/audit-packs-mapping.svg)](https://pypi.org/project/audit-packs-mapping/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](../../LICENSE)
+
+`audit-packs-mapping` is the compliance framework mapping and coverage calculation engine for the `audit-packs` ecosystem. It evaluates raw security scanner findings and maps them to control requirements in GRC frameworks (such as SOC 2, NIST 800-53, GDPR, HIPAA, and ISO 27001).
+
+## Installation
+
+```bash
+pip install audit-packs-mapping
+```
+
+## Features
+
+- **Framework Control Mapping**: Resolves raw scanner rule IDs (e.g. Checkov `CKV_AWS_19`, Semgrep rules) to specific compliance controls.
+- **Coverage Engine**: Computes compliance pass/fail/manual rates across active control frameworks based on finding states.
+- **OSCAL Export**: Generates NIST Open Security Controls Assessment Language (OSCAL) JSON representation of compliance postures.
+- **Pack Registry Support**: Loads, validates, and installs compliance packs containing control-to-rule mappings.
+
+## Learn More
+
+This library is part of the larger `audit-packs` Compliance Intelligence Engine. For the main command-line interface, GitHub Action integration, and framework mappings, see the [main repository](https://github.com/prakharsingh/audit-packs).

audit_packs_mapping-0.1.1/src/audit_packs_mapping.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/audit_packs_mapping/__init__.py
+src/audit_packs_mapping/coverage.py
+src/audit_packs_mapping/oscal.py
+src/audit_packs_mapping/packs.py
+src/audit_packs_mapping.egg-info/PKG-INFO
+src/audit_packs_mapping.egg-info/SOURCES.txt
+src/audit_packs_mapping.egg-info/dependency_links.txt
+src/audit_packs_mapping.egg-info/requires.txt
+src/audit_packs_mapping.egg-info/top_level.txt

audit_packs_mapping-0.1.1/src/audit_packs_mapping.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

audit_packs_mapping-0.1.1/src/audit_packs_mapping.egg-info/requires.txt

@@ -0,0 +1,2 @@
+audit-packs-core>=0.1.1
+PyYAML>=6.0

audit_packs_mapping-0.1.1/src/audit_packs_mapping.egg-info/top_level.txt

@@ -0,0 +1 @@
+audit_packs_mapping