Credential Scanning & Redaction
Relevant source files
The following files were used as context for generating this wiki page:
Credential Scanning & Redaction within the Token Optimizer project is a security-focused sub-system designed to protect sensitive information from being ingested into the Large Language Model (LLM) context. This process serves a dual purpose: it prevents the leakage of secrets (such as API keys and environment variables) and optimizes token usage by ensuring the AI never reads unnecessary, high-risk data.
The system operates through a combination of static file exclusion rules, active auditing by specialized sub-agents, and security-aware environment configurations. By implementing these measures, the project ensures that security-critical files are excluded from file discovery, search, and read operations, thereby protecting the user's credentials across all sessions.
Sources: skills/token-optimizer/references/implementation-playbook.md:65-71, skills/token-optimizer/references/agent-prompts.md:10-15
Security-Critical File Exclusion
The primary mechanism for preventing credential exposure is the enforcement of permissions.deny rules. These rules are configured in the settings.json file at either the global (~/.claude/settings.json) or project-level (.claude/settings.json).
Exclusion Mechanisms
Files matching these deny patterns are completely excluded from the AI's visibility. This means the AI cannot discover, search, or read these files, which inherently protects secrets and costs zero tokens per turn as the rules are enforced locally.
The diagram shows how the local permission engine intercepts AI requests before they can access sensitive files.
Sources: skills/token-optimizer/references/implementation-playbook.md:73-86
Target Security Patterns
The system specifically targets files known to contain sensitive credentials.
| Category | Patterns / Files | Reason |
|---|---|---|
| Environment | .env, .env.* | Contains API keys, database URLs, and secrets. |
| Credentials | secrets/**, *.key, *.pem | Cryptographic keys and private certificates. |
| Databases | *.db, *.sqlite | May contain session data or user credentials. |
| Sources: skills/token-optimizer/references/implementation-playbook.md:77-106 |
Audit and Analysis Logic
The system utilizes a specialized "Settings & Advanced Auditor" sub-agent to verify the status of credential protection. This agent scans for the presence of security rules and identifies vulnerabilities.
Auditor Responsibilities
- Deny Rule Verification: Checks for both global and project-level
permissions.denyconfigurations. - High-Priority Flagging: If no security deny rules are found for
.envorsecrets/, the auditor flags this as a "HIGH PRIORITY" security opportunity. - Environment Scrubbing: Audits the
CLAUDE_CODE_SUBPROCESS_ENV_SCRUBsetting (v2.1.83+), which strips Anthropic or cloud credentials from subprocesses. - Credential Leakage Detection: Scans for "Stop hooks" or heavyweight hooks that might inadvertently log or transmit sensitive data.
Sources: skills/token-optimizer/references/agent-prompts.md:155-165, skills/token-optimizer/references/agent-prompts.md:205-215
Data Flow for Security Synthesis
Audit findings are synthesized by a higher-tier agent to provide actionable security recommendations.
This flow illustrates how security-related settings are audited and then synthesized into a prioritized plan.
Sources: skills/token-optimizer/SKILL.md:144-155, skills/token-optimizer/references/agent-prompts.md:270-285
Implementation Constraints & Warnings
While redaction and exclusion are critical for security, they introduce specific operational side effects that the project manages through explicit user warnings.
Potential Side Effects
- Skill Failure: If a skill or MCP server legitimately needs to read API keys from a
.envfile at runtime, applying a deny rule will cause the skill to fail silently or return a permission error. - Token Accumulation: If a broad deny rule is applied to a path the AI frequently tries to explore, the repeated "permission denied" tool feedback accumulates in the conversation history, actually increasing token costs per turn.
- Database Access: Denying access to
*.sqlitefiles will break tools that rely on local search indexes or session memory tools.
Sources: skills/token-optimizer/references/implementation-playbook.md:90-110
Security-Aware Best Practices
The following table summarizes recommended configurations for credential protection.
| Configuration | Recommended Value | Source File |
|---|---|---|
permissions.deny | Narrow paths (e.g., ./.env) | implementation-playbook.md |
CLAUDE_CODE_SUBPROCESS_ENV_SCRUB | 1 | agent-prompts.md |
bypassPermissions | Audit for true (Security risk) | agent-prompts.md |
sandbox settings | Review failIfUnavailable | agent-prompts.md |
| Sources: skills/token-optimizer/references/implementation-playbook.md:83, skills/token-optimizer/references/agent-prompts.md:215-225 |
Summary of Behavioral Impacts
The system emphasizes that security rules must be applied with judgment. "Narrow, specific paths" are preferred over broad globs to prevent the AI from repeatedly hitting "permission denied" walls, which costs tokens in the form of accumulated error feedback. The ultimate goal is to reach a state where sensitive files are invisible to the AI, ensuring both context efficiency and credential safety.
Sources: skills/token-optimizer/references/implementation-playbook.md:112-115, skills/token-coach/references/coach-patterns.md:115-125