# Scoped Blackbox Assessments and Retests Now Available via Takumi API

Takumi's blackbox assessment now supports **scoped assessments** and **retests** via the [Takumi API](/docs/t/api). Previously, these capabilities were only available through the web console.

- **Scoped assessment**: Crawl the target application first, then select specific features and perspectives to assess
- **Retest**: Re-run assessments targeting feature–perspective pairs where vulnerabilities were found in previous results

To support these workflows, we've made the following additions to the blackbox assessment API:

- A new **crawl workflow** (`blackbox-crawl`) that discovers features in the target application without performing any assessment
- New **scoping options** for the assessment workflow (`blackbox-assessment`) that let you specify which features and perspectives to assess

## Scoped Assessment

You can dispatch a scoped assessment in two steps:

1. Dispatch the crawl workflow to discover features in the target application
2. Select the features and perspectives you want to assess, then dispatch the assessment workflow

This is useful when you want to focus on high-priority areas or only assess features that were recently updated.

### Dispatch the Crawl Workflow

Dispatch a crawl workflow as follows:

```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: "english",
        target_urls: ["https://app.example/"],
      },
      notification: { webhook_endpoint_ids: [WEBHOOK_ID] },
    }),
  },
).then((r) => r.json());
```

### Select Features and Dispatch the Assessment

Once the crawl completes, retrieve the discovered features. They are available as an artifact named `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); // => "authentication", "user_settings", "product_catalog", ...
  console.log("feature description:", feature.description);
}
```

Choose the feature names (`feature.name`) and perspectives you want to assess, then dispatch the assessment workflow with the crawl workflow run's 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/"],

        // Reuse features discovered by the crawl workflow
        resume: {
          kind: "assess_crawled_features",
          assess_crawled_features: {
            workflow_id: "blackbox-crawl",
            workflow_run_id: crawl_workflow_run_id,
          },
        },

        // Specify which feature–perspective pairs to assess
        pairs: [
          { feature_name: "authentication", perspective: "Injection" },
          { feature_name: "user_settings", perspective: "Authorization" },
          { feature_name: "product_catalog", perspective: "XSS" },
        ],
      },
    }),
  },
).then((r) => r.json());
```

## Retest

Blackbox assessment results include information about which feature and perspective each vulnerability was found in. After fixing a vulnerability, you can retest only the relevant feature–perspective pair instead of dispatching a full assessment.

First, retrieve the findings from a completed assessment by downloading the `findings` artifact:

```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); // => "authentication", "user_settings", ...
  console.log("perspective:", finding.perspective); // => "Injection", "Authorization", ...
  console.log("markdown description:", finding.description);
}
```

To retest after fixing a vulnerability, specify the feature name (`finding.feature_name`) and perspective (`finding.perspective`) from the findings. You also need to provide the previous assessment's workflow run ID so that the feature list can be reused.

```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/"],

        // Reuse the feature list from the previous assessment
        resume: {
          kind: "assess_crawled_features",
          assess_crawled_features: {
            workflow_id: "blackbox-assessment",
            workflow_run_id: "TWR...", // workflow_run_id of the previous assessment
          },
        },

        // Specify which feature–perspective pairs to retest
        pairs: [{ feature_name: "authentication", perspective: "Injection" }],
      },
    }),
  },
).then((r) => r.json());
```

## Limitations

Scoped assessments and retests are **only available for crawls and assessments dispatched via the Takumi API**. Results from assessments run through the web console cannot be used with the API, because the Takumi API and the web console's assessment feature manage their data independently. For details, see [Relationship with the Web Console's "Assessment" Feature](/docs/t/api#relationship-with-existing-features) in the API user guide.

## Getting Started

See the [API documentation](/docs/t/api) for full details.