Supply chain security

Strict mode

Early access

Strict mode for policies is in early access for Ultra and Enterprise customers. To enable it for your workspace, contact Cloudsmith. Behavior might change before general availability.

Strict mode for policies holds packages until security checks are complete and policies have been evaluated, so every download is checked, including the first. It applies to packages you upload and packages requested through upstreams set to cache only.

Strict mode replaces block until scan, which applies this behavior across an entire workspace. With strict mode, you choose which upstreams enforce it.

Plan your rollout

You can plan the rollout of strict mode in your workspace to minimise disruption to your developers. For details, see Rolling out strict mode in your workspace.

How it works

Policy evaluation

All policies, except cooldown policies, apply only to packages stored in Cloudsmith. A package served straight from an upstream is checked only against cooldown policies.

The following table shows which policies apply before a package's first download and before later downloads, split by package source:

* This applies once the package is cached and fully evaluated against policies. Before then, downloads behave like the first download.

** Except Docker images you push, which can be pulled before evaluation finishes. For details, see Docker images you push.

Cooldown policies are checked on every request. For uploads, this applies only if the policy is configured to include local packages.

What developers see

With strict mode, you can't download a package until it's evaluated against your policies. This applies to:

• Packages uploaded to your repository, except Docker images you push.
• Packages requested for the first time through an upstream set to cache only.

When a developer requests a package for the first time:

1. Cloudsmith holds the request open for up to 30 seconds while caching and evaluating the package.
2. If the package still isn't ready, Cloudsmith returns a 307 redirect to the same URL, and the package manager requests it again. This repeats until the package is ready.
3. The package is served unless a policy blocks it or Cloudsmith can't cache it. For the response developers get in each case, see If something goes wrong.

Package managers handle redirects, so developers usually don't need to change their setup. If a package manager times out first, see If builds time out.

If builds time out

If serving a package takes longer than the package manager allows, the build fails. This usually affects very large packages on their first download. Package managers stop waiting in one of two ways:

• A network timeout. The package manager stops waiting for data before Cloudsmith sends a redirect. For example, pip's default timeout is 15 seconds. Raise it to at least 30 seconds with pip install --timeout 30, or in CI with PIP_DEFAULT_TIMEOUT=30.
• A redirect limit. The package manager follows a fixed number of redirects, and each one allows up to 30 more seconds. For example, Maven 3.9 follows 5 redirects, so a package has about 3 minutes. Docker follows 10, so about 5.5 minutes.

Cloudsmith continues processing the package after the build fails. When you run the build again, any packages that are ready are served immediately.

You can configure your package manager to reduce how often builds time out. For details, see Check how your package manager fetches dependencies.

If something goes wrong

With strict mode enabled, a package isn't served if a policy quarantines or deletes it, or if Cloudsmith can't fetch or cache it.

In the rare case that an error prevents security checks or policy evaluations from completing, the package might be served. Cooldown policies still apply. The following table shows what happens in each case.

Optional: tell developers what to do when a package is blocked

If you use policy as code, supported package managers show developers the name and description of the policy that quarantined a package. Use the description to tell developers what to do next, such as who to contact or where to request an exemption.

For details, see Enhanced 403 error messaging.

Rolling out strict mode in your workspace

First downloads with strict mode are slower because each package is evaluated before it's served. How much this affects your builds depends on how you roll out strict mode and which package managers you use.

• Start with package managers that fetch in parallel: strict mode is configured per upstream, so you don't need to switch everything at once. Start with upstreams for package managers that fetch in parallel, such as npm and NuGet, where first-download delays overlap.

  Move upstreams for package managers that fetch one at a time, such as Maven and pip, after you've applied the settings recommended in Check how your package manager fetches dependencies.

• Expect large migrations to take longer: when you migrate from another registry, such as Nexus or Artifactory, almost every request is a first download, and each one waits for evaluation. Plan extra time for the migration, and apply the recommendations in this section before you start.

  Tip

  If you're pulling packages in bulk to populate a repository, you can set its upstreams to cache and proxy for the migration, then switch them to cache only after the migration finishes.

  Packages pulled during the migration are still evaluated once they're cached, and any policy actions, such as quarantine or tagging, apply from then on. Only do this while developers and builds aren't using those upstreams. Otherwise, their first downloads aren't checked before they're served.

Check how your package manager fetches dependencies

Some package managers fetch dependencies one at a time, so first-download delays add up. Others fetch several at once, so delays overlap.

Configure strict mode

Enable strict mode

Contact Cloudsmith to enable strict mode for your workspace.

When strict mode is enabled:

• Uploads are evaluated before they can be downloaded, except Docker images you push. No further setup is needed.
• Upstreams need one more step: set package delivery to cache only on each upstream where you want strict mode to apply. For details, see Set upstreams to cache only.

Set upstreams to cache only

To apply strict mode to upstreams, you must set them to cache only. Before setting any upstream to cache only, check Known limitations.

Web app

1. In your repository, go to the Sources tab.
2. Click the edit icon next to the upstream you want to configure.
3. Set Package delivery to Cache only.
4. Click Save.
5. Repeat for each upstream you want strict mode to apply to.

API

1. List the upstreams for a format. For example, to list upstreams for Python:

   shell

   curl -X GET \
     'https://api.cloudsmith.com/v1/repos/{workspace}/{repository}/upstream/python/' \
     --header 'Accept: application/json' \
     --header 'X-Api-Key: {token}'

2. Copy the slug_perm value for each upstream you want to change.

3. For each upstream, use the PATCH endpoint to update the mode:

   shell

   curl -X PATCH \
     'https://api.cloudsmith.com/v1/repos/{workspace}/{repository}/upstream/python/{slug_perm}/' \
     --header 'Accept: application/json' \
     --header 'Content-Type: application/json' \
     --header 'X-Api-Key: {token}' \
     --data '{
       "mode": "Cache Only"
     }'

   A successful update returns a 200 response.

CLI

1. List the upstreams for a format. For example, to list upstreams for Python:

   shell

   cloudsmith upstream python ls WORKSPACE/REPOSITORY

2. Copy the slug_perm for each upstream you want to change.

3. Create update.json:

   json

   {"mode": "Cache Only"}

4. Run:

   shell

   cloudsmith upstream python update WORKSPACE/REPOSITORY/SLUG_PERM update.json

Terraform

For each upstream, set mode = "cache only" with the cloudsmith_repository_upstream Terraform resource.

For usage details, see cloudsmith_repository_upstream (Resource) in the Terraform provider documentation.

Known limitations

Unsupported formats

Strict mode isn't available for Nix or Swift upstreams or uploads.

Signing for RPM and Debian upstreams

In cache only mode, Cloudsmith serves cached RPM and Debian packages exactly as the upstream published them, so they match the checksums in the upstream's index. Cloudsmith doesn't re-sign them with your repository's signing key.

• RPM: cached packages keep the upstream's signature, or have none if the upstream doesn't sign them.
• Debian: source packages (.dsc files) work the same way. Binary packages (.deb) are verified through your repository's signed Release file, as usual.

To install packages from these upstreams with signature checks on, configure your clients to trust the upstream's signing key. For RPM, add the key in the upstream's GPG Key field. For details, see Upstream proxying and caching.

Docker images you push

For Docker, strict mode applies only to images pulled through an upstream set to cache only. Images you push to a Cloudsmith repository can be pulled before policy evaluation finishes, because the OCI Distribution Specification requires pushed images to be available immediately.

Pushed images are still evaluated, and policy actions, such as quarantine, apply once evaluation finishes.

Entitlement tokens with visibility restrictions

Entitlement tokens with visibility restrictions can't download packages from upstreams set to cache only. The request returns 404 Not Found.

To fix this, remove the visibility restrictions from the token. In the web app, they're in the Visibility restrictions section of the token's settings. In the API, they're set with the limit_package_query parameter. For details, see Visibility restrictions.

Policies that use tags or indexing fields

With strict mode, the evaluation that runs before a package's first download happens during synchronization. At that point, some policy input fields aren't yet available:

• The automatic latest tag. The new package doesn't have it yet, and the previous version might still hold it. Other tags, including upstream, are present.
• indexed and num_files. These are false and 0, because content indexing runs after a package becomes available.

Policies that use these fields might have unexpected results on the first evaluation. They give the correct result the next time a policy trigger runs. For details, see Policy input.

Migrate from block until scan

If you use block until scan, Cloudsmith will contact you to plan your migration. Block until scan will be retired in Q1 2027.

1. Cloudsmith enables strict mode for your workspace.

2. You set package delivery to cache only on each upstream where you want first downloads checked, then tell Cloudsmith when you're done.

   Warning

   Strict mode applies only to upstreams set to cache only.

   Once block until scan is disabled, any upstream still set to Cache and proxy serves first downloads before security checks are complete and policies have been evaluated.

3. Cloudsmith disables block until scan for your workspace.

There's no downtime during the migration.

While both are enabled

Block until scan and strict mode can be enabled at the same time. Block until scan takes precedence: all packages are evaluated before they're served, and your cache only settings have no effect until block until scan is disabled. This means you can't see how strict mode behaves until Cloudsmith disables block until scan for your workspace.

Uploaded packages need no configuration. While both are enabled, block until scan evaluates uploads before they can be downloaded. Once it's disabled, strict mode does the same.

Updated 1 minute ago