概要
- 機能: Corgeaがプライベートパッケージレジストリにサインインし、プロジェクトが依存する社内パッケージと、それらが引き込むすべてのパッケージを解析できるようにします。
- 対象: 共有ライブラリ、プラットフォームSDK、自社フレームワークなど、社内公開されたパッケージに依存するアプリケーションを持つチーム。これらはMaven Central、PyPI、nuget.orgのような公開レジストリではなく、プライベートレジストリに置かれています。
なぜ必要か
Corgeaは各依存関係を、その提供元レジストリで参照して解析します。公開パッケージは誰でも取得できるため、そのまま解析できます。社内パッケージは異なり、認証情報がなければ中身を確認できず、その先にあるものはすべて見えません。 レジストリを接続していない場合、通常は次の状態になります。- スキャンの「Errors」タブに、該当ファイルのDependency Analysis警告が表示される。
- Corgeaが中身を確認できないため、社内パッケージがサブ依存関係なしで表示される。
- 社内パッケージ経由でしか到達できないものは解析されないため、脆弱性が検出されない。
利用可否
プライベートパッケージレジストリは、専用テナントをご利用のエンタープライズ契約のお客様が利用できます。組織ごとに有効化し、既定では無効です。アカウントで有効にするにはsupport@corgea.comまでご連絡ください。
対応パッケージタイプ
対応レジストリ
Corgeaは各パッケージタイプの標準プロトコルで接続するため、特定の製品に依存しません。標準クライアントが想定する形でパッケージを配信し、ユーザー名とトークンによる認証を受け付けるレジストリであれば利用できます。例えば次のような製品です。- Sonatype Nexus Repository
- Azure Artifacts
- GitHub Packages
- Google Artifact Registry
- MyGet
- ProGet
- 自己ホスト型のレジストリサーバー
事前準備
必要なものは次のとおりです。- Corgeaから到達できるレジストリ。 Corgeaはインターネット経由でレジストリに接続します。VPN内や社内ネットワークからのみ到達できるレジストリ、IP許可リストの内側にあるレジストリは、アクセスを許可するまで利用できません。
- 読み取り権限のあるトークン。 Corgeaはパッケージのダウンロードと依存関係情報の読み取りのみを行い、公開（アップロード）は一切行いません。
- 短期間で失効しないトークン。 Corgeaは登録されたトークンを保存し、スキャンごとに再利用します。
レジストリを設定する
手順1: レジストリの情報を用意する
レジストリ側で、Corgeaに使用させるリポジトリへの読み取り権限を持つトークン（またはサービスアカウント）を作成します。対応するユーザー名とリポジトリのURLを控えておきます。- Maven
- PyPI
- NuGet
社内アーティファクトを配信しているリポジトリのURLを使用します。例:
手順2: Corgeaにレジストリを追加する
Integrations → Package Registriesを開き、Manageをクリックします。
レジストリの追加、編集、削除にはManage Integrations権限が必要です。権限を参照してください。
手順3: 使用するプロジェクトを選ぶ
組織内のすべてのプロジェクトでこのレジストリを使えるようにするには、Apply to all projectsを有効のままにします。特定のプロジェクトに限定する場合はオフにして選択します。レジストリを使うプロジェクトの選択を参照してください。手順4: 再スキャンして結果を確認する
社内パッケージに依存するプロジェクトで新しいスキャンを実行し、次の点を確認します。- そのファイルのDependency Analysis警告が「Errors」タブから消えている。
- 社内パッケージにサブ依存関係が表示され、依存関係ツリーで展開できる。
- 社内パッケージ内にのみ存在する脆弱性が表示される。
レジストリを接続しても、過去のスキャン結果は変わりません。改善されたカバレッジを反映するには、新しいスキャンを実行してください。
スキャン中にCorgeaがレジストリへ到達できない場合も、公開パッケージを使ってスキャンは完了し、該当ファイルに警告が表示されます。レジストリの問題でスキャンが失敗したり、パイプラインが止まることはありません。ただし解消するまで、結果に社内パッケージは含まれません。
設定方法
Structured form（推奨）
URL、ユーザー名、トークンを入力すれば、あとはCorgeaが処理します。特別な理由がなければこちらを使用してください。Paste config file（上級者向け）
そのレジストリ用のパッケージマネージャー設定ファイルをすでに運用している場合は、代わりにそれを貼り付けられます。mirrors、proxies、どのパッケージをどのソースから取得するかといった、フォームでは指定できない設定が必要な場合に選びます。
settings.xml、pipの設定ファイル、またはNuGet.Configです。
既存レジストリの設定方法を切り替える場合は、新しい方法向けに認証情報をもう一度入力してください。Corgeaは使用中の方法の認証情報のみを保持します。
レジストリを使うプロジェクトの選択
レジストリは組織に対して一度設定し、次の2つの方法でプロジェクトに適用します。- Apply to all projects（既定）: 組織内のすべてのプロジェクトがそのレジストリを使えます。全社共通のレジストリに適しています。
- 特定のプロジェクト: 選択したプロジェクトのみ。レジストリを1つのチームが管理している場合や、段階的に導入する場合に適しています。
個別のプロジェクトを確認する
プロジェクトを開き、Settings → Package Registriesで適用されているレジストリを確認できます。- すべてに適用されるレジストリにはAll projectsのバッジが表示されます。変更はIntegrations → Package Registriesから行います。
- それ以外のレジストリにはトグルが表示され、そのプロジェクトで有効・無効を切り替えられます。
- 完全に無効化されたレジストリにはDisabledのバッジが表示されます。
プロジェクトのレジストリを変更するにはChange Project権限が必要です。プロジェクトアクセス制御が有効な場合は、そのプロジェクトへのアクセス権も必要です。
複数のレジストリを使う
必要な数だけレジストリを追加でき、1つのプロジェクトで複数を同時に使用できます。- 同じパッケージタイプに複数のレジストリ: すべてのレジストリを対象にパッケージを参照します。
- 異なるパッケージタイプ: それぞれ独立して扱われます。
- 1つのレジストリ上の複数リポジトリ: 個別に登録するのではなく、Additional repositoriesに列挙してください。
同じパッケージタイプでは、設定方法を統一してください。一部がStructured form、他がPaste config fileの場合、貼り付けたファイルは無視されます。
権限
割り当て方法は権限グループを参照してください。
セキュリティ
レジストリの認証情報は機密情報として扱われます。- 暗号化して保存: 認証情報は暗号化され、保存後に再表示されることはありません。レジストリを編集するとトークン欄は空欄で表示され、空欄のままにすれば既存のトークンが維持されます。
- スキャン中のみ使用: 認証情報は、スキャン実行中にレジストリへ認証するためだけに使用します。
- 分離: 認証情報と、それを使って取得したパッケージが、他のスキャンや他の組織と共有されることはありません。
- リポジトリには書き込まない: Corgeaが生成するファイルに認証情報が書き込まれることはありません。
- ログやメッセージでは非表示: Corgeaに表示されるエラーメッセージや診断情報から認証情報は除去されます。
- 読み取り専用アクセス: Corgeaはパッケージのダウンロードと依存関係情報の読み取りのみを行います。
制限されたネットワークでのレジストリ
ネットワークが公開レジストリを遮断し、すべてのパッケージを自社レジストリ経由にする方針の場合は、社内パッケージを配信し、かつ公開パッケージをプロキシするリポジトリをCorgeaに指定してください。これにより、必要なものをすべて1つのソースから取得できます。 レジストリが社内パッケージのみを配信し、公開レジストリにも到達できない場合、依存関係の解析は完了できません。トラブルシューティング
Dependency Analysis could not fully process this file
Dependency Analysis could not fully process this file
意味: 参照できないパッケージが見つかりました。多くの場合、サインインできないレジストリ上の社内パッケージです。対処: そのパッケージタイプのレジストリを追加し、対象プロジェクトに適用されていることを確認して再スキャンします。すでに接続済みの場合は、URLとトークンの有効性を確認してください。
Private package registry auth was enabled but no registry credentials could be loaded
Private package registry auth was enabled but no registry credentials could be loaded
意味: プロジェクトはプライベートレジストリを使う設定ですが、スキャン開始時に利用可能なレジストリがありませんでした。多くの場合、レジストリが無効化された、プロジェクトに適用されなくなった、または削除されています。対処: Integrations → Package Registriesを開き、そのパッケージタイプのレジストリが存在し、Enabledであり、すべてのプロジェクトに適用されているか、このプロジェクトを含んでいることを確認してください。
Private registry dependency resolution failed
Private registry dependency resolution failed
意味: サインインは成功しましたが、パッケージを取得できませんでした。トークンの期限切れや失効、URLが別のリポジトリを指している、レジストリに実際には存在しないパッケージなどが主な原因です。対処: 社内ネットワーク外から認証情報を確認します。
401や403は認証情報の誤り、404はURLの誤りを示します。Private registry dependency resolution timed out
Private registry dependency resolution timed out
意味: 依存関係の取得に時間がかかりすぎました。非常に大規模なプロジェクトや、レジストリの応答が遅い場合に起こります。対処: 可能な範囲でロックファイルをコミットしてスキャン時の処理を減らし、レジストリの応答時間を確認してください。そのうえで再スキャンします。
Some modules in a large repository were not covered
Some modules in a large repository were not covered
意味: リポジトリに含まれる独立したモジュールが、1回のスキャンで処理する数を超えています。対処: 対象外となったモジュールが重要な場合は、Corgeaのプロジェクトを分割するか、そのモジュールのロックファイルをコミットしてください。
Private registry CVE scan failed or timed out
Private registry CVE scan failed or timed out
意味: 社内パッケージは取得できましたが、それに対する脆弱性チェックが完了しませんでした。対処: 再スキャンしてください。公開パッケージの結果には影響しません。社内パッケージ固有の脆弱性のみが欠落する可能性があります。
Dependency analysis fails when public registries are blocked
Dependency analysis fails when public registries are blocked
意味: プロジェクトの解析には公開されているコンポーネントが必要ですが、レジストリからもインターネットからも取得できていません。対処: 公開パッケージもプロキシするリポジトリをレジストリに指定してください。制限されたネットワークでのレジストリを参照してください。
Will this interfere with my own package manager configuration?
Will this interfere with my own package manager configuration?
意味: 対応は不要です。Corgeaはリポジトリにコミットされた設定を置き換えるのではなく、それに加えてレジストリへのアクセスを追加するため、既存のソースやルールはそのまま有効です。対処: それでもソースが不足しているように見える場合は、リポジトリにコミットされた設定ファイルが妥当かどうか確認してください。読み取れないファイルは、ビルドを壊す恐れを避けるためCorgeaが変更しません。
My registry uses http instead of https
My registry uses http instead of https
意味: 動作しますが、トークンは暗号化されずに送信されます。対処: ローカルでの検証以外では
httpsを使用してください。I cannot find the feature in Corgea
I cannot find the feature in Corgea
意味: この機能は既定で無効で、その状態ではロック表示ではなく非表示になります。そのため操作できる項目は現れません。対処: プライベートパッケージレジストリは、専用テナントをご利用のエンタープライズ契約のお客様が利用できます。組織で有効にするにはsupport@corgea.comまでご連絡いただき、その後Integrationsページを再読み込みしてください。
ベストプラクティス
- 個人トークンではなく、専用の読み取り専用サービスアカウントを使用します。
- 長期有効なトークンを使用し、有効期限を管理して、スキャンのカバレッジが気付かないうちに低下しないようにします。
- パッケージタイプごとに1件登録し、それぞれ対応するURLを指定します。
- 公開パッケージもプロキシするリポジトリを優先します。ネットワークが制限されていても、いなくても機能します。
- 構造化フォームを優先し、そこで指定できない設定が必要な場合にのみ、設定ファイルの貼り付けを使用します。
- 可能な範囲でロックファイルをコミットします。スキャンが速くなり、結果も安定します。
- 通常の運用スケジュールでトークンをローテーションし、Corgea側のレジストリを更新します。変更しない場合は、編集時にトークン欄を空欄のままにしてください。
関連ドキュメント
- 依存関係スキャン（SCA） — 依存関係スキャン、依存関係ツリー、到達可能性の仕組み
- 権限グループ — View / Manage Integrationsの付与
- コンテンツアクセス管理 — プロジェクトを変更できる範囲の管理