Text of docs.gitlab.com › user › application_security › dependency_firewall as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Dependency firewall | GitLab Docs

/ Dependency firewall Tier : Premium, Ultimate Offering : GitLab.com, GitLab Self-Managed Status : Beta Introduced in GitLab 19.0 as an experiment . Changed to beta in GitLab 19.5. The dependency firewall is in beta . The policy schema and supported ecosystems might change between releases. The dependency firewall is free during beta. It is planned to become a paid feature, billed through GitLab Credits . You must opt in before you are charged, and GitLab gives notice first.

Use the dependency firewall to control which packages your developers and CI/CD jobs install. Run your package manager through the GitLab CLI with glab dependency-firewall , or its shorter alias glab df . GitLab checks each package against your dependency firewall policies before the package reaches your machine. Policies match packages by license, vulnerability risk, and malicious code. The firewall works with the registries your project already uses, such as npmjs.com, PyPI, Maven Central, or RubyGems.org.

GitLab does not host or mirror the packages it evaluates, so you do not have to move your dependencies into the GitLab package registry or change your registry configuration. For each package, the firewall returns one of these outcomes: Allowed: The package manager fetches the package as usual. Warned: The package manager fetches the package, and the CLI reports it. Blocked: The firewall refuses the package, and the package manager receives a 403 Forbidden response.

GitLab records each decision as an audit event . Supported ecosystems Ecosystem Package managers Java Maven, Gradle Node.js npm, pnpm, Yarn Python pip, uv, Poetry, pipenv, Twine Ruby RubyGems, Bundler Rust Cargo Go GitHub Packages in other ecosystems are fetched without evaluation. For the command to use with each package manager, see glab dependency-firewall . The CLI connects to registries directly, over HTTPS only, and refuses plain http:// requests.

It does not use an outbound corporate proxy, so glab df cannot reach registries in a network that requires one. Turn on the dependency firewall Turn on the dependency firewall before you create policies. While the firewall is off, GitLab does not evaluate packages, and glab df allows every package. On GitLab.com, you turn on the firewall for each top-level group. Subgroups and projects inherit the setting from their top-level group.

Prerequisites: The Owner role for the top-level group. To turn on the dependency firewall: In the top bar, select Search or go to and find your top-level group. In the left sidebar, select Settings > Secure . Turn on the Enable dependency firewall toggle. On GitLab Self-Managed, you turn on the firewall once for the whole instance. The setting applies to every project on the instance. There is no per-group toggle. Prerequisites: Administrator access.

To turn on the dependency firewall: In the upper-right corner, select Admin . In the left sidebar, select Settings > Security and compliance . Expand Dependency firewall . Select the Enable dependency firewall checkbox. Select Save changes . To turn off the firewall, repeat the steps for your offering and turn the setting off. Existing policies are preserved, but the firewall stops evaluating packages. Use the dependency firewall Run your package manager through the GitLab CLI to check each package against your policies.

You can run it on your machine or in a CI/CD job. Authentication is required. Prerequisites: The dependency firewall turned on for your group or instance. The GitLab CLI installed and authenticated. The Reporter, Security Manager, Developer, Maintainer, or Owner role for the project. To get started, follow the dependency firewall tutorial . Prevent bypassing the firewall The firewall evaluates only the traffic that glab df can see.

A package manager run on its own installs whatever it resolves, and so does an AI coding agent that calls a package manager for you. Neither reaches the firewall, so neither sees a block. Packages already in a package manager cache are also not re-evaluated. Maven reads from ~/.m2/repository/ , npm from node_modules/ , and Bundler from vendor/bundle/ . The firewall evaluates a package only when the package manager fetches it over the network.

To close that gap, enforce the firewall at your network egress point instead of relying on every caller to remember the prefix. The CLI adds the following header to every request it forwards to a registry, including metadata and index requests, and requests for allowed and warned packages: X-Gitlab-Dependency-Firewall: allowed Configure your egress proxy or gateway to allow HTTPS traffic to package registries only when that header is present.

A package manager that runs outside glab df sends no such header, so the request is refused at the network boundary rather than quietly succeeding. This control needs: An egress control point that inspects HTTPS traffic. The header travels inside the TLS session the CLI opens to the registry, so a gateway that sees only the destination host cannot read it. A rule for each registry hostname your teams use, such as registry.npmjs.org , pypi.org , files.pythonhosted.org , repo.maven.apache.org , and rubygems.org .

The header is set by the CLI, so this is a guardrail rather than a boundary. It stops a package manager or agent that does not know about the header. A caller that sets the header itself still reaches the registry. The header also does not prove that a policy evaluated the request. The CLI adds it even when the firewall is not evaluating the project, for example when the firewall is turned off or the project cannot be found.

The header shows only that the request went through glab df . The CLI never forwards blocked packages. Some configurations also send traffic around the CLI. For example, an http_proxy: setting in a gemrc file takes precedence over the proxy settings the CLI applies for gem and bundle , so that traffic is not inspected. RubyGems reads the system gemrc file, ~/.gemrc , and the file named by the GEMRC variable. It does not read these files from the repository, so a committed project file cannot cause this, but a CI image or a developer machine can.

Create a dependency firewall policy Dependency firewall policies are stored in the .gitlab/security-policies/policy.yml file of a security policy project . Build a policy in the policy editor, or edit that file in a merge request. GitLab applies policy changes only when a merge request is merged. For more information, see policy editor . A security policy project can have a maximum of five dependency firewall policies.

This limit is controlled by the dependency_firewall_policies_per_configuration_limit application setting. Creating a policy in a group means the policy applies to every project in the group and its subgroups. Creating a policy in a project means the policy applies only to that project. Prerequisites: By default, only group, subgroup, or project Owners have the permissions required to create or assign a security policy project.

Alternatively, you can create a custom role with the permission to manage security policy links . To create a dependency firewall policy: In the top bar, select Search or go to and find your group or project. In the left sidebar, select Secure > Policies . Select New policy . In Dependency firewall policy , select Select policy . Complete the fields. For what each one means, see Policy schema . Select Configure with a merge request .

Review and merge the merge request. After the merge request is merged, the policy takes effect on the next evaluation. Editor modes The policy editor opens in rule mode, a form that builds the policy for you. Rule mode covers the name, description, scope, enforcement mode, and rules. Bypass settings are under Advanced . To write the policy as YAML instead, select .yaml mode . Use YAML mode to copy a policy between projects, or to use a field that rule mode does not show.

You can switch between the two modes at any time. If the YAML

The rest of this page is on the live site.