How styrainc/opa-aws-cloudformation-hook works
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)