クイックスタート
このページでは、ホワイトボックス診断を例に、Takumi API の基本的な使い方をセットアップから結果取得まで順を追って説明します。 ファイルのアップロード・ワークフローの実行・結果の取得といった基本的な流れは他のワークフローでも共通ですので、他のワークフローを使いたい場合もぜひ参考にしてください。
全体像
Takumi API を使った診断は、大まかに以下のような通信の流れで進みます。
Webhook を使わず、ステータス確認 API をポーリングして完了を待機することも可能です。ただし GitHub Actions のように実行時間に課金される環境では、ポーリングで完了を待つのではなく、「Takumi のワークフローを呼び出してすぐに終了するプロセス」と「Webhook 通知にトリガーされ、完了したワークフローの結果を処理するプロセス」に分けるアーキテクチャがおすすめです。
セットアップ
アクセストークンを取得する
Takumi API では、ユーザーとして認証することも、ボットというエンティティとして認証することも可能です。CI/CD パイプラインなど、特定のユーザーに紐づかない主体として Takumi API を利用したい場合には、ボットとして認証する方法がおすすめです。一部の OIDC 対応環境では短命の認証情報を利用できるほか、長命の API キーを発行して 利用することもできます。
Takumi API で必要となるアクセストークンは以下のいずれかの方法で取得できます。詳細は 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 通知を参照してください。
ポーリングでワークフローの完了を待機する場合は、このセットアップは不要です。
診断対象のアプリケーションの所有権を証明する（一部ワークフローのみ）
実環境への動的な通信を伴う機能（ブラックボックス診断を含む）は、お客様が所有権を持つ対象にのみ行えます。未証明のアプリケーション URL を診断対象に指定すると、ワークフローの実行が拒否されます。
組織認証または診断対象の所有権証明に記載の方法で、アプリケーションの所有権を証明するセットアップを完了させてください。
なおホワイトボックス診断は実環境への動的な通信を伴わないため、この制約はありません。
ワークフローの入出力を理解する
ワークフローの入出力のスキーマは、ワークフローの種別ごとに異なります。そのスキーマは、OpenAPI ドキュメント に定義されています。
ホワイトボックス診断のワークフロー 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に指定する
/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 エンドポイントのレスポンススキーマの一部を以下に抜粋します。
/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 をワークフローの入力として指定する必要があります。ブラックボックス診断のようにワークフローにファイルを与える必要がない場合は、このステップは不要です。
ファイルアップロードの仕組みについて、詳しくはファイルアップロードを参照してください。
アップロード URL を取得する
まず、ファイルのサイズ（バイト数）を指定して、アップロード先 URLを取得します。
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）が返されます。
{
"file_id": "TIF...",
"upload_url": "https://..."
}
ファイルをアップロードする
取得した upload_url に対して、ソースコードのアーカイブを HTTP PUT でアップロードします。このリクエストに Authorization ヘッダーは不要です。
curl -s -X PUT "<upload_url>" --upload-file ./your-project.zip
アップロードを確定する
ファイルのアップロードが完了したら、アップロード確定 API を呼び出します。この操作が完了して初めて、ワークフローへの入力でこのファイルを参照できるようになります。
curl -s -H "Authorization: Bearer $ACCESS_TOKEN" \
https://api.cloud.shisho.dev/v1/o/$org_id/input-files/confirm-upload \
--json '{"file_id": "TIF..."}'
アップロードを取りやめる場合は、/o/{org_id}/input-files/cancel-upload を呼び出してアップロードをキャンセルしてください。これにより、アップロードの取りやめがストレージ容量制限に正しく反映されます。
ステップ 2: ワークフローを実行する
ワークフロー実行 API を呼び出します。
notification.webhook_endpoint_ids にセットアップ時に登録した Webhook のエンドポイント ID を指定することで、ワークフロー実行完了時に通知が送られます。
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 ドキュメント における各エンドポイントのリクエストスキーマを参照してください。
ワークフロー実行のキュー投入に成功すると、workflow_run_id が返されます。
{
"workflow_run_id": "TWR..."
}
ワークフローの完了までには数時間〜数日程度かかる場合があります。実行時間はアプリケーションの規模や複雑さなどによって変わります。
なお、実行中のワークフローをキャンセルするには、/o/{org_id}/workflows/{workflow_id}/cancel を呼び出します。
ステップ 3: 完了通知を受け取る
ワークフロー実行が完了すると、指定した Webhook エンドポイントに通知が届きます。Webhook 通知の詳細については、Webhook 通知を参照してください。
{
"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 エンドポイントから実行ステータスを取得できます。
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" であれば診断が成功しています。このレスポンスには、成果物の一覧も含まれています。
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 ドキュメント における各エンドポイントのレスポンススキーマを参照してください。また、それぞれの成果物の内容やフォーマットについても、レスポンススキーマに説明が記載されています。
たとえばホワイトボックス診断のジョブ取得 API /o/{org_id}/workflows/whitebox-assessment/describe のレスポンススキーマは以下のように定義されています。
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 をダウンロードする場合は以下のようになります。
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 でダウンロードできます。
curl -s -o report.md "<download_url>"
ワークフローの実行結果や成果物は最低30日間保持されますが、その後は削除される場合があります。結果を長期的に保存したい場合は、お客様の管理するストレージに保管してください。
まとめ
ここまでで、Takumi API を使ったホワイトボ ックス診断の基本的な流れを実践できました。
基本的な流れを把握したら、次のような活用方法もぜひお試しください。
- CI/CD との連携: GitHub Actions などの CI/CD パイプラインに組み込み、デプロイ後に自動で診断をトリガーする
- チケット管理システムとの連携: 診断結果をもとに GitHub Issues や Jira チケットを自動で作成する
- 他のワークフローの利用: Takumi API で利用可能な他のワークフロー（ブラックボックス診断など）を活用する