Documentation
Book a demo

Firewalls

Integrating with GitHub package firewall

Third-party package firewalls (also known as dependency firewalls) protect your registry against the ingress of vulnerable packages.

Cloudsmith has its own policy-backed package firewall covering 30+ formats from any source, including the ability to consume packages filtered through an external package firewall, such as GitHub package firewall.

Supported formats:

  • npm

Note

GitHub package firewall only checks packages when Cloudsmith first fetches them from the upstream. Packages already stored in Cloudsmith, including cached versions, are served directly, without a GitHub package firewall check. All egress from Cloudsmith is controlled with policy management.

For example, if your GitHub policy later blocks a version you’ve already stored, Cloudsmith continues to serve its cached copy. To prevent those downloads, remove or quarantine the blocked versions in Cloudsmith.

Prerequisites

  • GitHub Enterprise Cloud, with the package firewall enabled and a policy set by an enterprise admin. See GitHub's guide: Protecting endpoints with GitHub package firewall.
  • Your GitHub Enterprise slug, for example, my-enterprise.
  • A GitHub personal access token from a user or bot account that's a member of the enterprise. Read-only access to public repositories is enough.

Upstream configuration

Form fieldDescription
NameA descriptive name for this upstream source, for example, github-package-firewall.

A shortened version of this name will be used for tagging cached packages retrieved from this upstream.
PriorityThe order Cloudsmith checks your upstreams in. Use 1 if this is your main npm source.
Proxy URLThe URL for this upstream source. This must be a fully qualified URL including any path elements required to reach the root of the repository.

Use https://package-firewall.githubapp.com/npm/enterprises/<ENTERPRISE>, with your enterprise slug in place of <ENTERPRISE>.
Proxy onlyProxy requests through to upstream sources in order to match assets that are not present in this repository.
Cache and proxyProxy the initial request for an asset through to the upstream source and then store (cache) resolved assets in this repository for future requests.
Verify SSL CertificatesIf enabled, SSL certificates are verified when requests are made to this upstream. We recommend leaving this enabled for all public sources to help mitigate Man-In-The-Middle (MITM) attacks.
AuthenticationToken authentication is required for GitHub package firewall upstreams. Select Token and paste your GitHub personal access token.
Headers (optional)Optional key-value headers that can be passed to upstreams with each request.

Adding a GitHub package firewall upstream

  1. In your Cloudsmith repository, go to the Sources tab.

  2. Click Add upstream / Configure upstream, click Manual setup, and then select npm.

  3. In the Name field, enter a name for the upstream, for example, github-package-firewall.

  4. In the Priority field, set the priority. If this is your main npm source, enter 1.

    For more information about upstream priority, see Upstream concepts: Priority.

  5. In the Proxy URL field, enter https://package-firewall.githubapp.com/npm/enterprises/<ENTERPRISE>, replacing <ENTERPRISE> with your enterprise slug.

  6. Under Package delivery, select Cache and proxy to keep a copy of each allowed package in Cloudsmith after the first download.

  7. Under Authentication, select Token, then paste your GitHub personal access token.

  8. In the Additional options section, leave Verify SSL certificate enabled.

  9. Click Create.

    The new upstream appears on the Upstream registries section of the Sources tab.

Important

If you want every upstream npm fetch to go through the firewall, ensure that the GitHub upstream is the repository’s only npm upstream. Any other, such as the public npm registry, lets packages bypass the firewall. Check connected repositories and their inherited upstreams for the same bypass.

Pull a package through your GitHub package firewall upstream

Private repositories

If your Cloudsmith repository is private, you must authenticate npm to Cloudsmith before you can install packages. Follow the private registry setup instructions to add your Cloudsmith credentials to your .npmrc file.

  1. Point npm at your Cloudsmith repository:

    shell
    npm config set registry https://npm.cloudsmith.io/<WORKSPACE>/<REPOSITORY>/

  2. Install a package:

    shell
    npm install lodash

  3. List the versions you can use:

    shell
    npm view lodash versions

    The output only includes the versions your GitHub policy allows.

What happens when a version is blocked

The firewall doesn't return an error for a blocked version. Instead, it leaves the version out of the package's version list, so Cloudsmith never sees it. If you request a blocked version, npm reports that the version doesn't exist:

shell
npm error 404 No match found for version 4.17.21

Use a version your policy allows, or ask your GitHub Enterprise admin to review the policy.

Important

Packages allowed by the firewall are still scanned and checked against your Cloudsmith policies after they're cached.