@sanity-labs/backstage-plugin-secret-scanning-backend

Serves GitHub secret-scanning alerts to Backstage, sliced per repository.

How it works

One org-wide sweep of GET /orgs/{org}/secret-scanning/alerts?per_page=100&state=open is paginated, filtered, projected and held in memory for a TTL. Card renders are served as slices of that sweep, so a catalog page full of cards costs zero extra GitHub calls. Concurrent misses share a single in-flight sweep rather than each starting their own.

The credential never leaves GitHub

The GitHub response carries the raw credential in secret, plus first_location_detected, locations_url and several *_comment fields. Those are dropped in service/alerts.ts (projectAlert) the moment a page is read: the projection builds a fresh object from an allow-list of fields, never a spread of the raw alert. Nothing sensitive is returned, logged, cached or written to disk — the UI links to html_url and the credential stays in GitHub.

RawSecretScanningAlert in service/types.ts deliberately declares only the readable fields, so a sensitive field is not reachable through the type.

Filtering

Applied before the sweep is cached:

• forks are dropped (repository.fork === true) — we do not own that history
• archived repositories are dropped (repository.archived === true)
• denylisted repositories are dropped — push-protection by default, which is our own custom-pattern test suite and is deliberately full of fixtures

Note that repository.visibility and repository.archived are null on this endpoint, so the archived filter only fires if GitHub starts populating the field. Nothing here infers repository visibility: publicly_leaked means the same secret was also found by GitHub's scans of public GitHub content, which is not a statement about where this alert lives.

Configuration

secretScanning:
  # Required — GitHub organization to sweep (or GITHUB_ORG)
  org: sanity-io
  # Required — token with the security_events scope (or GITHUB_TOKEN)
  token: ${GITHUB_TOKEN}
  # Optional — sweep cache TTL in minutes (default: 30, 0 disables caching)
  cacheTime: 30
  # Optional — repositories excluded from the sweep (default: [push-protection])
  denyRepos:
    - push-protection
  # Optional — GitHub API base URL (default: https://api.github.com)
  # apiBaseUrl: https://api.github.com

Installation

// packages/backend/src/index.ts
backend.add(
  import('@sanity-labs/backstage-plugin-secret-scanning-backend'),
);

Endpoints

GET /api/secret-scanning/alerts?repo=<owner>/<name>

{
  "repo": "sanity-io/kong",
  "fetchedAt": "2026-08-11T10:00:00Z",
  "counts": {
    "active": 0,
    "unknown": 4,
    "inactive": 0,
    "publicLeak": 0,
    "multiRepo": 0,
    "total": 4
  },
  "alerts": [
    {
      "number": 12,
      "secretType": "Azure Cache for Redis access key",
      "state": "open",
      "validity": "unknown",
      "publiclyLeaked": false,
      "multiRepo": false,
      "createdAt": "2026-07-01T00:00:00Z",
      "htmlUrl": "https://github.com/sanity-io/kong/security/secret-scanning/12"
    }
  ]
}

Counts mirror GitHub's own alert list: validity partitions the alerts, and GitHub's two alert labels are tallied alongside.

| Count | Condition | | ------------ | ----------------------------------------------- | | active | validity === active | | unknown | validity === unknown, or validity is absent | | inactive | validity === inactive | | publicLeak | publiclyLeaked — GitHub's public leak label | | multiRepo | multiRepo — GitHub's multi-repo label |

active + unknown + inactive === total. publicLeak and multiRepo are labels, not buckets: they overlap the validity counts and do not sum to total.

Absence of a label is not a negative finding. GitHub only runs public-leak detection on provider-based patterns, so a missing public leak often means "not evaluated" rather than "not leaked". Likewise unknown validity means GitHub does not support validation for that token type, or could not reach the provider — partner-pattern validity checks are off by default, and only GitHub's own tokens are validated until they are enabled.

A repository with no open alerts gets a zeroed report, not a 404 — that is the common case.

Scoring

Scorecard checks score on active only — a secret GitHub verified with the provider and found live. unknown and inactive do not count against a service: inactive is already revoked, and unknown is an absence of evidence, not evidence of exposure.

That makes the check only as good as GitHub's validity coverage. Partner-pattern validity checks are off by default, so until they are enabled almost everything lands in unknown and a service can score clean while the card shows several potentially active secrets. Enabling those checks is a precondition for the score meaning anything, not a later refinement.

publicLeak is the natural second signal once that holds, since it is the escalator GitHub itself flags — but it is a label, not a state, so a check on it has to read the label count rather than a bucket.

GET /api/secret-scanning/health

Status, cache statistics and the non-secret configuration.