Ruby projects using Bundler can now route installs through Takumi Guard to block known-malicious packages before they reach your CI or development environment.

Overview​

Takumi Guard is a security proxy that sits between your package manager and the upstream registry. It checks every install request against GMO Flatt Security's threat database and blocks known-malicious packages.

With this release, the same protection that npm and Python users have is now available for the Ruby ecosystem:

• Package Blocking: Malicious gems are blocked before any code executes
• Download Tracking: Records install history for authenticated users
• Breach Notifications: Get notified if a package you installed is later flagged as malicious

Getting Started​

All of the following work anonymously — no account or registration required.

Bundler​

Route all bundle install calls through Takumi Guard with a single configuration line:

bundle config set --global mirror.https://rubygems.org https://rubygems.flatt.tech/

This transparently forwards all install requests through the proxy without changing your Gemfile.

GitHub Actions​

Add one line to your workflow:

steps:
  - uses: actions/checkout@v4
  - uses: flatt-security/setup-takumi-guard-rubygems@v1
  - run: bundle install

For full setup options including authentication and breach notifications, see the RubyGems quickstart guide.

Verify Your Setup​

Once you're set up, try installing the harmless test gem hola-takumi at the blocked version 0.1.0:

cd $(mktemp -d) && printf 'source "https://rubygems.org"\ngem "hola-takumi", "0.1.0"\n' > Gemfile && bundle install

If Takumi Guard is working, Bundler fails with the following error:

Fetching gem metadata from https://rubygems.flatt.tech/.
Could not find gem 'hola-takumi (= 0.1.0)' in rubygems repository
https://rubygems.org/ or installed locally.

For details, see "Verify Your Setup" in the RubyGems quickstart.

Email Registration Unlocks More (Free)​

Register your email to receive notifications if a gem you installed is later found to be malicious. Free of charge.

Step 1: Register your email

curl -X POST https://rubygems.flatt.tech/api/v1/tokens \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Step 2: Get your API key from the welcome email. The key is included directly in the email body — no link to click.

Step 3: Configure your package manager with your token (using the token from Step 2)

bundle config set --global mirror.https://rubygems.org https://token:tg_anon_xxxxxx@rubygems.flatt.tech/

Your installs are now tracked, and you will be notified if a downloaded package is later flagged.

Organization-Wide Management, Too​

Running Takumi Guard across your team? Admin deployment, installation log search, centralized org user token management, and breach-notification webhooks are all available for organization-wide operations. Get started with a Takumi subscription (Guard enabled):

1. Go to https://cloud.shisho.dev/hello/takumi and sign in
2. Register your organization and subscribe to Takumi
3. Navigate to Guard > Settings from the sidebar
4. Click "Enable" to activate Guard

Once Guard is enabled, follow the Admin Deployment guide to begin setup.

If you only need Bot token authentication from GitHub Actions, no payment is required. A payment screen appears during organization registration, but you can skip it — simply register your GitHub organization from the Guard page to receive a Bot ID.

Overview​

Previously, the Vulnerability Verification feature only supported vulnerabilities detected by Takumi blackbox assessments. With this update, you can manually create verification tasks for any vulnerability, even those not linked to a Takumi assessment.

This enables use cases such as:

• Validating vulnerability reports from bug bounty programs
• Verifying findings from third-party security audit reports

Availability​

This feature is available to all Takumi byGMO users.

For details, see the Vulnerability Verification documentation.

Overview​

With this release, organizations can configure:

• A webhook endpoint, chosen from the organization's existing outgoing webhooks.
• An email address, chosen from the organization's email allowlist (must be confirmed).

Either destination, or both, can be enabled. The same breach payload is sent to each configured destination, so teams can plug Guard into their incident response flow — forwarding to Slack / PagerDuty via webhook, paging a shared inbox by email, or both.

Getting Started​

Navigate to Guard > Settings in the Takumi / Shisho Cloud console and open the Breach Notifications section.

• Pick a webhook from the dropdown. If the list is empty, register one in the webhook settings page first.
• Pick a confirmed email address from the dropdown. If the list is empty, add and confirm one in the email allowlist first.
• Save. Settings take effect immediately for downloads going forward.

See the breach notifications user guide for the full description of when notifications are sent and how they are delivered.

Notes​

• Only downloads made after the destinations are saved are affected. Historical downloads are not re-notified when the configured destinations change.
• Per-token email notifications for email-verified tokens continue to work as before — no configuration needed.

Overview​

Issuing tokens from the console fits well into everyday workflows where individual tokens need to be issued on demand — for example, when a new teammate needs access on their first day, or when provisioning one for a contractor on a short engagement.

Right after issuance, the console displays the new token alongside ready-to-paste npm and PyPI setup commands, so the recipient can get started immediately.

The Guard API flow continues to work as before and remains the right choice for rolling out tokens at scale via configuration management or MDM tools.

Getting Started​

1. Open Guard > Tokens in the Shisho Cloud console.
2. Click Issue Token.
3. Enter a User Identifier and click Issue.

The token secret is shown only once at issuance. Copy it immediately and store it in a safe place.

For user identifier conventions, revocation, and other details, see Token Management.

Overview​

You can download assessment reports as PDF files with a professionally formatted cover page. This is useful for sharing results with stakeholders who prefer offline documents, or for archiving assessment records.

Getting Started​

On any completed assessment's report page, click the "Issue PDF Report" button and select a cover page language. Once the PDF is generated, a download link will be sent to your email address.

For details, please see the blackbox assessment documentation or the whitebox assessment documentation.

Overview​

Vulnerability Verification re-runs the original attack scenario for a specific vulnerability. Run it after deploying your fix to confirm that the remediation works as intended.

Dispatch it from the "Verify Vulnerability" button on an application assessment report, then select the vulnerability you want to verify.

The result is shown as Not Vulnerable or Vulnerable, along with the reasoning behind the verdict.

Prerequisites​

You need a completed blackbox assessment with at least one detected vulnerability. No additional setup, such as GitHub integration, is required.

Availability​

Vulnerability Verification is available to all Takumi byGMO users with blackbox assessment access.

For details, see the Vulnerability Verification documentation.

Overview​

Setting up Takumi Guard on individual developer machines can be time-consuming, especially for large teams. The new admin deployment feature provides ready-to-use scripts that configure npm, pip, uv, and Poetry to use the Guard registry proxy, handling token issuance and credential setup automatically.

Tokens issued by the setup script can be viewed and managed in the Shisho Cloud console under Guard > Tokens.

Getting Started​

The following diagram shows the overall architecture of admin deployment.

Steps:

1. Create a Bot in the Shisho Cloud console (Settings > Bots) and assign the "Takumi Guard Token Issuer" role
2. Generate an API key for the Bot
3. Download the setup script from Guard > Settings > Admin Deployment
4. Wrap the script with your management tool (Jamf, Intune, Ansible, etc.) and deploy

For detailed instructions, see the Admin Deployment guide.

Key Features​

Multi-ecosystem support​

Configures npm, pip, uv, and Poetry in a single script execution. No need to prepare separate instructions for each package manager your developers use.

Idempotent execution​

Safe to run multiple times. On the first run, the script issues a token and updates configuration files. On subsequent runs, it detects existing tokens and reuses them, skipping already-configured tools. This makes it safe to push via your management tool on a recurring schedule.

Incremental scope​

Start with npm only, then add PyPI later — incremental adoption is fully supported. Existing configurations are preserved when adding new ecosystems.

# First run: npm only
TG_BOT_API_KEY="..." ./setup.sh BOT_ID USER_ID npm

# Later: add PyPI (npm config is preserved)
TG_BOT_API_KEY="..." ./setup.sh BOT_ID USER_ID pypi

Backup creation​

Before modifying any configuration file, the script automatically creates a timestamped persistent backup (e.g., ~/.npmrc-backup-20260408-162351). To revert Guard configuration, simply copy the backup file back.

Important Notes​

Existing users who are already using Guard with email-verified tokens (tg_anon_…) cannot be consolidated into org user tokens (tg_org_…). Email-verified tokens and org user tokens are independent authentication methods. Existing email-verified tokens continue to work as before, but they are separate from the org user tokens issued by admin deployment.

If you want unified management across your organization, we recommend distributing org user tokens via admin deployment and asking developers to remove their existing email-verified token configurations.

Getting Started with Your Organization​

To use Guard's organization features (admin deployment, installation log search, etc.), you need a Takumi subscription with Guard enabled.

1. Go to https://cloud.shisho.dev/hello/takumi and sign in
2. Register your organization and subscribe to Takumi
3. Navigate to Guard > Settings from the sidebar
4. Click "Enable" to activate Guard

Once Guard is enabled, follow the Admin Deployment guide to begin setup.

Overview​

Package installation logs give you a searchable audit trail of all package downloads across your organization. Each log entry records the timestamp, package name and version, ecosystem (npm / PyPI), the principal who initiated the download, and whether it was allowed or blocked.

This enables faster incident response when a package is flagged as malicious — you can immediately identify which pipelines installed it and when.

Getting Started​

Navigate to Guard > Logs in the Shisho Cloud console.

Key Capabilities​

Search by package name​

Search for a package name to see when and by whom it was installed across your organization. You can also filter by version. This is useful for identifying the blast radius when a vulnerability is reported in a specific package.

Ecosystem switching​

Switch between npm and PyPI to search the ecosystem relevant to your organization's package managers.

Date range filtering​

Filter by preset ranges (24 hours, 7 days, 14 days) or specify a custom range. The searchable window is currently 14 days, and we plan to extend this as much as possible going forward.

Principal and status visibility​

Each log entry shows the principal who initiated the download (org user token identifier, anonymous token, etc.) and whether the download was allowed or blocked by the blocklist. Blocked downloads are also recorded, so you can verify that the blocklist is functioning as expected.

Future Vision​

We are working on making search criteria more flexible so you can filter logs from a wider variety of perspectives.

We are also exploring real-time log streaming for customers using SIEM and other enterprise security solutions. If you have requirements or use cases, please reach out to your account manager.

Overview​

To ensure that blocked packages remain blocked across all Yarn versions, Takumi Guard now processes package metadata differently for Yarn clients. This strengthens policy enforcement so that packages flagged by your organization's policies cannot bypass blocking through lockfile-based resolution.

What Changes​

Yarn v1​

After this change, yarn.lock entries will contain Takumi Guard's registry URL instead of the upstream registry URL. This is expected behavior and cannot be avoided — it is necessary to ensure that blocked packages are consistently enforced when resolved through the lockfile.

Yarn v2–v4 (Berry)​

Yarn v2–v4 users are not affected by this lockfile change.

npm, pnpm, and Bun​

No change. These package managers are unaffected.

Recommendation​

For new projects, we recommend using pnpm over Yarn. pnpm works seamlessly with Takumi Guard and offers strong supply chain security features out of the box.

Overview​

In "Scoped Assessment" mode, Takumi first crawls the target application to discover its features, then pauses so you can select which features and perspectives to assess.

Automatic crawling can sometimes miss endpoints that require complex navigation steps. With this new manual editing feature, you can adjust the crawl results before proceeding to the assessment. This allows you to include features and endpoints that the automatic crawler could not reach.

The following operations are available on the edit page:

• Add endpoints to existing features: Add missing endpoints to already-discovered features
• Remove endpoints from existing features: Exclude endpoints detected during crawling that are not needed for the assessment
• Add new features: Add features that were not detected during crawling, along with their endpoints

Note that hostnames can only be chosen from those already discovered during crawling. Apex features (representing the main entry point of the application) cannot be edited.

Getting Started​

This feature is available for blackbox assessments in the "Crawled" state. Click the "Edit Crawl Results" button at the bottom-left of the priority matrix on the assessment page to access the edit page.

For details, see the blackbox assessment documentation.

Background​

The software supply chain continues to face serious threats. Recent incidents such as the LiteLLM compromise (external link) and the axios compromise (summary by GMO Flatt Security) highlight that even widely-used packages are not immune to attacks. As demand for Takumi Guard grows in response to this landscape, we are committed to supporting organizations at scale.

Organizations with large-scale environments — many concurrent GitHub Actions jobs sharing a single token — could hit the previous 10,000 req/min rate limit during peak activity, resulting in 429 Too Many Requests errors. To ensure Takumi Guard can protect even the largest CI pipelines without friction, we have raised the limit.

What Changed​

The rate limit window for GitHub Actions/Bot tokens was reduced from 60 seconds to 10 seconds while keeping the same per-window count (10,000 requests). This effectively raises the allowed throughput to ~60,000 req/min per token.

No action is required on your side. The change is applied automatically.

Getting Started with Organization Usage​

To use Takumi Guard with a Bot token tied to your GitHub organization, follow these steps:

1. Visit https://cloud.shisho.dev/hello/takumi and sign in
2. Register your organization. A payment screen will be displayed, but payment is not required to use this feature
3. Navigate to the Guard page from the left sidebar
4. Enter the GitHub organization name you want to protect — a Bot ID will be issued for your organization

5. Add the setup step to your GitHub Actions workflow. Specifically, make the following three changes:
   • Add id-token: write to permissions (required for OIDC)
   • Add other required permissions such as contents: read
   • Add the flatt-security/setup-takumi-guard-npm@v1 action with your Bot ID

Once configured, all package requests from your GitHub Actions workflows will be authenticated with the Bot token and benefit from the higher rate limit.

Details​

See the Limitations & Caveats page for the full rate limit table.

Overview​

Previously, your API key was revealed only after clicking a verification link in the setup email. This worked in most environments, but enterprise email security tools (like Microsoft Defender Safe Links) pre-scan URLs via GET requests, consuming the one-time token before you could click it.

The new flow removes the link entirely. Your key and setup commands arrive ready to use.

Before: Register → click verification link → see key → configure your project

After: Register → key and copy-paste setup commands arrive in email → done

Security​

The key in your inbox has limited exposure. Here's why:

• The key alone exposes nothing. It cannot retrieve user data, download history, or any sensitive information.
• Invalid keys don't break your builds. If the key leaks and you invalidate it, npm install and pip install continue to work. Only the elevated rate limit (10k req/min) stops applying; the standard rate limit remains in effect.
• You can rotate immediately. The welcome email includes a one-line command to regenerate your key, so you can rotate it out of your inbox right after setup.

Key Recovery​

Lost your API key? No need to contact support.

Re-register with the same email to receive a reset code. Use it to generate a fresh key — the email includes a copy-pasteable command. If the code expires, simply re-register again. There is no dead end.

For details, see Token Management.

What's Staying the Same​

• Existing API keys continue to work — no action needed
• Old verification links now display instructions to re-register
• Both npm and PyPI ecosystems are supported

See Takumi Guard for setup instructions.

This ensures you can control credit consumption in advance, regardless of assessment type or mode, preventing unexpected large-scale credit usage.

What Changed​

All blackbox and whitebox assessments now require credit limits for each phase (feature enumeration and scanning).

This prevents running large-scale assessments without credit limits and incurring unintended excessive credit consumption. If the actual consumption exceeds the specified credit limit, the excess credits will not be charged.

Incremental Assessment Approach​

With credit limits, all assessments support an incremental approach:

• Start with a small credit limit to understand the assessment's scope and the types of vulnerabilities detected
• Review the interim report to decide whether additional scanning is needed
• Adjust credit limits and priorities as needed to run additional scans

This allows you to progressively expand the assessment scope while reviewing results, without consuming a large amount of credits at once.

Impact on Existing Assessments​

In-progress and completed assessments are not affected. This change applies to newly created assessments going forward.

User Guide​

For details on how to start an assessment, see the following documentation.

• Whitebox Assessment
• Blackbox Assessment

Risk Focus Assessment lets you start with the highest-risk areas, review results, and incrementally expand the assessment scope — all within a credit limit. You can set priorities explicitly or let Takumi prioritize automatically based on risk analysis. When the credit limit is reached, the assessment outputs results up to that point and stops. You can then add more credits and resume where you left off.

This is useful when you want predictable credit consumption or need to prioritize critical areas within a budget.

Usage Examples​

Assess within a Credit Limit​

To assess within a credit limit with automatic prioritization, specify crawl_credit_limit and/or scan_credit_limit when dispatching the workflow. Each can be set independently. The following example sets a crawl credit limit of 20 and a scan credit limit of 50 (consuming at most 70 credits total).

const { workflow_run_id } = await fetch(
  `${TAKUMI_API}/v1/o/${TAKUMI_ORG}/workflows/blackbox-assessment/dispatch`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      input: {
        language: "english",
        target_urls: ["https://app.example/"],

        crawl_credit_limit: 20, // Credit limit for crawling (optional)
        scan_credit_limit: 50, // Credit limit for scanning (optional)
      },
    }),
  },
).then((r) => r.json());

When crawl_credit_limit is set and the limit is reached during crawling, the crawl stops and scanning begins on the features discovered so far.

After crawling, Takumi automatically determines the priority of each feature-perspective combination based on risk analysis and scans them in priority order. When scan_credit_limit is reached, the assessment outputs the results collected so far and stops.

When the assessment finishes, you receive the assessment report and findings, along with a scan_progress artifact that shows which feature-perspective combinations were completed.

{
  // Combinations that were scanned
  "completed": [
    { "feature_name": "authentication", "perspective": "Injection" },
    { "feature_name": "user_settings", "perspective": "Authorization" },
    // ...
  ],
  // Combinations skipped because they were deemed unnecessary
  "skipped": [
    { "feature_name": "Apex", "perspective": "CSRF" },
    // ...
  ],
}

To assess more combinations, see Resume an Assessment with Additional Credits.

Assess within a Credit Limit with Custom Priorities​

You can also set priorities explicitly for each feature-perspective combination. This lets you adjust priorities based on business impact, recent code changes, or other factors. Specify the priority field in the pairs parameter used for scoped assessments and retests.

const { workflow_run_id } = await fetch(
  `${TAKUMI_API}/v1/o/${TAKUMI_ORG}/workflows/blackbox-assessment/dispatch`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      input: {
        language: "english",
        target_urls: ["https://app.example/"],

        scan_credit_limit: 50, // Credit limit for scanning (optional)

        // Reuse features discovered by a previous crawl workflow
        resume: {
          kind: "assess_crawled_features",
          assess_crawled_features: {
            workflow_id: "blackbox-crawl",
            workflow_run_id: "TWR...", // workflow_run_id of the crawl
          },
        },

        pairs: [
          // feature_name must match a name from the crawl workflow's `features` artifact
          {
            feature_name: "authentication",
            perspective: "Injection",
            priority: "high",
          },
          {
            feature_name: "user_settings",
            perspective: "Authorization",
            priority: "medium",
          },
          {
            feature_name: "product_catalog",
            perspective: "XSS",
            priority: "low",
          },

          // When priority is omitted, Takumi assigns one automatically based on risk analysis
          { feature_name: "checkout", perspective: "BusinessLogic" },
        ],
      },
    }),
  },
).then((r) => r.json());

When the credit limit is reached, you can check which combinations were completed using the scan_progress artifact, as described in Assess within a Credit Limit.

Resume an Assessment with Additional Credits​

You can resume an assessment that stopped due to a credit limit or was scoped to a subset of combinations. The resumed assessment inherits the previous results and continues scanning unscanned combinations in priority order.

const { workflow_run_id: next_workflow_run_id } = await fetch(
  `${TAKUMI_API}/v1/o/${TAKUMI_ORG}/workflows/blackbox-assessment/dispatch`,
  {
    method: "POST",
    headers,
    body: JSON.stringify({
      input: {
        language: "english",
        target_urls: ["https://app.example/"],

        scan_credit_limit: 50, // Credit limit for the additional scan (optional)

        resume: {
          kind: "continue_assessment",
          continue_assessment: {
            workflow_id: "blackbox-assessment",
            workflow_run_id: workflow_run_id, // workflow_run_id of the assessment to resume
          },
        },

        // Optionally scope or reprioritize (omit to let Takumi prioritize all remaining combinations)
        pairs: [
          // feature_name must match a name from the resumed assessment's `features` artifact
          {
            feature_name: "authentication",
            perspective: "Injection",
            priority: "high",
          },
          // ...
        ],
      },
    }),
  },
).then((r) => r.json());

You can optionally specify pairs to scope the resumed assessment to specific combinations or adjust priorities. If omitted, Takumi automatically prioritizes all remaining unscanned combinations.

You can repeat this cycle — assess, review results, resume — to incrementally expand your assessment scope while reviewing findings along the way.

Limitations​

This feature is only available for assessments dispatched via the Takumi API. You cannot resume a web console assessment from the API, or vice versa. For details, see Relationship with the Web Console's "Assessment" Feature in the API user guide.

Getting Started​

See the API documentation for full details.

Setting a Credit Limit​

When dispatching a crawl workflow, use the input.credit_limit parameter to cap credit consumption. Once the limit is reached, the crawl exits and outputs all features discovered so far.

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

        // Credit limit
        credit_limit: 20,
      },
    }),
  },
).then((r) => r.json());

Resuming a Crawl with Additional Credits​

To crawl more broadly or explore specific features in greater depth, you can resume a completed crawl. The resumed crawl inherits all previously discovered features and endpoints, and any newly found ones are added. You can also provide additional instructions to focus the crawl on specific areas.

const { workflow_run_id: crawl_workflow_run_id2 } = 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/"],

        // Resume from a previous crawl
        resume: {
          workflow_id: "blackbox-crawl",
          workflow_run_id: crawl_workflow_run_id, // workflow_run_id of the previous crawl
        },

        // Credit limit (optional)
        credit_limit: 20,

        // Additional instructions (optional)
        additional_instructions:
          "Focus on crawling the APIs (/api/v1/users/...) used by the page accessible at /page/abc",
      },
      notification: { webhook_endpoint_ids: [WEBHOOK_ID] },
    }),
  },
).then((r) => r.json());

Getting Started​

See the API documentation for details.

• 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:

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.

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:

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:

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.

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 in the API user guide.

Getting Started​

See the API documentation for full details.

Configuring Credit Limits and Assessment Priorities​

From this release onward, starting a new whitebox assessment will first perform feature enumeration only.

Once this process completes, the assessment transitions to Crawled status. Opening that assessment displays the Risk Focus assessment configuration screen.

From this screen, you can set the credit limit for the assessment and the assessment priority for each feature and perspective combination.

Additional Scans​

After the initial scan completes, the assessment enters Pending status. Opening that assessment lets you review the report of findings discovered so far, and run additional scans by adjusting the credit limit and priority settings.

User Guide​

See Whitebox Assessment for more details.

When a new version appears on PyPI, it is held for 72 hours before being made available through Takumi Guard. This gives security analysis systems time to detect malicious packages before they are installed in your projects.

Background​

Supply chain attacks targeting PyPI are increasing in both volume and sophistication. Attackers publish malicious packages and rely on automated tooling to pull them into projects within minutes — often before anyone has a chance to review them.

The majority of malicious packages are detected and removed within a few days of publication. By introducing a short waiting period, the quarantine significantly reduces the window of exposure.

This approach — known as a dependency cooldown — has been widely adopted across the JavaScript ecosystem (npm, pnpm, yarn, Bun). Takumi Guard brings the same protection to Python, working transparently with any package manager.

How It Works​

From the developer's perspective, pip install works exactly as before — it installs the latest version that has passed the quarantine window.

# Example: package has versions 1.0.0 (5 days old) and 1.1.0 (1 day old)
$ pip install --index-url https://pypi.flatt.tech/simple/ example-package

# pip installs 1.0.0 (passes quarantine)
# 1.1.0 is not yet available (published less than 72 hours ago)

After 72 hours, version 1.1.0 becomes available automatically — no action needed.

No Configuration Required​

If you are already using Takumi Guard for PyPI (https://pypi.flatt.tech/simple/), the quarantine is applied automatically. No changes to your setup are needed.

export PIP_INDEX_URL=https://pypi.flatt.tech/simple/
pip install requests  # works as before

The quarantine works with pip, uv, poetry, and any other PEP 503-compatible package manager — no per-tool configuration needed.

With this change, you can control credit consumption upfront for every blackbox assessment, preventing unexpected credit usage.

What changed​

Previously, you had to choose between a "standard assessment" and a "Risk Focus Assessment" when starting a blackbox assessment. With this update, specifying a credit threshold is now required for all blackbox assessments, and Risk Focus Assessment has been integrated as the standard assessment method.

Credit threshold​

You set a credit threshold for each assessment job at the time of creation. Takumi runs the job within the specified credit limit and stops when the threshold is reached. You will not be charged for any credits consumed beyond the threshold.

• In "Full Assessment" mode, you specify thresholds for both crawling and scanning at the start
• In "Scoped Assessment" mode, you specify the crawling threshold first, then set the scanning threshold when starting the scan

Risk Focus Assessment features​

Risk Focus Assessment is an approach that efficiently prioritizes high-risk areas using credit thresholds and priority settings. Its key features are as follows.

• Priority-based incremental assessment: Set priorities for each combination of features and perspectives to assess high-risk areas first
• Automatic priority assignment: Takumi automatically determines assessment priorities based on risk analysis. You can also set priorities manually
• Review interim results and run additional scans: After the assessment pauses upon reaching the credit threshold, you can review interim reports and choose to run additional scans or complete the assessment

Impact on existing assessments​

There is no impact on in-progress or completed assessments. This change applies only to newly created assessments going forward.

User guide​

See Blackbox Assessment for details.

Python projects using pip, uv, or poetry can now route installs through Takumi Guard to block known-malicious packages before they reach your CI or development environment.

Overview​

Takumi Guard is a security proxy that sits between your package manager and the upstream registry. It checks every install request against a real-time threat database and blocks known-malicious packages.

With this release, the same protection that npm users have is now available for the Python ecosystem:

• Package Blocking: Malicious PyPI packages are blocked before any code executes
• Download Tracking: Records install history for authenticated users
• Breach Notifications: Get notified if a package you installed is later flagged as malicious
• Version-Level Blocking: Block specific compromised versions while allowing safe versions through

Getting Started​

pip / uv​

Add the following to your shell profile (.bashrc, .zshrc, etc.):

# pip
export PIP_INDEX_URL=https://pypi.flatt.tech/simple/

# uv (does not read PIP_INDEX_URL — requires its own variable)
export UV_INDEX_URL=https://pypi.flatt.tech/simple/

Or configure in pip.conf (~/.config/pip/pip.conf on Linux/macOS, %APPDATA%\pip\pip.ini on Windows):

[global]
index-url = https://pypi.flatt.tech/simple/

For a one-time install without changing your environment:

pip install --index-url https://pypi.flatt.tech/simple/ <package>

poetry​

Add Takumi Guard as the primary source:

poetry source add --priority=primary takumi-guard https://pypi.flatt.tech/simple/

GitHub Actions​

Add one line to your workflow:

steps:
  - uses: actions/checkout@v4
  - uses: flatt-security/setup-takumi-guard-pypi@v1
  - run: pip install -r requirements.txt

For full setup options including authentication and breach notifications, see the PyPI quickstart guide.

Email Registration (Breach Notifications)​

Register your email to receive notifications if a package you installed is later found to be malicious. No account required, free of charge.

Step 1: Register your email

curl -X POST https://pypi.flatt.tech/api/v1/tokens \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com"}'

Step 2: Click the verification link in the email. You will see a page with your API key and setup instructions.

Step 3: Configure your package manager with your token

export PIP_INDEX_URL=https://token:tg_anon_xxxxxx@pypi.flatt.tech/simple/

# If you use uv, also add:
export UV_INDEX_URL=https://token:tg_anon_xxxxxx@pypi.flatt.tech/simple/

Your installs are now tracked, and you will be notified if a downloaded package is later flagged.

Supported Package Managers​