# リスクフォーカス型ブラックボックス診断が Takumi API で利用可能に

Web コンソールで提供してきた[リスクフォーカス診断](/docs/ja/r/202602-takumi-risk-focus)が、[Takumi API](/docs/ja/t/api) のブラックボックス診断でも利用可能になりました。

リスクフォーカス型診断は、**指定したクレジットの範囲内で、優先度の高い機能・観点から診断**を進めるものです。優先度は明示的に指定することも、Takumi に優先度づけを任せることもできます。クレジット上限に達すると、Takumi はそこまでの診断結果（レポート等）を出力して中断します。中断した診断に対して、クレジットを追加して続きから診断を再開することも可能です。

クレジット消費を予測可能にしたい場合や、予算内で重要な箇所を優先的に診断したい場合などに活用いただけます。

## 活用例

### 指定したクレジットの範囲内で診断する {#auto-prioritization}

診断する機能・観点の優先度づけを Takumi に任せ、指定したクレジットの範囲内で診断を実行するには、`crawl_credit_limit` および `scan_credit_limit` を指定してワークフローを呼び出します。クロールとスキャンそれぞれに対してクレジット上限を設定でき、片方だけの設定も可能です。以下の例では、クロール時のクレジット上限を 20、スキャン時のクレジット上限を 50 に設定しています（このとき、最大でも 70 クレジットの消費となります）。

```typescript
const { workflow_run_id } = await fetch(
  `${TAKUMI_API}/v1/o/${TAKUMI_ORG}/workflows/blackbox-assessment/dispatch`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      input: {
        language: "japanese",
        target_urls: ["https://app.example/"],

        crawl_credit_limit: 20, // クロールに使うクレジットの上限 (任意)
        scan_credit_limit: 50, // スキャンに使うクレジットの上限 (任意)
      },
    }),
  },
).then((r) => r.json());
```

クロールに使うクレジットの上限 `crawl_credit_limit` を指定した場合、クロール中にクレジット上限に達するとそこでクロールを終了し、そこまでに発見された機能に対してスキャンを実行します。

クロールの終了後、発見されたそれぞれの機能と観点の組み合わせに対して、Takumi がリスク分析に基づいて優先度を自動的に決定し、優先度の高いものから順にスキャンを実行します。スキャン中にクレジット上限 `scan_credit_limit` に達すると、そこまでの診断結果を出力して診断が終了します。

診断が終了すると、診断レポートや検出された脆弱性一覧に加え、「どの機能・観点は診断完了したのか」を示す `scan_progress` というアーティファクトが出力されます。

```js
{
  // 診断完了した機能・観点の組み合わせ
  "completed": [
    { "feature_name": "認証", "perspective": "Injection" },
    { "feature_name": "ユーザー設定", "perspective": "Authorization" },
    // ...
  ],
  // 診断の必要がないと判定されたためスキップされた組み合わせ
  "skipped": [
    { "feature_name": "Apex", "perspective": "CSRF" },
    // ...
  ],
}
```

より多くの機能・観点を診断したい場合は、[クレジットを追加して診断を続行する](#continue-assessment)を参照してください。

### 機能・観点の優先度を指定して、クレジット上限の範囲内で診断する {#custom-prioritization}

診断する機能・観点の優先度を明示的に指定することも可能です。ビジネスインパクトの大きさや前回診断からのアップデートの有無などに基づき、自由に優先度を調整できます。具体的には、[「一部だけ診断」「再診断」](/docs/ja/r/202603-takumi-api-blackbox-scoped-assessment)で用いる `pairs` パラメータに `priority` フィールドを指定します。

```typescript
const { workflow_run_id } = await fetch(
  `${TAKUMI_API}/v1/o/${TAKUMI_ORG}/workflows/blackbox-assessment/dispatch`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      input: {
        language: "japanese",
        target_urls: ["https://app.example/"],

        scan_credit_limit: 50, // スキャンに使うクレジットの上限 (任意)

        // クロールワークフローで発見された機能一覧を利用するよう指定
        resume: {
          kind: "assess_crawled_features",
          assess_crawled_features: {
            workflow_id: "blackbox-crawl",
            workflow_run_id: "TWR...", // クロールワークフローの実行 ID
          },
        },

        pairs: [
          // feature_name には、クロールワークフローの `features` アーティファクトに記載された機能名を指定
          { feature_name: "認証", perspective: "Injection", priority: "high" },
          {
            feature_name: "ユーザー設定",
            perspective: "Authorization",
            priority: "medium",
          },
          { feature_name: "商品カタログ", perspective: "XSS", priority: "low" },

          // 優先度を指定しない場合は、Takumi がリスク分析に基づいて自動的に優先度を判断
          { feature_name: "決済", perspective: "BusinessLogic" },
        ],
      },
    }),
  },
).then((r) => r.json());
```

診断中にクレジット上限に達して終了した場合に、どの機能・観点の組み合わせが診断完了したのかを確認する方法は、[「指定したクレジットの範囲内で診断する」](#auto-prioritization)の記載と同様です。

:::info

機能・観点の優先度を指定する場合は、事前に診断対象の機能を洗い出す必要があります。既に完了したクロールワークフローまたは診断ワークフローの `features` アーティファクトに記載された機能名を `pairs` に指定し、その `workflow_run_id` を `resume.assess_crawled_features` に指定してください。

:::

## クレジットを追加して診断を続行する {#continue-assessment}

クレジット上限に達して終了した診断や、一部の機能・観点だけを `pairs` に指定して実行した診断など、未診断の機能・観点がある診断に対して、クレジットを追加して続きから診断を再開できます。再開された診断では、前回の診断結果が引き継がれ、未診断の機能・観点のうち優先度の高いものから順に診断が進みます。

```typescript
const { workflow_run_id: next_workflow_run_id } = await fetch(
  `${TAKUMI_API}/v1/o/${TAKUMI_ORG}/workflows/blackbox-assessment/dispatch`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      input: {
        language: "japanese",
        target_urls: ["https://app.example/"],

        scan_credit_limit: 50, // 追加スキャンに使うクレジットの上限 (任意)

        resume: {
          kind: "continue_assessment",
          continue_assessment: {
            workflow_id: "blackbox-assessment",
            workflow_run_id: workflow_run_id, // 再開したい診断のワークフロー実行 ID
          },
        },

        // 診断する機能・観点の絞り込み・優先度の調整 (任意)
        pairs: [
          // feature_name には、再開元の診断ワークフローの `features` アーティファクトに記載された機能名を指定
          { feature_name: "認証", perspective: "Injection", priority: "high" },
          // ...
        ],
      },
    }),
  },
).then((r) => r.json());
```

診断を続行する際には、`pairs` パラメータを指定して診断対象を絞り込んだり、優先度を調整したりすることもできます。省略した場合は、未診断の機能・観点全てに対し Takumi がリスク分析に基づいて自動的に優先度を判断して診断を進めます。

このサイクル（診断 → 結果確認 → 再開）を繰り返すことで、結果を見ながら段階的に診断範囲を広げていくことも可能です。

## 制限事項

本機能は **Takumi API 経由で実行した診断に対してのみ**利用可能です。Web コンソールから実行した診断を API から続行したり、その逆を行うことはできません。詳細は API ユーザーガイドの「[Web コンソールの「診断」との関係](/docs/ja/t/api#relationship-with-existing-features)」をご覧ください。

## 利用開始方法

詳細は [API ドキュメント](/docs/ja/t/api)をご覧ください。