{"id":31581042,"url":"https://github.com/fluohq/compliance-as-code","last_synced_at":"2025-10-05T21:52:27.459Z","repository":{"id":317492144,"uuid":"1067566639","full_name":"fluohq/compliance-as-code","owner":"fluohq","description":"Generate compliance code from Nix. Evidence as Telemetry.","archived":false,"fork":false,"pushed_at":"2025-10-01T07:47:50.000Z","size":163,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-01T09:09:25.360Z","etag":null,"topics":["code-generation","compliance","gdpr","hipaa","nix","observability","opentelemetry","security","soc2"],"latest_commit_sha":null,"homepage":"","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fluohq.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-01T03:42:01.000Z","updated_at":"2025-10-01T07:43:19.000Z","dependencies_parsed_at":"2025-10-01T09:24:45.193Z","dependency_job_id":null,"html_url":"https://github.com/fluohq/compliance-as-code","commit_stats":null,"previous_names":["fluohq/compliance-as-code"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fluohq/compliance-as-code","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluohq%2Fcompliance-as-code","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluohq%2Fcompliance-as-code/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluohq%2Fcompliance-as-code/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluohq%2Fcompliance-as-code/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fluohq","download_url":"https://codeload.github.com/fluohq/compliance-as-code/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fluohq%2Fcompliance-as-code/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278526242,"owners_count":26001325,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code-generation","compliance","gdpr","hipaa","nix","observability","opentelemetry","security","soc2"],"created_at":"2025-10-05T21:52:26.224Z","updated_at":"2025-10-05T21:52:27.451Z","avatar_url":"https://github.com/fluohq.png","language":"Nix","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Compliance as Code\n\n\u003e **A collection of patterns for treating compliance evidence as observable telemetry.**\n\n## The Problem\n\nYou spent 40 hours preparing evidence for your audit. You created Word documents, screenshots, and manual logs to prove your system does what your code already does.\n\nThen the auditor trusts the Word doc more than your code.\n\n**This is backwards.**\n\n## The Pattern\n\nWhat if compliance evidence was just... telemetry? What if every method that implements a control automatically emits an immutable span proving it happened?\n\n```java\n@GDPREvidence(\n    control = GDPRControls.Art_17,  // Right to Erasure\n    evidenceType = EvidenceType.AUDIT_TRAIL\n)\npublic DeletionResult deleteUserData(String userId) {\n    int deleted = database.deleteAllUserData(userId);\n    return DeletionResult.success(deleted);\n}\n\n// OpenTelemetry span automatically emitted:\n// ✓ timestamp, traceId, framework, control\n// ✓ input.userId, output.deletedRecords, duration\n// ✓ sideEffects: [\"database.deleteAllUserData\"]\n// → Immutable proof that deletion occurred\n```\n\nQuery compliance evidence in Grafana like any other telemetry:\n\n```promql\n{compliance.framework=\"gdpr\", compliance.control=\"Art.17\"}\n```\n\n## Core Concepts\n\nThis repository demonstrates several key patterns:\n\n1. **Evidence as Telemetry**: Compliance evidence should be OpenTelemetry spans, not Word docs\n2. **Code Generation**: Define controls once, generate code for multiple languages\n3. **Observable Controls**: Every control implementation emits immutable proof\n4. **Declarative Compliance**: Annotate code with what it does, evidence follows automatically\n5. **Query-First Design**: Evidence should be queryable like logs and metrics\n\n### Evidence-Based Architecture\n\nMethods produce **immutable evidence** as OpenTelemetry spans:\n\n- **Timestamp**: When the control was executed\n- **Trace ID**: Full distributed trace context\n- **Control**: Which compliance requirement was satisfied\n- **Inputs/Outputs**: What data was processed (with automatic redaction)\n- **Duration**: How long it took\n- **Result**: Success or failure\n- **Side Effects**: What external systems were touched\n\n### Language Patterns\n\nThe same evidence pattern works across languages:\n\n| Language | Pattern | Example |\n|----------|---------|---------|\n| **Java** | Annotations | `@GDPREvidence(control = GDPRControls.Art_51f)` |\n| **TypeScript** | Decorators | `@GDPREvidence({ control: GDPRControls.Art_51f })` |\n| **Python** | Decorators | `@gdpr_evidence(control='Art.5(1)(f)')` |\n| **Go** | Manual Spans | `span := gdpr.BeginSpan(gdpr.Art_51f)` |\n\n## What's Included\n\nThis repository contains:\n\n1. **Design Patterns**: Examples of treating compliance as observable telemetry\n2. **Control Definitions**: GDPR, SOC 2, HIPAA, FedRAMP, ISO 27001, PCI-DSS (95 controls total)\n3. **Code Generators**: Nix-based generators for Java, TypeScript, Python, Go\n4. **Working Examples**: 15+ examples across backend, data, and infrastructure\n\n**This is a reference implementation**, not a production framework. Use these patterns in your own systems.\n\n## Examples\n\n### Backend Frameworks\n\n- **[Go HTTP Server](./examples/backend/go-http/)** - Context-based evidence spans\n- **[Java Spring Boot](./examples/backend/java-spring-boot/)** - Annotation-based evidence\n- **[Java Camel](./examples/backend/java-camel/)** - Route-based evidence emission\n- **[Python FastAPI](./examples/backend/python-fastapi/)** - Async decorator pattern\n- **[Python Django](./examples/backend/python-django/)** - View-based evidence\n- **[TypeScript NestJS](./examples/backend/typescript-nestjs/)** - DI integration\n- **[TypeScript Express](./examples/backend/typescript-express/)** - Middleware pattern\n- **[TypeScript tRPC](./examples/backend/typescript-trpc/)** - Type-safe RPC evidence\n\n### Data Tools\n\n- **[AWS SDK Wrapper](./examples/data/aws-sdk-wrapper/)** - S3/DynamoDB with compliance evidence\n- **[Snowflake Wrapper](./examples/data/snowflake-wrapper/)** - Data warehouse query evidence (placeholder)\n- **[Airtable Wrapper](./examples/data/airtable-wrapper/)** - Low-code tool compliance (placeholder)\n\n### Infrastructure\n\n- **[Kubernetes Admission Controller](./examples/infrastructure/kubernetes-admission/)** - Policy enforcement with evidence\n- **[Terraform Provider](./examples/infrastructure/terraform-provider/)** - IaC compliance (placeholder)\n- **[Pulumi Wrapper](./examples/infrastructure/pulumi-wrapper/)** - Infrastructure evidence emission\n\nSee **[examples/](./examples/)** for complete code.\n\n## Using These Patterns\n\n### 1. Study the Examples\n\nStart with the language you use:\n\n```bash\n# View Go example\ncat examples/backend/go-http/main.go\n\n# View Java example\ncat examples/backend/java-spring-boot/src/main/java/com/example/compliance/UserController.java\n```\n\n### 2. Adapt to Your Stack\n\nThese are **patterns**, not a library. Copy the concepts:\n\n```java\n// Pattern: Emit evidence before/after business logic\npublic User getUser(String userId) {\n    Span span = tracer.spanBuilder(\"get_user\")\n        .setAttribute(\"compliance.framework\", \"gdpr\")\n        .setAttribute(\"compliance.control\", \"Art.15\")\n        .setAttribute(\"userId\", userId)\n        .startSpan();\n\n    try {\n        User user = database.findById(userId);\n        span.setAttribute(\"recordsReturned\", 1);\n        return user;\n    } finally {\n        span.end();\n    }\n}\n```\n\n### 3. Query Your Evidence\n\n```promql\n# All GDPR evidence\n{compliance.framework=\"gdpr\"}\n\n# Right to erasure operations\n{compliance.control=\"Art.17\"}\n\n# Failed compliance operations\n{compliance.result=\"failure\"}\n```\n\n## Key Design Patterns\n\n### 1. Evidence as Structured Attributes\n\nUse OpenTelemetry span attributes to make evidence queryable:\n\n```javascript\nspan.setAttribute('compliance.framework', 'gdpr');\nspan.setAttribute('compliance.control', 'Art.15');\nspan.setAttribute('compliance.operation', 'data_access');\nspan.setAttribute('input.userId', userId);\nspan.setAttribute('output.recordsReturned', records.length);\n```\n\n### 2. Control Mapping to Canonical Objectives\n\nMap controls to abstract security objectives rather than cross-framework mappings:\n\n```nix\n# SOC 2 CC6.1, HIPAA 164.312(a)(1), GDPR Art.32 all map to:\ncanonicalObjectives = [\"IAM.AUTHZ.ACCESS.LEAST_PRIVILEGE\"];\n```\n\nThis enables querying across frameworks by security objective.\n\n### 3. Language-Native Patterns\n\nUse each language's idiomatic patterns:\n- **Java**: Annotations with AspectJ\n- **TypeScript**: Decorators with reflect-metadata\n- **Python**: Function decorators\n- **Go**: Explicit span creation (no magic)\n\n### 4. Reproducible Builds\n\nUse Nix flakes for deterministic code generation:\n- Same control definitions always produce same code\n- Cryptographic verification of all dependencies\n- Complete audit trail from definition to generated code\n\n## Why This Approach?\n\n### For Developers\n\n- **No manual evidence**: Code proves what it does automatically\n- **Same tools**: Query compliance like you query logs\n- **Type-safe**: Controls are compile-time constants, not strings\n- **Framework-agnostic**: Works with Spring, FastAPI, Express, etc.\n\n### For Auditors\n\n- **Timestamped evidence**: OpenTelemetry spans with precise timestamps and context\n- **Real-time**: No waiting for screenshots or manual logs\n- **Complete context**: Full distributed traces, not isolated events\n- **Queryable**: Filter by framework, control, timerange, user, etc.\n\n### For Security Teams\n\n- **Observable controls**: See which controls are actually running\n- **Continuous monitoring**: Alert on missing or failed evidence\n- **Cross-framework**: Map GDPR to SOC 2 to HIPAA via canonical objectives\n- **Traceability**: Link evidence spans back to code that emitted them\n\n## Philosophy\n\nThese patterns are based on three principles:\n\n1. **Compliance is a byproduct of good software**, not a separate artifact\n2. **Evidence should be as observable as logs, metrics, and traces**\n3. **Controls should be declared once, proven continuously**\n\nIf your code implements a control, it should automatically prove it did so. This is compliance as **observable infrastructure**.\n\n## Contributing\n\nThis is an open collection of patterns. Contributions welcome:\n\n- New language examples\n- Additional compliance frameworks\n- Better code generation techniques\n- Real-world usage patterns\n\nSee **[CONTRIBUTING.md](./CONTRIBUTING.md)** for guidelines.\n\n## Documentation\n\n- **[Examples Directory](./examples/)** - Working code across 15+ frameworks\n- **[Developer Guide](./frameworks/DEVELOPER_GUIDE.md)** - Implementation patterns\n- **[Control Definitions](./frameworks/)** - GDPR, SOC 2, HIPAA, etc.\n- **[Code Generators](./frameworks/generators/)** - Nix-based generation\n\n## License\n\nApache 2.0 - Use these patterns freely in commercial projects.\n\n## Inspiration\n\nThese patterns build on:\n- **[Nix](https://nixos.org/)** - Reproducible builds and deterministic generation\n- **[OpenTelemetry](https://opentelemetry.io/)** - Observable telemetry as evidence\n- Years of manual compliance work that could have been automated\n\n---\n\n**Compliance is observable infrastructure. Evidence is just telemetry.**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluohq%2Fcompliance-as-code","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffluohq%2Fcompliance-as-code","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffluohq%2Fcompliance-as-code/lists"}