glab-dependency-firewall

glab dependency-firewall

パッケージ URL を確認し、GitLab Dependency Firewall 経由でサポート対象のパッケージマネージャーを実行して、記録されたアクティビティを調べます。このコマンドグループは試験的な機能です。長期的に使用する自動化で依存する前に、利用可能であることを確認してください。

NuGet トラフィックの照合

プロキシは、NuGet v3 flatcontainer のパッケージダウンロードと、マルチパート PUT によるパッケージ／シンボルのアップロードを認識します。サポート対象の flatcontainer 形式以外の .nupkg ダウンロード URL など、対象範囲内で解析できないトラフィックはすべてフェイルクローズします。この照合機能は nuget または dotnet のラッパーを提供せず、package コマンドでサポートされる PURL タイプも拡張しません。親ヘルプに記載されているラッパーのみを使用してください。

1 つのパッケージを確認する

パッケージマネージャーを実行せずに、バージョン付きパッケージ座標 1 つのポリシー判定を確認する場合は、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 は、認識済みで Content-Length が既知のパッケージアーティファクトを、アーティファクト全体をメモリにバッファーするのではなく、ストリーミングします。これは、拡張子またはサポート対象のバイナリ Content-Type によって識別される wheel、crate、tarball、ZIP、gem、JAR、WAR、AAR、NuGet パッケージに適用されます。長さが不明なレスポンス、転送時に展開されたレスポンス、メタデータ、および成功以外のレスポンスには、HTTP フレーミングとヘッダーを安全に修復できるよう、引き続きバッファー方式が使用されます。パッケージマネージャーのチェックサム／整合性検証を維持し、部分ダウンロードのエラーはすべてインストール失敗として扱ってください。

glab コマンド	実行ファイル	例
cargo	cargo	glab dependency-firewall cargo fetch
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

GitLab リモートが対象のプロジェクトを示す Git リポジトリ内でラッパーを実行し、事前に glab の認証を確認してください。ポリシーによるブロックは確定的な判定として扱い、その結果を回避するためだけにラッパーを使わず再試行しないでください。

解析できないパッケージトラフィック

プロキシは、対象範囲内のパッケージのアップロードまたはダウンロードを認識しても、パッケージの座標を特定できない場合、フェイルクローズします。たとえば、公開メタデータの形式が不正な場合、検査上限を超えるアップロード、アーティファクトのファイル名やパスの形式が不正な場合などです。このようなリクエストは HTTP 403 でブロックされ、上流レジストリやポリシーチェッカーに接続する前に、ブロックとして記録されます。ポリシーチェックでエラーが発生した場合も、リクエストはブロックされます。

対象外と分類されたメタデータ、インデックス、サイドカーへのリクエストは、そのまま通過します。これは、あらゆるパッケージプロトコルが検査されるという意味ではありません。トラブルシューティングでは、記録された理由とパッケージマネージャーのリクエスト形式を確認してください。解析またはポリシーによるブロックを回避するために、ラッパーを使わずに再試行しないでください。内部のエコシステムマッチャーがあっても、CLI ラッパーが追加で利用できるとは限りません。

ラッパーのヘルプ

ラッパー名の後ろにあるものはすべて、変更されずにパッケージマネージャーへ渡されます。ラッパーコマンドでは 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 cargo
glab help dependency-firewall npm
glab help dependency-firewall maven
glab help dependency-firewall uv
glab help dependency-firewall yarn

ドキュメントや自動化を作成する場合は、すべてのラッパーについて glab help dependency-firewall <wrapper> を使用してください。ラッパーを確認する目的で glab dependency-firewall <wrapper> --help に頼らないでください。

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：1 つ以上のエントリがブロックされました。

終了コード 3 は一時的なコマンド失敗ではなく、ポリシーの結果として扱ってください。ブロックされたパッケージ、バージョン、理由を提示してください。ポリシーを回避したり、ログを書き換えたりしないでください。警告によってコマンドが失敗しない場合でも、レビューの参考情報として扱ってください。

現在、人が読みやすい形式の要約では、端末が対応している場合、色付きの Unicode ボックスを使用します。この表示形式を解析しないでください。自動化には終了コードと基となるログを使用してください。

トラブルシューティング

アクティビティが報告されない場合：

• コマンドの実行に使われた現在の作業ディレクトリに .gitlab/df/ci-log.json が存在することを確認してください。
• パッケージマネージャーがネストされたワークスペースで実行された場合、リポジトリルートにあるログが適用されると決めつけないでください。

ラッパーのヘルプが分かりにくい場合：

• glab help dependency-firewall <wrapper> を使用してください。
• ラッパーを直接実行すると、パッケージマネージャーの起動前に必ず GitLab プロジェクトとクライアントが解決されます。また、ラッパー名の後ろにある glab フラグはパッケージマネージャーに渡されます。

パッケージマネージャーが一覧にない場合：

• 内部のサポートコードや類似するパッケージエコシステムを根拠に、ラッパーを作り出さないでください。
• 対象の glab／GitLab バージョンについて、現在の親ヘルプと公式ドキュメントを確認してください。

パッケージマネージャーが誤ったレジストリ／インデックス／ソースを使用する場合：

• ラッパーは既存のパッケージマネージャー設定を意図的に使用します。
• 認証情報を表示せずに設定を確認し、glab が設定を書き換えることを期待するのではなく、パッケージマネージャーの文書化されたワークフローで修正してください。

コマンドリファレンス

チェックサム検証済みの親、パッケージチェック、ラッパー、要約のヘルプについては、references/commands.md を参照してください。