Compliance Reporting

Use compliance reporting to convert captured decision traces into structured framework-aligned evidence artifacts.

Overview

This feature evaluates controls across supported frameworks using decision snapshots and workflow activity. Engineers can generate repeatable, auditable reports for governance reviews and operational compliance checks.

What Engineers Use It For

• Generate framework-aligned reports from captured decision activity
• Convert telemetry into review-ready evidence artifacts
• Track control pass/fail trends over defined time windows
• Export deterministic JSON/Markdown outputs for downstream systems

Features

• Multi-Framework Support - SOC2, HIPAA, and GDPR report generation
• Automated Control Evaluation - framework-specific control checks
• Risk Assessment - overall compliance status and scoring
• Export Options - Markdown and JSON output formats
• Time-Range Filtering - analyze compliance over specific periods

Quick Start

from briefcase_ai.compliance.reports import SOC2ReportGenerator
from datetime import datetime, timedelta

# Create a report generator
generator = SOC2ReportGenerator()

# Generate a report
report = generator.evaluate(
    engagement_id="regulated_workflow",
    workstream_id="decision_review_team",
    start_date=datetime.now() - timedelta(days=90),
    end_date=datetime.now()
)

# Check overall compliance
print(f"Status: {report.overall_status}")
print(f"Score: {report.overall_score}")
print(f"Controls Passed: {report.controls_passed}/{report.total_controls_evaluated}")

# Export to markdown
markdown = report.to_markdown()
with open("soc2_report.md", "w") as f:
    f.write(markdown)

# Export to JSON
json_data = report.to_json()

Report Generators

SOC2ReportGenerator

Evaluates Trust Service Criteria controls:

from briefcase_ai.compliance.reports import SOC2ReportGenerator
from datetime import datetime

generator = SOC2ReportGenerator()
report = generator.evaluate(
    engagement_id="regulated_workflow",
    workstream_id="decision_review_team",
    start_date=datetime(2024, 1, 1),
    end_date=datetime(2024, 3, 31)
)

Controls Evaluated:

• CC6.1 - Access Controls (user authentication and authorization)
• CC7.2 - Monitoring (security event detection and response)
• CC8.1 - Change Management (controlled code and configuration changes)
• CC9.1 - Logical Access (system access controls)

HIPAAReportGenerator

Evaluates HIPAA Security Rule requirements:

from briefcase_ai.compliance.reports import HIPAAReportGenerator
from datetime import datetime

generator = HIPAAReportGenerator()
report = generator.evaluate(
    engagement_id="regulated_workflow",
    workstream_id="decision_review_team",
    start_date=datetime(2024, 1, 1),
    end_date=datetime(2024, 3, 31)
)

GDPRReportGenerator

Evaluates GDPR article compliance:

from briefcase_ai.compliance.reports import GDPRReportGenerator
from datetime import datetime

generator = GDPRReportGenerator()
report = generator.evaluate(
    engagement_id="regulated_workflow",
    workstream_id="decision_review_team",
    start_date=datetime(2024, 1, 1),
    end_date=datetime(2024, 3, 31)
)

ComplianceReportGenerator (Base Class)

Abstract base class for all report generators. Subclass it to add custom framework support:

from briefcase_ai.compliance.reports.base import ComplianceReportGenerator

class CustomReportGenerator(ComplianceReportGenerator):
    def evaluate(self, engagement_id, workstream_id, start_date, end_date):
        # Custom evaluation logic
        ...

Constructor signature: ComplianceReportGenerator(briefcase_client=None)

Report Properties

All compliance reports include the following properties:

# Status and Scoring
report.overall_status          # ComplianceStatus enum
report.overall_score           # Float 0.0-1.0
report.controls_passed         # Integer count
report.total_controls_evaluated # Integer count

# Details
report.engagement_id           # String
report.workstream_id           # String
report.evaluation_period       # (start_date, end_date) tuple
report.framework               # "SOC2", "HIPAA", "GDPR", etc.

# Control Results
report.control_results         # List[ControlResult]
report.failed_controls         # List[ControlResult]
report.partial_controls        # List[ControlResult]

ComplianceStatus Enum

class ComplianceStatus(Enum):
    COMPLIANT              # All controls passed
    NON_COMPLIANT          # One or more controls failed
    PARTIALLY_COMPLIANT    # Some controls passed, some failed
    NOT_EVALUATED          # No data available for evaluation

Export Formats

Markdown Export

markdown = report.to_markdown()
# Generates a formatted markdown report with:
# - Executive summary
# - Control assessment table
# - Detailed findings per control
# - Recommendations

JSON Export

json_data = report.to_json()
# Returns a serializable dictionary with all report data:
{
  "framework": "SOC2",
  "overall_status": "COMPLIANT",
  "overall_score": 0.95,
  "controls_passed": 9,
  "total_controls_evaluated": 10,
  "control_results": [...]
}

Installation

Compliance reporting requires optional dependencies:

pip install "briefcase-ai[compliance]"

This installs:

• markdown>=3.4.0 - Markdown rendering
• pdfkit>=1.0.0 - PDF generation (optional)
• jinja2>=3.1.0 - Template rendering

Example Report

from briefcase_ai.compliance.reports import SOC2ReportGenerator
from datetime import datetime, timedelta

# Generate quarterly SOC2 report
generator = SOC2ReportGenerator()
report = generator.evaluate(
    engagement_id="regulated_workflow",
    workstream_id="security_team",
    start_date=datetime.now() - timedelta(days=90),
    end_date=datetime.now()
)

# Display summary
if report.overall_status.name == "COMPLIANT":
    print(f"Compliant: {report.overall_score:.1%}")
else:
    print(f"Not Compliant: {report.overall_score:.1%}")
    for control in report.failed_controls:
        print(f"  - {control.control_id}: {control.description}")

# Export
with open("Q1_SOC2_Report.md", "w") as f:
    f.write(report.to_markdown())