# クイックスタート

このページでは、ホワイトボックス診断を例に、Takumi API の基本的な使い方をセットアップから結果取得まで順を追って説明します。
ファイルのアップロード・ワークフローの実行・結果の取得といった基本的な流れは他のワークフローでも共通ですので、他のワークフローを使いたい場合もぜひ参考にしてください。

## 全体像

Takumi API を使った診断は、大まかに以下のような通信の流れで進みます。

```mermaid
sequenceDiagram
    participant User as API 利用者
    participant API as Takumi API

    User->>API: 入力ファイルをアップロード
    API-->>User: file_id

    User->>API: ワークフローを実行
    API-->>User: workflow_run_id

    Note over API: Takumi が診断を実行<br/>（数時間〜数日）

    API-)User: Webhook で完了を通知

    User->>API: 結果・成果物を取得
    API-->>User: 診断結果・レポート等
```

:::note
Webhook を使わず、ステータス確認 API をポーリングして完了を待機することも可能です。ただし GitHub Actions のように実行時間に課金される環境では、ポーリングで完了を待つのではなく、「Takumi のワークフローを呼び出してすぐに終了するプロセス」と「Webhook 通知にトリガーされ、完了したワークフローの結果を処理するプロセス」に分けるアーキテクチャがおすすめです。
:::

## セットアップ

### アクセストークンを取得する

Takumi API では、ユーザーとして認証することも、ボットというエンティティとして認証することも可能です。CI/CD パイプラインなど、特定のユーザーに紐づかない主体として Takumi API を利用したい場合には、ボットとして認証する方法がおすすめです。一部の OIDC 対応環境では短命の認証情報を利用できるほか、長命の API キーを発行して利用することもできます。

Takumi API で必要となるアクセストークンは以下のいずれかの方法で取得できます。詳細は [shishoctl CLI でアクセスする](https://shisho.dev/docs/ja/c/accessing-via-shishoctl-cli/) を参照してください。

- ユーザーとして認証する: `shishoctl auth signin` でサインインし、`shishoctl auth print-access-token` でトークンを取得する
- ボットとして認証する: `shishoctl auth signin:bot` でサインインし、`shishoctl auth print-access-token` でトークンを取得する

取得したアクセストークンを、以降の API リクエストのヘッダーに付与します。

```
Authorization: Bearer {ACCESS_TOKEN}
```

### Webhook を設定する

ワークフロー実行の完了通知を受け取るために Webhook を設定します。具体的な手順は [Webhook 通知](/docs/ja/t/api/features/webhook.md)を参照してください。

ポーリングでワークフローの完了を待機する場合は、このセットアップは不要です。

### 診断対象のアプリケーションの所有権を証明する（一部ワークフローのみ）

実環境への動的な通信を伴う機能（ブラックボックス診断を含む）は、お客様が所有権を持つ対象にのみ行えます。未証明のアプリケーション URL を診断対象に指定すると、ワークフローの実行が拒否されます。

[組織認証または診断対象の所有権証明](/docs/ja/t/concepts/assessment-authentication.md)に記載の方法で、アプリケーションの所有権を証明するセットアップを完了させてください。

なおホワイトボックス診断は実環境への動的な通信を伴わないため、この制約はありません。

## ワークフローの入出力を理解する

ワークフローの入出力のスキーマは、ワークフローの種別ごとに異なります。そのスキーマは、[OpenAPI ドキュメント](https://api.cloud.shisho.dev/v1/docs/openapi.json) に定義されています。

ホワイトボックス診断のワークフロー ID は `whitebox-assessment` であり、API エンドポイントは `/o/{org_id}/workflows/whitebox-assessment/*` です。

ワークフロー実行 API `/o/{org_id}/workflows/whitebox-assessment/dispatch` のリクエストスキーマの一部を以下に抜粋します。このスキーマから、入力について以下のことがわかります。

- 診断対象のコードベースは `/o/{org_id}/input-files` の API を通じて事前にアップロードしておき、そのファイル ID を `input.targets[].file_upload.file_id` に指定する。コードベースは ZIP 形式または tar.gz 形式でアップロードできる
- 診断レポートの出力言語を `input.language` に指定する

```yaml
/o/{org_id}/workflows/whitebox-assessment/dispatch:
  post:
    requestBody:
      content:
        application/json:
          schema:
            properties:
              input:
                properties:
                  # 診断対象のコードベース
                  targets:
                    description: Source code archives to analyze
                    type: array
                    items:
                      properties:
                        file_upload:
                          properties:
                            description: Source code archive uploaded via the input files API
                            file_id: { type: string }
                            archive_type:
                              enum: [zip, tar_gz]
                  # 診断レポートの出力言語
                  language:
                    enum: [english, japanese]
                  # ... (他のパラメータについては OpenAPI ドキュメントを参照してください)
              notification:
                description: Optional notification configuration for the workflow run
                properties:
                  # ワークフロー完了の通知先
                  webhook_endpoint_ids:
                    type: array
                    items: { type: string }
```

次に、ワークフローの実行結果のスキーマを見てみましょう。ワークフローが完了すると `/o/{org_id}/workflows/{workflow_id}/describe` エンドポイントでその結果を確認できます。ホワイトボックス診断の `/o/{org_id}/workflows/whitebox-assessment/describe` エンドポイントのレスポンススキーマの一部を以下に抜粋します。

```yaml
/o/{org_id}/workflows/whitebox-assessment/describe:
  post:
    responses:
      "200":
        content:
          application/json:
            schema:
              properties:
                status:
                  description: Current status of the workflow run
                  enum: [RUNNING, EXITED]
                artifacts:
                  description: Downloadable artifacts produced by the workflow run. Present only when status is EXITED
                  type: array
                  items:
                    properties:
                      name: { type: string }
                output:
                  description: Output of the workflow run. Present only when status is EXITED
                  properties:
                    kind:
                      description: Whether the workflow run succeeded or was aborted
                      enum: [SUCCESS, ABORTED]
                    successOutput:
                      description: The success output. Present only when kind is SUCCESS
                      properties:
                        findings:
                          description: A JSON file containing the list of vulnerability findings. The schema is available at `/v1/docs/workflow-artifacts/whitebox-assessment/findings.json`
                          properties:
                            artifact_name: { type: string }
                          type: object
                        report:
                          description: The assessment report in Markdown format
                          properties:
                            artifact_name:
                              type: string
                          type: object
                      type: object
                    abortedReason:
                      description: The reason the workflow run was aborted. Present only when kind is ABORTED
                      properties: # ... (省略)
```

ここから、ホワイトボックス診断が成功した場合に生成される成果物について以下のことがわかります。

- `report`: 診断レポートの Markdown ファイル
- `findings`: 検出された脆弱性のリストを含む JSON ファイル。JSON Schema が `https://api.cloud.shisho.dev/v1/docs/workflow-artifacts/whitebox-assessment/findings.json` に定義されている

では、実際にワークフローを実行してみましょう。

## ワークフローを使う

### ステップ 1: 入力ファイルをアップロードする

ホワイトボックス診断では診断対象のコードベースを ZIP または tar.gz 形式でアップロードし、そのファイル ID をワークフローの入力として指定する必要があります。ブラックボックス診断のようにワークフローにファイルを与える必要がない場合は、このステップは不要です。

ファイルアップロードの仕組みについて、詳しくは[ファイルアップロード](/docs/ja/t/api/features/file-upload.md)を参照してください。

#### アップロード URL を取得する

まず、ファイルのサイズ（バイト数）を指定して、アップロード先 URLを取得します。

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.cloud.shisho.dev/v1/o/$org_id/input-files/get-upload-url \
  --json '{"content_length": 123456}'
```

成功すると、`file_id`（ファイルの識別子）と `upload_url`（アップロード先の一時 URL）が返されます。

```json
{
  "file_id": "TIF...",
  "upload_url": "https://..."
}
```

#### ファイルをアップロードする

取得した `upload_url` に対して、ソースコードのアーカイブを HTTP PUT でアップロードします。このリクエストに `Authorization` ヘッダーは不要です。

```bash
curl -s -X PUT "<upload_url>" --upload-file ./your-project.zip
```

#### アップロードを確定する

ファイルのアップロードが完了したら、アップロード確定 API を呼び出します。この操作が完了して初めて、ワークフローへの入力でこのファイルを参照できるようになります。

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.cloud.shisho.dev/v1/o/$org_id/input-files/confirm-upload \
  --json '{"file_id": "TIF..."}'
```

:::note
アップロードを取りやめる場合は、`/o/{org_id}/input-files/cancel-upload` を呼び出してアップロードをキャンセルしてください。これにより、アップロードの取りやめがストレージ容量制限に正しく反映されます。
:::

### ステップ 2: ワークフローを実行する

ワークフロー実行 API を呼び出します。

`notification.webhook_endpoint_ids` にセットアップ時に登録した Webhook のエンドポイント ID を指定することで、ワークフロー実行完了時に通知が送られます。

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.cloud.shisho.dev/v1/o/$org_id/workflows/whitebox-assessment/dispatch \
  --json '{
    "input": {
      "language": "japanese",
      "targets": [
        {
          "file_upload": {
            "file_id": "TIF...",
            "archive_type": "zip"
          }
        }
      ]
    },
    "notification": {
      "webhook_endpoint_ids": ["WH..."]
    }
  }'
```

ワークフローの入力形式はワークフローの種別ごとに異なります。詳細は [OpenAPI ドキュメント](https://api.cloud.shisho.dev/v1/docs/openapi.json) における各エンドポイントのリクエストスキーマを参照してください。

ワークフロー実行のキュー投入に成功すると、`workflow_run_id` が返されます。

```json
{
  "workflow_run_id": "TWR..."
}
```

:::note
ワークフローの完了までには数時間〜数日程度かかる場合があります。実行時間はアプリケーションの規模や複雑さなどによって変わります。
:::

なお、実行中のワークフローをキャンセルするには、`/o/{org_id}/workflows/{workflow_id}/cancel` を呼び出します。

### ステップ 3: 完了通知を受け取る

ワークフロー実行が完了すると、指定した Webhook エンドポイントに通知が届きます。Webhook 通知の詳細については、[Webhook 通知](/docs/ja/t/api/features/webhook.md)を参照してください。

```json
{
  "type": "api.workflow_run.exited",
  "timestamp": "2024-01-01T00:00:00Z",
  "data": {
    "workflow_id": "whitebox-assessment",
    "workflow_run_id": "TWR..."
  }
}
```

`data.workflow_run_id` でワークフロー実行を特定し、次のステップで結果を取得します。

なお Webhook ではなくポーリングでワークフロー完了を待機する場合には、`/o/{org_id}/workflows/{workflow_id}/describe` エンドポイントから実行ステータスを取得できます。

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.cloud.shisho.dev/v1/o/$org_id/workflows/whitebox-assessment/describe \
  --json '{"workflow_run_id": "TWR..."}'
```

### ステップ 4: 結果を取得する

ワークフロー実行が完了したら、`/o/{org_id}/workflows/{workflow_id}/describe` を呼び出してワークフロー実行の結果を取得します。
`output.kind` が `"SUCCESS"` であれば診断が成功しています。このレスポンスには、成果物の一覧も含まれています。

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.cloud.shisho.dev/v1/o/$org_id/workflows/whitebox-assessment/describe \
  --json '{"workflow_run_id": "TWR..."}'
```

ワークフローの結果の形式はワークフローの種別ごとに異なります。詳細は [OpenAPI ドキュメント](https://api.cloud.shisho.dev/v1/docs/openapi.json) における各エンドポイントのレスポンススキーマを参照してください。また、それぞれの成果物の内容やフォーマットについても、レスポンススキーマに説明が記載されています。

たとえばホワイトボックス診断のジョブ取得 API `/o/{org_id}/workflows/whitebox-assessment/describe` のレスポンススキーマは以下のように定義されています。

```yaml
successOutput:
  properties:
    findings:
      description: A JSON file containing the list of vulnerability findings. The schema is available at `/v1/docs/workflow-artifacts/whitebox-assessment/findings.json`
      properties:
        artifact_name: { type: string }
    report:
      description: The assessment report in Markdown format
      properties:
        artifact_name: { type: string }
```

成果物をダウンロードするには、`/o/{org_id}/workflows/{workflow_id}/get-artifact-download-url` を呼び出してダウンロード URL を取得します。例えば、ホワイトボックス診断の診断レポート `report` をダウンロードする場合は以下のようになります。

```bash
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
  https://api.cloud.shisho.dev/v1/o/$org_id/workflows/whitebox-assessment/get-artifact-download-url \
  --json '{
    "workflow_run_id": "TWR...",
    "artifact_name": "report"
  }'
```

レスポンスに含まれる `url` から、成果物を HTTP GET でダウンロードできます。

```bash
curl -s -o report.md "<download_url>"
```

:::note
ワークフローの実行結果や成果物は最低30日間保持されますが、その後は削除される場合があります。結果を長期的に保存したい場合は、お客様の管理するストレージに保管してください。
:::

## まとめ

ここまでで、Takumi API を使ったホワイトボックス診断の基本的な流れを実践できました。

基本的な流れを把握したら、次のような活用方法もぜひお試しください。

- **CI/CD との連携**: GitHub Actions などの CI/CD パイプラインに組み込み、デプロイ後に自動で診断をトリガーする
- **チケット管理システムとの連携**: 診断結果をもとに GitHub Issues や Jira チケットを自動で作成する
- **他のワークフローの利用**: Takumi API で利用可能な他のワークフロー（ブラックボックス診断など）を活用する