Enterprise Policy Manager

Cooldown policy

Early Access

The cooldown policy feature is available in early access for Ultra and Enterprise customers. To request early access or register interest in additional format support, contact us.

A cooldown policy hides newly published versions of packages from your repository index until they reach a minimum age based on the package version’s publish date. Packages that do not meet the age requirement are hidden from the index, preventing package managers from accessing them. This protects your supply chain from recently published packages that may carry malware or have not yet undergone sufficient community scrutiny, while automatically resolving to the latest compliant version when one is available.

A cooldown policy applies at the Cloudsmith index level and is supported for npm and Python packages that originate from a public upstream source. It can apply to packages proxied directly from an upstream source as well as packages that are cached in your Cloudsmith workspace.

Automatic reversal

If a cooldown policy is updated, disabled, or deleted, packages will be reevaluated. This is different from other policies that only apply to cached packages and do not have automatic reversal.

How it works

A cooldown policy is a templated Rego policy with specific customizable settings and variables. For information about which parts of your cooldown policy are customizable, see Policy configuration.

Only one cooldown policy can be created per workspace.

A cooldown policy is evaluated directly on the package index, which is made up of two types of packages:

• Upstream cached packages already in your Cloudsmith workspace.
• Packages that originate from an upstream source but are not yet cached in your Cloudsmith workspace.

By default, a cooldown policy applies to upstream cached packages already in your Cloudsmith workspace and packages coming directly from an upstream source.

When a cooldown policy is enabled, packages that do not meet the configured age requirement are hidden from the index.

• Packages that are not yet cached in Cloudsmith and need to be requested directly from a public upstream source are hidden from the index. They will not be downloaded or cached in Cloudsmith.
• Packages that are already cached in Cloudsmith are quarantined and hidden from the index until the cooldown period elapses. Once the cooldown period expires, the package is unquarantined and becomes available for download and visible in the index, provided it does not violate any other active policies.

Tip

You can exclude packages that are already cached in your Cloudsmith workspace from the policy scope:

• Via the web app: By unchecking the Apply to packages already in use option in the Edit policy view.
• Via the API: By setting the include_local_packages variable to false in your Rego policy logic.

Decision logs for a cooldown policy are only generated for packages that are already cached in your Cloudsmith workspace. They are accessible via the Cloudsmith web app and the Cloudsmith API.

Cloudsmith determines a package's age by using metadata retrieved from the upstream source. Where package age metadata is not populated, the cooldown policy will not apply, meaning the package will not be hidden from the index.

Supported package formats

The developer experience

What developers experience depends on how their dependencies are specified:

• Compliant version available: The package manager resolves to the latest compliant version. Non-compliant versions are skipped automatically.
• No compliant version available: Cloudsmith returns a 404 Not Found or 403 Forbidden error - this is common when pinned versions or a lockfile is used to resolve dependencies. Behavior may vary in different package managers. To resolve this, choose a version that satisfies the cooldown requirement.

Impact on existing packages

If caching is enabled on upstreams, packages previously pulled through Cloudsmith are already stored in your workspace. Excluding those from the policy means your existing builds are unlikely to break, because only new package versions entering the workspace are subject to the cooldown period. If a cooldown policy is applied to packages that are already in your workspace, or if upstreams are proxy-only, builds are more likely to break because non-compliant versions may be hidden.

Enhanced 403 error messaging

For supported package managers, Cloudsmith returns a customizable error message to the native client when a package is hidden from the index. The message is returned as part of the standard 403 response body and surfaced directly by the package manager, with no client-side configuration required.

The message includes:

• Policy name: The name of the cooldown policy that matched the package.
• Policy description: The policy description field, which you can use to include internal guidance — for example, who to contact, or a link to internal documentation.
• Policy ID: The unique identifier for the policy action, for reference and troubleshooting.

Supported package managers

• uv (Python)
• npm

Policy configuration

Note

A cooldown policy is always set to Terminal, which prevents the evaluation of any further policies if this policy matches. This setting cannot be edited.

Note

Index-applicable policies have a higher precedence than any other policy. This setting cannot be edited.
Policies within a workspace are ordered based on the precedence integer defined in each policy. The policy with the lowest number is evaluated first, then each remaining policy is evaluated in order of ascending precedence.

You can configure and edit the following fields for your cooldown policy:

API parameters

Rego variables

Creating and managing a cooldown policy via the Cloudsmith web app (recommended method)

To create and manage a cooldown policy, you must have access to Policy Manager in your workspace.

Important

Policy changes may take a few minutes to take effect on cached packages. If you have any questions, contact support.

Create a cooldown policy via the Cloudsmith web app (recommended method)

Note

Only one cooldown policy can be created per workspace.

1. From your Cloudsmith dashboard, go to the Policies tab and click Create a new policy.
2. Select Start from a template, and then select the Cooldown period template.
   The Cooldown period policy template opens.
3. Click Use template to create the cooldown policy. When created from a template, your cooldown policy is disabled by default.
   The cooldown policy opens in the Edit policy view.
4. (Optional) Click the edit icon next to the policy name to customize the policy name and description.
5. Customize the policy options. For guidance on which policy options are configurable, see Policy configuration.
6. Click Save policy to save and apply your changes.

After the policy is created and enabled, it might take a few minutes to take effect on packages that are already cached in your workspace.

Edit a cooldown policy via the Cloudsmith web app (recommended method)

To edit an existing cooldown policy, go to Policies and select the cooldown policy from the list. The policy opens in read-only mode. Click Edit policy to make changes.

For more information about editable policy fields, see Policy configuration.

After a policy is edited, it might take a few minutes for changes to take effect on packages that are already cached in your workspace.

Enable a cooldown policy via the Cloudsmith web app (recommended method)

You can enable a cooldown policy from the Policies tab of the Cloudsmith dashboard:

1. From the Cloudsmith dashboard, go to the Policies tab.
2. In the policy list, find the cooldown policy that you want to enable. Hovering over the toggle next to the policy displays Click to enable policy.
3. Click the toggle to enable the policy.

After a policy is enabled, it might take a few minutes to take effect on packages that are already cached in your workspace.

Disable a cooldown policy via the Cloudsmith web app (recommended method)

You can disable a cooldown policy from the Policies tab of the Cloudsmith dashboard:

1. From the Cloudsmith dashboard, go to the Policies tab.
2. In the policy list, find the cooldown policy that you want to disable. Hovering over the toggle next to the policy displays Click to disable policy.
3. Click the toggle to disable the policy.

After a policy is disabled, it might take a few minutes to take effect on packages that are already cached in your workspace.

Delete a cooldown policy via the Cloudsmith web app (recommended method)

You can delete a cooldown policy from the Policies tab of the Cloudsmith dashboard:

1. From the Cloudsmith dashboard, go to the Policies tab.
2. In the policy list, find the cooldown policy that you want to delete.
3. Click the options menu next to the policy.
4. Click Delete policy.
5. In the Delete policy: DANGER view that opens, click Delete to confirm that you want to delete the policy.

After a policy is deleted, it might take a few minutes to take effect on packages that are already cached in your workspace.

Creating and managing a cooldown policy via the Cloudsmith API

To create and manage a cooldown policy, you must have access to Policy Manager in your workspace.

Important

Policy changes may take a few minutes to take effect on cached packages. If you have any questions, contact support.

A cooldown policy can be created and managed via the Cloudsmith API by using the following endpoints:

• Create a policy
• Update a policy
• Partially update a policy
• List policies
• Retrieve a policy
• Delete a policy

Policy logic must meet specific criteria to be recognized and applied as a cooldown policy by Cloudsmith.

Ensure that your policy logic:

• Is syntactically correct
• Has a match rule
• Contains the following required variables:
  • within_past_days
  • supported_formats
  • included_repositories
  • excluded_repositories
  • include_local_packages
• Uses only supported operators:
  • ==
  • !=
  • >
  • >=
  • <
  • <=
  • in
  • not
• Uses only supported fields and functions:
  • input.v0.package.name
  • input.v0.package.version
  • input.v0.package.format
  • input.v0.package.filename
  • input.v0.package.is_local
  • input.v0.package.upstream_metadata.published_at
  • input.v0.package.uploaded_at
  • input.v0.repository.slug
  • startswith
  • endswith
  • contains
  • regex_match
  • re_match
  • regex.match
  • time.now_ns
  • time.add_date
  • time.parse_rfc3339_ns

Example policy:

package cloudsmith

import rego.v1

default match := false

# Cooldown window in days. Packages whose upstream publish date is more recent than this are filtered out.
within_past_days := 14

# Supported formats are npm and python
supported_formats := {"python", "npm"}

# Repo allow-list, by repo slug, scoped to this policy's org.
# Empty set = policy applies to every repo in the org.
# If a repo slug is in both 'included_repositories' and 'excluded_repositories', the repo is excluded.
included_repositories := {}

# Repo deny-list, by repo slug, scoped to this policy's org.
# Repos listed here always bypass the policy, regardless of `included_repositories`.
excluded_repositories := {}

# When false, only upstream/proxied packages are evaluated and locally uploaded packages are always allowed. Set true to apply the cooldown to local uploads as well.
include_local_packages := true

match if count(reason) != 0

# Whether to evaluate this package at all. Skips local packages unless `include_local_packages` is enabled.
_should_evaluate if {
    not input.v0.package.is_local
}

_should_evaluate if {
    include_local_packages == true
}

_repo_allowed if {
    count(included_repositories) == 0
    not input.v0.repository.slug in excluded_repositories
}

_repo_allowed if {
    input.v0.repository.slug in included_repositories
    not input.v0.repository.slug in excluded_repositories
}

# Produce a reason when the package is in scope, and was published within the cooldown window.
reason contains msg if {
    _should_evaluate
    _repo_allowed
    pkg := input.v0.package
    within_past_days_date := time.add_date(time.now_ns(), 0, 0, 0 - within_past_days)
    publish_date := time.parse_rfc3339_ns(pkg.upstream_metadata.published_at)
    publish_date >= within_past_days_date
    pkg.format in supported_formats
    msg := sprintf(
        "Package %v/%v (%v) is within the %v-day cooldown period: published %v",
        [pkg.name, pkg.version, pkg.format, within_past_days, pkg.upstream_metadata.published_at],
    )
}

Exemptions

When creating a cooldown policy, you can exclude specific repositories, formats, and local packages from the policy scope by using the options described in Policy configuration.

Note

For the initial early access release, it is not possible to add exemptions for specific package versions directly. We are treating this as a priority area ahead of general availability, and are gathering user feedback during early access to ensure that we take the right approach.

In the meantime, if a specific package version needs to bypass the cooldown policy urgently, we recommend that your security or platform team downloads the required package directly and uploads it into Cloudsmith manually. The cooldown policy will not apply to these packages because they have no upstream publication metadata to indicate the package age.

Viewing packages that violate your cooldown policy

Upstream packages that are already cached in your Cloudsmith workspace and violate your cooldown policy are displayed as HIDDEN in the Cloudsmith web app and via the Cloudsmith API. These packages cannot be downloaded, unhidden, or unquarantined.

To find packages currently hidden due to a cooldown policy, search your workspace using the search term status:hidden:

Hovering over the HIDDEN status in the web app will display why the package is hidden:

When a cooldown policy is deleted or disabled, packages previously displayed as HIDDEN revert to their prior status.

After a cooldown policy is created, it may take several minutes for the non-compliant packages in your Cloudsmith workspace to appear as HIDDEN.

Current limitations

The following is a non-exhaustive list of known limitations during early access:

• Exemptions: It is not possible to add exemptions for specific package versions directly.
• Connected repositories: The cooldown policy feature is not currently supported for connected repositories.

Updated last week