Bundler を使用する Ruby プロジェクトで、Takumi Guard 経由でインストールをルーティングすることで、CI や開発環境に届く前に悪性パッケージをブロックできるようになりました。

概要​

Takumi Guard は、パッケージマネージャーと上流レジストリの間に位置するセキュリティプロキシです。すべてのインストールリクエストを GMO Flatt Security の脅威データベースと照合し、悪性パッケージをブロックします。

今回のリリースにより、npm・Python ユーザーが利用していた保護機能が Ruby エコシステムでも利用可能になりました。

• パッケージブロック: 悪性な gem をコード実行前にブロック
• ダウンロード追跡: 認証済みユーザーのインストール履歴を記録
• 感染可能性の通知: ダウンロードした Gem が後から悪性であると判明した場合に通知

利用開始方法​

以下のいずれも、アカウント登録不要で匿名のまま利用できます。

Bundler​

Takumi Guard 経由で bundle install をルーティングする設定です。設定行を 1 つ追加するだけで、すべてのインストールリクエストがプロキシを通過するようになります。

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

Gemfile の変更は不要で、透過的にプロキシを通じてすべてのインストールリクエストが処理されます。

GitHub Actions​

ワークフローに 1 行追加するだけで導入できます。

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

認証や感染可能性の通知を含む詳細なセットアップ手順は RubyGems クイックスタートガイド をご覧ください。

検証方法​

セットアップが完了したら、検証用・無害なブロック済み gem hola-takumi のバージョン 0.1.0 をインストールしてみてください。

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

Takumi Guard が正しく動作していれば、Bundler は以下のエラーでインストールに失敗します。

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.

詳しい手順は RubyGems クイックスタートの「セットアップの確認」 を参照してください。

メール登録してより便利に（無料）​

メールアドレスを登録すると、ダウンロードした Gem が後から悪性であると判明した場合に通知が届きます。無料で利用できます。

ステップ 1: メールアドレスを登録する

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

ステップ 2: ウェルカムメールから API キーを取得する。API キーはメール本文に直接記載されています。リンクをクリックする手順は不要です。

ステップ 3: トークンでパッケージマネージャーを設定する（ステップ 2 で取得したトークンを使用）

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

以降のインストールが追跡され、ダウンロードしたパッケージに問題が見つかった場合に通知が届きます。

組織単位での管理も可能​

チームで Takumi Guard を運用するなら、管理ツールによる一括セットアップ、インストールログの検索、組織ユーザートークンの一元管理、感染可能性の Webhook 通知 など、組織単位での運用を効率化する機能がまとめて利用できます。Takumi サブスクリプション（Guard 有効化）で始められます。

1. https://cloud.shisho.dev/hello/takumi にアクセスし、サインインする
2. 組織を登録し、Takumi サブスクリプションを契約する
3. 画面左のサイドバーから Guard > 設定 にアクセスする
4. 「有効化する」ボタンをクリックして Guard を有効化する

有効化が完了したら、管理ツールによる一括セットアップガイドに従ってセットアップを進めてください。

なお、GitHub Actions の Bot トークン 利用だけなら決済は不要です。組織登録時に決済画面が表示されてもそのままスキップして、Guard ページから GitHub 組織を登録するだけで Bot ID を取得できます。

機能概要​

これまで脆弱性検証機能は、Takumi のブラックボックス診断で検出された脆弱性のみを対象としていました。 本アップデートにより、Takumi による診断結果に紐づかない脆弱性についても、手動で検証タスクを作成して再現検証を実行できるようになりました。

これにより、以下のようなユースケースに対応できます。

• バグバウンティプログラムで報告された脆弱性の妥当性確認
• 第三者の脆弱性診断レポートに含まれる指摘事項の検証

提供範囲​

本機能は、すべての Takumi byGMO ユーザにご利用いただけます。

使い方の詳細は 脆弱性検証 のドキュメントをご覧ください。

概要​

今回のアップデートにより、組織ごとに以下の通知先を設定できます。

• Webhook エンドポイント: 組織に登録済みの Webhook から選択します。
• メールアドレス: 組織のメール許可リストで確認済みのアドレスから選択します。

どちらか一方、両方、またはいずれも使用しない、のいずれの設定も可能です。設定した通知先には同じ通知ペイロードが送信されるため、Webhook 経由で Slack や PagerDuty に転送したり、共有メールアドレスでインシデント対応フローに載せたりと、既存の運用に合わせて組み込めます。

利用方法​

Shisho Cloud/Takumi 管理コンソールで「Guard > 設定」を開き、感染可能性の通知 セクションから設定してください。

• Webhook をドロップダウンから選択します。一覧が空の場合は、先に Webhook 設定ページから登録してください。
• 確認済みのメールアドレスをドロップダウンから選択します。一覧が空の場合は、先にメール許可リストへアドレスを追加し、確認を完了してください。
• 保存すると、以降のダウンロードに対して設定が反映されます。

通知が送信される条件や配信の仕組みについては、感染可能性の通知のユーザーガイドを参照してください。

補足​

• 通知先の保存以降に発生したダウンロードのみが対象です。通知先を変更しても、過去のダウンロードに対して改めて通知が送信されることはありません。
• メール認証トークンに対する従来の通知は、これまで通り、登録したメールアドレス宛に行われます。なおメール認証トークンをShisho Cloud 組織に紐づけることはできません。

概要​

コンソールからの発行は、日常的な運用のなかで必要に応じて個別にトークンを発行したいケースに適しています。たとえば、新しくチームに加わったメンバーが初日から利用を開始する場合や、短期の業務委託メンバー向けに発行する際に活用できます。

発行直後には、新しいトークンとあわせて npm・PyPI 向けのセットアップコマンドが表示されるため、受け取った側もすぐに利用を開始できます。

Guard API 経由の発行フローはこれまで通り利用でき、構成管理ツールや MDM を使った大規模配布には引き続き最適な選択肢です。

利用方法​

1. Takumi / Shisho Cloud コンソールで Guard > トークン に移動してください。
2. トークン発行 をクリックしてください。
3. ユーザー識別子 を入力して 発行 をクリックしてください。

トークンのシークレットは発行時に 一度だけ 表示されます。必ず発行直後にコピーして、安全な場所に保管してください。

ユーザー識別子の命名例や失効方法など、詳細はトークンの管理を参照してください。

概要​

診断レポートを、フォーマットされた表紙付きの PDF ファイルとしてダウンロードできます。オフラインでの共有や、診断記録のアーカイブに活用できます。

利用開始方法​

完了済みの診断レポートページで 「PDFレポートを発行」 ボタンをクリックし、表紙の言語を選択します。PDF の生成が完了すると、メールでダウンロードリンクが送付されます。

詳しくはブラックボックス診断のドキュメントまたはホワイトボックス診断のドキュメントをご覧ください。

機能概要​

脆弱性検証機能は、特定の脆弱性に対して以前と同じ攻撃シナリオを再実行します。 修正をデプロイした後に本機能を実行することで、対策が有効に機能しているかを検証することができます。

アプリケーション診断報告書の「脆弱性を検証する」ボタンから、対象の脆弱性を選択して実行します。

検証結果は 「脆弱性なし」 または 「脆弱性あり」 の判定として、理由とともに表示されます。

前提条件​

1件以上の脆弱性が検出された、完了済みのブラックボックス診断結果が必要です。GitHub連携等の追加設定なしで利用可能です。

提供範囲​

本機能は、ブラックボックス診断をご利用のすべての Takumi byGMO ユーザにご利用いただけます。

詳しくは 脆弱性検証 のドキュメントをご覧ください。

概要​

大規模なチームでは、個々の開発者マシンに Takumi Guard をセットアップするのに時間がかかります。一括セットアップ機能は、npm・pip・uv・Poetry に対して Guard レジストリプロキシを設定するスクリプトを提供し、トークンの発行とクレデンシャルの設定を自動的に処理します。

セットアップスクリプトによって発行されたトークンは、Takumi / Shisho Cloud コンソールの Guard > トークン で一覧・管理できます。

利用方法​

以下の図は、一括セットアップの全体構成を示しています。

手順は以下の通りです。

1. Takumi / Shisho Cloud コンソール（設定 > ボット）で Bot を作成し、「Takumi Guard トークン発行者」ロールを付与する
2. Bot の API キーを生成する
3. Guard > 設定 からセットアップスクリプトをダウンロードする
4. お使いの管理ツール（Jamf、Intune、Ansible など）でラッパースクリプトを作成し、対象端末に配信する

詳しい手順は管理ツールによる一括セットアップガイドを参照してください。

主な特徴​

マルチエコシステム対応​

npm・pip・uv・Poetry を 1 回のスクリプト実行でまとめて設定できます。開発者がどのパッケージマネージャーを使っていても、個別に手順を用意する必要はありません。

冪等な実行​

同じスクリプトを複数回実行しても安全です。初回実行時にトークンを発行し、設定ファイルを更新しますが、再実行時には既存のトークンを検出して再利用し、設定済みのツールはスキップします。管理ツールから定期的に配信しても問題ありません。

段階的なスコープ追加​

最初は npm のみを対象にセットアップし、後から PyPI を追加するといった段階的な導入が可能です。追加時にも既存の設定は維持されます。

# 初回：npm のみセットアップ
TG_BOT_API_KEY="..." ./setup.sh BOT_ID USER_ID npm

# 後日：PyPI を追加（npm の設定はそのまま維持）
TG_BOT_API_KEY="..." ./setup.sh BOT_ID USER_ID pypi

バックアップ作成​

設定ファイルを変更する前に、タイムスタンプ付きの永続バックアップを自動的に作成します（例：~/.npmrc-backup-20260408-162351）。万が一 Guard の設定を元に戻したい場合は、バックアップファイルをコピーするだけで復旧できます。

留意事項​

メール認証トークン（tg_anon_…）で既に Guard を利用しているユーザーを、組織ユーザートークン（tg_org_…）にまとめることはできません。メール認証トークンと組織ユーザートークンは独立した認証方式であり、既存のメール認証トークンは引き続きそのまま利用できますが、一括セットアップで発行される組織ユーザートークンとは別のものです。

組織全体で統一した管理を行いたい場合は、一括セットアップで新たに組織ユーザートークンを配信し、開発者に既存のメール認証トークンの設定を削除してもらうことを推奨します。

組織での利用を始める​

Takumi Guard の組織向け機能（一括セットアップ、インストールログの検索など）を利用するには、Takumi サブスクリプションの契約と Guard の有効化が必要です。

1. https://cloud.shisho.dev/hello/takumi にアクセスし、サインインする
2. 組織を登録し、Takumi サブスクリプションを契約する
3. 画面左のサイドバーから Guard > 設定 にアクセスする
4. 「有効化する」ボタンをクリックして Guard を有効化する

有効化が完了したら、管理ツールによる一括セットアップガイドに従ってセットアップを進めてください。

概要​

パッケージインストールログは、組織全体のパッケージダウンロードの検索可能な監査証跡を提供します。各ログエントリには、タイムスタンプ、パッケージ名とバージョン、エコシステム（npm / PyPI）、ダウンロードを開始した主体（プリンシパル）、許可またはブロックされたかのステータスが記録されます。

悪意あるパッケージが報告された際に、どのパイプラインがいつインストールしたかを迅速に特定できます。

利用方法​

Takumi / Shisho Cloud コンソールの Guard > ログ から利用できます。

主な機能​

パッケージ名による検索​

パッケージ名を入力して、組織全体でそのパッケージがいつ・誰によってインストールされたかを検索できます。バージョンを指定しての絞り込みにも対応しています。特定のパッケージに脆弱性が報告された際などに、影響範囲の特定に活用できます。

エコシステムの切り替え​

npm と PyPI を切り替えて検索できます。組織で利用しているパッケージマネージャーに応じて、対象のエコシステムを選択してください。

日付範囲の指定​

24 時間・7 日間・14 日間のプリセット、またはカスタム範囲で検索期間を絞り込めます。現時点では検索可能な範囲は過去 14 日間までですが、今後可能な限り拡張していく予定です。

プリンシパルとステータスの確認​

各ログエントリには、ダウンロードを開始した主体（組織ユーザートークンの識別子、匿名トークンなど）と、ブロックリストによってダウンロードが許可されたか・ブロックされたかのステータスが表示されます。ブロックされたダウンロードも記録されるため、ブロックリストが実際に機能していることを確認できます。

今後の展望​

検索条件をより柔軟にし、さまざまな観点からログを絞り込めるよう改善を進めていきます。

また、SIEM をはじめとする法人向けセキュリティソリューションを利用されているお客様向けに、ログ全量をリアルタイムにストリーム配信する仕組みも検討しています。ご要望やユースケースがありましたら、アカウントマネージャーまでお知らせください。

変更内容​

Yarn クライアントのみを対象に、ロックファイル内に対するメタデータ書き換えの挙動を変更しました。具体的には、メタデータ配信時に、tarball dist URLs を Takumi Guard レジストリの URL に書き換えるように変更されました。

変更背景​

Yarn v1 は tarball dist URLs を lockfile 内に含める挙動を取り、Yarn v2+ クライアントは、レジストリから得られるパッケージメタデータファイル内の tarball dist URLs とレジストリURLに乖離がある場合に lockfile 内に __archiveUrl フィールドを追加します。この挙動により、yarn 実行時にロックファイルのみが参照されるシナリオで、yarn クライアントが Takumi Guard を迂回する挙動をとる場合がございます。

変更の影響範囲​

npm・pnpm・Bun 等への影響​

影響はありません。

Yarn v1 への影響: 新規パッケージの追加・更新時に有​

yarn.lock のエントリに、従来のアップストリームレジストリ URL ではなく Takumi Guard のレジストリ URL が記録されるようになります。 これは他パッケージマネージャの利用時には起こらない挙動ですが、Yarn v1 においてのみ発生します。これはロックファイル経由の依存解決シナリオで、安定してブロック対象パッケージのインストールを防止するために必要な変更でございますので、ご理解いただけますと幸いです。

Yarn v2–v4（Berry）への影響: 無​

既存の yarn.lock 内の __archiveUrl フィールドが、次回のパッケージ更新時に削除されるようになります。この点以外には、既知の影響はありません。

概要​

「一部だけ診断」モードでは、まず対象アプリケーションをクロールして機能を洗い出し、その後に診断する機能・観点を選択して診断を実行します。

自動クロールは、複雑なステップが必要なエンドポイント等を見落とすことがあります。今回追加した手動編集機能を使うと、クロール完了後にその結果を調整したうえで診断に進めます。これにより、自動クロールでは到達できなかった機能・エンドポイントも診断対象に含めることができます。

編集ページでは、以下の操作が可能です。

• 既存機能へのエンドポイント追加: クロール済みの機能に、不足しているエンドポイントを追加します
• 既存機能からのエンドポイント削除: クロールで検出されたが診断対象として不要なエンドポイントを除外します
• 新規機能の追加: クロールで検出されなかった機能を、エンドポイントとあわせて追加します

利用開始方法​

本機能は Takumi によるブラックボックス診断機能にてご利用いただけます。

詳しくはブラックボックス診断のドキュメントをご覧ください。

背景​

ソフトウェアサプライチェーンへの脅威は深刻さを増しています。LiteLLM の侵害事案（外部リンク）や axios の侵害事案（弊社によるまとめ）に見られるように、広く利用されているパッケージであっても攻撃の対象となりえます。こうした状況を受け、Takumi Guard へのニーズは増加しており、可能な限りの貢献を果たすべく、大規模環境への対応を強化しています。

多数の GitHub Actions ジョブが単一トークンを共有する大規模環境では、ピーク時に従来の 10,000 回/分のレートリミットに到達し、429 Too Many Requests エラーが発生するケースがありました。最大規模の CI パイプラインでも Takumi Guard を摩擦なく利用できるよう、今回レートリミットを引き上げました。

変更内容​

GitHub Actions/Bot トークンのレートリミットウィンドウを 60 秒から 10 秒に短縮し、ウィンドウあたりのリクエスト数（10,000 回）は維持しました。これにより、実効スループットが約 60,000 回/分に向上しています。

ご利用者様側での対応は不要です。変更は自動的に適用されています。

組織での利用を始める​

Bot トークンを利用して GitHub 組織単位で Takumi Guard を導入するには、以下の手順で設定してください。

1. https://cloud.shisho.dev/hello/takumi にアクセスし、サインインする
2. 組織を登録する。決済画面が表示されますが、本機能の利用に決済は不要です
3. 画面左のサイドバーから Guard ページにアクセスする
4. 保護対象の GitHub 組織名を入力する — 組織に紐づく Bot ID が発行されます

5. GitHub Actions ワークフローにセットアップステップを追加します。具体的には、以下の 3 点を変更してください。
   • permissions に id-token: write を追加する（OIDC に必要）
   • contents: read など、ワークフローに必要な他の権限を追加する
   • flatt-security/setup-takumi-guard-npm@v1 アクションを Bot ID 付きで追加する

設定が完了すると、GitHub Actions ワークフローからのパッケージリクエストが Bot トークンで認証され、引き上げ後のレートリミットが適用されます。

詳細​

レートリミットの全体については制限事項・注意事項をご覧ください。

変更内容​

従来は、メール内の確認リンクをクリックして API キーを確認する流れでした。この方式はやや煩雑であり、かつ何らかの仕組み（セキュリティツール等）が事前に内容を確認する場合に、一部環境でセットアップがブロックされるケースもありました。

新しいフローでは、リスク評価の上、確認リンクを廃止しました。

• 変更前: 登録 → メール内のリンクをクリック → キーを表示 → 手動でコマンドを置き換え、設定
• 変更後: 登録 → メール内のセットアップコマンドをコピー＆ペーストで完了

メールには API キーの更新コマンドも含まれているため、セットアップ直後に API キーを新しいものに置き換えることもできます。

補足：セキュリティに関して​

メールに API キーが記載される方式の場合、メールサービス内に API キーが残置されます。 一方、以下の通り、本 API キーは漏洩時も大きなリスクを伴いません。

• APIキーを介して取得できる情報は、APIキーの最終利用日時のみです。 今後の機能追加に際しても、この挙動は維持されます。パッケージのダウンロード履歴や、ユーザーのアカウント情報などは取得できません。
• 無効なAPIキーでも、パッケージのブロックは動作します。 仮にAPIキーが漏洩・無効化されても、npm install や pip install は標準レート制限で動作し続けます。認証済ユーザーへのレートリミット（10,000 リクエスト/分）は適用されなくなります。

かつ、APIキーはいつでも CLI でローテーション可能であるため、残置が好ましくない場合はローテーションいただくこともできます。

補足：API キーを紛失した場合​

以前の API キーが見つからなくても、サポートへの問い合わせは不要です。

同じメールアドレスで再登録すると、リセットコードが届きます。このコードで新しいキーを生成できます。メールにはそのままコピー＆ペーストできるコマンドが記載されているため、複雑な手続きは不要です。コードの有効期限が切れた場合は、再度登録するだけで新しいコードを受け取れます。

詳細はトークン管理をご覧ください。

その他​

• 既存ユーザーの API キーはそのまま利用可能です。本変更に伴う対応は不要です。
• 古い確認リンクにアクセスすると、再登録の手順を案内するページが表示されます。
• 本変更は、npm・PyPI の両エコシステムに対応しています。

セットアップ手順については Takumi Guard をご参照ください。

これにより、どの診断タイプ・どの診断モードであっても、消費クレジット量を事前にコントロールできるようになり、意図しない大量のクレジット消費を防ぐことができます。

変更内容​

すべてのブラックボックス診断・ホワイトボックス診断において、診断の各フェーズ（機能列挙・スキャン）ごとにクレジット上限の指定が必須となりました。

これにより、クレジット上限が未設定のまま大規模な診断を実行し、意図しない大量のクレジット消費が発生する事象を防止できます。なお、実際の消費量が指定したクレジット上限を超過した場合でも、超過分のクレジットは請求されません。

段階的な診断の実施​

クレジット上限の仕組みにより、すべての診断で段階的なアプローチが可能です。

• 初回はクレジット上限を小さく設定して、診断の傾向や検出される脆弱性の種類を確認する
• 中間レポートを確認した上で、追加スキャンの必要性を判断する
• 必要に応じてクレジット上限と優先度を調整しながら、追加スキャンを実施する

これにより、一度に大量のクレジットを消費することなく、診断結果を見ながら段階的に診断範囲を広げていくことができます。

既存の診断への影響​

実行中および完了済みの診断には影響ありません。今後新しく作成する診断から本変更が適用されます。

ユーザーガイド​

診断の開始方法については、以下のドキュメントを参照してください。

• ホワイトボックス診断（都度）
• ブラックボックス診断

リスクフォーカス型診断は、指定したクレジットの範囲内で、優先度の高い機能・観点から診断を進めるものです。優先度は明示的に指定することも、Takumi に優先度づけを任せることもできます。クレジット上限に達すると、Takumi はそこまでの診断結果（レポート等）を出力して中断します。中断した診断に対して、クレジットを追加して続きから診断を再開することも可能です。

クレジット消費を予測可能にしたい場合や、予算内で重要な箇所を優先的に診断したい場合などに活用いただけます。

活用例​

指定したクレジットの範囲内で診断する​

診断する機能・観点の優先度づけを Takumi に任せ、指定したクレジットの範囲内で診断を実行するには、crawl_credit_limit および scan_credit_limit を指定してワークフローを呼び出します。クロールとスキャンそれぞれに対してクレジット上限を設定でき、片方だけの設定も可能です。以下の例では、クロール時のクレジット上限を 20、スキャン時のクレジット上限を 50 に設定しています（このとき、最大でも 70 クレジットの消費となります）。

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

        crawl_credit_limit: 20, // クロールに使うクレジットの上限 (任意)
        scan_credit_limit: 50, // スキャンに使うクレジットの上限 (任意)
      },
    }),
  },
).then((r) => r.json());

クロールに使うクレジットの上限 crawl_credit_limit を指定した場合、クロール中にクレジット上限に達するとそこでクロールを終了し、そこまでに発見された機能に対してスキャンを実行します。

クロールの終了後、発見されたそれぞれの機能と観点の組み合わせに対して、Takumi がリスク分析に基づいて優先度を自動的に決定し、優先度の高いものから順にスキャンを実行します。スキャン中にクレジット上限 scan_credit_limit に達すると、そこまでの診断結果を出力して診断が終了します。

診断が終了すると、診断レポートや検出された脆弱性一覧に加え、「どの機能・観点は診断完了したのか」を示す scan_progress というアーティファクトが出力されます。

{
  // 診断完了した機能・観点の組み合わせ
  "completed": [
    { "feature_name": "認証", "perspective": "Injection" },
    { "feature_name": "ユーザー設定", "perspective": "Authorization" },
    // ...
  ],
  // 診断の必要がないと判定されたためスキップされた組み合わせ
  "skipped": [
    { "feature_name": "Apex", "perspective": "CSRF" },
    // ...
  ],
}

より多くの機能・観点を診断したい場合は、クレジットを追加して診断を続行するを参照してください。

機能・観点の優先度を指定して、クレジット上限の範囲内で診断する​

診断する機能・観点の優先度を明示的に指定することも可能です。ビジネスインパクトの大きさや前回診断からのアップデートの有無などに基づき、自由に優先度を調整できます。具体的には、「一部だけ診断」「再診断」で用いる pairs パラメータに priority フィールドを指定します。

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

        scan_credit_limit: 50, // スキャンに使うクレジットの上限 (任意)

        // クロールワークフローで発見された機能一覧を利用するよう指定
        resume: {
          kind: "assess_crawled_features",
          assess_crawled_features: {
            workflow_id: "blackbox-crawl",
            workflow_run_id: "TWR...", // クロールワークフローの実行 ID
          },
        },

        pairs: [
          // feature_name には、クロールワークフローの `features` アーティファクトに記載された機能名を指定
          { feature_name: "認証", perspective: "Injection", priority: "high" },
          {
            feature_name: "ユーザー設定",
            perspective: "Authorization",
            priority: "medium",
          },
          { feature_name: "商品カタログ", perspective: "XSS", priority: "low" },

          // 優先度を指定しない場合は、Takumi がリスク分析に基づいて自動的に優先度を判断
          { feature_name: "決済", perspective: "BusinessLogic" },
        ],
      },
    }),
  },
).then((r) => r.json());

診断中にクレジット上限に達して終了した場合に、どの機能・観点の組み合わせが診断完了したのかを確認する方法は、「指定したクレジットの範囲内で診断する」の記載と同様です。

クレジットを追加して診断を続行する​

クレジット上限に達して終了した診断や、一部の機能・観点だけを pairs に指定して実行した診断など、未診断の機能・観点がある診断に対して、クレジットを追加して続きから診断を再開できます。再開された診断では、前回の診断結果が引き継がれ、未診断の機能・観点のうち優先度の高いものから順に診断が進みます。

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: "japanese",
        target_urls: ["https://app.example/"],

        scan_credit_limit: 50, // 追加スキャンに使うクレジットの上限 (任意)

        resume: {
          kind: "continue_assessment",
          continue_assessment: {
            workflow_id: "blackbox-assessment",
            workflow_run_id: workflow_run_id, // 再開したい診断のワークフロー実行 ID
          },
        },

        // 診断する機能・観点の絞り込み・優先度の調整 (任意)
        pairs: [
          // feature_name には、再開元の診断ワークフローの `features` アーティファクトに記載された機能名を指定
          { feature_name: "認証", perspective: "Injection", priority: "high" },
          // ...
        ],
      },
    }),
  },
).then((r) => r.json());

診断を続行する際には、pairs パラメータを指定して診断対象を絞り込んだり、優先度を調整したりすることもできます。省略した場合は、未診断の機能・観点全てに対し Takumi がリスク分析に基づいて自動的に優先度を判断して診断を進めます。

このサイクル（診断 → 結果確認 → 再開）を繰り返すことで、結果を見ながら段階的に診断範囲を広げていくことも可能です。

制限事項​

本機能は Takumi API 経由で実行した診断に対してのみ利用可能です。Web コンソールから実行した診断を API から続行したり、その逆を行うことはできません。詳細は API ユーザーガイドの「Web コンソールの「診断」との関係」をご覧ください。

利用開始方法​

詳細は API ドキュメントをご覧ください。

クレジット上限を指定してクロールする​

クロールワークフローを実行する際、input.credit_limit パラメータを用いてクロール時のクレジット消費の上限を指定できます。指定した場合、クレジット上限に達するとそこでクロールが終了し、そこまでに検出された機能一覧を出力します。

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

        // クレジット上限
        credit_limit: 20,
      },
    }),
  },
).then((r) => r.json());

クレジットを追加して続きからクロールを再開する​

より幅広くクロールしたい場合や、特定の機能をより深くクロールしたい場合に、終了したクロールに対して追加クロールを実行できます。追加クロールでは、発見済みの機能・エンドポイント一覧が引き継がれ、新たに発見された機能・エンドポイントが追加されます。追加クロール実行時に、クロールする対象を絞り込むための指示を与えることもできます。

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: "japanese",
        target_urls: ["https://app.example/"],

        // 前回クロールの結果を引き継いで追加クロールする
        resume: {
          workflow_id: "blackbox-crawl",
          workflow_run_id: crawl_workflow_run_id, // 前回クロールの workflow_run_id を指定
        },

        // クレジット上限 (任意)
        credit_limit: 20,

        // 追加の指示 (任意)
        additional_instructions:
          "/page/abc でアクセスできるページにおいてやり取りされる API (/api/v1/users/...) を重点的にクロールしてください",
      },
      notification: { webhook_endpoint_ids: [WEBHOOK_ID] },
    }),
  },
).then((r) => r.json());

利用開始方法​

詳細は API ドキュメントをご覧ください。

• 一部だけ診断: まず対象アプリケーションの機能をクロールし、Takumi が停止します。その後、診断したい機能や観点を選択して診断を実行します
• 再診断: 過去の診断結果で脆弱性が指摘された箇所を指定して診断を実行します

これらをサポートするため、ブラックボックス診断 API に対し以下の拡充を行いました。

• クロールワークフロー blackbox-crawl を追加
  対象アプリケーションをクロールし、洗い出した機能を出力するワークフローです。診断は行いません。
• 診断ワークフロー blackbox-assessment において、診断観点・機能を指定するオプションを追加
  過去のワークフロー (クロール・診断) で洗い出した機能の中から、診断対象とする機能や観点を選択できます。

一部だけ診断​

以下の流れで、機能・観点を絞り込んだ「一部だけ診断」を実現できます。

1. クロールワークフローを実行し、対象アプリケーションの機能を洗い出す
2. クロール結果をもとに診断対象とする機能・観点を選択し、診断ワークフローを実行する

重要度の高い箇所に絞って診断したい場合や、最近アップデートした機能だけを診断したい場合などに活用いただけます。

クロールワークフローを実行​

クロールワークフローは以下のように呼び出せます。

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

機能・観点を選択して診断ワークフローを実行​

クロールワークフローが完了したら、洗い出された機能一覧を確認します。クロールで発見された機能一覧は 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); // => "認証", "ユーザー設定", "商品カタログ", ...
  console.log("feature description:", feature.description);
}

ここから診断したい機能名 (feature.name) と観点を選択し、クロールワークフローの 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/"],

        // クロールワークフローで発見された機能一覧を再利用するよう指定
        resume: {
          kind: "assess_crawled_features",
          assess_crawled_features: {
            workflow_id: "blackbox-crawl",
            workflow_run_id: crawl_workflow_run_id,
          },
        },

        // 診断対象とする機能・観点を指定
        pairs: [
          { feature_name: "認証", perspective: "Injection" },
          { feature_name: "ユーザー設定", perspective: "Authorization" },
          { feature_name: "商品カタログ", perspective: "XSS" },
        ],
      },
    }),
  },
).then((r) => r.json());

再診断​

ブラックボックス診断の結果には、検出された脆弱性ごとに「どの機能のどの観点で見つかったか」という情報が含まれています。

脆弱性を修正した後に再診断したい際には、これらの情報を利用して、当該脆弱性が指摘された機能・観点だけを対象に診断を実行できます。例えば、認証機能におけるインジェクションの脆弱性を修正した後に、そこだけを再診断できます。

たとえば、認証機能で Injection の脆弱性が報告された場合、修正後にその組み合わせだけを再診断する、といった使い方が可能です。

まず、すでに完了した診断で検出された脆弱性を確認するには、findings という名前のアーティファクトをダウンロードします。

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); // => "認証", "ユーザー設定", ...
  console.log("perspective:", finding.perspective); // => "Injection", "Authorization", ...
  console.log("markdown description:", finding.description);
}

脆弱性を修正した後に再診断するには、この findings アーティファクトに記載されていた機能名 (finding.feature_name) と観点 (finding.perspective) を指定して再診断を実行します。前回診断に用いられた機能一覧情報を引き継ぐため、診断ワークフローの 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/"],

        // 前回の診断ワークフローで利用していた機能一覧を再利用するよう指定
        resume: {
          kind: "assess_crawled_features",
          assess_crawled_features: {
            workflow_id: "blackbox-assessment",
            workflow_run_id: "TWR...", // 前回診断の workflow_run_id を指定
          },
        },

        // 再診断したい機能・観点を指定
        pairs: [{ feature_name: "認証", perspective: "Injection" }],
      },
    }),
  },
).then((r) => r.json());

制限事項​

「一部だけ診断」と「再診断」は、Takumi API 経由で実行したクロール・診断に対してのみ利用可能です。Web コンソールから実行したクロール・診断の結果は、API 経由では利用できません。これは、Takumi API と Web コンソールの「診断」機能のデータが独立に管理されているためです。詳細は API ユーザーガイドの「Web コンソールの「診断」との関係」をご覧ください。

利用開始方法​

詳細は API ドキュメントをご覧ください。

クレジット上限と各機能・観点の診断優先度の設定​

本リリース以降、新規に「ソースコード」を対象にした診断を開始すると、まず対象機能の列挙のみが行われます。

上記の処理が完了すると、診断が「機能列挙済」の状態に遷移します。その診断のページを開くと、リスクフォーカス診断のための設定画面が表示されます。

この画面から、診断のクレジット上限、および、各機能・観点の組み合わせに対する診断優先度を設定できます。

追加スキャン​

初回の診断が完了後、診断が「診断再開待ち」の状態になります。その診断のページを開くと、これまでの診断結果のレポートを確認したり、クレジット上限や優先度の設定を変更して追加スキャンを実行したりすることができます。

ユーザーガイド​

ホワイトボックス診断（都度） を参照してください。

PyPI に新しいバージョンが公開されると、72時間の検疫期間を経てから Takumi Guard 経由で利用可能になります。この待機期間により、悪意あるパッケージがプロジェクトにインストールされる前にセキュリティ分析で検知できるようになります。

背景​

PyPI を標的としたサプライチェーン攻撃は増加の一途をたどっています。攻撃者は悪意あるパッケージを公開し、自動化されたツールによって数分以内にプロジェクトに取り込まれることを狙います。

悪意あるパッケージの大半は、公開から数日以内に検知・削除されます。短い待機期間を設けることで、攻撃に晒される期間を大幅に短縮できます。

このアプローチは 依存関係クールダウン と呼ばれ、JavaScript エコシステム（npm、pnpm、yarn、Bun）では広く採用されています。Takumi Guard は同等の保護を Python にもたらし、すべてのパッケージマネージャで透過的に動作します。

仕組み​

開発者から見ると、pip install は従来どおり動作します。検疫期間を通過した最新バージョンがインストールされます。

# 例: パッケージに 1.0.0（5日前）と 1.1.0（1日前）のバージョンがある場合
$ pip install --index-url https://pypi.flatt.tech/simple/ example-package

# pip は 1.0.0 をインストール（検疫通過済み）
# 1.1.0 はまだ利用できない（公開から72時間未満）

72時間が経過すると、バージョン 1.1.0 は自動的に利用可能になります。追加の操作は不要です。

設定不要​

すでに PyPI 向け Takumi Guard（https://pypi.flatt.tech/simple/）をご利用の場合、検疫は自動的に適用されます。設定の変更は必要ありません。

export PIP_INDEX_URL=https://pypi.flatt.tech/simple/
pip install requests  # 従来どおり動作します

pip、uv、poetry など、PEP 503 互換のすべてのパッケージマネージャで動作します。ツールごとの設定は不要です。

本変更により、すべてのブラックボックス診断で消費クレジット量を事前にコントロールできるようになるため、想定外のクレジット消費を防ぐことができます。

変更内容​

これまでのブラックボックス診断では、診断開始時に「通常の診断」と「リスクフォーカス診断」を選択する必要がありました。今回の変更により、すべてのブラックボックス診断でクレジット上限の指定が必須となるとともに、リスクフォーカス診断が標準の診断方式として統合されました。

クレジット上限の指定​

診断開始時に、その診断ジョブにおけるクレジット上限を設定します。Takumi は指定されたクレジットの範囲内でジョブを実行し、上限に達した時点で当該ジョブが停止します。上限を超過した分のクレジットは請求されません。

• 「全体を診断」モードではクロールとスキャンの両方の上限を診断開始時に指定します
• 「一部だけ診断」モードではクロールの上限を指定した後、診断実行時にスキャンの上限を指定します。

リスクフォーカス診断の特徴​

リスクフォーカス診断は、クレジット上限と優先度の仕組みにより、リスクの高い箇所から効率的に診断を進める方式です。主な特徴は以下の通りです。

• 優先度に基づく段階的な診断: 機能と観点の組み合わせごとに優先度を設定し、リスクの高い箇所から段階的に診断を進められます
• 優先度の自動設定: Takumi がリスク分析に基づいて診断の優先度を自動的に決定します。明示的に指定することも可能です。
• 中間結果の確認と追加スキャン: クレジット上限に達して診断が停止した後、中間レポートを確認しながら追加スキャンの実行や診断の完了を選択できます

既存の診断への影響​

実行中および完了済みの診断には影響ありません。今後新しく作成する診断から本変更が適用されます。

ユーザーガイド​

ブラックボックス診断 を参照してください。

pip、uv、poetry を使用する Python プロジェクトで、Takumi Guard 経由でインストールをルーティングすることで、CI や開発環境に届く前に悪性パッケージをブロックできるようになりました。

概要​

Takumi Guard は、パッケージマネージャーと上流レジストリの間に位置するセキュリティプロキシです。すべてのインストールリクエストをリアルタイムの脅威データベースと照合し、悪性パッケージをブロックします。

今回のリリースにより、npm ユーザーが利用していた保護機能が Python エコシステムでも利用可能になりました。

• パッケージブロック: 悪性 PyPI パッケージをコード実行前にブロック
• ダウンロード追跡: 認証済みユーザーのインストール履歴を記録
• 感染可能性の通知: ダウンロードしたパッケージに後からセキュリティアドバイザリが公開された場合に通知
• バージョン単位のブロック: 侵害されたバージョンのみをブロックし、安全なバージョンは通過

利用開始方法​

pip / uv​

シェルプロファイル（.bashrc、.zshrc など）に以下を追加してください。

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

# uv（PIP_INDEX_URL を参照しないため、専用の変数が必要）
export UV_INDEX_URL=https://pypi.flatt.tech/simple/

または pip.conf（Linux/macOS では ~/.config/pip/pip.conf、Windows では %APPDATA%\pip\pip.ini）に設定してください。

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

一度だけ試す場合は、--index-url を直接指定することもできます。

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

poetry​

Takumi Guard をプライマリソースとして追加します。

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

GitHub Actions​

ワークフローに 1 行追加するだけで導入できます。

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

認証や感染可能性の通知を含む詳細なセットアップ手順は PyPI クイックスタートガイド をご覧ください。

メール登録（感染可能性の通知）​

メールアドレスを登録すると、ダウンロードしたパッケージに後からセキュリティアドバイザリが公開された場合に通知が届きます。アカウント不要、無料で利用できます。

ステップ 1: メールアドレスを登録する

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

ステップ 2: 確認メール内のリンクをクリックしてください。API キーとセットアップ手順が表示されるページに遷移します。

ステップ 3: トークンでパッケージマネージャーを設定する

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

# uv を使用している場合は以下も追加:
export UV_INDEX_URL=https://token:tg_anon_xxxxxx@pypi.flatt.tech/simple/

以降のインストールが追跡され、ダウンロードしたパッケージに問題が見つかった場合に通知が届きます。

対応パッケージマネージャー​