# Takumi API を提供開始

Takumi の諸機能を Web UI や Slack を介さずに呼び出せる公開 HTTP API の提供を開始しました。CI/CD パイプラインやチケット管理システムと連携したり、脆弱性管理ワークフローなどに直接組み込んだりすることで、開発ライフサイクルの中で Takumi をよりシームレスにご活用いただけます。

現在は、ホワイトボックス診断とブラックボックス診断の「全体を診断」モードを API 経由でご利用いただけます。今後も「一部だけ診断」モードや[自動修正](/docs/ja/t/features/autofix)機能など、利用可能な機能を順次拡大予定ですので、ぜひご期待ください。

## Takumi API でできること

Takumi の診断をはじめとする機能を HTTP API 経由で自由に呼び出すことができます。診断などが完了した際に Webhook で通知を受け取ることもできます。

現在は以下の機能をお使いいただけます。API 経由で利用できる機能・モードは今後も順次拡大予定です。

| 機能                                                            | 備考                     |
| --------------------------------------------------------------- | ------------------------ |
| [ホワイトボックス診断](/docs/ja/t/features/whitebox-assessment) | 「全体を診断」モードのみ |
| [ブラックボックス診断](/docs/ja/t/features/blackbox-assessment) | 「全体を診断」モードのみ |

API を用いて Takumi をお好みのタイミング・場所で呼び出し、その結果をお好みの場所へ届けることができるため、これまで以上に Takumi を開発ライフサイクルにシームレスに組み込むことができます。

### 活用例

#### 定期的な診断

Takumi API を定期的に呼び出していただくことで、診断の定期実行を実現できます。

これまで定期的な診断は、連携済みの GitHub リポジトリに対する[ホワイトボックス診断](/docs/ja/t/features/periodic-assessment)に対してのみ提供していました。Takumi API を活用していただくことで、ブラックボックス診断の定期実行や、GitHub 以外のコードベースに対するホワイトボックス診断の定期実行なども可能になりました。

API を用いた定期診断の実装は、およそ [CI/CD パイプラインへの組み込み](#examples-ci-cd) で紹介する例と同様です。

#### CI/CD パイプラインへの組み込み {#examples-ci-cd}

たとえばデプロイワークフローの中で Takumi API を呼び出すことで、ステージング環境へのデプロイ後にホワイトボックス診断が自動実行されるパイプラインを構築できます。GitHub Actions での実装は大まかに以下のようになります。もちろん、GitHub Actions 以外の CI/CD プラットフォームでも同様のことが可能です。

```yaml
jobs:
  deploy-to-staging:
    # ...

  dispatch-takumi-assessment:
    runs-on: ubuntu-latest
    needs: deploy-to-staging
    steps:
      - uses: actions/checkout@v4

      # ソースコード ZIP を Takumi API にアップロード
      - name: Upload source code
        run: |-
          zip -r source.zip .

          UPLOAD=$(curl -s -H "Authorization: Bearer $TOKEN" \
            "$TAKUMI_API/v1/o/$TAKUMI_ORG/input-files/get-upload-url" \
            --json '{"content_length": '$(stat --format=%s source.zip)'}')
          FILE_ID=$(echo "$UPLOAD" | jq -r '.file_id')

          curl -s -X PUT "$(echo "$UPLOAD" | jq -r '.upload_url')" --upload-file source.zip

          curl -s -H "Authorization: Bearer $TOKEN" \
            "$TAKUMI_API/v1/o/$TAKUMI_ORG/input-files/confirm-upload" \
            --json '{"file_id": "'"$FILE_ID"'"}'
          echo "FILE_ID=$FILE_ID" >> "$GITHUB_ENV"

      # ホワイトボックス診断を実行
      - name: Dispatch whitebox assessment
        run: |-
          curl -s -H "Authorization: Bearer $TOKEN" \
            "$TAKUMI_API/v1/o/$TAKUMI_ORG/workflows/whitebox-assessment/dispatch" \
            --json '{
              "input": {
                "language": "japanese",
                "targets": [{"file_upload": {"file_id": "'"$FILE_ID"'", "archive_type": "zip"}}]
              },
              "notification": {"webhook_endpoint_ids": ["'"$WEBHOOK_ID"'"]}
            }'
          # 完了通知は Webhook で受け取る（次の活用例を参照）
```

#### チケット管理システムへの結果連携

Webhook 通知を起点に、診断結果から GitHub Issues や Jira などへ自動起票する仕組みを構築できます。例えば検出された脆弱性ごとに GitHub Issue を作成する実装は、概ね以下のようになります。

```typescript
const handleWebhookEvent = async (event: WebhookEvent) => {
  // event の例:
  // {
  //   type: "api.workflow_run.exited",
  //   data: { workflow_id: "whitebox-assessment", workflow_run_id: "TWR..." },
  // }

  // 実行結果を取得
  const { output } = await fetch(
    `${TAKUMI_API}/v1/o/${TAKUMI_ORG}/workflows/whitebox-assessment/describe`,
    {
      method: "POST",
      headers,
      body: JSON.stringify({ workflow_run_id: event.data.workflow_run_id }),
    },
  ).then((r) => r.json());

  if (output.kind !== "SUCCESS") {
    console.log("診断が中断されました:", output.abortedReason);
    return;
  }

  // 検出された脆弱性一覧をダウンロード
  const { url } = await fetch(
    `${TAKUMI_API}/v1/o/${TAKUMI_ORG}/workflows/whitebox-assessment/get-artifact-download-url`,
    {
      method: "POST",
      headers,
      body: JSON.stringify({
        workflow_run_id: event.data.workflow_run_id,
        artifact_name: output.successOutput.findings.artifact_name,
      }),
    },
  ).then((r) => r.json());

  const findingsData = await fetch(url).then((r) => r.json());

  // 脆弱性ごとに GitHub Issue を作成
  for (const finding of findingsData.findings) {
    await octokit.rest.issues.create({
      owner: GITHUB_ORG,
      repo: GITHUB_REPO,
      title: `[Takumi] ${finding.title}`,
      body: `**深刻度**: ${finding.description}\n\nこの脆弱性は Takumi によって検出されました。`,
      labels: ["security"],
    });
  }
};
```

## Web コンソールの「診断」との関係

Takumi API と Web コンソールの「診断」機能では**同じ診断エンジン**が使われますが、**診断データは共有されません**。API 経由で実行したワークフローの結果は Web コンソールの「診断」タブには表示されず、逆に Web コンソールで実行した診断の結果を API から取得することもできません。

両者は異なる設計思想に基づいているため、データは独立に管理されます。

- **Web コンソールは診断の進行状況を容易に把握できるよう設計**しています。そのため、「クロール → 一部機能を選択して検査」といった一連の流れを「診断」という単位の**状態変化**として管理しています。
- **Takumi API はユースケースの自由度をなるべく高める API を指向**しています。そのためクロール・診断などをそれぞれ**独立したワークフロー**として提供しています。これにより、Web コンソールの「診断」機能の流れに制限されることなく、自由な流れ・組み合わせで Takumi の諸機能を呼び出していただけます。

## 利用開始方法

詳細はユーザーガイドをご覧ください。

▼ ユーザーガイド: [Takumi API](/docs/ja/t/api)