Integrating IaC custom rules within a pipeline
The ideal scenario for managing, distributing, and enforcing your custom rules is to use a CI/CD like GitHub Actions.
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.
We use the snyk/custom-rules-example repository for the example; this repo contains all the custom rules written while getting started with the SDK.
We want to configure our pipeline to:
- Verify that new rules or changes to the existing rules don't break existing functionality.
- Publish the rules in
main
to an OCI registry. - Enforce the usage of custom rules in other pipelines.
- (Optionally) Configure the custom rules using environment variables.
An example of a PR check can be seen in https://github.com/snyk/custom-rules-example/pull/5 where we attempt to add a new rule called
my_rule
To verify that this rule works as expected, we have implemented unit tests. To run the unit tests as part of PR checks, we previously configured a GitHub Action under
.github/workflows
called test.yml
:.github/workflows/test.yml
name: Test Custom Rules
on:
push:
branches:
- '**' # matches every branch
- '!main' # excludes main
jobs:
unit_test:
runs-on: ubuntu-latest
steps:
- uses: actions/[email protected]
- uses: actions/[email protected]
with:
node-version: 15
- name: Install snyk-iac-rules
run: npm i -g snyk-iac-rules
- name: Run unit tests
run: snyk-iac-rules test
A few things to note about this workflow:
- We configured it to run on all non-
main
branches, so that it runs when PRs are open. - We added steps to setup a Node.js environment, so that we can then install the
snyk-iac-rules
SDK using npm. - We added a step to run
snyk-iac-rules test
, which will cause the PR check to fail if any of the tests fail.
You need to configure your
main
branch under Settings
-> Branches
first, so that no one can push directly to main
.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..github/workflows/test.yml
jobs:
contract_test:
runs-on: ubuntu-latest
steps:
- uses: actions/[email protected]
- uses: actions/[email protected]
with:
node-version: 15
- name: Install snyk-iac-rules
run: npm i -g snyk-iac-rules
- name: Build bundle
run: snyk-iac-rules build .
- name: Run contract with Snyk to check Infrastructure as Code files for issues
continue-on-error: true
uses: snyk/actions/[email protected]
env:
SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
with:
args: --rules=bundle.tar.gz
You can also expand these tests to use Shellspec and verify that the desired vulnerabilities get triggered, but we recommend using the unit tests for this.
Once a PR passes its checks from the previous section and gets merged into the
main
branch, you can publish our rules to an OCI registry. This allows you to configure a separate pipeline, to download the custom rules bundle from this location, and run the custom rules in order to catch misconfigurations.For this, we will add another workflow under
.github/workflows
called publish.yml
:.github/workflows/publish.yml
name: Publish Custom Rules
on:
push:
branches:
- 'main'
jobs:
publish:
runs-on: ubuntu-latest
steps:
- uses: actions/[email protected]