GitLabgitlab-org

cli

main
ply7 git calls238 ms101 KiB5 cachedprotocol v2
112 lines8.7 KiBRaw

Configure and monitor GitLab Dependency Firewall for local package managers. (BETA)

Synopsis

Commands to configure GitLab Dependency Firewall for local package managers, run local package managers with a summary of blocked or flagged packages, and view activity during the current session.

Each package manager command, like glab dependency-firewall npm, runs the package manager binary and forwards every argument to it verbatim, except pip's --proxy, which glab uses as its outbound proxy. While the package manager runs, the command:

  1. Starts a local proxy and routes the package manager's HTTPS traffic through it.
  2. Reads the name and version of each package the package manager downloads or publishes.
  3. Asks GitLab to evaluate the package against the policies for the project in your Git remote.
  4. Refuses blocked packages with a 403 response that gives the block reason, and lets allowed and warned packages through.
  5. Records blocked and warned packages in .gitlab/df/ci-log.json and prints a summary.

When the package manager finishes, the command prints a summary of the packages that matched your policies. A ✖ marks a blocked package, and a ▲ marks a package with a warning. If no package matched, the command prints no summary. A run with at least one blocked package prints the summary to standard error. A run with only warnings prints it to standard output.

Evaluation results are cached for the length of a run, so a package that appears many times in a dependency tree is evaluated once.

If GitLab can't evaluate a package, the command blocks it. If the Dependency Firewall isn't evaluating the project, the command allows every package.

The proxy checks only the requests it recognizes as package downloads and uploads. It forwards every other request to the host the package manager asked for, so it is not an egress filter and does not limit which hosts the package manager can reach.

The command does not change your registry configuration. For the length of the run, it sets environment variables that route the package manager's traffic through the proxy and make the package manager trust the proxy certificate. Your existing CA bundles stay trusted. The CA bundle the command gives the package manager also holds your system's trusted certificates.

To reach package registries, the proxy uses the outbound proxy in HTTPS_PROXY, including any credentials in its URL. For plain-HTTP registries it uses HTTP_PROXY instead, when that's set. For npm and pnpm, HTTPS_PROXY takes precedence over HTTP_PROXY for plain-HTTP registries too, matching those tools. It connects directly to the hosts listed in NO_PROXY. The proxy setting in your glab configuration applies only to GitLab API calls.

If an https:// outbound proxy requires a client certificate, the proxy presents the certificate in the client_cert setting for your GitLab host to it. Package registries never receive that certificate, and module downloads by glab dependency-firewall go don't present it.

Some package managers have proxy environment variables of their own, such as npm_config_https_proxy, YARN_HTTPS_PROXY, PIP_PROXY, and CARGO_HTTP_PROXY. The proxy reads those variables first, so for those package managers the outbound proxy can differ from HTTPS_PROXY and HTTP_PROXY. A proxy from Yarn's or pip's own settings also applies to hosts in NO_PROXY, as it does in those tools.

For npm, Yarn, pip, pipenv, and cargo, the proxy also reads the same settings from your user and global config files, such as ~/.npmrc, ~/.yarnrc, ~/.yarnrc.yml, pip.conf, and $CARGO_HOME/config.toml. For Maven and Gradle, it reads the proxy settings in your user and global config files first, such as ~/.m2/settings.xml and ~/.gradle/gradle.properties. It doesn't read proxy settings from files inside the project, such as a .npmrc or .cargo/config.toml in the repository, or a user or global config file stored there. Outside a Git repository, the working directory and everything under it count as the project.

A proxy from Maven's or Gradle's settings also applies to hosts in NO_PROXY, as it does in those tools, but not to the hosts in its nonProxyHosts or http.nonProxyHosts setting. Maven proxy passwords encrypted with settings-security.xml are not supported.

Connections to package registries trust the system certificates, the certificate in the ca_cert setting for your GitLab host, and the CA bundles in SSL_CERT_FILE, REQUESTS_CA_BUNDLE, PIP_CERT, TWINE_CERT, NODE_EXTRA_CA_CERTS, BUNDLE_SSL_CA_CERT, and CARGO_HTTP_CAINFO. GitLab API calls trust only the system certificates and ca_cert, so if your outbound proxy uses a private certificate authority, set ca_cert to that CA to cover both. glab dependency-firewall go uses the same outbound proxy and certificates for module downloads from a module proxy. On macOS, on Windows, and when only SSL_CERT_DIR is set, go keeps its own trust for them. Modules that go fetches directly from version control use the certificate and proxy settings of go and git.

Maven and Gradle registry connections also trust the JVM truststore set with -Djavax.net.ssl.trustStore in MAVEN_OPTS, GRADLE_OPTS, JAVA_OPTS, JAVA_TOOL_OPTIONS, JDK_JAVA_OPTIONS, or .mvn/jvm.config. Without that option, they trust the default truststore of the JDK in JAVA_HOME. When the option names a file that does not exist or cannot be opened, they trust that JDK's cacerts instead, as the JVM does. Only PKCS#12 truststores are read. When the command opens a truststore that one of these options names but cannot use it, for example a JKS truststore, it prints a warning. A JDK default truststore in JKS format, which JDK 17 and earlier ship, is skipped without a warning.

Maven registry connections also trust a truststore set with -Djavax.net.ssl.trustStore in the mvn arguments, MAVEN_ARGS, or .mvn/maven.config, unless one of the options above sets the same property, as on Maven 4. On Maven 3, such an option replaces the truststore the command gives Maven, so Maven cannot trust the proxy and the run fails. On the gradle command line, it does the same to Gradle. The command warns in both cases. Set it in MAVEN_OPTS or GRADLE_OPTS instead.

A truststore set in _JAVA_OPTIONS, or for Maven in MAVEN_DEBUG_OPTS or, on Maven 4, .mvn/jvm.config, replaces the truststore the command gives Maven or Gradle, so they cannot trust the proxy and the run fails. Set it in MAVEN_OPTS or GRADLE_OPTS instead. The command warns about _JAVA_OPTIONS and MAVEN_DEBUG_OPTS.

The command writes .gitlab/df/ci-log.json to the working directory on every run, including local runs. Add .gitlab/df/ to your .gitignore file.

To run a package manager command in a GitLab CI/CD job, set GLAB_ENABLE_CI_AUTOLOGIN to true so the command signs in with the CI/CD job token. The command requires git in the job image, unless you set GITLAB_REPO to $CI_PROJECT_PATH. When the firewall blocks a package, the install fails, and so does the job. For more information, see CI/CD auto-login.

yaml
install:
  variables:
    GLAB_ENABLE_CI_AUTOLOGIN: "true"
  script:
    - glab dependency-firewall npm ci

Package manager commands exit with the following codes:

Exit codeMeaning
The package manager exit codeThe package manager ran and exited.
1The package manager was not found on your PATH or could not start.
130The run was interrupted or stopped, for example, with Control+C or when a CI/CD job is canceled.

This feature is in beta and might not be ready for production use. It might be unstable and breaking changes can occur outside of major releases. For more information, see https://docs.gitlab.com/policy/development_stages_support/.

Aliases

plaintext
df

Options inherited from parent commands

plaintext
  -h, --help   Show help for this command.

Subcommands

1---
2title: '`glab dependency-firewall`'
3stage: AI Clients
4group: Developer Clients
5info: To determine the technical writer assigned to the Stage/Group associated with this page, see <https://handbook.gitlab.com/handbook/marketing/product-and-technical-marketing/technical-writing/#assignments>
6---
8<!--
9This documentation is auto generated by a script.
10Please do not edit this file directly. Run `make gen-docs` instead.
11-->
13Configure and monitor GitLab Dependency Firewall for local package managers. (BETA)
15## Synopsis
17Commands to configure GitLab Dependency Firewall for local package
18managers, run local package managers with a summary of blocked or
19flagged packages, and view activity during the current session.
21Each package manager command, like `glab dependency-firewall npm`, runs the package manager binary and forwards every argument to it verbatim, except pip's `--proxy`, which glab uses as its outbound proxy. While the package manager runs, the command:
231. Starts a local proxy and routes the package manager's HTTPS traffic through it.
241. Reads the name and version of each package the package manager downloads or publishes.
251. Asks GitLab to evaluate the package against the policies for the project in your Git remote.
261. Refuses blocked packages with a `403` response that gives the block reason, and lets allowed and warned packages through.
271. Records blocked and warned packages in `.gitlab/df/ci-log.json` and prints a summary.
29When the package manager finishes, the command prints a summary of the packages that matched your policies. A `✖` marks a blocked package, and a `▲` marks a package with a warning. If no package matched, the command prints no summary. A run with at least one blocked package prints the summary to standard error. A run with only warnings prints it to standard output.
31Evaluation results are cached for the length of a run, so a package that appears many times in a dependency tree is evaluated once.
33If GitLab can't evaluate a package, the command blocks it. If the Dependency Firewall isn't evaluating the project, the command allows every package.
35The proxy checks only the requests it recognizes as package downloads and uploads. It forwards every other request to the host the package manager asked for, so it is not an egress filter and does not limit which hosts the package manager can reach.
37The command does not change your registry configuration. For the length of the run, it sets environment variables that route the package manager's traffic through the proxy and make the package manager trust the proxy certificate. Your existing CA bundles stay trusted. The CA bundle the command gives the package manager also holds your system's trusted certificates.
39To reach package registries, the proxy uses the outbound proxy in `HTTPS_PROXY`, including any credentials in its URL. For plain-HTTP registries it uses `HTTP_PROXY` instead, when that's set. For npm and pnpm, `HTTPS_PROXY` takes precedence over `HTTP_PROXY` for plain-HTTP registries too, matching those tools. It connects directly to the hosts listed in `NO_PROXY`. The `proxy` setting in your glab configuration applies only to GitLab API calls.
41If an `https://` outbound proxy requires a client certificate, the proxy presents the certificate in the `client_cert` setting for your GitLab host to it. Package registries never receive that certificate, and module downloads by `glab dependency-firewall go` don't present it.
43Some package managers have proxy environment variables of their own, such as `npm_config_https_proxy`, `YARN_HTTPS_PROXY`, `PIP_PROXY`, and `CARGO_HTTP_PROXY`. The proxy reads those variables first, so for those package managers the outbound proxy can differ from `HTTPS_PROXY` and `HTTP_PROXY`. A proxy from Yarn's or pip's own settings also applies to hosts in `NO_PROXY`, as it does in those tools.
45For npm, Yarn, pip, pipenv, and cargo, the proxy also reads the same settings from your user and global config files, such as `~/.npmrc`, `~/.yarnrc`, `~/.yarnrc.yml`, `pip.conf`, and `$CARGO_HOME/config.toml`. For Maven and Gradle, it reads the proxy settings in your user and global config files first, such as `~/.m2/settings.xml` and `~/.gradle/gradle.properties`. It doesn't read proxy settings from files inside the project, such as a `.npmrc` or `.cargo/config.toml` in the repository, or a user or global config file stored there. Outside a Git repository, the working directory and everything under it count as the project.
47A proxy from Maven's or Gradle's settings also applies to hosts in `NO_PROXY`, as it does in those tools, but not to the hosts in its `nonProxyHosts` or `http.nonProxyHosts` setting. Maven proxy passwords encrypted with `settings-security.xml` are not supported.
49Connections to package registries trust the system certificates, the certificate in the `ca_cert` setting for your GitLab host, and the CA bundles in `SSL_CERT_FILE`, `REQUESTS_CA_BUNDLE`, `PIP_CERT`, `TWINE_CERT`, `NODE_EXTRA_CA_CERTS`, `BUNDLE_SSL_CA_CERT`, and `CARGO_HTTP_CAINFO`. GitLab API calls trust only the system certificates and `ca_cert`, so if your outbound proxy uses a private certificate authority, set `ca_cert` to that CA to cover both. `glab dependency-firewall go` uses the same outbound proxy and certificates for module downloads from a module proxy. On macOS, on Windows, and when only `SSL_CERT_DIR` is set, `go` keeps its own trust for them. Modules that `go` fetches directly from version control use the certificate and proxy settings of `go` and `git`.
51Maven and Gradle registry connections also trust the JVM truststore set with `-Djavax.net.ssl.trustStore` in `MAVEN_OPTS`, `GRADLE_OPTS`, `JAVA_OPTS`, `JAVA_TOOL_OPTIONS`, `JDK_JAVA_OPTIONS`, or `.mvn/jvm.config`. Without that option, they trust the default truststore of the JDK in `JAVA_HOME`. When the option names a file that does not exist or cannot be opened, they trust that JDK's `cacerts` instead, as the JVM does. Only PKCS#12 truststores are read. When the command opens a truststore that one of these options names but cannot use it, for example a JKS truststore, it prints a warning. A JDK default truststore in JKS format, which JDK 17 and earlier ship, is skipped without a warning.
53Maven registry connections also trust a truststore set with `-Djavax.net.ssl.trustStore` in the `mvn` arguments, `MAVEN_ARGS`, or `.mvn/maven.config`, unless one of the options above sets the same property, as on Maven 4. On Maven 3, such an option replaces the truststore the command gives Maven, so Maven cannot trust the proxy and the run fails. On the `gradle` command line, it does the same to Gradle. The command warns in both cases. Set it in `MAVEN_OPTS` or `GRADLE_OPTS` instead.
55A truststore set in `_JAVA_OPTIONS`, or for Maven in `MAVEN_DEBUG_OPTS` or, on Maven 4, `.mvn/jvm.config`, replaces the truststore the command gives Maven or Gradle, so they cannot trust the proxy and the run fails. Set it in `MAVEN_OPTS` or `GRADLE_OPTS` instead. The command warns about `_JAVA_OPTIONS` and `MAVEN_DEBUG_OPTS`.
57The command writes `.gitlab/df/ci-log.json` to the working directory on every run, including local runs. Add `.gitlab/df/` to your `.gitignore` file.
59To run a package manager command in a GitLab CI/CD job, set `GLAB_ENABLE_CI_AUTOLOGIN` to `true` so the command signs in with the CI/CD job token. The command requires `git` in the job image, unless you set `GITLAB_REPO` to `$CI_PROJECT_PATH`. When the firewall blocks a package, the install fails, and so does the job. For more information, see [CI/CD auto-login](https://docs.gitlab.com/cli/authentication/#auto-login).
61```yaml
62install:
63 variables:
64 GLAB_ENABLE_CI_AUTOLOGIN: "true"
65 script:
66 - glab dependency-firewall npm ci
67```
69Package manager commands exit with the following codes:
71| Exit code | Meaning |
72|-----------|---------|
73| The package manager exit code | The package manager ran and exited. |
74| `1` | The package manager was not found on your `PATH` or could not start. |
75| `130` | The run was interrupted or stopped, for example, with Control+C or when a CI/CD job is canceled. |
77This feature is in beta and might not be ready for production use.
78It might be unstable and breaking changes can occur outside of major releases.
79For more information, see
80<https://docs.gitlab.com/policy/development_stages_support/>.
82## Aliases
84```plaintext
85df
86```
88## Options inherited from parent commands
90```plaintext
91 -h, --help Show help for this command.
92```
94## Subcommands
96- [`bundle`](bundle.md)
97- [`cargo`](cargo.md)
98- [`ci-summary`](ci-summary.md)
99- [`gem`](gem.md)
100- [`go`](go.md)
101- [`gradle`](gradle.md)
102- [`job-proxy`](job-proxy/_index.md)
103- [`maven`](maven.md)
104- [`npm`](npm.md)
105- [`package`](package.md)
106- [`pip`](pip.md)
107- [`pipenv`](pipenv.md)
108- [`pnpm`](pnpm.md)
109- [`poetry`](poetry.md)
110- [`twine`](twine.md)
111- [`uv`](uv.md)
112- [`yarn`](yarn.md)
Diagnostics7 git calls · 238 ms
CallStatusSizeTime0238 ms
discover200185 B2 ms
git.upload-pack discover
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=2
git.response.bytes=185
git.server.agent=git/2.56.g1891de4-Linux
git.server.object_format=sha1
git.server.caps=agent ls-refs fetch server-option object-format
git.server.fetch=shallow wait-for-done filter
git.protocol.version=2
git.pkt.frames=9
git.pkt.data=7
git.pkt.flush=2
git.pkt.delim=0
git.pkt.bytes=185
git.pkt.payload.max=35
ls-refs20058 KiB · hit8 ms
git.upload-pack ls-refs
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=ls-refs
git.upstream.dur_ms=3
git.response.bytes=59849
git.response.cache=HIT
git.response.duration_ms=8
git.protocol.version=2
git.pkt.frames=731
git.pkt.data=730
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=59849
git.pkt.payload.max=143
git.ls_refs.count=730
git.ls_refs.head=refs/heads/main
fetchcombine:blob:none+tree:2 · deepen 12004.2 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=3
git.response.bytes=4273
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=combine:blob:none+tree:2
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=1
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=7
git.pkt.data=5
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=4273
git.pkt.payload.max=4173
git.sideband.band1.bytes=4173
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=11
git.pack.bytes=4173
git.fetch.wide.objects=11
git.fetch.wide.extra_bytes=3930
git.fetch.wide.blobs=0
fetchtree:0 · deepen 1020032 KiB · hit3 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=32926
git.response.cache=HIT
git.response.duration_ms=3
git.fetch.filter=tree:0
git.fetch.wants=0dd7574dce9e385c5c30540e6c15657adc6bdce9
git.fetch.haves.count=0
git.fetch.deepen=10
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=22
git.pkt.data=20
git.pkt.flush=1
git.pkt.delim=1
git.pkt.bytes=32926
git.pkt.payload.max=32046
git.sideband.band1.bytes=32046
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=80
git.pack.bytes=32046
git.pack.ofs_delta=36
git.pack.ref_delta=0
git.pack.chain.max=2
git.pack.trailer=cb0bad5d7ffc514895d8b21c4dd470327f90bc91
git.pack.full=44
Open pack map
fetchtree:02001.7 KiB · hit2 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=2
git.response.bytes=1744
git.response.cache=HIT
git.response.duration_ms=2
git.fetch.filter=tree:0
git.fetch.wants=5e4007a5673eb3bf5d0d7f1a1463c3b2ca3fb3bd
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=1744
git.pkt.payload.max=1717
git.sideband.band1.bytes=1717
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=1717
git.pack.trailer=3f1b9ccc7756e8941d6705e8187c87fd922113e6
Open pack map
fetchtree:0200603 B · hit4 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=4
git.response.bytes=603
git.response.cache=HIT
git.response.duration_ms=4
git.fetch.filter=tree:0
git.fetch.wants=5176f4db5d2291e59ebb86e84c285997df7bb735
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=603
git.pkt.payload.max=576
git.sideband.band1.bytes=576
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0
git.pack.objects=1
git.pack.bytes=576
git.pack.trailer=d6a5813e7d910c309af173a8e72c7467abf35dc7
Open pack map
fetch2003.5 KiB222 ms
git.upload-pack fetch
http.response.status_code=200
git.upstream.cf_ray=-
git.upstream.phase=fetch
git.upstream.dur_ms=222
git.response.bytes=3551
git.response.cache=MISS
git.response.duration_ms=222
git.fetch.wants=dea7e5c8039b9162b9e41cbbbaaf11c14737288c
git.fetch.haves.count=0
git.fetch.deepen=0
git.fetch.thin_pack=false
git.fetch.ofs_delta=true
git.protocol.version=2
git.pkt.frames=4
git.pkt.data=3
git.pkt.flush=1
git.pkt.delim=0
git.pkt.bytes=3551
git.pkt.payload.max=3524
git.sideband.band1.bytes=3524
git.sideband.band2.bytes=0
git.sideband.band3.bytes=0

Each row is one HTTP round trip ply made to the git server for this page, on one timeline. discover asks what the server speaks, ls-refs lists branch tips, fetch brings objects by id. A hit was served by Workers Cache. Tap a row for its wire details.

Remote
https://gitlab.com/gitlab-org/cli
Ref
refs/heads/main
Commit
0dd7574dce9e385c5c30540e6c15657adc6bdce9
cf-ray
a5e234ecd8dfa594
Request
9201b1c1…
Protocol
v2 · sha1
Agent
git/2.56.g1891de4-Linux
Filter
advertised
Fetch
shallow wait-for-done filter
Capabilities
agent ls-refs fetch server-option object-format