Findings、Answers、Reports

このガイドでは、workflow finding、analysis answer、report の違いと、それぞれをどこで読むかを説明します。

result surface には 3 つの別々の resource があります。

• Finding: workflow run に属し、rule result、rule provenance、result state、limitation、evidence を記録します。
• Answer: analysis run に属し、analysis profile が名前を付ける typed field、coverage、provenance、result state、limitation、evidence を持ちます。
• Report: 既存の answer data を表示します。run create では ID と version を持つ保存済み report template を使い、新しい表示 view には rerender endpoint の inline template を使います。

どの resource も uncertainty を clean pass に変換しません。

Workflow の検出結果

ワークフロー run の検出結果を一覧取得します。

curl --fail-with-body --get "$BASE_URL/api/v1alpha1/findings" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  --data-urlencode "run_id=$RUN_ID" \
  --data-urlencode "result_state=uncertain"

finding response の field は snake_case です。

{
  "id": "finding_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
  "run_id": "run_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
  "workflow_id": "wf_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
  "rule_id": "rule_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
  "rule_reference": "SEC-04",
  "result_state": "uncertain",
  "status": "open",
  "evidence": [
    {
      "id": "evidence_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
      "video_id": "vid_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
      "start_time": 42.25,
      "end_time": 49.75,
      "clip_url": "https://cdn.example.test/media/clip.mp4"
    }
  ]
}

GET /api/v1alpha1/findings/{finding_id} で 1 件の検出結果を取得します。evidence URL は確認可能な product URL です。result state は found、not_found、uncertain、not_checked です。

Analysis answer

analysis run の answer は次の route で取得します。

GET /api/v1alpha1/runs/{run_id}/answers

Answer には answer_type、typed field、coverage、limitations、provenance、evidence reference があります。events、evidence、snapshot、provenance の深い内容が必要な場合は expand[] を使います。request language は Analysis、表示 language は Reports And Templates で説明します。

完了した回答を JSON または Markdown にする場合は、レポートを生成 に進んでください。

Trust field

result を保存または export するときは、result_state、limitations、provenance_ref、evidence URL を保持してください。claim を evidence に追跡できない report は不完全です。

report manifest に署名付き evidence URL が含まれる場合、evidence_urls_expire_at はその有効期限を示します。evidence ID を保持し、有効期限が切れた URL は GET /api/v1alpha1/evidence/{evidence_id} で更新してください。この endpoint は 302 Found と新しい署名付き media URL、Cache-Control: no-store を返します。