Using a remote custom rules bundle

After you generate your custom rules bundle you can distribute it to one of our supported OCI registries by following the steps in Pushing a bundle.
After successfully pushing your custom rules bundle, you can enforce its usage using:
​Snyk Settings page​
​Snyk API​
​Environment variables​
Finally, once you've enforced your custom rules via one of the options above, configure the Snyk Snyk CLI with your username and password in order to allow us to authorize a pull from your OCI registry:
1
snyk config set oci-registry-username=<org registry username>
2
snyk config set oci-registry-password=<org registry password>
Copied!
This will set the following Snyk environment variables:
SNYK_CFG_OCI_REGISTRY_USERNAME
SNYK_CFG_OCI_REGISTRY_PASSWORD
Once you have done that, run a Snyk IaC scan as normal. The CLI will pull the bundle pushed to the configured container registry in the background.
1
snyk iac test <file>
Copied!
The resulting configuration scan issues will include issues from both the default Snyk rules, and your custom rules. Also see Understanding configuration issues.
Only one method for defining the bundle's path should be defined at any given time. Make sure to either disable the custom rules settings via the Snyk Settings page or the Snyk API. Alternatively, clear any previously-stored settings using snyk config unset.
Snyk Settings page
We recommend you use the Snyk Settings page to configure custom rules settings. This method gives a simple way to update the custom rules bundle's URL and tag whenever these are modified.
Tags are helpful for versioning your custom rules bundles. Configuring your updated bundle can be easily accomplished by setting the new version tag.
You can configure these remote bundles on both the organizational level and the group level. Configuring a remote bundle for a group applies the remote bundle to all the organizations in the group.
To configure remote bundles:
In the Infrastructure as Code Settings, locate the Rules section.
Configuring remote custom rules bundles on the organizational level can be done by navigating to Settings > Infrastructure as Code.
Similarly, configuring them on the group level can be done by navigating to Settings > Infrastructure as Code.
Enable the usage of remote bundles configuration using the Enable rules toggle. Doing so will display the form as shown below:
Configure the OCI registry URL and tag for your remote bundle of custom rules, and click Save changes to save.
Your remote bundle of custom rules is now configured and will be used when testing IaC files.
Overriding a group's remote bundle configurations
By default, configuring a remote bundle for a group applies the remote bundle to all the organizations in the group. So if the group configurations are updated, these changes apply to all of its organizations.
However, an organization can still override the group's configurations and define its own bundle and tag. These will not change when the group updates its configurations.
In order to override the group's configurations, go to the organization's Rules section on the Infrastructure as Code Settings.
Initially, the section is populated with the configurations inherited from the organization's group.
Update the configurations to those customized for your organization, and click Save changes.
Now, configurations on the group level will not override these customized settings for your organization.
You can restore the inheritance of group configurations at any time by using the Reset to group default button.
Snyk API
If manually updating the settings through the Snyk Settings page is too time-consuming, another option is to use the Snyk API. It currently allows to send any variation of the custom rules settings via an API call.
For example, in order to configure the custom rules bundle at the group level, call the Group IaC Settings API endpoint by providing the following body:
1
{
2
   "data": {
3
         "type": "iac_settings",
4
         "attributes": {
5
           "custom_rules": {
6
             "oci_registry_url": "registry-1.docker.io/group-account/group-bundle-image",
7
             "oci_registry_tag": "1.3.14",
8
             "is_enabled": true
9
           }
10
       }
11
   }
12
}
Copied!
If you want to update the tag only, you can send over a simpler body:
1
{
2
   "data": {
3
         "type": "iac_settings",
4
         "attributes": {
5
           "custom_rules": {
6
             "oci_registry_tag": "1.3.14"
7
           }
8
       }
9
   }
10
}
Copied!
And if you want to disable custom rules, you can just send over the is_enabled flag:
1
{
2
   "data": {
3
         "type": "iac_settings",
4
         "attributes": {
5
           "custom_rules": {
6
             "is_enabled": false
7
           }
8
       }
9
   }
10
}
Copied!
The API will reply with the group's settings, so you can confirm the changes:
1
{
2
  "type": "iac_settings",
3
  "id": "<group id>",
4
  "attributes": {
5
    "custom_rules": {
6
      "oci_registry_url": "registry-1.docker.io/group-account/group-bundle-image",
7
      "oci_registry_tag": "1.3.14",
8
      "is_enabled": true
9
    },
10
   "updated": "2021-11-27T11:34:33.132Z"
11
  }
Copied!
Overriding a group's remote bundle configurations
Similarly to the Settings page, the Group IaC Settings API **** applies the remote bundle to all the organizations in the group. An organization can override the group's configurations and define its own bundle and tag by using an API call.
To override the group's configurations, call the Org IaC Settings API endpoint by providing a different custom rules bundle and tag in the request body:
1
{
2
   "data": {
3
         "type": "iac_settings",
4
         "attributes": {
5
           "custom_rules": {
6
             "oci_registry_url": "registry-1.docker.io/org-account/org-bundle-imageage",
7
             "oci_registry_tag": "1.3.15",
8
             "is_enabled": true
9
           }
10
       }
11
   }
12
}
Copied!
The API replies with the organization's settings, and the group settings under the parents section, so you can compare the two:
1
{
2
  "type": "iac_settings",
3
  "id": "<org id>",
4
  "attributes": {
5
    "custom_rules": {
6
      "oci_registry_url": "registry-1.docker.io/org-account/org-bundle-image",
7
      "oci_registry_tag": "1.3.15",
8
      "is_enabled": true
9
    },
10
   "updated": "2021-11-27T11:34:33.132Z",
11
   "parents": {
12
      "group": {
13
        "id": "<group id>",
14
        "type": "iac_settings",
15
        "attributes": {
16
          "custom_rules": {
17
            "oci_registry_url": "registry-1.docker.io/group-account/group-bundle-image",
18
            "oci_registry_tag": "1.3.14",
19
            "is_enabled": true
20
          },
21
          "updated": "2021-11-19T10:59:45.259Z"
22
        }
23
      }
24
    }
25
  }
Copied!
To revert back to the group settings, call the API by providing the following request body:
1
{
2
   "data": {
3
         "type": "iac_settings",
4
         "attributes": {
5
           "custom_rules": {
6
             "inherit_from_parent": "group"
7
           }
8
       }
9
   }
10
}
Copied!
The API replies with the organization's settings, and the group settings under the parents section, so you can compare the two:
1
{
2
  "type": "iac_settings",
3
  "id": "<org id>",
4
  "attributes": {
5
    "custom_rules": {
6
      "oci_registry_url": "registry-1.docker.io/group-account/group-bundle-image",
7
      "oci_registry_tag": "1.3.14",
8
      "is_enabled": true,
9
      "inherit_from_parent": "group"
10
    },
11
   "updated": "2021-11-19T10:59:45.259Z",
12
   "parents": {
13
      "group": {
14
        "id": "<group id>",
15
        "type": "iac_settings",
16
        "attributes": {
17
          "custom_rules": {
18
            "oci_registry_url": "registry-1.docker.io/group-account/group-bundle-image",
19
            "oci_registry_tag": "1.3.14",
20
            "is_enabled": true
21
          },
22
          "updated": "2021-11-19T10:59:45.259Z"
23
        }
24
      }
25
    }
26
  }
Copied!
Environment variables
You can also configure the location of the custom rules bundle using Snyk config for your organization. In your project’s folder, run the following commands to configure your container registry with the Snyk IaC CLI:
1
snyk config set oci-registry-url=registry-1.docker.io/org-account/org-bundle-image:1.3.14
Copied!
This will set the following Snyk environment variable: SNYK_CFG_OCI_REGISTRY_URL
Ensure the OCI Registry URL is a valid URL; for example, for DockerHub:
registry-1.docker.io/org-account/org-bundle-image:1.3.14
Make sure to clear any previously defined URLs in the Snyk Settings page or disable custom rules, as only one method for defining the bundle's path should be defined at any given time.
Troubleshooting
Enable debug logs by running the command with a -d flag:
1
snyk iac test <file> -d
Copied!
Some possible problems:
Providing an invalid container registry URL. See the note above if you're using Docker Hub.
1
We were unable to download the custom bundle to the disk. 
2
Please ensure access to the remote Registry and validate you have provided all the right parameters.
Copied!
Providing invalid credentials.
1
There was an authentication error. Incorrect credentials provided.
2
    We were unable to download the custom bundle to the disk.
3
    Please ensure access to the remote Registry and validate you have provided all the right parameters.
Copied!
If you have found a discrepancy that you cannot explain, please raise a support ticket.

Using a local custom rules bundle

Integrating IaC custom rules within a pipeline

Last modified 7d ago

Export as PDF

Copy link

Edit on GitHub

Contents

Snyk Settings page

Snyk API

Environment variables

Troubleshooting