Findings API リファレンス

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

検出結果を一覧表示する

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>`

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

例

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

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"

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

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"

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

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"

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

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: 検証が完了し、その結果が検出結果のライフサイクルに適用された

ステータスを更新する

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 を指定できます。

重大度を上書きする

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 の非推奨エイリアスとしてのみ受け付けられます。

検出結果を再テストする

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 が更新されるため、変更ベースで処理するコンシューマーもこれらを検知できます。

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

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} を使用します。

パッチのサマリー

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 ガイドでは、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 を確認してください。検出結果の再テストを参照してください。

誤検知を記録する

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

Getting Started

Core Workflows

Advanced Features

Integrations

Help & Support

検出結果を一覧表示する

クエリパラメータ

レスポンス

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

例

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

ステータスを更新する

重大度を上書きする

検出結果を再テストする

コメント

パッチのサマリー

分析

MCP

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

誤検知を記録する

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

​クエリパラメータ

​レスポンス

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

​例

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

​ステータスを更新する

​重大度を上書きする

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

​コメント

​パッチのサマリー

​分析

​MCP

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

​誤検知を記録する

検出結果を一覧表示する

クエリパラメータ

レスポンス

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

例

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

ステータスを更新する

重大度を上書きする

検出結果を再テストする

コメント

パッチのサマリー

分析

MCP

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

誤検知を記録する