# ブラックボックス診断の「一部だけ診断」「再診断」が Takumi API で利用可能に

Takumi のブラックボックス診断における「一部だけ診断」「再診断」はこれまで Web コンソールからのみ利用可能でしたが、[Takumi API](/docs/ja/t/api) 経由でもこれらの診断を実行できるようになりました。

- **一部だけ診断**: まず対象アプリケーションの機能をクロールし、Takumi が停止します。その後、診断したい機能や観点を選択して診断を実行します
- **再診断**: 過去の診断結果で脆弱性が指摘された箇所を指定して診断を実行します

これらをサポートするため、ブラックボックス診断 API に対し以下の拡充を行いました。

- クロールワークフロー `blackbox-crawl` を追加  
  対象アプリケーションをクロールし、洗い出した機能を出力するワークフローです。診断は行いません。
- 診断ワークフロー `blackbox-assessment` において、診断観点・機能を指定するオプションを追加  
  過去のワークフロー (クロール・診断) で洗い出した機能の中から、診断対象とする機能や観点を選択できます。

## 一部だけ診断

以下の流れで、機能・観点を絞り込んだ「一部だけ診断」を実現できます。

1. クロールワークフローを実行し、対象アプリケーションの機能を洗い出す
1. クロール結果をもとに診断対象とする機能・観点を選択し、診断ワークフローを実行する

重要度の高い箇所に絞って診断したい場合や、最近アップデートした機能だけを診断したい場合などに活用いただけます。

### クロールワークフローを実行

クロールワークフローは以下のように呼び出せます。

```typescript
const { workflow_run_id: crawl_workflow_run_id } = await fetch(
  `${TAKUMI_API}/v1/o/${TAKUMI_ORG}/workflows/blackbox-crawl/dispatch`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      input: {
        language: "japanese",
        target_urls: ["https://app.example/"],
      },
      notification: { webhook_endpoint_ids: [WEBHOOK_ID] },
    }),
  },
).then((r) => r.json());
```

### 機能・観点を選択して診断ワークフローを実行

クロールワークフローが完了したら、洗い出された機能一覧を確認します。クロールで発見された機能一覧は `features` という名前のアーティファクトとして出力されます。

```typescript
const featuresData = await fetch(
  `${TAKUMI_API}/v1/o/${TAKUMI_ORG}/workflows/blackbox-crawl/get-artifact-download-url`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      workflow_run_id: crawl_workflow_run_id,
      artifact_name: "features",
    }),
  },
)
  .then((r) => r.json())
  .then(({ url }) => fetch(url))
  .then((r) => r.json());

for (const feature of featuresData.features) {
  console.log("feature name:", feature.name); // => "認証", "ユーザー設定", "商品カタログ", ...
  console.log("feature description:", feature.description);
}
```

ここから診断したい機能名 (`feature.name`) と観点を選択し、クロールワークフローの ID を指定して、診断ワークフローを呼び出します。

```typescript
const { workflow_run_id: assessment_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/"],

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

        // 診断対象とする機能・観点を指定
        pairs: [
          { feature_name: "認証", perspective: "Injection" },
          { feature_name: "ユーザー設定", perspective: "Authorization" },
          { feature_name: "商品カタログ", perspective: "XSS" },
        ],
      },
    }),
  },
).then((r) => r.json());
```

## 再診断

ブラックボックス診断の結果には、検出された脆弱性ごとに「どの機能のどの観点で見つかったか」という情報が含まれています。

脆弱性を修正した後に再診断したい際には、これらの情報を利用して、当該脆弱性が指摘された機能・観点だけを対象に診断を実行できます。例えば、認証機能におけるインジェクションの脆弱性を修正した後に、そこだけを再診断できます。

たとえば、認証機能で Injection の脆弱性が報告された場合、修正後にその組み合わせだけを再診断する、といった使い方が可能です。

まず、すでに完了した診断で検出された脆弱性を確認するには、`findings` という名前のアーティファクトをダウンロードします。

```typescript
const findingsData = await fetch(
  `${TAKUMI_API}/v1/o/${TAKUMI_ORG}/workflows/blackbox-assessment/get-artifact-download-url`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      workflow_run_id: assessment_workflow_run_id,
      artifact_name: "findings",
    }),
  },
)
  .then((r) => r.json())
  .then(({ url }) => fetch(url))
  .then((r) => r.json());

for (const finding of findingsData.findings) {
  console.log("title:", finding.title);
  console.log("feature:", finding.feature_name); // => "認証", "ユーザー設定", ...
  console.log("perspective:", finding.perspective); // => "Injection", "Authorization", ...
  console.log("markdown description:", finding.description);
}
```

脆弱性を修正した後に再診断するには、この `findings` アーティファクトに記載されていた機能名 (`finding.feature_name`) と観点 (`finding.perspective`) を指定して再診断を実行します。前回診断に用いられた機能一覧情報を引き継ぐため、診断ワークフローの ID の指定も必要です。

```typescript
const { workflow_run_id: assessment_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/"],

        // 前回の診断ワークフローで利用していた機能一覧を再利用するよう指定
        resume: {
          kind: "assess_crawled_features",
          assess_crawled_features: {
            workflow_id: "blackbox-assessment",
            workflow_run_id: "TWR...", // 前回診断の workflow_run_id を指定
          },
        },

        // 再診断したい機能・観点を指定
        pairs: [{ feature_name: "認証", perspective: "Injection" }],
      },
    }),
  },
).then((r) => r.json());
```

## 制限事項

「一部だけ診断」と「再診断」は、**Takumi API 経由で実行したクロール・診断に対してのみ**利用可能です。Web コンソールから実行したクロール・診断の結果は、API 経由では利用できません。これは、Takumi API と Web コンソールの「診断」機能のデータが独立に管理されているためです。詳細は API ユーザーガイドの「[Web コンソールの「診断」との関係](/docs/ja/t/api#relationship-with-existing-features)」をご覧ください。

## 利用開始方法

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