Prompt Guard

Project site: Prompt Guard

Detailed guides: Setup · Usage

Prompt Guard is a lightweight TypeScript scanner that flags personally identifiable information (PII) and prompt-injection phrases before a prompt reaches an AI model. The scanText scanner runs entirely in memory — no network calls. The optional callAIGuarded helper runs the scan, then forwards accepted prompts to OpenAI or any OpenAI-compatible endpoint (including a local Ollama model for zero API cost).

Table of contents

• What it detects
• Requirements
• Setup
• CLI usage
• Claude Code hook
• Secure account access for agent harnesses
• Programmatic usage
• Local secret vault
• Guarded OpenAI calls
• Local models
• Environment variables
• Options reference
• CI integration
• Publishing to npm
• Pre-commit hook
• Troubleshooting
• Development
• Data handling
• License

---

What it detects

PII Detection

• Email addresses
• Social media handles (@username on X, Instagram, TikTok)
• 13–19 digit credit-card-shaped numbers
• Social Security Numbers (XXX-XX-XXXX)
• Phone-number-shaped strings
• IPv4-shaped addresses

Secret Detection

• API keys (OpenAI sk-..., sk-proj-..., AWS AKIA...)
• GitHub tokens (ghp_*, github_pat_*)
• AWS secret access keys (40-char base64)
• Stripe keys (sk_live_*, sk_test_*)
• Database connection strings (postgres://user:pass@host, etc.)
• JWT tokens
• SSH private keys (-----BEGIN ... PRIVATE KEY-----)

Prompt Injection

• Phrases such as “ignore previous instructions”, “system prompt”, “you are now unbound”

These are the details you would not want posted publicly — they make content social-safe before sharing.

This is a best-effort pattern-based check, not a substitute for a complete security review or validation of payment-card numbers. A detected injection phrase is reported but is not removed from sanitizedText.

Requirements

• Node.js
• npm

Setup

From a clone of this repository, build and link the CLI globally:

npm install
npm run build
npm link

Alternatively, install the package globally from the repository directory:

npm install -g .

To install the published package from npm, use:

npm install -g @ai-clyde/promptguard

The scoped package has not been published yet. Until it is available, install from this repository with the local steps above.

CLI usage

After linking or installing, scan a text file:

prompt-guard examples/clean.txt
prompt-guard examples/leak.txt

After the package is published to npm, the same command can be run with npx:

npx @ai-clyde/promptguard examples/clean.txt

The CLI prints a sanitized preview when it detects issues and exits with status 1; clean input exits with status 0. To skip a category, pass a comma-separated list of match types:

prompt-guard examples/leak.txt --ignore=email,creditCard

Supported ignore names: email, socialHandle, creditCard, apiKey, githubToken, awsSecretKey, databaseUrl, jwtToken, stripeKey, sshPrivateKey, ipAddress, phoneNumber, ssn, prompt_injection. Ignored categories are neither reported nor redacted.

CLI flags

Flag	Description
--ignore=cat1,cat2	Skip comma-separated categories
--json	Output machine-readable JSON results
--sarif	Output SARIF 2.1.0 log (for code scanning tools)
--partial-redaction	Show last 4 chars instead of full redaction
--config=path	Load configuration from a .promptguardrc file
--tui / -t	Launch the terminal user interface

Terminal UI (TUI)

Launch a full-screen terminal interface with navigation:

prompt-guard --tui
# or
prompt-guard -t

The TUI provides:

• Dashboard — scan statistics with severity breakdown
• Scan File / Scan Directory — scan individual files or recursive directories
• View Results — detailed match listing with type and severity
• Sanitized Text — view PII-redacted output
• Configuration — edit ignore list, set minimum severity, reset defaults
• Export JSON — machine-readable JSON output
• About — version and license info

Navigate with arrow keys, select with Enter, press q to quit.

Local secret vault

The local vault keeps credentials encrypted on disk and lets a trusted application use a secret by ID without making the secret itself a model-facing tool result. Secret IDs may appear in prompts; values must not. The CLI asks for passphrases and secret values without echoing them, and never accepts secret values as command-line arguments:

prompt-guard vault set deployment-token        # interactive: enter passphrase + value
prompt-guard vault list                        # print IDs only
prompt-guard vault delete deployment-token
prompt-guard vault catalog                     # safe agent-visible metadata only
prompt-guard vault capture prompt.txt          # store detections and print redacted prompt
prompt-guard vault export vault-backup.json    # encrypted backup
prompt-guard vault import vault-backup.json    # restore backup
prompt-guard vault popup                       # interactive terminal GUI

This is the beginning of the README. Read the rest at the original. Read the full README ↗