glab-dependency-firewall

glab dependency-firewall

检查软件包 URL，通过 GitLab Dependency Firewall 运行受支持的软件包管理器，并查看记录的活动。此命令组处于实验阶段；在依赖它进行长期自动化之前，请确认其是否可用。

检查单个软件包

如果需要对一个带版本的软件包坐标进行策略判定，而不运行软件包管理器，请使用 package：

glab dependency-firewall package pkg:npm/[email protected]
glab dependency-firewall package pkg:pypi/[email protected]
glab dependency-firewall package pkg:maven/org.slf4j/[email protected]
glab dependency-firewall package pkg:gem/[email protected]

支持的 PURL 类型为 npm、pypi、maven 和 gem，且 PURL 必须包含版本。退出码 0 表示允许或警告，退出码 1 表示配置错误或传输失败，退出码 3 表示已拦截。即使警告的退出码为零，也应将其视为需要审查的内容；退出码 3 表示策略判定，不应试图通过重试绕过。此命令不会写入 .gitlab/df/ci-log.json，因此其结果不会显示在 ci-summary 中。

支持的包装器

每个包装器都会先从当前仓库解析 GitLab 项目并创建 GitLab API 客户端，然后获取该项目的 Dependency Firewall 策略，将其余参数转发给指定的软件包管理器二进制文件，对软件包流量执行策略，并汇总运行结果。项目解析始终在软件包管理器启动前执行。包装器使用软件包管理器现有的注册表、索引或源配置，不会重写这些配置。

当前版本的 glab 会流式传输已识别且内容长度已知的成功软件包制品，而不会将整个制品缓冲到内存中。按扩展名或受支持的二进制内容类型识别时，这涵盖 wheel、crates、tarballs、ZIP、gems、JAR、WAR、AAR 和 NuGet 软件包。长度未知、经传输解压的响应、元数据和非成功响应仍会使用缓冲路径，以便安全地修复 HTTP 分帧和标头。请保留软件包管理器的校验和／完整性验证，并将任何部分下载错误视为安装失败。

glab 命令	可执行文件	示例
bundle	bundle	glab dependency-firewall bundle install
gem	gem	glab dependency-firewall gem install rake
gradle	gradle	glab dependency-firewall gradle build
maven	mvn	glab dependency-firewall maven verify
npm	npm	glab dependency-firewall npm ci --ignore-scripts
pip	pip	glab dependency-firewall pip install requests
pipenv	pipenv	glab dependency-firewall pipenv install requests
pnpm	pnpm	glab dependency-firewall pnpm install left-pad
poetry	poetry	glab dependency-firewall poetry add requests
twine	twine	glab dependency-firewall twine upload dist/*
uv	uv	glab dependency-firewall uv pip install requests
yarn	yarn	glab dependency-firewall yarn add left-pad

请在 Git 仓库中运行包装器，并确保 GitLab 远程仓库指向目标项目；同时先验证 glab 身份验证。策略拦截具有权威性；切勿为了绕过结果而在包装器之外重试。

无法解析的软件包流量

当代理识别到范围内的软件包上传或下载请求，却无法确定其软件包坐标时，会默认拒绝。示例包括格式错误的发布元数据、超出检查限制的上传，以及格式错误的制品文件名或路径。这类请求会被 HTTP 403 拦截，并在联系上游注册表或策略检查器之前记录为拦截。策略检查错误也会导致请求被拦截。

被归类为范围外的元数据、索引和旁路请求仍会正常通过；这并不表示所有可能的软件包协议都会受到检查。排查问题时，请检查记录的原因和软件包管理器的请求格式。切勿为了绕过解析或策略拦截而在包装器之外重试。内部生态系统匹配器并不意味着还有其他 CLI 包装器可用。

Wrapper 帮助

Wrapper 名称之后的所有内容都会原样转发给软件包管理器。Wrapper 命令使用 DisableFlagParsing，因此不会在此处解析 -h、-R、--repo 或 --hostname 等 glab 标志。项目解析和 GitLab API 客户端创建仍会先运行；如果当前不在 GitLab 远程仓库中，或没有有效的身份验证上下文，glab dependency-firewall <wrapper> --help 会在软件包管理器显示帮助前失败。

# Parent command and supported wrappers
glab dependency-firewall --help
glab help dependency-firewall package

# glab's wrapper help without invoking the package manager
glab help dependency-firewall npm
glab help dependency-firewall maven
glab help dependency-firewall uv
glab help dependency-firewall yarn

生成文档或自动化时，请对每个 wrapper 使用 glab help dependency-firewall <wrapper>。不要依赖 glab dependency-firewall <wrapper> --help 来发现 wrapper。

汇总 CI 活动

ci-summary 会读取相对于当前工作目录的 .gitlab/df/ci-log.json。请在执行生成该日志的软件包管理器/Dependency Firewall 操作的同一目录中运行它。

if glab dependency-firewall ci-summary; then
  echo "No blocked dependency entries"
else
  rc=$?
  case "$rc" in
    1) echo "Dependency Firewall log could not be read" >&2 ;;
    3) echo "Dependency Firewall blocked one or more packages" >&2 ;;
    *) echo "Unexpected Dependency Firewall failure: $rc" >&2 ;;
  esac
  exit "$rc"
fi

退出代码：

• 0：没有被阻止的条目；仅允许、仅有警告或没有记录的活动。
• 1：无法读取或解析日志。
• 3：有一个或多个条目被阻止。

请将退出代码 3 视为策略结果，而非暂时性命令故障。请显示被阻止的软件包、版本和原因；不要绕过策略或改写日志。即使警告不会导致命令失败，也请将其作为审核依据。

当前的人类可读摘要会在终端支持时使用彩色 Unicode 方框。不要解析这种展示格式；自动化时请使用退出代码和底层日志。

故障排查

未报告任何活动：

• 确认命令所用的当前工作目录下存在 .gitlab/df/ci-log.json。
• 如果软件包管理器是在嵌套工作区中运行的，不要假设仓库根目录中的日志适用。

Wrapper 帮助令人困惑：

• 使用 glab help dependency-firewall <wrapper>。
• 直接调用 wrapper 时，始终会先解析 GitLab 项目并创建客户端，然后才启动软件包管理器；wrapper 名称之后的 glab 标志会传递给软件包管理器。

未列出某个软件包管理器：

• 不要根据内部支持代码或相似的软件包生态系统自行编造 wrapper。
• 请查阅当前父级帮助和目标 glab/GitLab 版本的官方文档。

软件包管理器使用了错误的 registry/index/source：

• Wrapper 有意使用现有的软件包管理器配置。
• 检查该配置时不要打印凭据，然后按照软件包管理器文档中的工作流修正配置，而不要指望 glab 重写配置。

命令参考

请参阅 references/commands.md，了解经校验和验证的父级、软件包检查、wrapper 和摘要帮助。