Skip to main content
前提条件 スキャンが完了しており、PolicyIQが有効になっている必要があります。PolicyIQを有効にするには、Corgeaの担当者にお問い合わせください。
Corgeaには、導入直後からセキュリティ分析を効果的に活用できるよう、包括的なポリシーセットがあらかじめ用意されています。これらの組み込みポリシーは、一般的なセキュリティパターン、フレームワーク、インフラ構成を対象としています。 ポリシーをカスタマイズまたは拡張し、ビジネス、ネットワーク、実行環境に関する追加情報を与えることで、脆弱性検出、誤検知判定、修正生成の精度をさらに高められます。ポリシーを通じてこうしたコンテキストを提供すると、Corgeaがお客様固有のセキュリティ要件とインフラをより正確に把握できるようになります。

ポリシーの重要な動作

ポリシーの構成を説明する前に、次の重要な動作を理解しておいてください。
  1. ポリシーの適用: 新しいポリシーは、その作成後に開始するスキャンにのみ適用されます。既存のスキャン結果には遡って適用されません。
  2. ポリシーの優先順位:
    • 誤検知判定と修正生成では、汎用的なポリシーよりも対象を限定した具体的なポリシーが優先されます
    • たとえば、SSRF専用の誤検知ポリシーは、汎用の誤検知ポリシーより優先されます
    • お客様が定義したポリシーは、常にCorgeaの標準ポリシーより優先されます
  3. ポリシーのグループ化: スキャンポリシーでは、セキュリティ上の懸念事項ごとに個別のポリシーを作るのではなく、関連する事項をまとめることを推奨します。たとえば、次のようにグループ化します。
    • 認証、認可、権限処理をまとめる
    • 関連するデータ検証チェックを組み合わせる
    • 相互に関連するセキュリティ制御の検証をまとめる これらのセキュリティ要件は重複し、相互に影響することが多いため、まとめて扱うことでより適切な結果を得られます。

ポリシーの構成

適切なポリシーには、次の要素を含めます。
  1. ポリシータイプ: 作成するポリシーの種類を指定します。たとえば、BLAST(脆弱性の検出)、False Positive(誤検知の判定)、Fix(コード修正の提案)があります。
  2. ビジネスコンテキスト: 次の項目について詳しく記述します。
    • ビジネスドメインおよび要件
    • ネットワークアーキテクチャおよびセキュリティ制御
    • 環境固有の構成
    • データの分類および取り扱い要件
    • コンプライアンス要件(例: PCI、HIPAA、GDPR)
  3. 説明: 上記のコンテキストを反映した明確な指示を記述します。次のような情報を含めます。
    • 環境内の特定の脆弱性パターン
    • アーキテクチャに関連するコード例
    • インフラを踏まえた問題の扱い方
  4. 脆弱性タイプ(CWE): リスクプロファイルに基づき、このポリシーで扱う脆弱性の種類を選択します。
  5. プロジェクト: ポリシーを適用するプロジェクトを選択します。これにより、環境ごとに異なるポリシーを設定できます。プロジェクトアクセス制御が有効な場合、管理者以外のユーザーが作成または管理できるのは、アクセス権を持つプロジェクトのポリシーだけです。また、アクセス可能なプロジェクトを1つ以上選択する必要があります。会社管理者は、すべてのプロジェクトに適用するポリシーも作成できます。
  6. ファイルパターン(Glob): 必要に応じて、ポリシーの対象をパターンに一致するファイルだけに限定します(例: src/**/*.py)。すべてのファイルに適用する場合は空欄にします。
  7. ガイダンスノート(任意): 社内向けの修正手順、社内標準へのリンク、実装上のヒントなど、開発者向けの固定ガイダンスを追加します。このガイダンスは、ポリシーの影響を受けた問題を表示するときに示されます。
  8. 指示タイプ: ポリシーの指示をCorgeaの組み込みポリシーとどのように組み合わせるかを選択します。
    • Append to Corgea Default Policy: Corgeaの組み込みポリシーに指示を追加し、両方のルールを維持します。固有のビジネスコンテキスト、セキュリティ制御、環境情報でデフォルトポリシーを補強する場合に使用します。
    • Replace Corgea Default Policy: ポリシーの指示でCorgeaのデフォルト動作を完全に置き換えます。特定の状況の処理方法を全面的に制御する場合に使用します。

ポリシー・プレイグラウンド

Policy Playgroundは、ポリシーを実際のスキャンに適用する前に、作成、更新、テストできる左右分割型のワークスペースです。左側でポリシーを記述し、右側で実際のコードに対してテストできるため、ページを移動せずにすばやく調整を繰り返せます。
  • ワークスペースは、左側のPolicy Editorと右側のTest Panelに分かれています。仕切りをドラッグして、各ペインの幅を調整できます。
  • 上部ツールバーのBack to Policiesを選択すると、いつでもPoliciesテーブルに戻れます。
  • Policiesテーブルから、既存のBLASTまたはFalse PositiveポリシーをPolicy Playgroundで直接開くことができます。
  • Policiesテーブルでは、Policy ID、名前、タイプ、説明を使って目的のポリシーを検索できます。
  • Policy Playgroundで編集内容を保存すると、新しいバージョンが作成され、ポリシーが更新されます。
  • エディタのInstruction Typeには、Replace Corgea Default PolicyAppend to Corgea Default Policyの2つの選択肢が表示されます。
  • ポリシーを全体に適用する場合は、ProjectsFile Pattern (Glob)CWEsを空欄にします。
  • プロジェクトアクセス制御が有効な場合、プロジェクト単位で権限を付与されたユーザーは、閲覧権限のあるポリシーを表示できます。ただし、編集または削除できるのは、そのユーザーがアクセスできるプロジェクトだけを対象とするポリシーに限られます。
Policy Playgroundでテストできるのは、BLASTポリシーとFalse Positiveポリシーのみです。FixポリシーはPolicy Centerから引き続き作成できますが、修正のテストにはまだ対応していないため、Playgroundでは**Fix (coming soon)**と表示されます。

ポリシーをテストする

ポリシーをテストするには、Projectfileを選択し、Testをクリックします。スキャン中はボタンに**Testing…**のスピナーが表示され、完了するまでボタンは無効になります。必須項目が不足している場合は、ボタンの下にインラインメッセージが表示され、追加が必要な項目(プロジェクト、ファイル、ポリシーの指示)が示されます。 デフォルトでは、ファイル選択画面には問題が検出されているファイルだけが表示されます。まだ存在しないファイルでテストするには、New Test Fileを有効にし、プロジェクトを選択してファイル名を入力します。選択したプロジェクトからスキャンに必要な言語とフレームワークのコンテキストが提供されるため、エディターに任意のコードを記述してポリシーをテストできます。

結果のレビュー

スキャンが完了すると、ファイルプレビューの下にある結果パネルに検出結果が表示されます。各検出結果は展開可能な行で、severityCWEline numberが表示されます。行を展開すると説明を確認でき、Jump to lineを選択するとファイルプレビューの該当行へ移動できます。
スキャンが完了しても一致する検出結果がなかった場合、パネルにNo issues found for this policyと表示されます。これにより、問題が見つからなかった場合でもテストが実行されたことを確認できます。

PRスキャンとコメントルール

PRスキャンとコメントルールでは、Corgeaがプルリクエストをスキャンする条件と、検出結果をプルリクエストへコメントする条件を制御します。
  • Scan Onlyはプルリクエストをスキャンしますが、検出結果のコメントは投稿しません。
  • Scan & Commentはスキャンを実行し、ルールに一致する検出結果へコメントします。
  • Severityは、ルールに一致する対象を選択した重大度に限定します。すべての重大度を対象にする場合は空欄にします。
  • Classification to commentは、コメントする対象を選択したCWEタイプに限定します。一致するすべてのCWEへコメントする場合は空欄にします。
  • ProjectsProject Tagsは、ルールの適用範囲を定義します。プロジェクトが直接選択されているか、選択したタグのいずれかがプロジェクトに付いている場合にルールが適用されます。両方とも空欄の場合、すべてのプロジェクトが対象です。
  • Integrationsを指定すると、選択したGitHub、GitLab、またはAzure DevOps連携からのプルリクエストだけにルールを限定できます。プロジェクトとプロジェクトタグの範囲だけを使用する場合は空欄にします。
PRルールページのプロジェクトタグフィルターを使うと、特定のタグを持つプロジェクトに適用されるScan & Commentルールを検索できます。ルールテーブルのProjects列では、選択したプロジェクトとプロジェクトタグがチップとして表示されます。プロジェクトまたはタグで範囲を限定していないルールにはAll Projectsと表示され、対象が多い場合は残りの項目が**+N more**のツールチップにまとめられます。

ポリシーのベストプラクティス

ポリシーを作成するときは、Corgeaに有効なコンテキストを提供できるよう、次のベストプラクティスに従ってください。
  1. 環境を具体的に記述する: インフラ、セキュリティ制御、代替コントロールについて詳しく記述します。
  2. ビジネスロジックを含める: ビジネス固有の検証ルール、データフロー、セキュリティ要件を説明します。
  3. セキュリティアーキテクチャを説明する: セキュリティレイヤー、信頼境界、保護メカニズムを文書化します。
  4. データのコンテキストを定義する: 環境内でデータの種類ごとにどのように扱うべきかを明記します。
  5. 例外を文書化する: セキュリティ上の問題に見えても正当とみなせるビジネス上のケースを記録します。

ポリシーの例を作成するときは、次の点を意識すると効果が高まります。
  1. 複数の例を用意する: ポリシータイプごとに、異なる内容の例を3〜5件含めます。
    • さまざまなユースケースやシナリオを示す
    • 環境固有のエッジケースをカバーする
    • さまざまな複雑度のケースを示す
    • 異なるセキュリティ制御と代替策を示す
  2. 実際の環境に即した例にする: 各例が次の条件を満たすようにします。
    • 実際のインフラやアーキテクチャを反映する
    • 実際に使用しているセキュリティ制御を含める
    • 固有のツールやフレームワークに言及する
    • 実際の開発パターンとプラクティスに合わせる
  3. 例を分かりやすく構成する: 次の形式で例を整理します。
    • 明確なセクション見出しとラベル
    • 一貫したフォーマットとインデント
    • 重要なポイントを説明する詳細なコメント
    • 異なるコンポーネントを区別するためのタグ
  4. コンテキストを含める: 各例に次の情報を含めます。
    • 具体的なビジネスシナリオ
    • 関連インフラの詳細
    • 導入済みのセキュリティ制御
    • 期待される動作と結果
以下に、これらの原則を反映したポリシー例を示します。

BLASTポリシーの例

ポリシータイプ:BLAST

誤検知ポリシーの例

ポリシータイプ:誤検知

修正ポリシーの例

次は、XSS脆弱性を防ぐカスタムミドルウェアを使用したFixポリシーの例です。 ポリシータイプ:修正
このコンテキストを提供することで、Corgeaはカスタムセキュリティミドルウェアと適切に連携し、XSS対策のセキュアコーディングガイドラインに沿った修正を生成できます。 ポリシータイプ:修正
ビジネス環境、セキュリティ制御、インフラについて十分なコンテキストを提供すると、Corgeaはお客様固有の要件に合った、より正確で関連性の高いセキュリティ分析を実行できます。

Preworkで生成されるポリシー

会社でPreworkを有効にすると、Corgeaはメインスキャンが完了する前に、プロジェクトのコンテキストを基にポリシーを生成できます。
  • 生成されたポリシーは Policies テーブルに表示され、SourceGenerated By Corgea Prework になります。
  • スキャン詳細の Policies タブには、そのスキャンに適用されたすべてのポリシーが表示されます。アーカイブ済みまたは非アクティブな古いバージョンも含まれ、各ポリシーを開いて詳細を確認できます。
  • Policies > SettingsPolicy Review が有効な場合、生成されたポリシーは Inactive として作成され、チームが確認してから手動で有効化できます。

ポリシーを生成する

PolicyIQページでは、いつでもポリシー生成を手動で開始できます。
1

「Generate Policy」をクリック

PolicyIQ ページの右上にある Generate Policy ボタンをクリックします。
2

生成フォームに入力

ダイアログで Pattern(例: Authentication)、ProjectPolicy Type を選択し、Generate をクリックして開始します。
3

Preworkの完了を待つ

Corgeaはバックグラウンドで Corgea-Prework スキャンを実行し、プロジェクトを分析します。Scans ページで進捗を確認できます。
4

生成されたポリシーを確認

完了すると、生成されたポリシーが Policies テーブルに表示されます。ポリシーをクリックすると、プロジェクトで検出された実際のコードパターンが記載された説明など、詳細を確認できます。

CorgeaポリシーのYAML設定

corgea.yamlファイルを使用して、プロジェクトのセキュリティポリシーを定義できます。この設定ファイルでは、次のような詳細なポリシーを指定できます。
  • 特定のCWE識別子
  • サブフォルダに合わせたポリシー
  • 新しいポリシーを別のブランチでテスト
この機能は Scale または Enterprise プランで利用でき、別途有効化が必要です。詳細は https://corgea.com/contact からお問い合わせください。 設定例はサンプルリポジトリで確認できます。 全体に適用するポリシーの例はメインポリシーを参照してください。 サブフォルダ固有のポリシー例は次のとおりです。 これらの設定を使用すると、各フォルダの役割を考慮して脆弱性を検出できます。特にモノレポで、フォルダごとに適切なコンテキストを設定する場合に役立ちます。

corgea.yaml の更新ワークフロー

1

ブランチを作成してスキャンを開始

corgea.yamlファイルを含む新しいブランチを作成し、プルリクエストを開きます。これにより、そのブランチのスキャンが自動的に開始されます。プロジェクトページから手動でスキャンを開始することもできます。
2

ポリシーファイルを確認

PolicyIQページを開き、Policy File in Repos セクションを確認します。
3

ポリシーファイルから生成されたポリシーを確認

このセクションをクリックし、corgea.yamlファイルから生成されたポリシーを確認します。
4

`Associated Issues`をクリック

Associated Issues列をクリックすると、このポリシーによって検出された問題を確認できます。
5

更新と検証を繰り返してPRをマージ

期待する結果が得られるまで変更と検証を繰り返します。完了したらプルリクエストをマージし、corgea.yamlファイルをメインブランチに取り込みます。

corgea.yaml の基本設定

corgea.yamlの基本構成は次のとおりです。
  • type: ポリシーの種類です。scan、false_positive、fixのいずれかを指定します。
  • description: ポリシーの内容です。脆弱性の検出方法を調整するための追加コンテキストや、社内セキュリティガイドラインを記述します。

corgea.yaml の高度な設定

必要に応じて、次のフィールドも追加できます。
  • instruction_type: ポリシーの指示をCorgeaの組み込みポリシーと組み合わせる方法を指定します。"append"または"overwrite"を設定できます。"append"では指示を組み込みポリシーに追加して両方のルールセットを維持し、"overwrite"(デフォルト)ではCorgeaのデフォルト動作を完全に置き換えます。
  • guidance_text: ポリシーに関連する問題を表示するときに開発者へ示す、任意の固定ガイダンスです。チーム固有の指示、社内リンク、修正に必要なコンテキストなどに使用します。
  • cwes: fixまたはfalse_positiveにのみ適用されます。ポリシーの対象を特定のCWEに限定できます。 例:
  • excludes: 特定のポリシーによるスキャンからパスを除外する場合、グロブ式で対象ファイルを指定します。
  • ignore_paths: すべてのスキャンと新規問題の作成からフォルダを除外する場合に指定します。 (注: ここで指定したファイルパスは、特定のポリシーだけでなく全体で無視されます。**/vendor/**のようなパターンは、任意のディレクトリ階層に一致します。)
  • path: サブフォルダごとにcorgea.yamlを配置する代わりに、パスを指定して設定を一元管理できます。
mini-juice-shopでcorgea.yamlを一元管理する例はこちらです。
一元管理用のYAMLを含むブランチでスキャンを開始すると、次のように表示されます。
1

PolicyIQページに生成された5つのポリシーが表示されます

2

各ポリシーと対応するパスを確認できます