Secretless

Secretless keeps API keys and other secrets invisible to AI coding tools. It is for developers using Claude Code, Cursor, GitHub Copilot, Windsurf, Cline, or Aider who do not want credentials landing in conversation history, tool calls, or file reads. Run npx secretless-ai init once in a project to migrate hardcoded credentials to a secure backend and block AI tools from reading secret files.

Setup

How it works

Secretless intercepts credential access at the tool level. Instead of credentials appearing in LLM context (conversation history, tool calls, file reads), tools reference environment variables. Secretless manages the lifecycle:

1. Scans project for credential patterns (API keys, tokens, connection strings)
2. Migrates credentials to a secure backend (OS keychain, 1Password, vault)
3. Replaces hardcoded values with $ENV_VAR references
4. Adds file patterns to block lists (prevents AI tools from reading .env files)
5. Injects a CLAUDE.md / .cursorrules section instructing tools to use env vars

Three-tier architecture

Secretless offers three layers of protection. Use one, two, or all three. Each works against any supported storage backend. Pick the tier that matches how a credential is used.

AIM is optional. Tier 1 and Tier 2 work against any of the five storage backends with no AIM involvement. Tier 3 adds identity-bound policy when an AIM server is reachable. Default-deny still enforces locally without one.

Credential pattern library

Scanning draws on 56 credential patterns from the @opena2a/credential-patterns@0.1.1 library, lockstep-asserted, across .js, .ts, .py, .go, .java, .rb, and more.

Fixture-path false positives are suppressed via .secretlessignore defaults (test/, __tests__/, examples/, e2e/, docs/vhs/, node_modules/, and similar). Run npx secretless-ai ignore <path> to append a path, or scan --no-ignore to keep fixture matches visible with a (looks like a test fixture) tag instead of re-suppressing them.

Storage Backends

MCP Context Protection

When AI tools use MCP servers, credentials can leak through:

• Tool call parameters (MCP server configs with inline API keys)
• File reads (.env, config files with embedded credentials)
• Conversation history (credentials pasted into chat)
• Error messages (stack traces revealing connection strings)

Secretless blocks all these vectors by ensuring credentials never enter the LLM context window.

HashiCorp Vault Backend

The Vault backend connects to a HashiCorp Vault instance using the KV v2 secrets engine. Secrets are read and written through the Vault HTTP API with token-based authentication. This backend is suited for teams that self-host their secret infrastructure or need cross-cluster credential synchronization.

npx secretless-ai backend set vault \
  --vault-addr https://vault.example.com \
  --vault-token $VAULT_TOKEN \
  --vault-mount secret \
  --vault-path secretless

GCP Secret Manager Backend

The GCP Secret Manager backend stores secrets in Google Cloud Secret Manager using the REST API with zero SDK dependency. Authentication uses Application Default Credentials (ADC) or a service account key file. This backend integrates natively with Cloud Run, GKE, and Cloud Functions.

# Authenticate with GCP (one-time)
gcloud auth application-default login

# Set as the active backend
npx secretless-ai backend set gcp-sm

Credential Scope Discovery

Credential Scope Discovery detects when the permissions associated with a credential change after it was initially stored. This covers both scope expansion (a token gains new permissions) and scope contraction (permissions are revoked). Detecting scope drift is important because a compromised token that silently gains elevated permissions can be exploited without triggering traditional secret rotation alerts.

Supported Providers

Commands

$ npx secretless-ai scope discover
  GCP_SERVICE_KEY    12 permissions recorded
  VAULT_TOKEN        5 capabilities recorded

$ npx secretless-ai scope check
  GCP_SERVICE_KEY    EXPANDED  +2 permissions (storage.objects.delete, iam.roles.create)
  VAULT_TOKEN        OK        no change

Broker Integration

Scope discovery integrates with the credential broker. Adding scopeCheck: true to a broker policy rule causes the broker to verify the credential scope baseline before granting access. If the scope has expanded since the last baseline, the broker blocks the request and logs a scope drift event.

{
  "rules": [
    {
      "credential": "GCP_SERVICE_KEY",
      "allow": ["my-deploy-script"],
      "scopeCheck": true
    }
  ]
}

Custom Deny Rules

Organizations can define additional deny patterns specific to their environment. These extend the built-in 56 credential patterns with company-specific env vars, config files, and CLI tools.

# Safe to commit -- contains patterns, not secrets
env:
  - ACME_*
  - INTERNAL_*

files:
  - "*.acme-credentials"
  - ".corp-config"

bash:
  - "curl*internal.corp.com*"
  - "corp-vault*get*"

Patterns use glob syntax where * matches any characters. Each pattern generates deny rules that block AI tools from accessing matching env vars, files, or running matching commands.

After editing the rules file, run npx secretless-ai init to apply changes to your AI tool configurations.

Secret Management

Secretless provides encrypted secret storage with multiple backend support. Secrets are stored outside the project directory and injected at runtime.

$ npx secretless-ai secret set OPENAI_API_KEY=sk-...
  Stored: OPENAI_API_KEY

$ npx secretless-ai run -- python app.py
  # app.py can read process.env.OPENAI_API_KEY at runtime

Credential Broker

The credential broker is a local daemon that mediates access to stored secrets. Instead of injecting all secrets into a process environment, the broker grants access per-request based on configurable policies. This enables rate limiting, trust-based access control, and audit logging for credential usage.

Policy constraints include rateLimit (max requests per time window), minTrustScore (AIM integration), requireCapability (named permission check), and scopeCheck (scope drift detection). Default policy is deny-all. Only explicitly allowed credentials are accessible.

The broker authenticates clients using bearer tokens. On startup, the broker generates a cryptographically random token (32 bytes via crypto.randomBytes) and writes it to ~/.secretless-ai/broker.token with mode 0600. Clients must include this token in the Authorization: Bearer header. Token comparison uses crypto.timingSafeEqual to prevent timing side-channel attacks.

Security Architecture

All cryptographic operations use Node.js built-in crypto module with no third-party dependencies.

All symmetric primitives (AES-256, HMAC-SHA256, scrypt) are not affected by quantum computing advances. Asymmetric operations (GCP JWT signing via RS256) are handled by cloud provider infrastructure and outside the scope of this tool.

Transcript Protection

AI tools store conversation transcripts locally. If a credential was accidentally pasted into a conversation, it persists in the transcript file. Secretless can scan and redact credentials from stored transcripts.

NanoMind integration

Optional integration with NanoMind adds two enhanced analysis features. Both gracefully degrade when the NanoMind packages are not installed.

• MCP injection screening. protect-mcp screens env-var values for prompt-injection patterns and warns when suspicious content is detected.
• Rich scan explanations. scan --explain generates context-aware security explanations for each finding using NanoMind's local inference engine.

Supported tools

Each supported AI tool gets a protection method matched to what that tool can enforce. Claude Code gets the strongest protection because it supports hooks: a shell script runs before every file read and blocks access at the tool level.