> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corgea.app/llms.txt
> Use this file to discover all available pages before exploring further.
# PolicyIQ
> ポリシーを通じてCorgeaにビジネスコンテキストを追加
**前提条件** [スキャン](scanning)が完了しており、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 Policy**と**Append to Corgea Default Policy**の2つの選択肢が表示されます。
* ポリシーを全体に適用する場合は、**Projects**、**File Pattern (Glob)**、**CWEs**を空欄にします。
* プロジェクトアクセス制御が有効な場合、プロジェクト単位で権限を付与されたユーザーは、閲覧権限のあるポリシーを表示できます。ただし、編集または削除できるのは、そのユーザーがアクセスできるプロジェクトだけを対象とするポリシーに限られます。
Policy Playgroundでテストできるのは、**BLAST**ポリシーと**False Positive**ポリシーのみです。**Fix**ポリシーはPolicy Centerから引き続き作成できますが、修正のテストにはまだ対応していないため、Playgroundでは\*\*Fix (coming soon)\*\*と表示されます。
### ポリシーをテストする
ポリシーをテストするには、**Project**と**file**を選択し、**Test**をクリックします。スキャン中はボタンに\*\*Testing…\*\*のスピナーが表示され、完了するまでボタンは無効になります。必須項目が不足している場合は、ボタンの下にインラインメッセージが表示され、追加が必要な項目（プロジェクト、ファイル、ポリシーの指示）が示されます。
デフォルトでは、ファイル選択画面には問題が検出されているファイルだけが表示されます。まだ存在しないファイルでテストするには、**New Test File**を有効にし、プロジェクトを選択してファイル名を入力します。選択したプロジェクトからスキャンに必要な言語とフレームワークのコンテキストが提供されるため、エディターに任意のコードを記述してポリシーをテストできます。
### 結果のレビュー
スキャンが完了すると、ファイルプレビューの下にある結果パネルに検出結果が表示されます。各検出結果は展開可能な行で、**severity**、**CWE**、**line number**が表示されます。行を展開すると説明を確認でき、**Jump to line**を選択するとファイルプレビューの該当行へ移動できます。
スキャンが完了しても一致する検出結果がなかった場合、パネルに**No issues found for this policy**と表示されます。これにより、問題が見つからなかった場合でもテストが実行されたことを確認できます。
## PRスキャンとコメントルール
PRスキャンとコメントルールでは、Corgeaがプルリクエストをスキャンする条件と、検出結果をプルリクエストへコメントする条件を制御します。
* **Scan Only**はプルリクエストをスキャンしますが、検出結果のコメントは投稿しません。
* **Scan & Comment**はスキャンを実行し、ルールに一致する検出結果へコメントします。
* **Severity**は、ルールに一致する対象を選択した重大度に限定します。すべての重大度を対象にする場合は空欄にします。
* **Classification to comment**は、コメントする対象を選択したCWEタイプに限定します。一致するすべてのCWEへコメントする場合は空欄にします。
* **Projects**と**Project 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
```
Business Context: Our application processes healthcare data behind a secure API gateway that handles encryption. Internal services communicate over a private network with mutual TLS. All database access is through our custom ORM that implements row-level encryption.
Description: Review code considering our infrastructure. Flag potential PHI exposure but account for our API gateway encryption. Consider our network segregation when evaluating internal service communication. Verify proper use of our custom ORM for database access.
Use Cases:
- Detecting direct database access bypassing our ORM
- Identifying services accidentally exposed outside the API gateway
- Finding improper internal service authentication
- Detecting logging of pre-encryption PHI
- Identifying misuse of our security infrastructure
```
### 誤検知ポリシーの例
**ポリシータイプ**:誤検知
```
Business Context: Our test environments use sanitized data and mock services. All external services are replaced with stubs. The test network is isolated and all traffic is monitored. We use a custom test framework that simulates security controls.
Description: Consider our test infrastructure when evaluating security issues. Data that appears sensitive is actually sanitized. External service calls are mocked. Network isolation provides additional security layers.
Use Cases:
- Validating test data handling
- Confirming proper use of service mocks
- Verifying test environment isolation
- Checking sanitized data usage
- Validating test security controls
```
### 修正ポリシーの例
次は、XSS脆弱性を防ぐカスタムミドルウェアを使用したFixポリシーの例です。
**ポリシータイプ**:修正
````
Business Context: We use a custom security middleware called "SecureMiddleware" that provides XSS protection, among other security features. All web applications must use this middleware for request handling. The middleware automatically sanitizes user input and encodes output to prevent XSS attacks.
Description: Generate fixes that integrate with our SecureMiddleware for XSS protection. Use the built-in sanitization and encoding functions provided by the middleware. Follow our secure coding guidelines for handling user input and rendering output.
Use Cases:
- Implementing XSS protection using SecureMiddleware
Example:
```javascript
// Import the SecureMiddleware
import SecureMiddleware from '../middleware/SecureMiddleware';
// Use the middleware for request handling
router.get('/profile', SecureMiddleware.sanitizeInput(), (req, res) => {
const username = req.query.username; // Username is now sanitized
// Render the profile page with encoded output
res.render('profile', {
username: SecureMiddleware.encodeOutput(username)
});
});
`` `
In this example, the `SecureMiddleware.sanitizeInput()` function is used to sanitize the `username` parameter from the query string, preventing XSS attacks through user input. The `SecureMiddleware.encodeOutput()` function is then used to encode the `username` value before rendering it in the template, preventing XSS attacks through output rendering.
- Integrating with our centralized security middleware
Example or description: [Add an content]
- Following secure coding practices for user input handling
Example or description: [Add an content]
- Implementing context-specific XSS protection measures
Example or description: [Add an content]
````
このコンテキストを提供することで、Corgeaはカスタムセキュリティミドルウェアと適切に連携し、XSS対策のセキュアコーディングガイドラインに沿った修正を生成できます。
**ポリシータイプ**:修正
```
Business Context: We use a custom security framework that provides encryption, authentication, and audit logging. All services must use our security middleware. We have specific requirements for key rotation and cipher selection.
Description: Generate fixes that integrate with our security framework. Use our standard middleware components. Follow our encryption standards and key management practices. Ensure proper audit logging through our centralized system.
Use Cases:
- Implementing framework-compliant security controls
Example or description: [Add an content]
- Integrating with our authentication services
Example or description: [Add an content]
- Setting up proper audit logging
Example or description: [Add an content]
- Configuring encryption using our standards
Example or description: [Add an content]
- Establishing service-to-service authentication
Example or description: [Add an content]
- Implementing environment-specific security measures
Example or description: [Add an content]
```
ビジネス環境、セキュリティ制御、インフラについて十分なコンテキストを提供すると、Corgeaはお客様固有の要件に合った、より正確で関連性の高いセキュリティ分析を実行できます。
## Preworkで生成されるポリシー
会社でPreworkを有効にすると、Corgeaはメインスキャンが完了する前に、プロジェクトのコンテキストを基にポリシーを生成できます。
* 生成されたポリシーは **Policies** テーブルに表示され、`Source` は **Generated By Corgea Prework** になります。
* スキャン詳細の **Policies** タブには、そのスキャンに適用されたすべてのポリシーが表示されます。アーカイブ済みまたは非アクティブな古いバージョンも含まれ、各ポリシーを開いて詳細を確認できます。
* **Policies > Settings** で **Policy Review** が有効な場合、生成されたポリシーは **Inactive** として作成され、チームが確認してから手動で有効化できます。
### ポリシーを生成する
PolicyIQページでは、いつでもポリシー生成を手動で開始できます。
**PolicyIQ** ページの右上にある **Generate Policy** ボタンをクリックします。
ダイアログで **Pattern**（例: Authentication）、**Project**、**Policy Type** を選択し、**Generate** をクリックして開始します。
Corgeaはバックグラウンドで **Corgea-Prework** スキャンを実行し、プロジェクトを分析します。**Scans** ページで進捗を確認できます。
完了すると、生成されたポリシーが **Policies** テーブルに表示されます。ポリシーをクリックすると、プロジェクトで検出された実際のコードパターンが記載された説明など、詳細を確認できます。
## CorgeaポリシーのYAML設定
`corgea.yaml`ファイルを使用して、プロジェクトのセキュリティポリシーを定義できます。この設定ファイルでは、次のような詳細なポリシーを指定できます。
* 特定のCWE識別子
* サブフォルダに合わせたポリシー
* 新しいポリシーを別のブランチでテスト
この機能は `Scale` または `Enterprise` プランで利用でき、別途有効化が必要です。詳細は [https://corgea.com/contact](https://corgea.com/contact) からお問い合わせください。
設定例は[サンプルリポジトリ](https://github.com/Corgea/mini-juice-shop)で確認できます。
全体に適用するポリシーの例は[メインポリシー](https://github.com/Corgea/mini-juice-shop/blob/main/corgea.yaml)を参照してください。
サブフォルダ固有のポリシー例は次のとおりです。
* [Frontend Policies](https://github.com/Corgea/mini-juice-shop/blob/main/frontend/corgea.yaml)
* [Backend Policies](https://github.com/Corgea/mini-juice-shop/blob/main/backend/corgea.yaml)
これらの設定を使用すると、各フォルダの役割を考慮して脆弱性を検出できます。特にモノレポで、フォルダごとに適切なコンテキストを設定する場合に役立ちます。
### corgea.yaml の更新ワークフロー
corgea.yamlファイルを含む新しいブランチを作成し、プルリクエストを開きます。これにより、そのブランチのスキャンが自動的に開始されます。プロジェクトページから手動でスキャンを開始することもできます。
PolicyIQページを開き、`Policy File in Repos` セクションを確認します。
このセクションをクリックし、corgea.yamlファイルから生成されたポリシーを確認します。
`Associated Issues`列をクリックすると、このポリシーによって検出された問題を確認できます。
期待する結果が得られるまで変更と検証を繰り返します。完了したらプルリクエストをマージし、corgea.yamlファイルをメインブランチに取り込みます。
### corgea.yaml の基本設定
corgea.yamlの基本構成は次のとおりです。
```
# This is the corgea YAML file used for defining and managing security policies within applications.
# For more information, visit: https://docs.corgea.app/policies
version: 1 # Specifies the version of the corgea YAML standard being used. Update only if the standard changes.
policies:
- type: "scan"
description: >
This section ensures that all directories and files are thoroughly scanned to detect any security vulnerabilities in the backend code.
It is essential to identify and address potential issues such as SQL injection, exposure of sensitive data, and unauthorized access.
Comprehensive scanning helps maintain the security and integrity of the application.
```
* `type`: ポリシーの種類です。scan、false\_positive、fixのいずれかを指定します。
* `description`: ポリシーの内容です。脆弱性の検出方法を調整するための追加コンテキストや、社内セキュリティガイドラインを記述します。
## corgea.yaml の高度な設定
必要に応じて、次のフィールドも追加できます。
* `instruction_type`: ポリシーの指示をCorgeaの組み込みポリシーと組み合わせる方法を指定します。`"append"`または`"overwrite"`を設定できます。`"append"`では指示を組み込みポリシーに追加して両方のルールセットを維持し、`"overwrite"`（デフォルト）ではCorgeaのデフォルト動作を完全に置き換えます。
* `guidance_text`: ポリシーに関連する問題を表示するときに開発者へ示す、任意の固定ガイダンスです。チーム固有の指示、社内リンク、修正に必要なコンテキストなどに使用します。
```
policies:
- type: "fix"
instruction_type: "append"
guidance_text: >
Use our secure logging utility and do not log raw request payloads.
description: >
Additionally, ensure all fixes integrate with our custom SecureMiddleware framework
and follow our internal security guidelines for key rotation.
cwes:
- "CWE-79" # XSS
```
* `cwes`: fixまたはfalse\_positiveにのみ適用されます。ポリシーの対象を特定のCWEに限定できます。
例:
```
cwes:
- "CWE-20" # CWE-20: Improper Input Validation
- "CWE-78" # CWE-78: Improper Neutralization of Special Elements used in an OS Command ('OS Command Injection')
- "CWE-209" # CWE-209: Information Exposure Through an Error Message
- "CWE-362"
- "CWE-79"
```
* `excludes`: 特定のポリシーによるスキャンからパスを除外する場合、グロブ式で対象ファイルを指定します。
```
excludes:
- "config/*"
- "migrations/*"
```
* `ignore_paths`: すべてのスキャンと新規問題の作成からフォルダを除外する場合に指定します。
（注: ここで指定したファイルパスは、特定のポリシーだけでなく全体で無視されます。`**/vendor/**`のようなパターンは、任意のディレクトリ階層に一致します。）
```
ignore_paths:
- "test/*"
```
* `path`: サブフォルダごとにcorgea.yamlを配置する代わりに、パスを指定して設定を一元管理できます。
mini-juice-shopでcorgea.yamlを一元管理する例は[こちら](https://github.com/Corgea/mini-juice-shop/blob/central_corgea_yaml/corgea.yaml)です。
```
# This is the corgea YAML file used for defining and managing security policies within applications.
# For more information, visit: https://docs.corgea.app/policies
version: 1 # Specifies the version of the corgea YAML standard being used. Update only if the standard changes.
policies:
- type: "scan"
path: 'backend'
description: >
...
- type: "scan"
path: 'frontend'
description: >
...
- type: "fix"
path: 'backend'
description: >
...
cwes:
- "CWE-22" # CWE-22: Improper Limitation of a Pathname to a Restricted Directory ('Path Traversal')
- type: "false_positive"
path: 'backend'
description: >
....
cwes:
- "CWE-20" # CWE-20: Improper Input Validation
- type: "false_positive"
path: "frontend"
description: >
...
cwes:
- "CWE-79" # CWE-79: Improper Neutralization of Input During Web Page Generation ('Cross-site Scripting')
```
一元管理用のYAMLを含むブランチでスキャンを開始すると、次のように表示されます。
