Skip to content

Compliance-as-Code Basics

Home › Tutorials › Advanced Practices › Compliance As Code Basics

Status: Placeholder - Content coming soon

Prerequisites: Your First Specification, understanding of compliance requirements

Planned Content

This tutorial teaches you how to implement compliance automation by tagging specifications with control references, generating risk assessments, and producing audit evidence.

What You'll Learn

  • Tag specifications with @control: references to OSCAL catalogs
  • Map requirements to compliance frameworks (21 CFR Part 11, GAMP 5, etc.)
  • Generate risk assessments: r2r create risk-assess
  • Validate control tags: r2r validate control-tags
  • Generate audit evidence from CI/CD pipeline
  • Understand OSCAL (Open Security Controls Assessment Language)

Tutorial Structure

  1. Understanding compliance-as-code
  2. Traditional compliance: manual documentation, periodic audits
  3. Compliance-as-code: automated validation, continuous evidence

  4. Benefits: shift-left, traceability, reduced audit prep time

  5. OSCAL catalogs and controls

  6. OSCAL standard overview
  7. Control catalogs (NIST 800-53, FDA controls, etc.)
  8. Control structure: ID, title, parameters, guidance

  9. Example: AC-1 (Access Control Policy)

  10. Tagging specifications

  11. Add control references to features
  12. Tag format: @control:AC-1 or @control:AC-1(a)
  13. Multiple controls: @control:AC-1 @control:AC-2

  14. Compliance tags: @cfr21part11, @gamp5

  15. Example: Access Control Specification 

    @L2 @ov @deps:go @control:AC-1 @control:AC-2 @cfr21part11
Feature: user-auth_access-control

  As a security officer
  I want to enforce access controls
  So that only authorized users can access the system

  Rule: Users must authenticate before accessing protected resources

    Scenario: Deny access without authentication
      Given I am not authenticated
      When I attempt to access protected resource "/api/data"
      Then I should receive a 401 Unauthorized response

  16. Validating control tags

  17. Check tags against catalog: r2r validate control-tags
  18. Ensure all referenced controls exist

  19. Verify tag format correctness

  20. Generating risk assessments

  21. Create assessment: r2r create risk-assess
  22. Produces OSCAL assessment-results document
  23. Maps specifications to controls

  24. Includes test evidence

  25. Understanding audit evidence

  26. Test results as evidence
  27. Build artifacts and signatures
  28. CI/CD logs and approvals

  29. Traceability matrix

  30. Compliance frameworks

  31. 21 CFR Part 11 (FDA electronic records)
  32. GAMP 5 (pharmaceutical GxP)
  33. NIST 800-53 (federal security controls)
  34. Custom organizational controls

Compliance Workflow

The tutorial demonstrates a complete compliance workflow:

# 1. Tag specifications with control references
vim specs/user-auth/access-control/specification.feature
# Add @control:AC-1 @control:AC-2

# 2. Validate control tags
r2r validate control-tags
# ✓ All control references valid

# 3. Run tests (generates evidence)
r2r test user-auth --suite acceptance

# 4. Generate risk assessment
r2r create risk-assess
# Creates .r2r/oscal/assessment-results.json

# 5. Review assessment
cat .r2r/oscal/assessment-results.json

Key Concepts Covered

  • Compliance-as-code principles
  • OSCAL standard and catalogs
  • Control tagging in specifications
  • Risk assessment generation
  • Evidence collection and traceability
  • Mapping to regulatory frameworks

OSCAL Document Types

  • Catalog: Control definitions (e.g., NIST 800-53)
  • Profile: Control baseline (selected controls)
  • Assessment Plan: How controls will be tested
  • Assessment Results: Test results and findings
  • POA&M: Plan of Action & Milestones

Benefits of Compliance-as-Code

  • Continuous validation: Every commit generates evidence
  • Automated traceability: Requirements → Controls → Tests → Evidence
  • Reduced audit prep: Evidence collected automatically
  • Version controlled: Compliance artifacts in git
  • Efficient audits: Auditors review automated evidence

Real-World Example

Scenario: FDA-regulated medical device software

  1. Tag specifications with 21 CFR Part 11 controls
  2. Run tests in CI/CD (generates evidence)
  3. Generate assessment results
  4. Export traceability matrix
  5. Submit to auditors with automated evidence
  6. Result: 80% reduction in audit prep time

Best Practices

  • Tag specifications at feature level
  • Validate control tags in pre-commit hooks
  • Generate assessments in CI/CD
  • Version control OSCAL documents
  • Review control coverage regularly
  • Keep catalogs up to date

Next Steps

After completing this tutorial, you'll understand compliance automation basics. Continue to CI/CD Integration to learn how to automate compliance validation in your pipeline.

Tutorials | How-to Guides | Explanation | Reference

You are here: Tutorials — learning-oriented guides that take you through steps to complete a project.