> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindfort.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Findings API リファレンス

> REST API と MCP で MindFort の検出結果を一覧表示、フィルタリング、トリアージ、再テストし、コメントを追加する方法を説明します。

検出結果をプログラムから閲覧するには、`GET /v1/findings` (API キー) または MCP の `list_findings` ツール (OAuth) を使用します。どちらも同じフィルターを使用し、同じサマリーフィールドを返します。

## 検出結果を一覧表示する

```bash theme={null}
curl -G "https://api.mindfort.app/v1/findings" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "target_id=${MINDFORT_TARGET_ID}" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "exclude_secured=true" \
  --data-urlencode "sort_by=severity" \
  --data-urlencode "limit=25"
```

### クエリパラメータ

| パラメータ | デフォルト | 説明 |
| - | - | - |
| `target_id` | — | 1 つのターゲットに絞り込み (**Target Inventory** の UUID) |
| `assessment_id` | — | 1 回のアセスメント実行の検出結果に絞り込み (**Assessments** の UUID) |
| `status` | `ACTIVE` | ライフサイクルフィルター: `ACTIVE`、`RESOLVED`、または `ARCHIVED` |
| `exclude_secured` | `false` | `true` の場合、情報提供用の secured プローブ (`severity=secured`) を除外 |
| `severity` | — | 重大度でフィルター: `critical`、`high`、`medium`、`low`、または `secured` (`info` は `secured` の非推奨エイリアス) |
| `sort_by` | `severity` | `severity` (スコアの高い順) または `created_at` |
| `order_direction` | `desc` | 並び順: `asc` または `desc` |
| `search` | — | 検出結果の ID、タイトル、説明、エンドポイント、影響を検索 |
| `status_filter` | — | 脆弱性フィルター: `vulnerable`、`secured`、または `all` |
| `active_only` | `false` | `true` の場合、アクティブな検出結果のみを返す |
| `org_wide` | `false` | 互換性のためのパラメータ。組織全体の結果を得るには `target_id` と `assessment_id` を省略 |
| `assigned_to_me` | `false` | `true` の場合、現在のユーザーに割り当てられた検出結果のみを返す |
| `assigned_to` | — | 担当者のユーザー ID でフィルター |
| `unassigned` | `false` | `true` の場合、担当者のいない検出結果のみを返す |
| `finding_type` | — | 公開 API で利用できるのは `red-team` の検出結果のみ |
| `limit` | `25` | ページサイズ (最大 `100`) |
| `offset` | `0` | ページネーション用のオフセット |

### レスポンス

`findings` の各項目には次のフィールドが含まれます。

| フィールド | 説明 |
| - | - |
| `id` | 検出結果の UUID |
| `assessment_id` | アセスメントに関連付けられている場合のアセスメント UUID |
| `target_name` | 利用可能な場合のターゲット名 |
| `finding_type` | 常に `red-team` |
| `title` | 検出結果のタイトル |
| `severity` | `critical`、`high`、`medium`、`low`、または `secured` |
| `severity_score` | 数値スコア (低重大度または secured の項目では `0` の場合あり) |
| `overridden_severity` | 設定されている場合、ユーザーが選択した重大度の上書き値 |
| `status` | `ACTIVE`、`RESOLVED`、または `ARCHIVED` |
| `target_id` | ターゲットの UUID |
| `created_at` | ISO 8601 タイムスタンプ |
| `updated_at` | 検出結果の最新の可視的な変更を示す ISO 8601 タイムスタンプ |
| `retest_status` | 再テストが存在する場合の現在の再テスト実行状態 |
| `retest_started_at` | 現在の再テストの実行が開始された日時 |
| `retest_completed_at` | 現在の再テストが完了または失敗した日時 |
| `retest_failure_reason` | 再テストを実行できなかった理由 (顧客に表示されるもの) |
| `retest_in_progress` | 再テストがキュー待ちまたは実行中の間は `true` |

レスポンスには、ページネーション用の `total`、`limit`、`offset`、`next_cursor` も含まれます。`offset + len(findings) >= total` になるまで `offset` を使用してください。`next_cursor` は不透明なページネーションマーカーです。

### ダッシュボードと一致させる

MindFort の UI では、API パラメータに対応するタブとフィルターを使用しています。

| ダッシュボードの表示 | API / MCP での対応 |
| - | - |
| **Open** (脆弱性のみ、デフォルト) | `status=ACTIVE` および `exclude_secured=true` |
| **Open** (secured プローブを含む) | `status=ACTIVE` (`exclude_secured` を省略、または `exclude_secured=false`) |
| **Resolved** | `status=RESOLVED` |
| **Archived** | `status=ARCHIVED` |
| 1 つのアセスメントの検出結果 | `assessment_id=<uuid>` |

> [!NOTE]
>
> `exclude_secured=true` を指定しない場合、一覧の結果には、ダッシュボードのデフォルトの Open タブでは非表示になっている情報提供用の **secured** プローブの検出結果 (`severity=secured`) が含まれます。API や MCP の件数が UI より多く見えるのは、これが原因である可能性があります。

### 例

**ターゲットの脆弱性 (デフォルトの Open タブと一致):**

```bash theme={null}
curl -G "https://api.mindfort.app/v1/findings" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "target_id=${MINDFORT_TARGET_ID}" \
  --data-urlencode "exclude_secured=true"
```

**特定のアセスメントの検出結果:**

```bash theme={null}
curl -G "https://api.mindfort.app/v1/findings" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "assessment_id=${MINDFORT_ASSESSMENT_ID}" \
  --data-urlencode "exclude_secured=true"
```

**アーカイブ済みの検出結果:**

```bash theme={null}
curl -G "https://api.mindfort.app/v1/findings" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "target_id=${MINDFORT_TARGET_ID}" \
  --data-urlencode "status=ARCHIVED"
```

## 検出結果の詳細を取得する

```bash theme={null}
curl "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}"
```

`description`、`impact`、`evidence`、`approach`、`remediation_advice`、`status`、再テストの判定コンテキストを含むすべてのフィールドを返します。

現在の実行状態は `retest_status` で判断します。

* `QUEUED`: 受け付け済みだが、まだ実行されていない
* `RUNNING`: 実行中
* `FAILED`: 実行を完了できなかった。`retest_failure_reason` を確認してください
* `COMPLETED`: 検証が完了し、その結果が検出結果のライフサイクルに適用された

## ステータスを更新する

```bash theme={null}
curl -X POST "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/status" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"status":"RESOLVED","resolve_reason":"FIX"}'
```

有効な値: `ACTIVE`、`RESOLVED`、`ARCHIVED`。`status` が `RESOLVED` の場合は、`resolve_reason` (`FIX` または `WONT_FIX`) と、任意の `resolve_context` (最大 2000 文字) を含めることができます。

一括更新は `POST /v1/findings/status` で利用でき、最大 50 件の `finding_ids` を指定できます。

## 重大度を上書きする

```bash theme={null}
curl -X PATCH "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/severity" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"severity":"high"}'
```

使用できる値: `critical`、`high`、`medium`、`low`、`secured`。上書きを解除するには `null` を渡します。`info` は `secured` の非推奨エイリアスとしてのみ受け付けられます。

## 検出結果を再テストする

```bash theme={null}
curl -X POST "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/retest" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}"
```

`ACTIVE`、`RESOLVED`、または `ARCHIVED` の検出結果に対して非同期の再テストを開始します。別の再テストがすでにキュー待ちまたは実行中の場合、リクエストは失敗します。

リクエストが受け付けられたら、`GET /v1/findings/{finding_id}` をポーリングします。再テストが完了すると、MindFort は検証結果を適用します。

* テストした条件下で問題が修正されたことを示す再テスト結果の場合、検出結果は `RESOLVED` になります。
* 問題が引き続き再現可能であることを示す再テスト結果の場合、検出結果は `ACTIVE` になります。
* 実行に失敗した場合、セキュリティ上の結果は変更されず、`retest_failure_reason` が設定されます。

再テストの `RUNNING` および `FAILED` への遷移では検出結果の `updated_at` が更新されるため、変更ベースで処理するコンシューマーもこれらを検知できます。

## コメント

```bash theme={null}
curl -G "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/comments" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "limit=25"
```

```bash theme={null}
curl -X POST "https://api.mindfort.app/v1/findings/${MINDFORT_FINDING_ID}/comments" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"content":"Patched in PR #482 — ready for retest."}'
```

編集には `PATCH /v1/findings/{finding_id}/comments/{comment_id}` を、削除には `DELETE /v1/findings/{finding_id}/comments/{comment_id}` を使用します。

## パッチのサマリー

```bash theme={null}
curl -G "https://api.mindfort.app/v1/findings/patches" \
  -H "Authorization: Bearer ${MINDFORT_API_KEY}" \
  --data-urlencode "limit=50"
```

パッチのアクティビティがある検出結果を、`pr_url`、`patch_status`、`patch_state` とともに返します。現在のユーザーの検出結果に限定するには `assigned_to_me=true` を、検出結果の ID、タイトル、説明、エンドポイント、影響で検索するには `search` を使用します。認可された組織には、プライベートリポジトリの URL を含め、保存されている GitHub プルリクエストの URL が返されます。パッチのアクティビティは、検出結果のライフサイクルステータスとは独立しています。

## 分析

検出結果の分析エンドポイントは、任意の `target_id` を受け付けます。組織全体のメトリクスを取得するには省略してください。`GET /v1/findings/severity-score-history` は `granularity` (`day`、`week`、または `month`) を受け付け、修正状況のメトリクスでは、さらに任意で両端を含む `from` と `to` の日付を指定できます。

| エンドポイント | 説明 |
| - | - |
| `GET /v1/findings/counts` | ライフサイクル、露出、重大度ごとの件数 |
| `GET /v1/findings/severity-distribution` | 重大度の分布 |
| `GET /v1/findings/category-distribution` | OWASP および脆弱性タグの分布 |
| `GET /v1/findings/severity-score-history` | 重大度スコアの履歴 |
| `GET /v1/findings/metrics/current` | 現在のセキュリティメトリクス |
| `GET /v1/findings/metrics/timeseries` | 時系列メトリクス (`from`、`to`、任意の `granularity`) |
| `GET /v1/findings/metrics/remediation` | 修正状況のメトリクス (MTTR) |
| `GET /v1/findings/metrics/sla` | SLA 違反のメトリクス |
| `GET /v1/findings/metrics/aging` | 検出結果の経過日数の区分 |

ターゲットのヘルススコアは `GET /v1/targets/{target_id}/health-score` で取得できます。

## MCP

[MCP ガイド](https://docs.mindfort.ai/ja/guides/mcp.md)では、`list_findings` ツールで同じ意味のフィルターを利用できます。`target_id`、`assessment_id`、`status`、`exclude_secured`、`severity`、`sort_by`、`order_direction`、`search`、または割り当てに関するフィルターを渡してください。MCP のコレクションツールは、生のオフセットではなく不透明な `cursor` を使用します。

サーバーの更新後に MCP を再インストールする必要は**ありません**。同じ `https://api.mindfort.app/mcp` URL のまま、エージェントを再起動するか新しいチャットを開始すれば、最新のツールスキーマが読み込まれます。

## 再テストの認証情報を復旧する

`retest_failure_code` が認証の失敗または利用できない認証情報を示している場合は、同じターゲットの代替の認証情報で再試行してください。公開の再テストリクエストでは、代替のプライマリ認証情報として `target_credential_id` を指定できます。2 つの認証情報を使用する検出結果で両方のアカウントを確認するには、ダッシュボードを使用してください。

代替の指定は、条件を満たす認証情報の失敗があった後にのみ許可されます。これにより今後の再テストで使用する認証情報が変更されますが、元の検出結果に記録された認証情報は変更されません。顧客に表示される説明については、`retest_failure_reason` を確認してください。[検出結果の再テスト](https://docs.mindfort.ai/ja/guides/retesting.md)を参照してください。

## 誤検知を記録する

検出結果のライフサイクルステータスを更新する際、誤検知と判断した場合は、`status: "ARCHIVED"`、`resolve_reason: "FALSE_POSITIVE"`、および判断の理由を説明する空でない `resolve_context` を使用します。`FIX` と `WONT_FIX` は、`RESOLVED` の検出結果に対する解決理由です。リクエストの完全な仕様については、ステータスエンドポイントのスキーマを参照してください。


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