Compliance Reporting

[!WARNING] Status: Planned. Compliance reporting is part of the governance layer currently under development. The design below describes the planned behavior.

ChooChoo will automate the generation of compliance artifacts for auditors. Reports will be built from the Audit Trail, compliance tags on your Contracts, and the Decision Traces captured by the platform.

Supported Frameworks

ChooChoo's tagging system (complianceTags) maps directly to major regulatory frameworks. The tags applied to fields in your Data Contracts determine which frameworks are in scope for a given report. Each Agent's System Card also declares the compliance.frameworks it aligns with, allowing reports to be filtered by agent and framework.

See the Standards Reference for the full list of supported open standards, and Compliance Tags for the taxonomy of tags that map to frameworks.

Generating Reports

You can generate a PDF or JSON report for a specific audit period using the choochoo report command:

choochoo report generate \
  --framework gdpr \
  --start-date 2025-01-01 \
  --end-date 2025-12-31 \
  --format pdf

The --framework flag filters the report to include only artifacts and decisions relevant to the specified regulatory framework. You can generate reports for multiple frameworks by running the command multiple times.

Report Content

A standard report includes:

1. Executive Summary: High-level posture and risk summary. Aggregates risk scores across all changes in the audit period.
2. Inventory: List of all Data Products and Contracts containing in-scope data, with their lifecycle states.
3. Access Log: List of all agents and humans who accessed or modified sensitive schemas. Sourced from the Audit Trail.
4. Approval Evidence: Cryptographic proof of human approval for all high-risk changes. Includes the full Decision Trace chain linking actor → artifact → policy → reasoning → outcome.

Audit Trail Integration

Reports are generated directly from the Audit Trail, which serves as the "black box" flight recorder for your software factory. The audit log's append-only, cryptographically signed nature (see Security Considerations) ensures that report data cannot be tampered with.

The default audit retention period is 7 years (2555 days), configurable via the governance.auditRetentionDays setting in .choochoorc. This default satisfies SOX and HIPAA retention requirements.

Viewing Reports in The Station

The Station provides a GUI for generating and viewing compliance reports. GRC teams can:

• Filter reports by framework, date range, and risk level
• Drill down into individual Decision Traces for any flagged change
• Export reports as PDF for external auditors
• Schedule recurring report generation

Access to compliance reports is controlled via RBAC — the auditor role provides read-only access to the Audit Trail and Compliance Reports.

Related