メインコンテンツまでスキップ
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 連携を設定してください。

組織通知の設定方法​

組織単位の通知について
  • 利用するには、Guard を有効化した Takumi サブスクリプションが必要です。詳しくは料金と請求を参照してください。
  • この設定画面にアクセスするには、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）のみです。パッケージ情報の参照（インストールなし）は追跡対象に含まれません。この仕組みにより、実際のコード実行リスクに基づいた通知を受け取れます。

に最終更新