f3c12544e8 · audit-labs/audit-report

.github/workflows/ci.yml added +26

@@ -0,0 +1,26 @@
	1	name: CI
	2
	3	on:
	4	push:
	5	pull_request:
	6
	7	jobs:
	8	test:
	9	runs-on: ubuntu-latest
	10	strategy:
	11	matrix:
	12	python-version: ["3.10", "3.12"]
	13	steps:
	14	- uses: actions/checkout@v5
	15	- name: Set up Python ${{ matrix.python-version }}
	16	uses: actions/setup-python@v6
	17	with:
	18	python-version: ${{ matrix.python-version }}
	19	- name: Install
	20	run: \|
	21	python -m pip install --upgrade pip
	22	pip install -e ".[dev]"
	23	- name: Ruff
	24	run: ruff check .
	25	- name: Tests
	26	run: pytest -q

MAPPING.md added +40

@@ -0,0 +1,40 @@
	1	# Rulesets — provenance and control-mapping rationale
	2
	3	An `audit-report` ruleset (`audit_report/rulesets/*.yaml`) turns collected
	4	evidence into control-relevant findings: each rule names a table, a check, and the
	5	control identifiers the signal is offered as evidence for. This document records
	6	where those mappings come from and their limits.
	7
	8	## What a mapping claims — and does not
	9
	10	- A rule's `controls` list says: "this signal is relevant to these controls."
	11	- A fail means a setting is in a state that does not support the control.
	12	It is not a compliance verdict — the auditor still owns the conclusion.
	13	- The control identifiers (`SOC2:CC6.1`, `ISO:A.5.17`, `NIST:IA-2`, …) are
	14	reproduced; the frameworks' normative control text is not. See the catalog
	15	provenance in [control-coverage `MAPPING.md`](https://github.com/audit-labs/control-coverage/blob/main/MAPPING.md).
	16	- The mappings are the maintainers' interpretation, not reviewed or endorsed
	17	by the AICPA, ISO/IEC, or NIST.
	18
	19	## Framework revisions referenced
	20
	21	- SOC 2 — Trust Services Criteria 2017 (2022 revised points of focus).
	22	- ISO/IEC 27001 — 27001:2022 Annex A.
	23	- NIST SP 800-53 — Rev. 5.
	24
	25	## Versioning and traceability
	26
	27	- Each ruleset carries `name` and `version` fields.
	28	- Every report stamps the tool name + version and the ruleset `name`, `version`,
	29	and a SHA-256 of the ruleset file into its output (`tool` / `ruleset` in
	30	JSON; the header line in Markdown/HTML).
	31	- An auditor can therefore tie any finding back to the exact ruleset that produced
	32	it, and re-perform against it. Bump `version` on any change to a rule's
	33	controls, checks, or thresholds.
	34
	35	## Authorship and review
	36
	37	- Author: the audit-labs maintainer.
	38	- Review status: maintainer self-review; no independent professional review.
	39	Validate a ruleset against your own control set before relying on it.
	40	- Effective date: 2026-08.

audit_report/cli.py +1 −1

	@@ -181,7 +181,7 @@ def main(argv: list[str] \| None = None) -> int:
181	return _run_diff(args, package, ruleset, formats)	181	return _run_diff(args, package, ruleset, formats)
182		182
183	findings = evaluate(package, ruleset)	183	findings = evaluate(package, ruleset)
184	report = reporters.build_report(package, findings)	184	report = reporters.build_report(package, findings, ruleset)
185	_emit(lambda fmt: reporters.render(report, fmt), formats, args.out, "report")	185	_emit(lambda fmt: reporters.render(report, fmt), formats, args.out, "report")
186		186
187	counts = report.counts	187	counts = report.counts

audit_report/reporters/__init__.py +23 −2

 from dataclasses import dataclass
 from datetime import datetime, timezone
+from .. import __version__
 from ..engine import Finding, control_coverage, summarize
 from ..loader import Package
+from ..rules import Ruleset
 from . import html as _html
 from . import json as _json
 from . import markdown as _markdown
     package: Package
     findings: list[Finding]
     generated_at: str
+    ruleset: Ruleset | None = None
     @property
     def counts(self) -> dict[str, int]:
     def coverage(self) -> dict[str, dict]:
         return control_coverage(self.findings)
+    @property
+    def provenance(self) -> dict[str, dict]:
+        """Tool + ruleset identity, so a report can be tied to what produced it."""
+        rs = self.ruleset
+        return {
+            "tool": {"name": "audit-report", "version": __version__},
+            "ruleset": {
+                "name": rs.name if rs else "",
+                "platform": rs.platform if rs else "",
+                "version": rs.version if rs else "",
+                "sha256": rs.sha256 if rs else "",
+            },
+        }
-def build_report(package: Package, findings: list[Finding]) -> Report:
+def build_report(
+    package: Package, findings: list[Finding], ruleset: Ruleset | None = None
+) -> Report:
     """Assemble a :class:`Report` with a UTC generation timestamp."""
     stamp = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
-    return Report(package=package, findings=findings, generated_at=stamp)
+    return Report(
+        package=package, findings=findings, generated_at=stamp, ruleset=ruleset
+    )
 RENDERERS = {

audit_report/reporters/html.py +12 −1

	@@ -90,10 +90,21 @@ def render(report: Report) -> str:
90	parts: list[str] = []	90	parts: list[str] = []
91		91
92	parts.append(f"<h1>Evidence Report — {escape(pkg.subject)}</h1>")	92	parts.append(f"<h1>Evidence Report — {escape(pkg.subject)}</h1>")
		93	prov = report.provenance
		94	tool, rs = prov["tool"], prov["ruleset"]
		95	ruleset_meta = ""
		96	if rs["sha256"]:
		97	rs_ver = f" {escape(rs['version'])}" if rs["version"] else ""
		98	ruleset_meta = (
		99	f" · Ruleset <code>{escape(rs['name'])}{rs_ver}</code> "
		100	f"<code>sha256:{escape(rs['sha256'][:12])}</code>"
		101	)
93	parts.append(	102	parts.append(
94	f"<p class='meta'>Platform <code>{escape(pkg.platform)}</code> · "	103	f"<p class='meta'>Platform <code>{escape(pkg.platform)}</code> · "
95	f"Source <code>{escape(pkg.path.name)}</code> · "	104	f"Source <code>{escape(pkg.path.name)}</code> · "
96	f"Generated {escape(report.generated_at)}</p>"	105	f"Generated {escape(report.generated_at)} · "
		106	f"Tool <code>{escape(tool['name'])} {escape(tool['version'])}</code>"
		107	f"{ruleset_meta}</p>"
97	)	108	)
98	parts.append(	109	parts.append(
99	"<p class='summary-pills'>"	110	"<p class='summary-pills'>"

audit_report/reporters/json.py +2

         "platform": pkg.platform,
         "source_package": pkg.path.name,
         "generated_at": report.generated_at,
+        "tool": report.provenance["tool"],
+        "ruleset": report.provenance["ruleset"],
         "summary": report.counts,
         "coverage": report.coverage,
         "findings": [

audit_report/reporters/markdown.py +9

	@@ -42,6 +42,15 @@ def render(report: Report) -> str:
42	out.append(f"- Subject: {pkg.subject}")	42	out.append(f"- Subject: {pkg.subject}")
43	out.append(f"- Source package: `{pkg.path.name}`")	43	out.append(f"- Source package: `{pkg.path.name}`")
44	out.append(f"- Generated: {report.generated_at}")	44	out.append(f"- Generated: {report.generated_at}")
		45	prov = report.provenance
		46	tool, rs = prov["tool"], prov["ruleset"]
		47	out.append(f"- Tool: {tool['name']} {tool['version']}")
		48	if rs["sha256"]:
		49	rs_ver = f" {rs['version']}" if rs["version"] else ""
		50	out.append(
		51	f"- Ruleset: {rs['name']}{rs_ver} "
		52	f"(`sha256:{rs['sha256'][:12]}`)"
		53	)
45	out.append(	54	out.append(
46	f"- Result: {counts[FAIL]} failing · {counts[PASS]} passing · "	55	f"- Result: {counts[FAIL]} failing · {counts[PASS]} passing · "
47	f"{counts[NOT_APPLICABLE]} not applicable"	56	f"{counts[NOT_APPLICABLE]} not applicable"

audit_report/rules.py +19 −3

 from __future__ import annotations
+import hashlib
 from dataclasses import dataclass, field
 from pathlib import Path
 @dataclass
 class Ruleset:
-    """A named collection of rules for one platform."""
+    """A named collection of rules for one platform.
+    ``version`` and ``sha256`` identify *which* ruleset produced a report, so an
+    auditor can re-perform against the exact mapping used. ``sha256`` is the
+    digest of the ruleset file's bytes as loaded.
+    """
     platform: str
     rules: list[Rule]
+    name: str = ""
+    version: str = ""
+    sha256: str = ""
 def _as_number(value: str) -> float | None:
 def load_ruleset(path: str | Path) -> Ruleset:
     """Parse a ruleset YAML file into a :class:`Ruleset`, validating each rule."""
-    data = yaml.safe_load(Path(path).read_text(encoding="utf-8")) or {}
+    text = Path(path).read_text(encoding="utf-8")
+    data = yaml.safe_load(text) or {}
     platform = data.get("platform")
     if not platform:
         raise ValueError(f"{path}: ruleset is missing a 'platform'")
             raise ValueError(f"{rule.id}: unknown check type {check_type!r}")
         rules.append(rule)
-    return Ruleset(platform=platform, rules=rules)
+    return Ruleset(
+        platform=platform,
+        rules=rules,
+        name=data.get("name", platform),
+        version=str(data.get("version", "")),
+        sha256=hashlib.sha256(text.encode("utf-8")).hexdigest(),
+    )

audit_report/rulesets/aws.yaml +5

 # (aws_audit_<profile>_<date>/). Each rule names a CSV table, a check, and the
 # controls the signal is offered as evidence for. A "fail" means a setting is in
 # a state that does NOT support the control — an auditor still owns the verdict.
+#
+# Provenance and control-mapping rationale: see MAPPING.md. Bump `version` on any
+# change to a rule's controls, checks, or thresholds so reports stay traceable.
+name: AWS ITGC ruleset
+version: "2026.08.0"
 platform: aws
 rules:

audit_report/rulesets/github.yaml +5

 # Evaluated against an audit-tools GitHub evidence package
 # (github_audit_<org>_<date>/). Complements gh-attest: same spirit of mapping
 # GitHub signals to controls, applied offline to a captured CSV package.
+#
+# Provenance and control-mapping rationale: see MAPPING.md. Bump `version` on any
+# change to a rule's controls, checks, or thresholds so reports stay traceable.
+name: GitHub ITGC ruleset
+version: "2026.08.0"
 platform: github
 rules:

audit_report/rulesets/gitlab.yaml +5

 #   * audit-tools omits a CSV entirely when a collector returns no rows, so an
 #     absent table reports as "not applicable", not "pass". A rule can only
 #     speak to data that was actually collected.
+#
+# Provenance and control-mapping rationale: see MAPPING.md. Bump `version` on any
+# change to a rule's controls, checks, or thresholds so reports stay traceable.
+name: GitLab ITGC ruleset
+version: "2026.08.0"
 platform: gitlab
 rules:

tests/test_reporters.py +20 −3

 import pytest
-from audit_report import reporters
+from audit_report import __version__, reporters
 from audit_report.cli import main
 from audit_report.engine import evaluate
 from audit_report.loader import load_package
 def _report(pkg_name="aws_audit_acme_2026-01-01", ruleset="aws.yaml"):
     pkg = load_package(FIXTURES / pkg_name)
-    findings = evaluate(pkg, load_ruleset(RULESETS / ruleset))
+    rs = load_ruleset(RULESETS / ruleset)
-    return reporters.build_report(pkg, findings)
+    findings = evaluate(pkg, rs)
+    return reporters.build_report(pkg, findings, rs)
 def test_markdown_render_contains_sections():
     assert ids["aws.iam.console-mfa"] == "fail"
+def test_json_stamps_tool_and_ruleset_provenance():
+    data = json.loads(reporters.render(_report(), "json"))
+    assert data["tool"] == {"name": "audit-report", "version": __version__}
+    rs = data["ruleset"]
+    assert rs["name"] == "AWS ITGC ruleset"
+    assert rs["platform"] == "aws"
+    assert rs["version"] == "2026.08.0"
+    assert len(rs["sha256"]) == 64  # full SHA-256 hex digest of the ruleset file
+def test_markdown_shows_ruleset_provenance():
+    md = reporters.render(_report(), "md")
+    assert "**Tool:** audit-report" in md
+    assert "sha256:" in md
 def test_html_escapes_evidence(tmp_path):
     pkg_dir = tmp_path / "aws_audit_x_2026-01-01"
     pkg_dir.mkdir()

Commit f3c12544e8

Commit `f3c12544e8`