supaguard

A Claude Code plugin that detects API keys and credentials on your machine and stops them before they reach the AI. This is the free OSS edition of supaguard, an AI usage governance service by supa.

Install

Run these two lines in Claude Code:

/plugin marketplace add supa-hq/supaguard
/plugin install supaguard@supaguard

Checks take effect in new sessions after installation.

What it does

1. Prompt scanning. Scans your prompt locally before it is sent. High-confidence patterns such as AWS keys and GitHub tokens block the submission; JWTs and random-looking strings only produce a warning.
2. Credential-file read protection. Blocks attempts to read .env, SSH private keys, ~/.aws/credentials and similar files via Read / Grep / Bash. What is never read never enters the context, and never leaves the machine.
3. Local logging. Detection events are appended to ~/.supaguard/events.jsonl. /supaguard:status shows a summary for today and the last 7 days.

What it detects

Content detection ships with 211 default rules from gitleaks (MIT), converted from a pinned tag (v8.30.1). The evaluation pipeline matches gitleaks: keyword prefilter, then regex, then an entropy threshold on the secret group, then allowlists (example keys and placeholders pass through). On top of that, a warning-only entropy detector flags random-looking strings of 32 characters or more.

Of the detections, only 21 high-confidence rules block submission (AWS / GitHub / GitLab / Anthropic / OpenAI / Stripe / Slack / GCP / npm / private-key PEM blocks); the remaining ~190 rules warn only. Adjust the block list via blockRules in rules/supaguard.json.

Files protected from reads:

• .env (templates such as .env.example are excluded)
• SSH private keys (id_rsa / id_ed25519, etc.)
• ~/.aws/credentials, .netrc, .git-credentials, .npmrc, .pgpass, kubeconfig, Docker config
• .pem / .p12 / .pfx / .key

Rules live in rules/gitleaks.json (generated — regenerate with npm run convert:gitleaks, do not edit by hand) and rules/supaguard.json (protected paths and the block-promotion list).

Privacy

Everything runs locally on your machine. This plugin sends nothing anywhere. No telemetry. The log never contains the detected values themselves — rule IDs and counts only. If in doubt, read the source: the entire check is a single script (scripts/guard.mjs).

Configuration

Create ~/.supaguard/config.json to change the behavior:

{
  "mode": "enforce",
  "disabledRules": ["jwt"]
}

• mode: enforce (default, blocks) / warn (warnings only) / off
• disabledRules: rule IDs listed here are disabled

To pass a false positive right away, add [allow-secret] to your prompt — that single prompt bypasses the block (the detection is still logged).

Defense in depth with permissions.deny

We recommend combining supaguard with Claude Code's built-in permissions.deny. Deny rules stop Read-tool access at the settings level, which is stronger than a hook (a hook that crashes fails open; supaguard fails closed only for file-read checks, and still cannot match deny's robustness). Deny rules, however, cannot inspect Bash commands like cat .env or the prompt text itself — that is what supaguard covers.

Example ~/.claude/settings.json:

{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(~/.aws/credentials)",
      "Read(~/.ssh/**)",
      "Read(**/*.pem)"
    ]
  }
}

Requirements and limitations

• Requires a recent Claude Code and Node.js 18+ (hooks invoke node)
• Detection is a first-stage regex + entropy engine. Secrets that match no pattern pass through
• Path checks are a deterrent, not a complete barrier. Copying a file before reading it, or referencing it through wildcards, can bypass them. Use the permissions.deny combination above and review the log
• Claude Code hooks fail open by default (if the hook itself crashes, the operation passes). supaguard fails closed only for file-read checks (tool-check); prompt checks stay fail-open so a bug in the scanner never blocks your work

The semantic detection model and organization-wide policy distribution / audit logging are part of the paid service: https://supa.co.jp/guard/

Tests

npm test

License

Apache-2.0. The bundled detection rules derive from gitleaks (MIT, Copyright (c) 2019 Zachary Rice). See THIRD_PARTY_LICENSES.