Warning
Project Status: 🧪 In development — not tested This status must not be changed by AI unless explicitly instructed by the repository owner.
SecretProtectorAi is a local-first guard for AI coding harness tool calls and results. It scans supported tool inputs and outputs for common API keys, tokens, credentials, private keys, and secret-like values, then allows, asks for confirmation, or cancels according to policy.
It is built for humans and AI agents: the core is deterministic and host-neutral, the CLI is scriptable, and each harness integration declares exactly which interception paths it can protect.
harness tool call/result -> adapter -> bounded scan -> confirm/cancel -> model-visible result
The default mode is cancel. confirm holds a suspicious call/result and asks for one explicit approval; a missing, timed-out, or headless approval is denied. Safe warning messages contain categories and locations only. Raw matches are not included in findings, diagnostics, audit records, or model-facing block messages.
The scanner combines reviewed provider recognizers, credential-context heuristics, entropy checks, bounded encoding checks, stream overlap, and resource limits. Regex is one detection layer, not a guarantee.
npm install secret-protector-ai
npx secret-protector doctorFor a local checkout:
npm ci
npm run verifyInitialize local policy with npx secret-protector init, or set SECRET_PROTECTOR_MODE=confirm for a process.
| Harness | Native input blocking | Native result inspection/replacement | Human prompt | Status |
|---|---|---|---|---|
| Command Code | Yes | Yes, through beforeToolCall/afterToolCall |
Yes | Protected by documented cmdc 1.11.0 mod hooks |
| Pi | Yes | Yes, through tool_call/tool_result |
Yes | Protected by documented extension hooks |
| OpenCode | Yes | Version-sensitive tool.execute.after |
No built-in adapter prompt | Verify the installed version before relying on result replacement |
| Antigravity | Yes, through PreToolUse |
No documented completed-result payload | Host ask/force_ask |
Pre-tool protection; post-output suppression is not claimed |
| JSONL | Yes | Inspect-only; host must enforce returned decision | No | Language-neutral adapter contract |
Install examples and templates are in docs/integrations.md. Run secret-protector doctor after installation and treat any unsupported capability as a real limitation.
secret-protector scan ./tool-output.json
cat tool-output.json | secret-protector scan
secret-protector policy
secret-protector doctor
secret-protector verifyscan prints safe inspection metadata and exits 1 when policy would not allow the event. It never prints the matched value. verify uses a synthetic sentinel and asserts that the safe message does not contain it.
The JSONL protocol accepts one canonical event per line and returns one safe decision per line. It is useful for wrappers and adapters written in any language:
cat event.jsonl | secret-protector guardA process wrapper cannot see in-process events, non-terminal channels, already-streamed content, or host-managed transcripts. It is not equivalent to native result interception.
- No detector finds every secret or understands every encoding.
- Output already delivered to a model cannot be recalled.
- A host that bypasses or misconfigures its adapter is outside the security boundary.
- Antigravity's documented post-tool hook does not provide the completed result, so this project does not claim post-output suppression there.
- OpenCode result mutation must be verified against the exact installed version.
- MCP is not treated as the universal security boundary; a host can bypass an MCP server if a raw tool remains available.
Use this to reduce accidental disclosure, not as a guarantee of secret discovery or prevention.
Processing is local by default. Audit is disabled by default. Findings contain detector IDs, severity, confidence, structural paths, lengths, and keyed fingerprints; they do not contain raw values. The threat model and bounded-processing rules are in docs/threat-model.md and docs/privacy.md.
npm ci
npm run verify
npm run pack:checkUse synthetic-only fixtures. If a host adapter's interception guarantee changes, update docs/integration-matrix.md and its representative tests together.
When testing an adapter, report the harness version, the exact hook/event, whether the synthetic value was model-visible, false positives, and the approval experience. Use the adapter feedback issue template rather than posting real credentials.
MIT