# styrainc/opa-aws-cloudformation-hook architecture

> Architecture diagram of the GitHub repository styrainc/opa-aws-cloudformation-hook, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/styrainc/opa-aws-cloudformation-hook
- Repository: https://github.com/styrainc/opa-aws-cloudformation-hook

## Overview

##### Project type and purpose
- This is an integration project (“OPA AWS CloudFormation Hook”) that glues AWS CloudFormation with the Open Policy Agent (OPA).
- Purpose: enforce Rego policies on CFN stacks by installing a CloudFormation Hook that sends resource data to an OPA server and blocks stack operations if there are violations.

##### File structure
- Top-level directories:
- .github / ci / deregister-hook.sh: CI pipelines and scripts for build, test, resource-type checks.
- examples:
– policy: Rego policy modules plus tests.
– templates: CFN YAML templates to exercise policies.
- hooks:
– hook-role.yaml & template.yml: CloudFormation Hook configuration.
– src/styra_opa_hook: Python package implementing the hook (handlers.py, models.py).
– requirements.txt & configuration JSONs.
- test: integration.sh and validate.py for local policy testing.
- Patterns:
- Single “service” (the CFN Hook) built in Python, deployed via CloudFormation.
- External dependency: OPA server (REST API).

##### README for additional insights
- README describes hook lifecycle: on CFN stack create/update/delete, AWS invokes the Hook, which POSTs resource properties to OPA, gets a decision, then either allows or rejects the change, logging violations.

##### Elements
- Hook runtime (Python handler)
- OPA server
- Policy store (Rego files)
- CloudWatch logs
- CI/CD pipelines
- CFN → Hook
- Hook → OPA
- OPA → Hook
- Hook → CFN & CloudWatch
- GitHub Actions → test & build → Hook code + policies
- External service (orange for OPA)
- Pipeline (gray)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "AWS Managed"
        CFN["AWS CloudFormation Service"]:::aws
        CW["AWS CloudWatch Logs"]:::aws
    end

    subgraph "Customer Hook"
        Hook["CloudFormation Hook (Python Handler)"]:::customer
        Models["Hook Data Models"]:::customer
        Config["Hook Deployment Configuration"]:::customer
        Req["Hook Package Definition and Dependencies"]:::customer
    end

    subgraph "OPA Policy Decision Point"
        OPA["OPA Server"]:::external
        Policies["Rego Policies"]:::customer
    end

    subgraph "CI/CD Pipeline"
        GH["GitHub Actions"]:::pipeline
        Scripts["CI/CD Scripts"]:::pipeline
        Tests["Test Harness"]:::pipeline
        Docs["Documentation & Architecture Diagrams"]:::docs
    end

    CFN -->|"Invoke Hook"| Hook
    Hook -->|"POST resource data"| OPA
    OPA -->|"Decision + Violations"| Hook
    Hook -->|"Allow/Deny Response"| CFN
    Hook -->|"Log Violations"| CW

    GH -->|"Run Resource Type Checks"| Scripts
    GH -->|"Run OPA Tests"| Tests
    Scripts -->|"Push Code & Policies"| Hook
    Tests -->|"Validate against Templates"| Policies
    Tests -->|"Use CFN Templates"| Templates["CFN Example Templates"]:::customer

    click Hook "https://github.com/styrainc/opa-aws-cloudformation-hook/blob/main/hooks/src/styra_opa_hook/handlers.py"
    click Models "https://github.com/styrainc/opa-aws-cloudformation-hook/blob/main/hooks/src/styra_opa_hook/models.py"
    click Config "https://github.com/styrainc/opa-aws-cloudformation-hook/blob/main/hooks/template.yml"
    click Config "https://github.com/styrainc/opa-aws-cloudformation-hook/blob/main/hooks/hook-role.yaml"
    click Config "https://github.com/styrainc/opa-aws-cloudformation-hook/blob/main/hooks/styra-opa-hook-configuration.json"
    click Config "https://github.com/styrainc/opa-aws-cloudformation-hook/blob/main/hooks/styra-opa-hook.json"
    click Req "https://github.com/styrainc/opa-aws-cloudformation-hook/blob/main/hooks/requirements.txt"
    click Req "https://github.com/styrainc/opa-aws-cloudformation-hook/blob/main/hooks/.rpdk-config"
    click Policies "https://github.com/styrainc/opa-aws-cloudformation-hook/tree/main/examples/policy"
    click Templates "https://github.com/styrainc/opa-aws-cloudformation-hook/tree/main/examples/templates"
    click GH "https://github.com/styrainc/opa-aws-cloudformation-hook/blob/main/.github/workflows/check-resource-types.yaml"
    click GH "https://github.com/styrainc/opa-aws-cloudformation-hook/blob/main/.github/workflows/generate-assets.yaml"
    click GH "https://github.com/styrainc/opa-aws-cloudformation-hook/blob/main/.github/workflows/opa-tests.yaml"
    click Scripts "https://github.com/styrainc/opa-aws-cloudformation-hook/blob/main/ci/check-resource-types.sh"
    click Scripts "https://github.com/styrainc/opa-aws-cloudformation-hook/blob/main/ci/resourcetypes.rego"
    click Scripts "https://github.com/styrainc/opa-aws-cloudformation-hook/blob/main/deregister-hook.sh"
    click Tests "https://github.com/styrainc/opa-aws-cloudformation-hook/blob/main/test/validate.py"
    click Tests "https://github.com/styrainc/opa-aws-cloudformation-hook/blob/main/test/integration.sh"
    click Tests "https://github.com/styrainc/opa-aws-cloudformation-hook/blob/main/test/requirements.txt"
    click Docs "https://github.com/styrainc/opa-aws-cloudformation-hook/tree/main/docs/assets"

    classDef aws fill:#e6f7ff,stroke:#1f77b4,color:#1f77b4;
    classDef customer fill:#e6ffe6,stroke:#2ca02c,color:#2ca02c;
    classDef external fill:#fff0b3,stroke:#ff7f0e,color:#ff7f0e;
    classDef pipeline fill:#f2f2f2,stroke:#7f7f7f,color:#7f7f7f;
    classDef docs fill:#f9e6ff,stroke:#9467bd,color:#9467bd;
```
