Skip to main content

Quick Start

info

The English user guide is currently in beta preview. Most of the documents have been automatically translated from the Japanese version. Should you find any inaccuracies, please reach out to Flatt Security.

This page walks you through the basics of using Takumi API—from setup to retrieving results—using whitebox assessment as an example. The core flow (uploading files, running a workflow, and retrieving results) is common across all workflows, so this guide applies to other workflows as well.

Overview​

An API-driven assessment follows roughly this communication flow:

note

You can also poll the status API instead of using webhooks. However, if you're running in an environment that charges by execution time (such as GitHub Actions), consider splitting the process into two parts: one that dispatches the workflow and exits immediately, and another that is triggered by the webhook to process the results. This minimizes the time your execution environment stays running.

Setup​

Get an Access Token​

Takumi API supports authentication both as a user and as a bot—a non-person entity. For CI/CD pipelines and other automated contexts not tied to a specific user, bot authentication is recommended. Some OIDC-compatible environments support short-lived credentials; alternatively, you can issue a long-lived API key.

You can obtain an access token using one of the following methods. For details, see Accessing via shishoctl CLI.

  • Authenticate as a user: Sign in with shishoctl auth signin, then retrieve a token with shishoctl auth print-access-token
  • Authenticate as a bot: Sign in with shishoctl auth signin:bot, then retrieve a token with shishoctl auth print-access-token

Include the token in all subsequent API requests:

Authorization: Bearer {ACCESS_TOKEN}

Configure a Webhook​

Set up a webhook to receive notifications when a workflow completes. For step-by-step instructions, see Webhook Notifications.

This setup is not required if you plan to poll for workflow completion instead.

Verify Ownership of the Target Application (Some Workflows Only)​

Features that communicate dynamically with a live environment (including blackbox assessment) can only target applications you own. If you specify an unverified application URL as the assessment target, the workflow will be rejected.

Complete the ownership verification process as described in Organization Verification and Ownership Verification.

Whitebox assessment does not involve dynamic communication with a live environment, so this restriction does not apply.

Understand Workflow Inputs and Outputs​

The input and output schemas differ by workflow type and are defined in the OpenAPI documentation.

The workflow ID for whitebox assessment is whitebox-assessment, and its API endpoints are under /o/{org_id}/workflows/whitebox-assessment/*.

Here is a partial excerpt of the request schema for the workflow dispatch endpoint /o/{org_id}/workflows/whitebox-assessment/dispatch. From this schema, you can see:

  • The target codebase must be uploaded in advance via the /o/{org_id}/input-files API. Specify the resulting file ID in input.targets[].file_upload.file_id. Supported archive formats are ZIP and tar.gz.
  • Specify the output language for the assessment report in input.language.
/o/{org_id}/workflows/whitebox-assessment/dispatch:
  post:
    requestBody:
      content:
        application/json:
          schema:
            properties:
              input:
                properties:
                  # Target codebases for assessment
                  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 for the assessment report
                  language:
                    enum: [english, japanese]
                  # ... (see OpenAPI documentation for other parameters)
              notification:
                description: Optional notification configuration for the workflow run
                properties:
                  # Webhook endpoint to notify on workflow completion
                  webhook_endpoint_ids:
                    type: array
                    items: { type: string }

Next, let's look at the output schema. Once a workflow completes, you can retrieve its results from the /o/{org_id}/workflows/{workflow_id}/describe endpoint. Here is a partial excerpt of the response schema for /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: # ... (omitted)

From this, you can see the artifacts produced when a whitebox assessment succeeds:

  • report: The assessment report in Markdown format
  • findings: A JSON file containing the list of detected vulnerabilities. The JSON Schema is available at https://api.cloud.shisho.dev/v1/docs/workflow-artifacts/whitebox-assessment/findings.json

Let's now walk through running a workflow.

Run a Workflow​

Step 1: Upload Input Files​

Whitebox assessment requires uploading the target codebase as a ZIP or tar.gz archive, then specifying the file ID as workflow input. If the workflow doesn't require file input (such as blackbox assessment), skip this step.

For details on how file upload works, see File Upload.

Get an Upload URL​

First, specify the file size in bytes to obtain an upload 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}'

On success, the response includes a file_id (the file identifier) and an upload_url (a temporary URL for upload).

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

Upload the File​

Upload your source code archive to the upload_url via HTTP PUT. No Authorization header is required for this request.

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

Confirm the Upload​

After uploading, call the confirm-upload API. The file is not available as workflow input until this step completes.

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

If you decide not to complete the upload, call /o/{org_id}/input-files/cancel-upload to cancel it. This ensures the cancelled upload is correctly reflected in your storage usage.

Step 2: Run the Workflow​

Call the workflow dispatch API to start the assessment.

Specify the webhook endpoint ID you registered during setup in notification.webhook_endpoint_ids to receive a notification when the workflow completes.

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

The input format varies by workflow type. For details, refer to the request schema for each endpoint in the OpenAPI documentation.

On success, the response includes the workflow_run_id.

{
  "workflow_run_id": "TWR..."
}
note

Workflows can take anywhere from a few hours to a few days to complete, depending on the size and complexity of the application.

To cancel a running workflow, call the /o/{org_id}/workflows/{workflow_id}/cancel endpoint.

Step 3: Receive the Completion Notification​

When the workflow completes, Takumi sends a notification to your webhook endpoint. For details on webhook notifications, see Webhook Notifications.

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

Use data.workflow_run_id to identify the workflow run, then proceed to the next step to retrieve the results.

If you prefer polling over webhooks, you can check the run status from the /o/{org_id}/workflows/{workflow_id}/describe endpoint:

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..."}'

Step 4: Retrieve Results​

Once the workflow has completed, call /o/{org_id}/workflows/{workflow_id}/describe to fetch the results. If output.kind is "SUCCESS", the assessment succeeded. The response also includes a list of artifacts.

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..."}'

The result format varies by workflow type. For details, refer to the response schema for each endpoint in the OpenAPI documentation. The schema also describes the content and format of each artifact.

For example, the response schema for /o/{org_id}/workflows/whitebox-assessment/describe defines the following:

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 }

To download an artifact, call /o/{org_id}/workflows/{workflow_id}/get-artifact-download-url to obtain a download URL. For example, to download the assessment report (report) from a whitebox assessment:

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"
  }'

Download the artifact via HTTP GET using the url from the response:

curl -s -o report.md "<download_url>"
note

Workflow results and artifacts are retained for a minimum of 30 days, but may be deleted after that. If you need to keep results long-term, we recommend downloading them promptly.

Next Steps​

You've now completed the basic flow for running a whitebox assessment via Takumi API. Now that you have the fundamentals down, here are some ways to take it further:

  • CI/CD integration: Embed Takumi in a GitHub Actions pipeline to automatically trigger assessments after deployment
  • Ticket management integration: Automatically create GitHub Issues or Jira tickets based on assessment findings
  • Other workflows: Explore other workflows available through Takumi API, such as blackbox assessment
Last updated on