This repository integrates AWS CloudFormation (CFN) with OPA using AWS Cloud Formation Hooks. Use this integration if you want to enforce policies over AWS resources (e.g., EC2 instances, S3 buckets, etc.) provisioned with CloudFormation. For example, using this integration you can enforce policy across resources like:
AWS Cloud Formation Hooks were added in February 2022. The feature is still relatively new for AWS Cloud Formation. If you run into any issues please report them here.
The OPA hook works by installing an AWS CloudFormation Hook to your environment.
When creating, updating, or deleting a CloudFormation Stack, the hook is triggered to validate the configuration. When used in conjunction with OPA, the hook will send the property information from each resource in a Stack to your OPA server. When this information is received, OPA will validate the request against your defined policies and send back any violations it may have found, which will stop the stack creation and log the violations to AWS CloudWatch. If no violations are reported, the resources contained in the stack are created, updated or deleted accordingly.
NOTE: Installing OPA into your AWS environment is currently out of scope for this documentation. For local development, a tool like ngrok could be used to point at an OPA running on your machine.
Want to try out this integration yourself? See the AWS Cloud Formation Hooks tutorial in the OPA documentation.
Provided in this repository, you'll find the code for the hook you'll deploy in your AWS account to enable OPA policy
enforcement for your CloudFormation resources under the hooks directory. See the
OPA tutorial on the topic for instructions on
how to quickly get started, or the
development guide
in AWS the documentation if you'd like to learn more about how it works.
To give you an idea about what policy for AWS CloudFormation Hooks might look like, this repository provides a number of example resources and policies:
- The
examples/templatesdirectory contains example templates used for testing - The
examples/policydirectory contains example policies
In order to quickly iterate on changes in your Rego policies, you may use the validate.py tool provided under the
test directory. The tool allows you to test your policies against provided CloudFormation template files, without
actually submitting them to a hook installed in your environment. With an OPA server started with your policy
files loaded (e.g. opa run --server --watch examples/policy), you may use the tool like:
test/validate.py my-cloudformation-template.yamlThe tool will extract all resources found in the template and submit them to OPA one by one, in the same manner the hook operates once installed. Should any violation be encountered, the tool will print them to the console.
Deregistering a hook requires removal of not just the hook type, but also any versions of the hook deployed. In order
to help with that, you may use the deregister-hook.sh script provided in this repo, with the ARN of the hook provided
as the only argument:
./deregister-hook.sh <ARN of your hook here>
For questions, discussions and announcements related to Styra products, services and open source projects, please join the Styra community on Slack!