メインコンテンツまでスキップ
Markdown で見る

感染可能性の通知

Takumi Guard では、以前にダウンロードしたパッケージに対してセキュリティアドバイザリが公開された際に、感染可能性の通知 を受け取れます。ダウンロード時には安全と判断されていたパッケージが、後に悪意あるものや危殆化されたものと判明したケースに備えるための仕組みです。

通知の受け取り方​

通知の受け取り方は、二種類あります。

メール認証トークンの場合​

メール認証トークンで認証してパッケージをダウンロードしている場合、登録済みのメールアドレスで通知を受け取れます。メールでは、次の情報を確認できます。

  • ダウンロードしたパッケージ名とバージョン
  • ダウンロードした日時
  • フラグが立てられた理由（マルウェアの種類または脆弱性の説明）
  • 推奨される対応（パッケージの削除、環境の監査など）

この通知を有効にするための特別な設定は不要です。メール認証トークンを利用していれば、自動的に通知を受け取れます。

Bot ID・組織ユーザートークンの場合​

Bot ID（GitHub Actions OIDC 経由）や組織ユーザートークンで認証してパッケージをダウンロードしている場合、組織単位で感染可能性の通知を受け取れます。通知の設定は Takumi / Shisho Cloud コンソールから行い、次の 2 種類の通知先を組み合わせて利用できます。

  • Webhook エンドポイント：組織に登録済みの Outgoing Webhook のうち 1 つを選択できます。選択した Webhook で、機械処理に適した JSON ペイロードを受け取れます。
  • メールアドレス：組織のメール許可リストに登録され、確認（Confirm）済みのアドレスのうち 1 つを選択できます。指定したアドレスで、アドバイザリの要点をまとめた HTML メールを受け取れます。

どちらか一方のみ、または両方、いずれの設定も可能です。チームのインシデント対応フローに合わせて選択してください。

info

匿名（認証なし）で Takumi Guard を利用している場合、ダウンロードがいずれの身元にも帰属しないため、感染可能性の通知を受け取れません。通知を受け取るには、メールアドレスの登録または Bot ID を使った GitHub Actions 連携を設定してください。

アドバイザリの詳細閲覧について

通知に記載されるアドバイザリ ID（GHSA-… や FSSA-… など）は、公開状況や調査段階によっては詳細情報を一般公開できない場合があります。受け取った通知の詳細を確認したい場合は、サポート窓口までお問い合わせください。

なお、お問い合わせを多くいただいている関係上、有償でご利用のお客様への対応を優先しており、無料でご利用の場合はご返答できないことがあります。あらかじめご容赦ください。

組織通知の設定方法​

組織単位の通知について
  • 利用するには、Guard を有効化した基本サブスクリプションが必要です。詳しくは料金と請求を参照してください。
  • この設定画面にアクセスするには、Takumi マネージャーまたはオーナーのロールが必要です。

組織単位の通知先は、次の手順で設定してください。

  1. Takumi / Shisho Cloud コンソールで Guard > 設定 に移動し、感染可能性の通知 セクションを開いてください。

    感染可能性の通知の設定画面

  2. Webhook で通知を受け取る場合は、Webhook 通知 のトグルをオンにし、送信先 Webhook から通知先の Outgoing Webhook を選択してください。

  3. メールで通知を受け取る場合は、メール通知 のトグルをオンにし、送信先アドレス から通知先のメールアドレスを選択してください。必要に応じて、事前にメール許可リストへの登録と確認を済ませてください。また、必要に応じて通知メールの本文に使用する言語を選択してください。

  4. 画面下部の 保存 ボタンをクリックしてください。

設定は、保存後すぐに有効になります。通知対象は、設定保存以降に発生したダウンロードのみです。通知先を変更しても、過去のダウンロードについて改めて通知を受け取ることはありません。

Webhook ペイロード​

Webhook エンドポイントを設定すると、Takumi webhook の形式の HTTP POST リクエストとして感染可能性の通知を受け取れます。type は guard.malicious_package_detected です。ペイロードの例は、次のとおりです。

{
  "type": "guard.malicious_package_detected",
  "timestamp": "2026-04-17T12:00:00Z",
  "data": {
    "advisory": {
      "advisory_id": "GHSA-xxxx-xxxx-xxxx",
      "ecosystem": "npm",
      "package_name": "example-pkg",
      "affected_versions": ["1.0.0"],
      "severity": "critical",
      "published_at": "2026-04-17T10:00:00Z"
    },
    "affected_downloads": [
      {
        "timestamp": "2026-04-15T08:30:00Z",
        "version": "1.0.0",
        "principal_type": "ci_cd",
        "principal_name": "my-ci-bot",
        "repository": "example-org/example-repo"
      }
    ],
    "summary": {
      "total_downloads": 12,
      "unique_users": 3,
      "unique_org_tokens": 2,
      "unique_repositories": 2,
      "earliest_download": "2026-04-14T09:00:00Z",
      "latest_download": "2026-04-15T08:30:00Z",
      "truncated": false
    }
  }
}

data 配下の各フィールドは、次のとおりです。

  • advisory：通知のきっかけとなった脅威アドバイザリ
    • advisory_id：アドバイザリの識別子
    • ecosystem：npm または pypi
    • package_name：悪性パッケージ名
    • affected_versions：影響を受けるバージョン一覧。空の場合は、すべてのバージョンが影響を受ける
    • severity：critical、high、medium、low のいずれか
    • published_at：アドバイザリの公開日時
  • affected_downloads：組織に紐づく、悪性パッケージのダウンロード一覧。各要素には、次のフィールドが含まれる
    • timestamp：ダウンロード日時
    • version：ダウンロードされたバージョン
    • principal_type：human、ci_cd、org_token、anonymous のいずれか（Guard ログ UI の「CI/CD」「Org Token」バッジ表記と対応）
    • principal_name：プリンシパルの表示名
    • principal_email：プリンシパルのメールアドレス（human の場合に含まれる）
    • repository：送信元リポジトリ（ci_cd の場合に含まれる）
  • summary：affected_downloads の集計値。各フィールドは次のとおり
    • total_downloads：ペイロードに含まれるダウンロード件数。truncated が true の場合、実際の件数はこれを超える
    • unique_users：ユニークな human プリンシパル数
    • unique_org_tokens：ユニークな org_token プリンシパル数
    • unique_repositories：ユニークな ci_cd リポジトリ数
    • earliest_download、latest_download：検知されたダウンロードのうち最古・最新の日時
    • truncated：ペイロード上限（1000 件）に達した場合に true。実際のダウンロード件数が total_downloads を超えることを示す
info

配信の挙動（リトライ、冪等性、署名検証）については、Webhook 通知を参照してください。

通知のフロー​

新しいアドバイザリが公開されると、通知は次の流れでユーザーに届きます。

  1. Takumi Guard が、影響を受けるパッケージとバージョンのダウンロード履歴を照会する
  2. アドバイザリ公開前にそのパッケージをダウンロードしたすべてのトークン・組織を特定する
  3. 影響を受けるトークンまたは組織ごとに、紐付けられた通知先へ通知を配信する。メール認証トークンの場合は登録メールアドレスに、組織に紐づくダウンロードの場合は組織設定で指定した Webhook・メールアドレスに届く

具体的なフローは、次のとおりです。

info

Takumi Guard が追跡対象とするのは、tarball のダウンロード（.tgz）のみです。パッケージ情報の参照（インストールなし）は追跡対象に含まれません。この仕組みにより、実際のコード実行リスクに基づいた通知を受け取れます。

に最終更新