> ## 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.

# ファインディングと検出

> 脆弱性そのものを表すエンドポイントと、1回のスキャンでの報告を表すエンドポイントの違い

APIでは、脆弱性を2つのレベルで扱います。

* **検出**(detection)は、1回のスキャンで報告された脆弱性の1件の発生です。ファイルと行、パッケージとCVE、またはIaCルールなど、そのスキャンが報告した内容そのものを表します。スキャンを実行するたびに、新しいIDを持つ新しい検出が作成されます。**Issues**に分類されているエンドポイントが返すのは検出であり、*問題*(issue)と*検出*は同じものを指します。
* **ファインディング**(finding)は、1つのプロジェクトにおける脆弱性そのものです。その脆弱性を検出したすべてのスキャンにまたがって存在し、スキャン間で変わらない1つのIDを持ちます。ステータス、コメント、担当者、受け入れ済みリスクの有効期限、期限、SLAといったトリアージ情報は、ファインディングに保持されます。

> [!NOTE]
>
> **`/detections`は`/issues`と同じAPIで、名前だけが新しくなったものです。** **Issues**に分類されているすべてのエンドポイントは`/detections`配下でも提供され、コード、パラメーター、レスポンスはまったく同じです。「issue」という名前はファインディングと混同されやすかったため、`/detections`と呼ぶことにしました。各結果は1回のスキャンにおける脆弱性の検出であり、脆弱性そのものではありません。新しい連携では`/detections`を使用してください。`/issues`も引き続きサポートされるため、既存の連携を変更する必要はありません。

![3回のスキャンがそれぞれ独自の検出を持ち、トリアージの判断を保持する1つのファインディングを指している図](https://mintcdn.com/corgea/iJfCXTeBC6cZmqD9/images/api/findings-detections-light.ja.svg?fit=max\&auto=format\&n=iJfCXTeBC6cZmqD9\&q=85\&s=3ec4139c4ba2107dac9aaf45bd0f7237)

| | ファインディング | 検出(問題) |
| - | - | - |
| 何を表すか | 1つのプロジェクトにおける1つの脆弱性 | 1回のスキャンにおけるその脆弱性の1件の発生 |
| ID | 再スキャン、ブランチ、フィンガープリントの移行を経ても同じUUID | スキャンごとに新しいID |
| トリアージ | ここに保持される | ファインディングの内容を反映する |
| 用途 | チケット同期、一括トリアージ、メトリクス、「まだ未対応か?」の確認 | コード、行番号、修正、スキャンごとのレポート |
| もう一方へのリンク | `latest_detection.id` | `finding_id` |

## 2つのレベルを行き来する

各検出の項目には、そのファインディングの`finding_id`が含まれます。検出をまとめる際は、必ずこのIDでグループ化してください。`first_detection_date`はファインディングの属性であってキーではないため、グループ化には使えません。このフィールドが`null`になるのは、ファインディングが導入される前に取り込まれた検出だけです。

各ファインディングには`latest_detection`が含まれます。これは最新の検出で、検出エンドポイントが受け取るIDと、種別ごとの位置情報(`file_path`と`line_number`、`path`、`package`と`version`と`cve`、または`path`、`rule_id`、`start_line`と`end_line`)を持ちます。

どちらのレベルで行ったトリアージの変更も、ファインディングに反映され、そのすべての検出にも反映されます。

## 呼び出すエンドポイントの選び方

| 目的 | 呼び出すエンドポイント |
| - | - |
| スキャンが報告したすべての内容をコードの位置付きで取得する | `GET /api/v1/scan/{scan_id}/detections`と、SCA、コンテナ、IaC向けの各バリエーション |
| 1件の発生に対する説明と修正を取得する | `GET /api/v1/detections/{issue_id}` |
| 脆弱性ごとに1行ずつ、プロジェクト、ステータス、緊急度で絞り込んで取得する | `GET /api/v1/findings` |
| 前回の同期以降の変更を取得する | `GET /api/v1/findings?status_changed_since=…` |
| スキャンやプロジェクトとともに検出が削除された脆弱性を取得する | `GET /api/v1/findings?detection_state=retired` |
| 1つの脆弱性のトリアージ状態を取得する | `GET /api/v1/findings/{finding_id}` |
| 複数の脆弱性のステータスを変更する | `finding_ids`または`rule`を指定した`PATCH /api/v1/triage/findings` |
| 1件の検出を通じてステータスを変更する(変更はそのファインディングに反映されます) | `PATCH /api/v1/detections/{issue_id}` |

## 検出エンドポイント

`/detections`は**Issues**に分類されているエンドポイントの新しい名前であり、別のAPIではありません。いずれも両方のパスで応答します。

| Issuesのパス | Detectionsのパス |
| - | - |
| `/api/v1/issues` | `/api/v1/detections` |
| `/api/v1/issue/{issue_id}` | `/api/v1/detections/{issue_id}` |
| `/api/v1/issues/sca`、`/api/v1/issues/sca/{issue_id}` | `/api/v1/detections/sca`、`/api/v1/detections/sca/{issue_id}` |
| `/api/v1/issues/container`、`/api/v1/issues/iac` | `/api/v1/detections/container`、`/api/v1/detections/iac` |
| `/api/v1/scan/{scan_id}/issues`とそのバリエーション | `/api/v1/scan/{scan_id}/detections`とそのバリエーション |

どちらのパスも同じコードを実行し、`issues`キーや`total_issues`キーを含めて同じレスポンスを返します。新しい連携では`/detections`を使用してください。`/issues`も引き続きサポートされます。

## ファインディングエンドポイント

`GET /api/v1/findings`は、ファインディングごとに1行を、初めて検出された日時の新しい順に返します。`page`と`page_size`(最大100)でページネーションでき、`total_findings`に件数が含まれます。特に記載がない限り、フィルターにはカンマ区切りのリストを指定できます。

| パラメーター | 値 |
| - | - |
| `issue_type` | `sast`、`secret`、`logic_auth`、`code_quality`、`dependency`、`container`、`iac`。デフォルト:トークンが表示できるすべてのセキュリティ種別(`code_quality`を除く) |
| `status` | `open`、`fix_in_progress`、`accepted_risk`、`false_positive`、`fixed`、`duplicate` |
| `urgency` | `CR`、`HI`、`ME`、`LO` |
| `project_id` | プロジェクトID |
| `project` | プロジェクト名(1件) |
| `repo` | リポジトリURLの部分文字列 |
| `cwe` | `CWE-79`または`79` |
| `detection_state` | `active`(デフォルト)、`retired`、`all` |
| `status_changed_since` | ISO 8601形式の日時、または日付(UTCの午前0時として解釈)。この時点より後にトリアージが変更されたファインディング |
| `created_since` | ISO 8601形式の日時、または日付(UTCの午前0時として解釈)。この時点より後に初めて検出されたファインディング |
| `assigned_to` | ユーザーID(1件) |
| `sort_by` | `-created_at`(デフォルト)、`created_at`、`urgency`、`-urgency`、`status`、`-status`、`status_changed_at`、`-status_changed_at`。`created_at`はファインディングが初めて検出された日時で、`created_since`が絞り込みに使う値と同じです。レスポンスには含まれず、ファインディングの最も古い検出がスキャンとともに削除されていない限り、`first_detection_date`と一致します |

`branch`フィルターはありません。ファインディングはプロジェクトに属し、ブランチはその検出の属性だからです。トークンには、その種別の検出一覧と同じ表示権限が必要です。表示権限のない種別を指定すると`403`になります。

`GET /api/v1/findings/{finding_id}`は、同じ形式でファインディングを1件返します。トリアージ関連のフィールドに加えて、`urgency`、`classification`、`project`、`detection_state`、`first_detection_date`、`last_detection_date`、`detections_count`、`latest_detection`が含まれます。

### `detection_state`

ファインディングは、プロジェクト内に検出が存在する間は`active`です。最後の検出がスキャンまたはプロジェクトとともに削除されると`retired`になります。再スキャンで報告されなくなったファインディングはretiredにはなりません。`active`のまま、`status`が`fixed`になります。retiredになったファインディングもトリアージ情報を保持するため、検出が再び現れた場合は同じファインディングIDに紐付けられ、同じ判断が引き継がれます。

> [!NOTE]
>
> アカウントのファインディングインデックスの構築が完了するまで、`detection_state`は`null`になり、`GET /api/v1/findings`は`404`を返します。検出エンドポイントと`GET /api/v1/findings/{finding_id}`には影響しません。

## ファインディング単位のトリアージ

`PATCH /api/v1/triage/findings`は`finding_ids`を受け付けます。ファインディングID(`GET /api/v1/findings`の結果、または検出項目の`finding_id`から取得)のリスト、あるいは検出IDのリストを指定できます。ファインディングIDはそのファインディングの最新の検出を表し、判断はファインディングのすべての検出に反映されます。どこにも一致しないIDは`unresolved_ids`として返され、不一致として扱われるため、古いIDが含まれていても残りのIDには適用されます。一括トリアージの対象はSAST、シークレット、ロジック、コード品質、依存関係の各種別です。コンテナまたはIaCのIDは`unresolved_ids`として返され、監査行の`finding_type`は`sast`または`sca`になります。

`rule`には`statuses`のスコープを指定できます。たとえば、現在受け入れ済みリスクになっているすべてのファインディングを、1回の呼び出しで誤検知に変更できます。

## 同期ループの例

チケットのキーにはファインディングIDを使用してください。検出IDはスキャンごとに変わりますが、ファインディングIDは変わりません。

1回の実行で3つの一覧を読み取り、1回の一括更新を行います。一覧はすべてページ分割されるため、`page_size=100`を指定し、`page`が`total_pages`に達するまで`page=1, 2, …`と順に取得してください。実行の開始時刻をUTCの完全なISO 8601形式の日時として保存し、次回の`<前回の実行時刻>`に指定します。

1. `GET /api/v1/findings?created_since=<前回の実行時刻>`:新しいファインディングごとにチケットを作成します。新しいファインディングにはまだトリアージの変更がないため、手順2では返されません。
2. `GET /api/v1/findings?status_changed_since=<前回の実行時刻>&detection_state=all`:retiredのファインディングを含め、トリアージの変更を反映します。`status`が`fixed`になったファインディングは、対応するチケットをクローズします。
3. `GET /api/v1/findings?detection_state=retired`:retiredのファインディングを照合します。retiredになっても時刻は記録されず、ステータスも変わらないため、どちらのカーソルでも返されません。この一覧全体を未完了のチケットと照合し、一覧に含まれるものをクローズするか、フラグを付けてください。検出が再び現れると、ファインディングは同じIDのまま`active`に戻ります。
4. `finding_ids`を指定した`PATCH /api/v1/triage/findings`:チケットシステムで行った判断をCorgeaに書き戻します。`200`が返った場合でも`unresolved_ids`を確認してください。そこに含まれるIDは更新されていません。コンテナとIaCのファインディングのIDもすべてここに含まれます。バッチ内のその他のIDは更新されています。

コード品質のファインディングも同期する場合は、各一覧の呼び出しに`issue_type`を指定してください。デフォルトでは除外されます。`GET /api/v1/findings`が`404`を返した場合は、同期対象がないのではなく、アカウントのファインディングインデックスの構築が完了していないことを意味します。前回のカーソルを保持したまま、後で再試行してください。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.