/v1/secrets

Request#

{ "text": "AWS_SECRET_ACCESS_KEY=AKIAZQ3XVGH4KJPBMNRT", "redact": "mask" }

(Not AWS’s own docs placeholder, AKIA...EXAMPLE — gitleaks’ aws-access-token rule allowlists anything ending EXAMPLE by design, so that value never fires here either.)

Checks this gate runs#

Every check here is pure rule-based text scanning — gitleaks’ own regexes, keyword prefilter, entropy thresholds and allowlists, all reimplemented over Go’s own regexp, no network calls, no model inference — so all of them are free on every plan (CLAUDE.md design rule 4: “Never withhold a zero-marginal-cost check”).

Eight finding codes cover roughly 220 individual detection rules plus our own patterns — gitleaks’ own rule id rides along in data.matches[].rule (e.g. "github-pat", "aws-access-token") for a caller who wants to act on the specific pattern without parsing a finding’s message.

Source and licence#

The detection rules are gitleaks’ own default ruleset (MIT licence), fetched at a pinned release (v8.30.1) and embedded like every other StormDoor reference list — not re-derived, not hand-picked. meta.ruleset reflects the pinned version. We reimplement gitleaks’ matching semantics (keyword prefilter, secretGroup extraction, Shannon-entropy thresholds, allowlists) over Go’s own regexp rather than shelling out to the gitleaks binary, so every rule runs unchanged but as one in-process scan.

What this gate does not cover#

• It never tests a credential against the provider it looks like it belongs to. Format-only verification is the whole product here — calling AWS, GitHub, or Stripe with a value we found in someone’s request body would mean using a stranger’s credential to find out if it’s real, which we won’t do. A secret.provider_token finding means “this looks like a live AWS/GitHub/Stripe/etc. key,” not “this key still works.”
• No free-floating entropy scan. Every check requires a recognisable shape (a PEM header, a provider’s own prefix, or a credential-shaped keyword next to a high-entropy value) — a bare high-entropy string with no such context is not flagged. That would flag every hash, UUID, and base64 image alongside real secrets.
• We never echo the matched value. A finding’s message names the pattern that matched (from the rule’s own description), never the secret itself — the same rule /v1/pii follows, and the reason location is an offset, not a quote.

Overlapping matches#

A private-key match always wins over anything inside its PEM block. A named-provider match always wins over a generic-credential match on the same span — gitleaks’ own generic-vs-specific dedup, reimplemented as this gate’s overlap-resolution priority (same mechanism /v1/pii uses for e.g. a payment card partially overlapping a phone number).

Redaction#

redact: "mask" adds data.redacted to the response: your input text with every match replaced by *, one asterisk per character, so offsets still line up. It’s the only redaction mode — see the response format docs for why hashing, tokenising and removal are all cut rather than offered.

Matches, truncation and offsets#

Every match also appears in data.matches as { "code", "rule", "start", "end" }. rule is the specific gitleaks rule id that fired. start/end are Unicode code-point offsets of the secret itself, not the whole matched text — e.g. for AWS_SECRET_ACCESS_KEY=AKIA..., the offsets bound AKIA..., not the AWS_SECRET_ACCESS_KEY= prefix that helped identify it. A scan is capped at 100 matches; past that, data.truncated: true is set and only the first 100 (by position) are returned.

Example#

curl -s -X POST https://api.stormdoor.dev/v1/secrets \
  -H "Authorization: Bearer sk_live_..." \
  -H "content-type: application/json" \
  -d '{"text":"AWS_SECRET_ACCESS_KEY=AKIAZQ3XVGH4KJPBMNRT","redact":"mask"}'

{
  "ok": true,
  "verdict": "block",
  "findings": [
    {
      "code": "secret.provider_token",
      "severity": "high",
      "message": "Identified a pattern that may indicate AWS credentials, risking unauthorized cloud resource access and data breaches on AWS platforms.",
      "location": "23-43"
    }
  ],
  "data": {
    "matches": [
      { "code": "secret.provider_token", "rule": "aws-access-token", "start": 23, "end": 43 }
    ],
    "redacted": "AWS_SECRET_ACCESS_KEY=********************"
  },
  "checks_run": ["secret.generic_credential", "secret.private_key", "secret.provider_token"],
  "checks_skipped": [],
  "meta": { "gate": "secrets", "ruleset": "reference-..." }
}

See response format for how checks_skipped reasons work, and don’t proxy that array — or the raw match offsets — to your own end users.