audit-labs/audit-report

audit-report

Turns an audit-tools evidence package into a control-mapped, auditor-ready report — Markdown, self-contained HTML, or JSON — driven by declarative rulesets.

audit-tools collects raw CSVs (IAM users, branch protections, security groups…). audit-report reads that package, applies pass/fail rules, maps each result to SOC 2, ISO 27001, and NIST SP 800-53 controls, and produces a report you can hand to an auditor or gate a pipeline on.

Like gh-attest, this tool produces evidence, not a compliance verdict. A failing row means a setting is in a state that does not support a control; the final judgment belongs to the organization and its auditor.

Install

pip install audit-report

To hack on it from a clone instead, see Development.

Usage

Point it at a package directory produced by audit-tools:

# Markdown report to stdout (platform + ruleset auto-detected from the dir name)
audit-report ./output/aws_audit_default_2026-07-29

# All three formats into ./report/
audit-report ./output/github_audit_acme_2026-07-29 --format md,html,json --out report/

# Gate CI: exit non-zero if any high-severity check fails
audit-report ./output/aws_audit_prod_2026-07-29 --fail-on high --out report/

Diff mode — compare two packages

Pass --baseline to report how a package drifted from an earlier one. Both are evaluated with the same ruleset; the report classifies each rule as regressed, fixed, drifted (an ongoing failure whose evidence rows changed), changed, or unchanged — and shows exactly which evidence rows appeared or disappeared.

# How did prod change between two audit runs?
audit-report ./output/aws_audit_prod_2026-07-29 \
  --baseline ./output/aws_audit_prod_2026-06-29 \
  --format md,html --out drift/

# Fail CI if this change regressed any high-severity control
audit-report ./output/aws_audit_prod_2026-07-29 \
  --baseline ./output/aws_audit_prod_2026-06-29 --fail-on high

In diff mode --fail-on gates on regressions at or above the given severity, and output files are named diff.* instead of report.*.

Trend mode — track controls over time

Pass --trend and point at a folder of dated packages (for example audit-tools' output/). Every package in the series is evaluated with the same ruleset and laid out as a timeline — one row per rule, one column per date — so you can watch a control drift in and out of compliance.

# Heatmap of every control across all retained prod packages
audit-report ./output --trend --format html,json --out trend/

# Disambiguate when the folder holds more than one series
audit-report ./output --trend --subject prod --out trend/

The series must share one platform and subject (use --subject to pick one) and contain at least two packages. In trend mode --fail-on reflects the latest package, so it can double as a snapshot gate. Output files are named trend.*.

You can also run it without installing:

python -m audit_report ./output/aws_audit_default_2026-07-29

Options

What a report contains

• Summary — failing / passing / not-applicable counts.
• Control coverage matrix — every cited control, its framework, and a worst-wins status rolled up from the rules that reference it. One failing rule marks the control as not fully evidenced.
• Findings — failures first, then by severity, each with the reason, why it matters, remediation, and the exact evidence rows that failed.

Bundled rulesets

Writing your own rules

A ruleset is a YAML file: a platform and a list of rules. Each rule names a CSV table, a check, the controls it maps to, and human-readable text. Point at one with --ruleset.

platform: aws
rules:
  - id: aws.iam.console-mfa
    title: Console users have MFA enabled
    table: iam_users            # <table>.csv inside the package
    severity: high              # high | medium | low
    controls: [SOC2:CC6.1, ISO:A.5.17, NIST:IA-2]
    rationale: A console user without a second factor is one stolen password from access.
    remediation: Enforce MFA for all console users, or remove their console password.
    check:
      type: fail_rows_where     # every matching row is a failure
      when:
        all:
          - {column: console_password, op: is_true}
          - {column: mfa_enabled, op: is_false}

Check types

Condition language — a condition is a leaf {column, op, value}, or one of {all: [...]}, {any: [...]}, {not: ...}. Operators: equals, not_equals, is_true, is_false, in, not_in, gt, gte, lt, lte, empty, not_empty. Control codes referenced by a rule must exist in audit_report/catalog.py.

Continuous integration

Run it on a schedule or in a pipeline to keep evidence current and gate on regressions. See docs/ci.md and the ready-to-copy examples:

• examples/github-actions-audit.yml
• examples/gitlab-ci-audit.yml

The --fail-on exit code (1 = a finding/regression met the threshold, 2 = usage error) lets a workflow separate "the audit found a problem" from "the job is misconfigured".

Stability

audit-report is stable as of v1.0.0 and follows semantic versioning. The JSON report schema — findings carrying their controls and pass / fail / not_applicable status — is a committed contract that control-coverage consumes directly; it will not break without a major-version bump.

Development

pip install -e ".[dev]"
pytest        # run from the project root
ruff check .

License

GPL-3.0-or-later. See LICENSE.