Documentation
Book a demo

Policy as code

Policy exemptions

Policies are designed to cover the majority of cases, but strict enforcement can create friction with legitimate business needs, such as a legacy application depending on a package with a known vulnerability or a non-compliant license with no patched version available. Without a way to exempt specific packages, these situations create operational bottlenecks or push teams toward unauthorized workarounds.

When a package is quarantined by a policy, you can create an exemption to allow it to bypass future policy evaluations. Exemptions in Cloudsmith can be managed through a policy that defines an exact allowlist of packages and versions.

Re-evaluation is continuous and will be triggered by a policy change. Changes typically take effect within a few minutes.

Tip

An exemption policy can be created and managed via the Cloudsmith web app, API, and Terraform provider.

Cooldown policies

Exemptions for cooldown policies are not currently supported.

Create an exemption policy in the Cloudsmith web app

  1. From your Cloudsmith dashboard, go to the Policies tab.

  2. Click +Create new policy.

  3. Select Start from a template, then select Exact allowlist exemption.

  4. Click Use template.

  5. Click the pencil icon next to the policy name to edit the policy name and description, and to set the policy precedence and terminal setting.

  6. Update the allowlist in the policy’s Rego to remove example packages and add new packages to be exempt, and configure the policy actions to:

    • Set package state = Available
    • Add package tags = exempt

  7. Click Save policy.

Cloudsmith will prompt you to enable the policy. Before enabling a policy, you can test it by using the Workspaces Policies Simulate List endpoint. The endpoint evaluates your exemption policy against all packages in the workspace and returns a decision log for each evaluation, without applying any actions. This lets you confirm that the policy behaves as expected before enabling it. To use this endpoint, you need the policy's unique identifier (slug_perm), which you can retrieve using the Workspace Policies List endpoint.

Adding a package and version to the exemption allowlist

This policy will be updated over time to add and remove packages and versions from the allowlist. You can edit the policy's Rego directly in the web app to add new packages, or edit it using the Cloudsmith API or Terraform provider. The process is the same as for any other policy.

To manage additions to the exemption policy's allowlist at scale, you can use a GitOps-style workflow. GitOps means managing configuration through Git: changes are made to version-controlled files, reviewed via pull requests, and automatically applied when merged.

The following is an example pattern you can adapt; it is not a built-in Cloudsmith feature. For a working reference implementation, see the exemptions example in the rego-recipes repository.

  1. A developer adds an exemption to an allowlist file (for example, exemptions/allow.json) in source control.
  2. The developer opens a pull request.
  3. DevOps or security reviews and approves the pull request.
  4. When the pull request merges to main, an automation step (for example, a GitHub Actions workflow):
    • Validates the allowlist entries
    • Regenerates the exemption policy's Rego from a template
    • Uploads the updated policy to Cloudsmith via the API

After the policy is updated, Cloudsmith re-evaluates it against the packages in your workspace. Newly allowlisted packages are set to Available and tagged exempt, based on the policy's configured actions. Re-evaluation typically takes effect within a few minutes.

Because exemptions in Cloudsmith are managed as a policy, policy decision logs are created every time an exemption policy runs.

Create a policy in the Cloudsmith API and Cloudsmith Terraform Provider

As exemptions in Cloudsmith are managed as a policy, you can also create and manage them using the Cloudsmith API and the Cloudsmith Terraform provider.

For details on managing policies via the API, see Workspaces Policies Create. For details on managing policies via the Terraform provider, see Terraform provider: Policy as code.

Tip

Review exemptions periodically. Set a recurring cadence to review active exemptions and confirm each is still needed, for example, monthly.