Get started with the dependency firewall

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed
  • Status: Beta

Set up the dependency firewall and see its first result. You turn the firewall on, add a policy that reports matches without blocking them, install a package, and read what the firewall saw.

The policy in this guide uses warn mode, so nothing is blocked while you try it out. The last step covers switching to enforcement.

Expect this to take about 15 minutes.

Prerequisites:

  • Your namespace must have access to the Premium or Ultimate tier.
  • On GitLab.com, you must have the Owner role for the top-level group. On GitLab Self-Managed, you must be an administrator.
  • You need a project with a package manager this feature supports. This guide uses npm.

Authentication

Use the dependency firewall in CI/CD

In a CI/CD job, run your package manager through glab df in the job script, and set the GLAB_ENABLE_CI_AUTOLOGIN CI/CD variable to true. The CLI then signs in with the CI/CD job token, so the job needs no other credentials.

The job token can evaluate packages for its own project only. The user who triggered the job needs one of the roles listed in the prerequisites.

For an example job that fails when any package is blocked, see glab dependency-firewall ci-summary.

Authenticate in your development workstation

You can authenticate by executing the following command. More information in Authenticate with GitLab.

shell
glab auth login

Step 1: Turn on the firewall

On GitLab.com:

  1. In the top bar, select Search or go to and find your top-level group.
  2. Select Settings > Secure.
  3. Turn on the Enable dependency firewall toggle.

On GitLab Self-Managed:

  1. In the upper-right corner, select Admin.
  2. Select Settings > Security and compliance.
  3. Expand Dependency firewall.
  4. Select the Enable dependency firewall checkbox, then select Save changes.

Nothing is evaluated yet. The firewall needs a policy, which you add next.

Step 2: Add a policy in warn mode

Policies live in a security policy project. If your group does not have one, GitLab creates it when you save your first policy.

  1. In the top bar, select Search or go to and find your group.

  2. Select Secure > Policies.

  3. Select New policy.

  4. In Dependency firewall policy, select Select policy.

  5. The editor opens in rule mode, a form. To paste the policy instead, select .yaml mode.

  6. Replace the contents of the editor with the following policy:

    yaml
    dependency_firewall_policy:
      - name: Audit high-risk packages
        description: Reports packages with critical vulnerabilities or malicious code.
        enabled: true
        enforcement_type: warn
        rules:
          - type: risk_severity
            denied:
              # threshold is the number of vulnerabilities you permit.
              # 0 permits none, so a single critical vulnerability matches.
              - severity: critical
                threshold: 0
          - type: malicious
            denied:
              - is_malicious: true
  7. Select Configure with a merge request.

  8. Review and merge the merge request.

This policy reports any package that carries a critical vulnerability or is flagged as malicious. Because enforcement_type is warn, nothing is blocked.

Step 3: Install a package through the firewall

Policies are evaluated by the GitLab CLI, so install and authenticate first.

Clone the project the policy applies to, then install its dependencies with glab df in front of your usual command:

shell
git clone https://gitlab.example.com/my-group/my-project.git
cd my-project
glab df npm install

npm runs as it always does. The CLI checks each package it resolves against your policy.

Step 4: Read the result

After npm finishes, the CLI prints what the firewall saw:

╭──────────────────────────────────────────────────────────────────────────────────╮
│ ▲  GitLab Dependency Firewall                                                    │
│ 1 package warning                                                                │
├──────────────────────────────────────────────────────────────────────────────────┤
│    PACKAGE  VERSION  REASON                                                      │
│ ▲  lodash   4.17.15  Package 'lodash' violates 'Audit high-risk packages' policy │
╰──────────────────────────────────────────────────────────────────────────────────╯

A ▲ marks a warned package. Had the policy been in enforced mode, this package would show a ✖ instead, and npm would have failed.

If no summary is printed, none of the packages matched your policy. Try glab df npm install lodash@4.17.15, which has known vulnerabilities, to see a match.

To check a package without installing it, run glab df package pkg:npm/lodash@4.17.15. For more information, see glab dependency-firewall package.

To see the same results in GitLab, select Secure > Dependency firewall in your group or project. The dashboard counts what has been blocked and warned on, and lists each active rule.

Step 5: Switch to enforcement

When the warnings match what you expect to block, change the policy to enforce them:

  1. Select Secure > Policies.
  2. In the policy row, select Edit.
  3. For Enforcement mode, select Enforce. In .yaml mode, set enforcement_type to enforced.
  4. Select Configure with a merge request, then review and merge it.

Matching packages are now refused. The package manager receives a 403 Forbidden response and the install fails, which stops the package from reaching the machine or the pipeline.

Roll out enforcement gradually. Use policy_scope to apply a policy to a few projects first, and bypass settings to exempt a service account that must keep publishing.

Next steps