Home / Usage

Use Prompt Guard

Prompt Guard uses local pattern checks to identify common PII and prompt-injection phrases. Pattern checks are best-effort; they can miss unfamiliar formats and should be one layer of your application's security controls.

Command-line usage

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

The CLI accepts a file path or directory and an optional set of flags:

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

Local secret vault

Store secrets locally under an ID. The CLI hides passphrases and values while typing; the first command creates the encrypted vault.

prompt-guard vault set deployment-token
prompt-guard vault list
prompt-guard vault catalog
prompt-guard vault capture prompt.txt
prompt-guard vault export vault-backup.json
prompt-guard vault import vault-backup.json
prompt-guard vault popup
prompt-guard vault delete deployment-token

vault export writes an encrypted backup. vault import verifies it with the vault passphrase and replaces the default vault; back up existing data first. Import paths may be outside the current directory; export paths are restricted to the current directory.

vault popup opens the interactive terminal GUI. Add secrets with a name and tag, delete entries, and inspect a safe metadata preview; it never displays a decrypted value. vault catalog returns only IDs, generic titles, a fixed redacted preview, and safe-use guidance.

Capture and redact locally, then require a human to review and explicitly approve the prompt before any model request. Detection is best-effort; the capture result always sets manualReviewRequired: true, since unknown sensitive values can remain:

const protectedPrompt = await vault.captureAndRedactPrompt(incomingPrompt);
const approvedPrompt = await reviewPromptLocally(protectedPrompt);
const answer = await callAIGuarded(approvedPrompt, { autoSanitize: true });

reviewPromptLocally is an application-provided human review step, not a vault method. Do not pipe prompt-guard vault capture output directly into a model. Secret IDs, names, and tags are encrypted at rest; older vaults migrate automatically when opened.

For harness registration, createVaultCatalogTool(vault) returns a zero-argument tool descriptor whose handler returns only the safe catalog. Adapt it to your harness’s tool schema; never register withSecret as an agent tool.

Use a secret from trusted host code with SecretVault.withSecret:

import { SecretVault } from '@ai-clyde/promptguard';

async function deployTool() {
  const vault = await SecretVault.open({ passphrase: await loadLocalPassphrase() });
  try {
    return await vault.withSecret('deployment-token', (token) =>
      deployApprovedArtifact({ token }),
    );
  } finally {
    vault.close();
  }
}

Never expose a generic “get secret” tool to the model. Bind fixed IDs in host policy, pass values only to allow-listed local operations, and keep them out of prompts, tool results, logs, and telemetry. A model-controlled shell with the same OS account can bypass application-level restrictions; use harness tool allowlists and process isolation. Detection is pattern-based and cannot identify every possible secret.

The vault uses scrypt and AES-256-GCM and stores data in the per-user application data directory. The callback receives a temporary buffer that is zeroed afterward; do not retain or copy it. Use a unique passphrase of at least 12 characters; there is no password recovery or network sync. CLI commands require a terminal and do not accept passphrases through environment variables. Set PROMPT_GUARD_VAULT_PATH to use a custom path.

Claude Code hook

prompt-guard hook reads a Claude Code hook event from stdin. If UserPromptSubmit finds a secret, it blocks the prompt. If PreToolUse finds one, it denies the tool call (or asks first, with --tool-decision=ask). Reasons name only the detection type and severity, never the value. Malformed input exits with code 2 so the hook fails closed.

{
  "hooks": {
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "prompt-guard hook", "timeout": 10 }] }
    ],
    "PreToolUse": [
      { "matcher": "Bash|Write|Edit|WebFetch",
        "hooks": [{ "type": "command", "command": "prompt-guard hook --tool-decision=ask", "timeout": 10 }] }
    ]
  }
}

Flags: --min-severity (default medium), --ignore, --config, --tool-decision=deny|ask. Hooks cannot rewrite prompts; keep secrets in the vault and refer to them by ID.

Scan TypeScript text

import { scanText } from '@ai-clyde/promptguard';

const result = scanText(userPrompt);
if (!result.isSafe) {
  console.log(result.matches);
  // Block the request or review result.sanitizedText.
}

• isSafe is true only when no enabled check matched.
• matches contains each detected category, its matched value, and severity.
• sanitizedText replaces detected PII with redaction markers.

Injection phrases are reported but left unchanged in sanitizedText. Do not treat the sanitized output as safe to send if the prompt was flagged for injection.

Severity levels

Every match is assigned a severity:

Guard an OpenAI request

import { callAIGuarded } from '@ai-clyde/promptguard';

const answer = await callAIGuarded(userPrompt, {
  autoSanitize: true,
});

Set OPENAI_API_KEY in the environment before importing the AI helper. With autoSanitize: true, PII is redacted before the OpenAI call. Detected prompt injection always throws and is never sent, even when auto-sanitization is enabled. Without auto-sanitization, any detected PII or injection blocks the call.

The helper sends prompts that pass the configured checks to OpenAI. The standalone scanText function itself performs no network requests.

Configuration file (.promptguardrc)

Create a .promptguardrc in your project root:

{
  "ignore": ["ipAddress", "phoneNumber"],
  "minSeverity": "high",
  "partialRedaction": true,
  "customPatterns": {
    "internalTicket": {
      "pattern": "\\bTKT-\\d{6}\\b",
      "severity": "low"
    }
  }
}

Use --config=path to point to a custom config file. Options passed to scanText() or CLI flags take precedence over the config file.

See the setup guide to install and link the CLI locally.