# 感染可能性の通知 {#breach-notifications}

**感染可能性の通知**は、Takumi Guard を通じて以前にダウンロードしたパッケージに対してセキュリティアドバイザリが公開された際に送信されます。ダウンロード時には安全と判断されていたパッケージが、後に悪意あるものまたは危殆化されたものと判明した場合に発生します。

## 通知の受け取り方 {#notification-methods}

通知の受け取り方は、Takumi Guard の利用方法によって異なります。

### メールで登録した場合 {#breach-email}

メール認証トークンで認証してパッケージをダウンロードしていた場合、登録済みのメールアドレスに通知が送信されます。メールには以下の情報が含まれます。

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

これを有効にするための特別な設定は不要です。感染可能性の通知はメール認証トークンすべてに対して自動的に機能します。

### GitHub Actions + Bot ID を利用している場合 {#breach-webhook}

Shisho Cloud 組織に紐づけた Bot ID で GitHub Actions からパッケージをダウンロードしている場合、組織レベルでの Webhook 通知を今後提供予定です。Webhook の宛先や認証方法は Shisho Cloud コンソールから設定できるようになります。

### その他の場合 {#breach-none}

匿名（認証なし）で Takumi Guard を利用している場合、ダウンロードがいずれの身元にも帰属しないため、感染可能性の通知を受け取ることはできません。通知を受け取るには、[メールアドレスの登録](/docs/ja/t/guard/quickstart/npm.md#setup-email-verified)または [Bot ID を使った GitHub Actions 連携](/docs/ja/t/guard/quickstart/npm.md#setup-ci-org)を設定してください。

## 通知のフロー {#breach-flow}

新しいアドバイザリが公開されると、以下の流れで通知が送信されます。

1. Takumi Guard が影響を受けるパッケージとバージョンのダウンロード履歴を照会する
2. アドバイザリ公開前にそのパッケージをダウンロードしたすべてのトークンを特定する
3. 影響を受けるトークンごとに、紐付けられた通知先（メールアドレスなど）に通知を送信する

```mermaid
sequenceDiagram
    participant User as ユーザー
    participant Guard as Takumi Guard
    participant NPM as 公開 npm レジストリ
    participant DB as ダウンロード履歴

    Note over User,NPM: パッケージのインストール時
    User->>Guard: npm install example-pkg
    Guard->>NPM: プロキシリクエスト
    NPM-->>Guard: パッケージ tarball
    Guard->>DB: ダウンロード記録（トークン・パッケージ・バージョン・日時）
    Guard-->>User: パッケージ tarball

    Note over Guard,DB: アドバイザリ公開時
    Guard->>DB: 影響を受けるダウンロード履歴を照会
    DB-->>Guard: 該当トークン一覧
    Guard->>User: メール通知
```

:::info
追跡されるのは tarball のダウンロード（`.tgz`）のみです。パッケージ情報の参照（インストールなし）は記録されません。これにより、通知が実際のコード実行リスクを反映するようになっています。
:::