依存関係ファイアウォールAPI

このAPIを使用して、プロジェクトの依存関係ファイアウォールと対話します。依存関係ファイアウォールは、プロジェクトのセキュリティポリシーを満たさないパッケージがフェッチされる前にブロックします。

プロジェクトの依存関係ファイアウォールのステータスを取得する

指定されたプロジェクトの依存関係ファイアウォールのステータスを取得します。このエンドポイントを使用して、実行全体でファイアウォールをスキップするかどうかを決定します。ファイアウォールがオフになっているプロジェクトは、404 Not Foundではなく成功応答を返すため、アクセスできないプロジェクトと区別できます。

このエンドポイントは、パーソナルアクセストークン、プロジェクトアクセストークン、グループアクセストークン、OAuthトークン、またはCI/CDジョブトークンを受け入れます。デプロイトークンはサポートされていません。認証されていないリクエストは、公開プロジェクトを含め、拒否されます。

CI/CDジョブトークンには、特定のきめ細かい権限は必要ありません。それを制約するのは、ジョブが実行されるプロジェクトです。ジョブトークンはそのプロジェクトのみを確認できます。他のプロジェクトへのリクエストは403 Forbiddenで拒否されます。これは、ターゲットプロジェクトがジョブのプロジェクトを受信ジョブトークン許可リストに許可している場合でも、その許可リストエントリがどのようなきめ細かい権限を付与しているかに関わらず拒否されます。あるプロジェクトのファイアウォールステータスは、別のプロジェクトのパイプラインが必要とする情報ではありません。

前提条件:

• プロジェクトを読み取る権限が必要です。

GET /projects/:id/dependency_firewall/enablement

サポートされている属性は以下のとおりです:

成功した場合、200 OKと次のレスポンス属性を返します:

可能な応答コード:

機能フラグがオフの間は、エンドポイントはまだ一般公開されていないため、200ではなく404を返します。したがって、404応答は3つのことのいずれかを意味し、クライアントはテキストの表現ではなく、応答ボディが使用するキーによってそれらを区別します:

• {"enabled": false}のようなenabledキーを持つボディは、このプロジェクトで機能フラグがオフであることを意味します。ファイアウォールはアクティブではないため、クライアントは実行時にそれをスキップできます。
• {"error":"404 Not Found"}のようなerrorキーを持つボディは、このエンドポイントがインスタンスに存在しないことを意味します。例えば、インスタンスがGitLab Community Editionを実行しているか、このエンドポイントが追加される前のバージョンである可能性があります。クライアントは設定の問題を報告する代わりに、以前の動作にフォールバックする必要があります。
• messageキーを持つボディは、エンドポイントが存在し、リクエストを拒否したことを意味します。プロジェクトが存在しないか、読み取ることができません。クライアントは設定の問題を報告し、プロジェクトを保護されていないものとして扱ってはなりません。

この決定をメッセージテキストに依存させないでください。プロジェクトを読み取れない呼び出し元は{"message":"404 Project Not Found"}を取得しますが、プロジェクトへのアクセス権がないきめ細かいトークンは{"message":"404 Not Found"}を取得します。これは、表現だけを比較するとエンドポイントが見つからないケースと同じように読み取れます。

リクエスト例:

curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/dependency_firewall/enablement"

レスポンス例:

{
  "enabled": true
}

パイプラインジョブから認証するには、JOB-TOKENヘッダーを使用してCI/CDジョブトークンを使用します:

curl --request GET \
  --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
  --url "https://gitlab.example.com/api/v4/projects/1/dependency_firewall/enablement"

プロジェクトの依存関係ファイアウォールポリシーに対してパッケージを評価する

指定されたプロジェクトの依存関係ファイアウォールポリシーに対して単一のパッケージを評価します。

このエンドポイントは、パーソナルアクセストークン、プロジェクトアクセストークン、グループアクセストークン、OAuthトークン、またはCI/CDジョブトークンを受け入れます。ジョブトークンは、そのジョブが実行されるプロジェクトのパッケージのみを評価できます。ターゲットプロジェクトがその受信ジョブトークン許可リストにジョブのプロジェクトを許可している場合でも、他のプロジェクトのジョブトークンは403 Forbiddenステータスコードで拒否されます。デプロイトークンはサポートされていません。

前提条件:

• プロジェクトのレポーターロール以上が必要です。パッケージレジストリをオンにする必要はありません。依存関係ファイアウォールはアップストリームレジストリからフェッチされた依存関係を評価するため、評価権限はプロジェクトのパッケージレジストリ設定とは独立しています。

POST /projects/:id/dependency_firewall/evaluate

サポートされている属性は以下のとおりです:

リクエストヘッダー:

• X-Gitlab-Dependency-Firewall-Session-Id: オプション。単一のパッケージマネージャー呼び出しからのすべての評価をグループ化するため、パッケージごとに1つの評価をトリガーする単一のインストールコマンドをこの値で関連付けることができます。GitLabは評価の監査イベントと分析イベントに値を記録し、検証せずに不透明な値として扱います。

値は1から255文字で、文字、数字、アンダースコア、ハイフンのみを含めることができます。値がこれらの制約を満たさない場合、GitLabはそれを無視し、ヘッダーを送信しなかったかのように評価が進行します。リクエストは失敗しません。

成功した場合、200 OKと次のレスポンス属性を返します:

outcome属性は次のいずれかの値をとります:

• allowed: ポリシー規則がパッケージと一致しませんでした。依存関係ファイアウォールが有効になっていてもポリシーがリンクされていないプロジェクトは、常にallowedを返します。allowedの結果は、GitLabがパッケージの脆弱性またはライセンスデータを保持しているという断言ではありません。パッケージメタデータデータベースに存在しないパッケージも許可されます。
• warned: ポリシー規則がパッケージと一致し、一致するポリシーは警告モードです。
• blocked: ポリシー規則がパッケージと一致し、一致するポリシーは適用モードです。

このエンドポイントは、以下のステータスコードも返すことがあります:

リクエスト例:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/1/dependency_firewall/evaluate" \
  --data '{"ecosystem": "npm", "name": "lodash", "version": "4.17.15"}'

レスポンス例:

{
  "outcome": "blocked",
  "reason": "Package 'lodash' violates 'deny-mit' policy"
}

依存関係ファイアウォールが有効になっているが、ポリシーがリンクされていないプロジェクトの応答例:

{
  "outcome": "allowed",
  "reason": null
}

パイプラインジョブから、CI/CDジョブトークンで認証します:

curl --request POST \
  --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
  --header "Content-Type: application/json" \
  --url "https://gitlab.example.com/api/v4/projects/1/dependency_firewall/evaluate" \
  --data '{"ecosystem": "npm", "name": "lodash", "version": "4.17.15"}'