Skip to main content
View as Markdown

Breach Notifications

info

The English user guide is currently in beta preview. Most of the documents have been automatically translated from the Japanese version. Should you find any inaccuracies, please reach out to Flatt Security.

With Takumi Guard, you can receive a breach notification when a security advisory is published for a package you previously downloaded. This mechanism protects you when a package that was considered safe at download time is later found to be malicious or compromised.

How You Receive Notifications​

There are two ways to receive notifications.

With Email-Verified Tokens​

If you authenticate with an email-verified token when downloading a package, you receive notifications at your registered email address. The email includes:

  • The package name and version you downloaded
  • When you downloaded it
  • Why it was flagged (malware type or vulnerability description)
  • Recommended action (remove the package, audit your environment, etc.)

No action is required on your part to enable this. As long as you use an email-verified token, you automatically receive breach notifications.

With Bot IDs or Org User Tokens​

If you authenticate with a Bot ID (via GitHub Actions OIDC) or an org user token when downloading packages, you can receive organization-level breach notifications. Configure notifications from the Takumi / Shisho Cloud console by combining the following two destination types:

  • Webhook endpoint — choose one of the Outgoing Webhooks registered for the organization. You receive a machine-readable JSON payload at the selected webhook.
  • Email address — choose one confirmed address from the organization's email allowlist. You receive an HTML summary email with the key advisory details at the selected address.

You can enable one or both. Choose whichever matches how your team handles incidents.

info

If you use Takumi Guard anonymously (without authentication), downloads are not attributed to any identity, so you cannot receive breach notifications. To receive notifications, set up email registration or Bot ID integration with GitHub Actions.

Configuring Organization Notifications​

About Organization Notifications
  • This feature requires an active Takumi subscription with Guard enabled. See Pricing & Billing for details.
  • Access to this settings page requires the Takumi Manager or Owner role.

Configure organization-level destinations with the following steps:

  1. In the Takumi / Shisho Cloud console, navigate to Guard > Settings and open the Breach Notifications section.

  2. To receive webhook notifications, turn on the Webhook Notifications toggle and choose the destination from Destination Webhook.

  3. To receive email notifications, turn on the Email Notifications toggle and choose the destination from Destination Address. Add and confirm an address in the Email Allowlist beforehand if needed. Choose the language of the notification email body as needed.

  4. Click the Save button at the bottom of the screen.

Settings take effect immediately after saving. Guard will only send notifications for downloads that occur after the destinations are saved. Historical downloads are not re-notified when destinations change.

Webhook Payload​

When you configure a webhook endpoint, you receive breach notifications as HTTP POST requests in the Takumi webhook format. The type is guard.malicious_package_detected. A sample payload is shown below.

{
  "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
    }
  }
}

Fields inside data:

  • advisory — the threat advisory that triggered this notification.
    • advisory_id — unique identifier for the advisory.
    • ecosystem — npm or pypi.
    • package_name — name of the malicious package.
    • affected_versions — list of affected versions. An empty list means all versions are affected.
    • severity — critical, high, medium, or low.
    • published_at — when the advisory was published.
  • affected_downloads — downloads of the malicious package attributed to the organization. Each entry contains:
    • timestamp — when the download occurred.
    • version — downloaded version.
    • principal_type — one of human, ci_cd, org_token, or anonymous. Aligned with the "CI/CD" and "Org Token" badges in the Guard logs UI.
    • principal_name — display name of the principal.
    • principal_email — email of the principal. Present for human principals.
    • repository — source repository. Present for ci_cd principals.
  • summary — aggregated counts across affected_downloads:
    • total_downloads — number of downloads in this payload. When truncated is true, the actual count exceeds this number.
    • unique_users — number of unique human principals.
    • unique_org_tokens — number of unique org_token principals.
    • unique_repositories — number of unique ci_cd repositories.
    • earliest_download, latest_download — timestamps of the oldest and most recent detected downloads.
    • truncated — true when the per-payload cap (1000 entries) is hit, indicating the actual download count is greater than total_downloads.
info

For delivery semantics (retries, idempotency, signature verification), see Webhook Notifications.

Notification Flow​

When a new advisory is published, notifications reach users through the following flow:

  1. Takumi Guard queries the download history for the affected package and version.
  2. It identifies all tokens and organizations that downloaded the package before the advisory was published.
  3. For each affected token or organization, it delivers a notification to the associated destinations — the registered email address for email-verified tokens, and the webhook and/or email address configured for organization-attributed downloads.

The detailed flow is shown below.

info

Takumi Guard tracks only tarball downloads (.tgz). Metadata requests (checking package info without installing) are not included in tracking. This way, you receive notifications based on actual code execution risk.

Last updated on