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.

Overview

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.

Aims

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.

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 we attempt to add a new rule called my_rule
(note: this is the same rule we showed when learning how to write a 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
1
name: Test Custom Rules
2
3
on:
4
push:
5
branches:
6
- '**' # matches every branch
7
- '!main' # excludes main
8
9
jobs:
10
unit_test:
11
runs-on: ubuntu-latest
12
steps:
13
- uses: actions/[email protected]
14
15
- uses: actions/[email protected]
16
with:
17
node-version: 15
18
19
- name: Install snyk-iac-rules
20
run: npm i -g snyk-iac-rules
21
22
- name: Run unit tests
23
run: snyk-iac-rules test
Copied!
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 -> Branchesfirst, 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.
.github/workflows/test.yml
1
jobs:
2
contract_test:
3
runs-on: ubuntu-latest
4
steps:
5
- uses: actions/[email protected]
6
7
- uses: actions/[email protected]
8
with:
9
node-version: 15
10
11
- name: Install snyk-iac-rules
12
run: npm i -g snyk-iac-rules
13
14
- name: Build bundle
15
run: snyk-iac-rules build .
16
17
- name: Run contract with Snyk to check Infrastructure as Code files for issues
18
continue-on-error: true
19
uses: snyk/actions/[email protected]
20
env:
21
SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
22
with:
23
args: --rules=bundle.tar.gz
Copied!
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.

Publishing the custom rules

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
1
name: Publish Custom Rules
2
3
on:
4
push:
5
branches:
6
- 'main'
7
8
jobs:
9
publish:
10
runs-on: ubuntu-latest
11
steps:
12
- uses: actions/[email protected]
13
14
- uses: actions/[email protected]
15
with:
16
node-version: 15
17
18
- name: Install snyk-iac-rules
19
run: npm i -g snyk-iac-rules
20
21
- name: Build bundle
22
run: snyk-iac-rules build .
23
24
- name: Login to Docker Hub
25
uses: docker/[email protected]
26
with:
27
username: ${{ secrets.OCI_REGISTRY_USERNAME }}
28
password: ${{ secrets.OCI_REGISTRY_PASSWORD }}
29
30
- name: Publish rules
31
run: snyk-iac-rules push --registry $OCI_REGISTRY_URL bundle.tar.gz
32
env:
33
OCI_REGISTRY_URL: "${{ secrets.OCI_REGISTRY_NAME }}:v1"
Copied!
It looks similar to the previous workflow, but there are a few things to note about this one:
  • We configured it to run only on main branches, so that it runs when PRs are merged.
  • We added a step 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 make sure to configure the GitHub secrets under Settings -> Secrets.
  • We added a step to run snyk-iac-rules build followed by snyk-iac-rules push, which will publish our generated custom rules bundle to an OCI registry.

Versioning rules

If we want to release an experimental version of the custom rules without affecting all our CI/CD pipelines, we can use tagging to version our bundles.
So, we can start trialing bundle v2-beta while still using v1 in most of our services:
.github/workflows/publish.yml
1
- name: Publish experimental rules
2
run: snyk-iac-rules push --registry $OCI_REGISTRY_URL bundle.tar.gz
3
env:
4
OCI_REGISTRY_URL: "${{ secrets.OCI_REGISTRY_NAME }}:v1"
5
- name: Publish rules
6
run: snyk-iac-rules push --registry $OCI_REGISTRY_URL bundle.tar.gz
7
env:
8
OCI_REGISTRY_URL: "${{ secrets.OCI_REGISTRY_NAME }}:v2-beta"
Copied!
Make sure 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 public Group IaC Settings API.
This means configuring the GitHub Action above with another job for updating Snyk to use the configured custom rules bundle:
1
- name: Update Snyk
2
run: |
3
curl --location --request PATCH 'https://api.snyk.io/v3/groups/<group id>/settings/iac/?version=2021-11-03~beta' \
4
--header 'Content-Type: application/vnd.api+json' \
5
--header 'Authorization: token ${{ secrets.SNYK_TOKEN }}' \
6
--data-raw '{
7
"data": {
8
"type": "iac_settings",
9
"attributes": {
10
"custom_rules": {
11
"oci_registry_url": "registry-1.${{ secrets.OCI_REGISTRY_NAME }}",
12
"oci_registry_tag": "v1",
13
"is_enabled": true
14
}
15
}
16
}
17
}'
Copied!
This API call will update the chosen Snyk group and all the organizations underneath it to use the configured custom rules bundle.
For now, if we want to configure an organization to use a different bundle, such as the v2-beta one, we are limited to using the Snyk Settings page. There we can either configure a new bundle or disable custom rules so that we can use environment variables in our CI/CD pipeline to run the custom rules.
In a different repository, all you have to do is authenticate with one of the organizations underneath this group and add the Snyk IaC GitHub Action to a workflow:
1
name: Snyk Infrastructure as Code Custom Rules
2
3
on:
4
push:
5
6
jobs:
7
snyk-iac-security:
8
runs-on: ubuntu-latest
9
steps:
10
- uses: actions/[email protected]
11
12
- name: Run Snyk to check Infrastructure as Code files for issues
13
continue-on-error: false
14
uses: snyk/actions/[email protected]
15
env:
16
SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
Copied!
The result is that the GitHub action will fail until the generated misconfigurations have been resolved:
1
Testing example.tf...
2
3
4
Infrastructure as code issues:
5
✗ IAM Role missing one of the required tags: owner, description or type [Medium Severity] [CUSTOM-RULE-8]
6
introduced by input > resource > aws_iam_role[new_role] > tags
7
8
✗ Vendor or Service must have either owneralternate or ticketgroup or both tags. [Medium Severity] [CUSTOM-RULE-9]
9
introduced by input > resource > aws_iam_role[new_role] > tags
Copied!

Configuring the custom rules

Additionally, if using an API or the Snyk Settings page seem too restrictive, we also provide a way to configure the custom rules by using the environment variables.
You can use the Snyk IaC GitHub Action with the SNYK_CFG_OCI_REGISTRY_URL, SNYK_CFG_OCI_REGISTRY_USERNAME, and SNYK_CFG_OCI_REGISTRY_PASSWORD environment variables to scan your configuration files for any custom rules which may have been breached.
The GitHub Action reads these environment variables and pulls down the bundle pushed in the previous step to the configured OCI registry. The GitHub action will look similar to this:
1
name: Snyk Infrastructure as Code Custom Rules
2
3
on:
4
push:
5
6
jobs:
7
snyk-iac-security:
8
runs-on: ubuntu-latest
9
steps:
10
- uses: actions/[email protected]
11
12
- name: Run Snyk to check Infrastructure as Code files for issues
13
continue-on-error: false
14
uses: snyk/actions/[email protected]
15
env:
16
SNYK_TOKEN: ${{ secrets.SNYK_TOKEN }}
17
SNYK_CFG_OCI_REGISTRY_URL: ${{ secrets.OCI_REGISTRY_URL }}
18
SNYK_CFG_OCI_REGISTRY_USERNAME: ${{ secrets.OCI_REGISTRY_USERNAME }}
19
SNYK_CFG_OCI_REGISTRY_PASSWORD: ${{ secrets.OCI_REGISTRY_PASSWORD }}
Copied!
Last modified 5d ago