Back to Documentation
ComplianceUpdated 2026-04-02

Building Compliance Reports

Using Vorion's compliance report generator with OSCAL SSP integration and automated evidence collection.

Building Compliance Reports

Compliance reporting in Vorion is not a manual process of collecting screenshots and writing narratives. The platform generates evidence programmatically from the governance pipeline, proof chain, and test suite, then structures it into machine-readable formats compatible with OSCAL (Open Security Controls Assessment Language).

This guide covers the compliance evidence pipeline, OSCAL SSP generation, and how to wire reports into your audit workflow.

The Evidence Pipeline

Vorion's compliance evidence is generated from three sources:

  1. Proof Chain -- Cryptographically linked governance decisions
  2. Test Results -- Automated compliance test outcomes
  3. Runtime Metrics -- Trust scores, circuit breaker events, anomaly detections

Evidence files are collected in compliance/evidence/ with timestamped filenames:

compliance/
  evidence/
    npm-audit-2026-04-02.json        # Dependency vulnerability scan
    security-latest-2026-04-02.log   # SAST scan results
    code-reviews-2026-04-02.txt      # Review evidence
    test-results-2026-04-02.json     # Test suite output
    proof-chain-export-2026-04-02.json  # Proof chain snapshot
  governance-matrix.yaml              # Control-to-framework mapping

Automated Evidence Collection

The evidence collector runs as part of CI/CD and can be triggered manually:

# Collect all evidence for current state
pnpm compliance:collect

# This runs:
# 1. npm audit --json > compliance/evidence/npm-audit-$(date).json
# 2. Semgrep scan with JSON output
# 3. Test suite with coverage report
# 4. Proof chain export (last 30 days)
# 5. Trust score snapshots for all active agents

Each evidence file includes metadata for traceability:

{
  "collectedAt": "2026-04-02T14:30:00Z",
  "collector": "vorion-compliance-pipeline",
  "version": "3.0.0",
  "commitSha": "abc123def456",
  "pipelineRunId": "run-789",
  "evidenceType": "npm-audit",
  "data": { ... }
}

Proof Chain as Evidence

The Proof Plane is the primary evidence source for governance compliance. Every decision made by the platform is recorded as a cryptographically chained event.

Exporting Proof Records

import { ProofPlane } from '@vorionsys/proof-plane';

const proofPlane = new ProofPlane({ /* config */ });

// Export all events for a specific agent
const agentHistory = await proofPlane.getAgentHistory(agentId);

// Export events by type (e.g., all DECISION_MADE events)
const decisions = await proofPlane.queryEvents({
  type: 'DECISION_MADE',
  startTime: thirtyDaysAgo,
  endTime: now,
});

// Export a full trace for a specific request
const trace = await proofPlane.getTrace(correlationId);
// Returns: INTENT_RECEIVED -> DECISION_MADE -> EXECUTION_STARTED
//          -> EXECUTION_COMPLETED (or EXECUTION_FAILED)

Verifying Chain Integrity

Before submitting proof chain evidence, verify its integrity:

const verification = await proofPlane.verifyChainAndSignatures({
  startIndex: 0,
  endIndex: events.length - 1,
});

if (!verification.valid) {
  console.error('Broken links:', verification.brokenLinks);
  console.error('Invalid signatures:', verification.invalidSignatures);
  // Do not submit compromised evidence
}

The verification result is itself evidence -- it proves the chain was intact at verification time. Include the verification result in your compliance package.

OSCAL SSP Integration

OSCAL (Open Security Controls Assessment Language) is a NIST-developed standard for machine-readable compliance documentation. Vorion generates OSCAL System Security Plan (SSP) components that integrate with your existing OSCAL toolchain.

Governance Matrix to OSCAL

The governance matrix (compliance/governance-matrix.yaml) maps Vorion controls to multiple frameworks:

# compliance/governance-matrix.yaml
controls:
  - id: VOR-AC-001
    title: "Trust-Tier-Based Access Control"
    frameworks:
      nist-800-53: ["AC-2", "AC-3", "AC-6"]
      nist-ai-rmf: ["GV-2.1", "MP-2.1"]
      soc2: ["CC6.1"]
      iso-27001: ["A.9.2.3"]
      eu-ai-act: ["Art. 14"]
    implementation:
      component: "packages/basis/src/trust-capabilities.ts"
      status: "implemented"
      evidence:
        - type: "test"
          path: "packages/basis/tests/trust-capabilities.test.ts"
        - type: "proof-chain"
          query: "type=DECISION_MADE"

Generating OSCAL SSP Components

# Generate OSCAL SSP from governance matrix
pnpm compliance:oscal-ssp

# Output: compliance/oscal/ssp-vorion.json

The generated SSP includes:

  • System characteristics: Platform version, deployment model, boundaries
  • Control implementations: Per-control narrative + evidence links
  • Implementation status: Implemented, partial, planned, or not applicable
  • Responsible roles: Mapped to RBAC levels
{
  "system-security-plan": {
    "system-characteristics": {
      "system-name": "Vorion AI Governance Platform",
      "system-id": "vorion-basis-v3",
      "description": "Enterprise AI governance on BASIS specification"
    },
    "control-implementation": {
      "implemented-requirements": [
        {
          "control-id": "ac-6",
          "description": "Agents initialize at trust score 0 with 3 capabilities...",
          "implementation-status": "implemented",
          "responsible-roles": ["system-administrator"],
          "statements": [
            {
              "statement-id": "ac-6_smt.a",
              "description": "35 capabilities across 8 categories, unlocked progressively by trust tier"
            }
          ]
        }
      ]
    }
  }
}

OSCAL Assessment Results

After evidence collection, generate assessment results:

# Run assessment against SSP
pnpm compliance:assess

# Output: compliance/oscal/assessment-results-2026-04-02.json

Assessment results reference specific evidence artifacts:

{
  "finding": {
    "control-id": "au-9",
    "title": "Protection of Audit Information",
    "status": "satisfied",
    "observations": [
      {
        "description": "Proof chain verification passed for 47,832 events",
        "evidence": "compliance/evidence/proof-chain-export-2026-04-02.json",
        "method": "automated-test"
      }
    ]
  }
}

Report Templates

Vorion ships report templates for common audit scenarios.

SOC 2 Type II Report Package

pnpm compliance:report --template soc2-type2 --period 2026-Q1

# Generates:
# - Control narrative document (markdown)
# - Evidence inventory (CSV)
# - Proof chain export (JSON)
# - Test results summary (JSON)
# - Trust score history for all agents (JSON)

NIST AI RMF Self-Assessment

pnpm compliance:report --template nist-ai-rmf

# Generates per-function coverage reports:
# - GOVERN: 10 controls, 10 implemented
# - MAP: 7 controls, 6 implemented, 1 partial
# - MEASURE: 7 controls, 7 implemented
# - MANAGE: 7 controls, 5 implemented, 2 partial

EU AI Act Conformity Assessment

pnpm compliance:report --template eu-ai-act

# Maps trust tiers to EU risk levels
# Generates Article-by-Article evidence references
# Includes conformity assessment readiness score

Continuous Compliance Monitoring

Rather than periodic compliance checks, wire compliance monitoring into your CI/CD pipeline.

CI Integration

# .github/workflows/compliance.yml
name: Compliance Gate
on:
  push:
    branches: [main]
  schedule:
    - cron: '0 6 * * 1'  # Weekly Monday 6am

jobs:
  compliance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pnpm install
      - run: pnpm compliance:collect
      - run: pnpm compliance:assess
      - run: |
          # Fail if any HIGH/CRITICAL findings
          jq '.findings[] | select(.severity == "HIGH" or .severity == "CRITICAL")' \
            compliance/oscal/assessment-results-*.json | \
          if [ -s /dev/stdin ]; then exit 1; fi

Dashboard Integration

Compliance metrics are exposed via Prometheus:

# Trust compliance metrics
vorion_compliance_controls_total{status="implemented"} 47
vorion_compliance_controls_total{status="partial"} 5
vorion_compliance_controls_total{status="planned"} 3

# Evidence freshness
vorion_compliance_evidence_age_seconds{type="npm-audit"} 3600
vorion_compliance_evidence_age_seconds{type="proof-chain"} 86400

# Assessment results
vorion_compliance_findings_total{severity="HIGH"} 0
vorion_compliance_findings_total{severity="MEDIUM"} 2

Evidence Chain of Custody

For auditors who need to verify evidence integrity:

  1. Evidence collection is logged to the Proof Plane as a COMPLIANCE_EVIDENCE_COLLECTED event
  2. Evidence files include SHA-256 hashes in their metadata
  3. OSCAL documents are signed with the platform's Ed25519 key
  4. Audit trail links each evidence artifact to the pipeline run that generated it
// Verify evidence integrity
import { verifyEvidenceIntegrity } from '@vorionsys/compliance';

const result = await verifyEvidenceIntegrity('compliance/evidence/');
// result.files: number of evidence files checked
// result.valid: number with matching hashes
// result.tampered: number with hash mismatches
// result.missing: number referenced but not found

Recommended Actions

  1. Set up weekly evidence collection via the CI schedule trigger
  2. Generate OSCAL SSP and commit to version control for auditability
  3. Wire compliance metrics into your observability dashboard
  4. Run quarterly assessments and compare against previous quarters
  5. Export proof chain before any system migration or major upgrade

Next Steps

All Documentation