IaC custom rules within a pipeline
Using a CI/CD such as GitHub Actions is ideal for managing, distributing, and enforcing your custom rules.
Overview of IaC custom rules in a pipeline
This example shows how a security team can:
Store their rules in a GitHub repository
Use GitHub Actions to add different development-time steps to their pipelines
Configure a different GitHub repository to run a GitHub Action pipeline that uses the custom rules to gate changes.
Snyk uses the snyk/custom-rules-example repository for the example; this repo contains all the custom rules written while getting started with the SDK.
Aims: Configure our pipeline to:
Verify that new rules or changes to the existing rules do nor break existing functionality.
Publish the rules in
main
to an OCI registry.Enforce the use of custom rules in other pipelines.
Optionally: Configure the custom rules using environment variables.
Adding PR checks using GitHub Action
An example of a PR check can be seen in https://github.com/snyk/custom-rules-example/pull/5 where there is an attempt to add a new rule called my_rule
. This is the same rule shown for learning how to write a rule.
To verify that this rule works as expected, unit tests were implemented. To run the unit tests as part of PR checks, a GitHub Action was configured previously under .github/workflows
called test.yml
:
A few things to note about this workflow:
It was configured to run on all non-
main
branches, so that it runs when PRs are open.Steps were added steps to set up a Node.js environment to enable installing the
snyk-iac-rules
SDK using npm.A step was added to run
snyk-iac-rules test
, which will cause the PR check to fail if any of the tests fail.
You must configure your main
branch under Settings
-> Branches
first, so that no one can push directly to main
.
Snyk IaC GitHub Action
Another way to test the rules is by testing the contract with the Snyk CLI by using the Snyk IaC GitHub Action, making sure the generated bundle can be read by the CLI.
To do this, you will need a step for installing the Snyk CLI and a SNYK_TOKEN
, which can be found in your Snyk Account Settings.
You can also expand these tests to use Shellspec and verify that the desired vulnerabilities get triggered, but Snyk recommends using the unit tests for this.
Publishing the custom rules
Once a PR passes its checks from the previous section and gets merged into the main
branch, you can publish the Snyk rules to an OCI registry. This allows you to configure a separate pipeline, download the custom rules bundle from this location, and run the custom rules in order to catch misconfigurations.
For this, add another workflow under .github/workflows
called publish.yml
:
It looks like the previous workflow, but there are a few things to note about this one:
It was configured to run only on
main
branches, so that it runs when PRs are merged.A step was added to authenticate with Docker Hub, our chosen OCI registry. For a list of supported registries, read about pushing bundles. Use the docker/login-action GitHub Action to do that and be sure to configure the GitHub secrets under
Settings
->Secrets
.A step was added to run
snyk-iac-rules build
followed bysnyk-iac-rules push
, which will publish the generated custom rules bundle to an OCI registry.
Versioning rules
If you want to release an experimental version of the custom rules without affecting all our CI/CD pipelines, use tagging to version the bundles.
Start trialing bundle v2-beta
while still using v1
in most of our services:
Ensure that the OCI_REGISTRY_NAME configured in the GitHub Secrets does not already contain the tag or the protocol if you want to use this workflow.
Enforcing the custom rules
After publishing the custom rules to an OCI registry, you can configure a separate pipeline to use these rules.
One way to do this is by using the API endpoint Update the Infrastructure as Code settings for a group.
This means configuring the GitHub Action above with another job for updating Snyk to use the configured custom rules bundle:
This API call will update the chosen Snyk Group and all the Organizations underneath it to use the configured custom rules bundle.
To configure an Organization to use a different bundle, such as the v2-beta
one, use the Snyk Settings page. You can either configure a new bundle or disable custom rules to allow using environment variables in the CI/CD pipeline to run the custom rules.
In a different repository, authenticate with one of the Organizations underneath this Group and add the Snyk IaC GitHub Action to a workflow: