Use a remote IaC custom rules bundle

After you generate your custom rules bundle, you can distribute it to one of the supported OCI registries by following the steps in Pushing a bundle.

After successfully pushing your custom rules bundle, you can enforce the use of the bundle using any of the following:

Finally, after you have enforced your custom rules using one of these options, configure the Snyk Snyk CLI with your username and password to allow Snyk to authorize a pull from your OCI registry:

snyk config set oci-registry-username=<org registry username>
snyk config set oci-registry-password=<org registry password>

This sets the following Snyk environment variables:

  • SNYK_CFG_OCI_REGISTRY_USERNAME

  • SNYK_CFG_OCI_REGISTRY_PASSWORD

After you have completed this configuration, you can run a Snyk IaC scan. The CLI will pull the bundle pushed to the configured container registry in the background.

snyk iac test <file>

The resulting configuration scan issues will include issues from both the default Snyk rules and your custom rules. See also Understanding the IaC CLI test results.

Only one method for defining the bundle's path should be defined at any given time. Make sure to disable the custom rules settings using the Snyk settings page or the Snyk API. Alternatively, clear any previously-stored settings using snyk config unset.

Snyk settings and remote custom rules bundle

Snyk recommends you use the Snyk settings page to configure custom rules settings. This is 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 Organization 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.

You can configure remote custom rules bundles on the Organization level by navigating to Settings > Infrastructure as Code.

You can configure remote custom rules bundles on the Group level by navigating to Settings > Infrastructure as Code.

  • Enable remote bundles configuration using the Enable rules toggle. Doing so loads the form to specify the Registry URL and tag as shown in this example:

  • 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.

You can override remote bundle configurations for a Group using Snyk Settings.

By default, configuring a remote bundle for a Group applies the remote bundle to all the Organizations in the Group. Thus if the Group configurations are updated, these changes apply to all of its Organizations.

However, an Organization can still override the Group configurations and define its own bundle and tag. These will not change when the Group updates its configurations.

To override the Group configurations, go to the Organization's Rules section in 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 and remote custom rules bundle

If manually updating the settings through the Snyk Settings page is too time-consuming, you can use the Snyk API. It currently allows you to send any variation of the custom rules settings using an API call.

{
   "data": {
         "type": "iac_settings",
         "attributes": {
           "custom_rules": {
             "oci_registry_url": "registry-1.docker.io/group-account/group-bundle-image",
             "oci_registry_tag": "1.3.14",
             "is_enabled": true
           }
       }
   }
}
  • If you want to update the tag only, you can send over a simpler body:

{
   "data": {
         "type": "iac_settings",
         "attributes": {
           "custom_rules": {
             "oci_registry_tag": "1.3.14"
           }
       }
   }
}
  • If you want to disable custom rules, you can send over the is_enabled flag:

{
   "data": {
         "type": "iac_settings",
         "attributes": {
           "custom_rules": {
             "is_enabled": false
           }
       }
   }
}

The API replies with the Group settings so you can confirm the changes:

{
  "type": "iac_settings",
  "id": "<group id>",
  "attributes": {
    "custom_rules": {
      "oci_registry_url": "registry-1.docker.io/group-account/group-bundle-image",
      "oci_registry_tag": "1.3.14",
      "is_enabled": true
    },
   "updated": "2021-11-27T11:34:33.132Z"
  }

You can override remote bundle configurations using the Snyk API.

Similarly to the Settings page, the Update the Infrastructure as Code settings for a aroup API applies the remote bundle to all the Organizations in the Group. An Organization can override the configurations for a Group and define its own bundle and tag by using an API call.

{
   "data": {
         "type": "iac_settings",
         "attributes": {
           "custom_rules": {
             "oci_registry_url": "registry-1.docker.io/org-account/org-bundle-imageage",
             "oci_registry_tag": "1.3.15",
             "is_enabled": true
           }
       }
   }
}
  • The API replies with the Organization settings and the Group settings under the parents section so that you can compare the two:

{
  "type": "iac_settings",
  "id": "<org id>",
  "attributes": {
    "custom_rules": {
      "oci_registry_url": "registry-1.docker.io/org-account/org-bundle-image",
      "oci_registry_tag": "1.3.15",
      "is_enabled": true
    },
   "updated": "2021-11-27T11:34:33.132Z",
   "parents": {
      "group": {
        "id": "<group id>",
        "type": "iac_settings",
        "attributes": {
          "custom_rules": {
            "oci_registry_url": "registry-1.docker.io/group-account/group-bundle-image",
            "oci_registry_tag": "1.3.14",
            "is_enabled": true
          },
          "updated": "2021-11-19T10:59:45.259Z"
        }
      }
    }
  }
  • To revert back to the Group settings, call the API by providing the following request body:

{
   "data": {
         "type": "iac_settings",
         "attributes": {
           "custom_rules": {
             "inherit_from_parent": "group"
           }
       }
   }
}