Stop pasting API keys into AI chat. When you paste sk-proj-xxx into Claude Code, that secret is now in your conversation history, Anthropic's logs, and potentially exposed to prompt injection attacks. secretctl fixes this. Your AI gets command results, never secret values. Every day, developers paste secrets into AI coding assistants: This is a security incident waiting to happen. - Secrets in con
Add this skill
npx mdskills install forest6511/secretctlWell-documented local secrets manager with MCP integration preventing AI exposure to plaintext credentials
1# secretctl23<p align="center">4 <a href="README.md">5 <img src="https://img.shields.io/badge/πΊπΈ_English-blue" alt="English">6 </a>7 <a href="README-ja.md">8 <img src="https://img.shields.io/badge/π―π΅_ζ₯ζ¬θͺ-green" alt="ζ₯ζ¬θͺ">9 </a>10</p>1112**Stop pasting API keys into AI chat.**1314When you paste `sk-proj-xxx` into Claude Code, that secret is now in your conversation history, Anthropic's logs, and potentially exposed to prompt injection attacks.1516secretctl fixes this. Your AI gets command results, never secret values.1718[](https://go.dev/)19[](LICENSE)20[](https://forest6511.github.io/secretctl/)21[](https://codecov.io/gh/forest6511/secretctl)22232425---2627## The Problem2829Every day, developers paste secrets into AI coding assistants:3031```32You: "Help me debug this AWS error"33You: "Here's my config: AWS_ACCESS_KEY_ID=AKIA..."34```3536**This is a security incident waiting to happen.**3738- Secrets in conversation history39- Secrets in cloud logs40- Secrets exposed to prompt injection41- No way to rotate or revoke4243## The Solution4445secretctl injects secrets as environment variables. Your AI runs commands and sees results, but **never sees the actual credentials**.4647- **Single binary** β No servers, no configuration, no subscription48- **Local-first** β Secrets never leave your machine49- **MCP integration** β Works with Claude Code out of the box50- **Defense in depth** β AES-256-GCM + Argon2id + output sanitization5152```53# That's it. You're done.54secretctl init55secretctl set API_KEY56secretctl get API_KEY57```5859### Why Local-First & AI-Safe?60611. **Your secrets, your machine** β No cloud sync, no third-party servers, no subscription fees. Your credentials stay on your device, period.62632. **AI agents don't need plaintext** β When Claude runs `aws s3 ls`, it needs the *result*, not your AWS keys. secretctl injects credentials directly into commandsβAI never sees them.64653. **Defense in depth** β AES-256-GCM encryption at rest, Argon2id key derivation, MCP policy controls, and automatic output sanitization. Multiple layers, not a single point of failure.6667```mermaid68flowchart LR69 subgraph Flow["How It Works"]70 AI["π€ AI Agent<br/>(Claude)"]71 MCP["π secretctl<br/>MCP Server"]72 CMD["β‘ Command<br/>(aws, etc)"]7374 AI -->|"1. Run aws s3 ls<br/>with aws/*"| MCP75 MCP -->|"2. Inject secrets<br/>as env vars"| CMD76 CMD -->|"3. Execute"| MCP77 MCP -->|"4. Sanitized output<br/>[REDACTED]"| AI78 end7980 AI ~~~ NOTE["β Gets command results<br/>β Never sees secret values"]81```8283## Installation8485### From Source8687```bash88# Requires Go 1.24+89git clone https://github.com/forest6511/secretctl.git90cd secretctl91go build -o secretctl ./cmd/secretctl92```9394### Binary Releases9596Download the latest release from [GitHub Releases](https://github.com/forest6511/secretctl/releases).9798**CLI:**99- `secretctl-linux-amd64` β Linux (x86_64)100- `secretctl-linux-arm64` β Linux (ARM64)101- `secretctl-darwin-amd64` β macOS (Intel)102- `secretctl-darwin-arm64` β macOS (Apple Silicon)103- `secretctl-windows-amd64.exe` β Windows (x86_64)104105**Desktop App:**106- `secretctl-desktop-macos` β macOS (Universal)107- `secretctl-desktop-linux` β Linux (AppImage)108- `secretctl-desktop-windows.exe` β Windows (Installer)109110#### Verify Downloads111112```bash113# Download checksums.txt and verify114sha256sum -c checksums.txt115```116117#### macOS: Gatekeeper Warning118119macOS may show a security warning for unsigned apps. To allow:120121```bash122# Option 1: Remove quarantine attribute123xattr -d com.apple.quarantine secretctl-darwin-arm64124125# Option 2: Right-click the app and select "Open"126```127128#### Windows: SmartScreen Warning129130Windows SmartScreen may show a warning. To allow:1311321. Click "More info"1332. Click "Run anyway"134135## Quick Start136137### 1. Initialize your vault138139```bash140secretctl init141# Enter your master password (min 8 characters)142```143144### 2. Store a secret145146```bash147echo "sk-your-api-key" | secretctl set OPENAI_API_KEY148```149150### 3. Retrieve a secret151152```bash153secretctl get OPENAI_API_KEY154```155156### 4. List all secrets157158```bash159secretctl list160```161162### 5. Delete a secret163164```bash165secretctl delete OPENAI_API_KEY166```167168## Features169170### Core171172- **AES-256-GCM encryption** β Industry-standard authenticated encryption173- **Argon2id key derivation** β Memory-hard protection against brute force174- **SQLite storage** β Reliable, portable, no external dependencies175- **Audit logging** β HMAC-chained logs for tamper detection176- **AI-safe by design** β MCP integration never exposes plaintext secrets to AI agents177178### Metadata Support179180```bash181# Add notes and tags to secrets182secretctl set DB_PASSWORD --notes="Production database" --tags="prod,db"183184# Add URL reference185secretctl set API_KEY --url="https://console.example.com/api-keys"186187# Set expiration188secretctl set TEMP_TOKEN --expires="30d"189190# Filter by tag191secretctl list --tag=prod192193# Show expiring secrets194secretctl list --expiring=7d195196# View full metadata197secretctl get API_KEY --show-metadata198```199200### Run Commands with Secrets201202Inject secrets as environment variables without exposing them in your shell history:203204```bash205# Run a command with a single secret206secretctl run -k API_KEY -- curl -H "Authorization: Bearer $API_KEY" https://api.example.com207208# Use wildcards to inject multiple secrets209# Pattern aws/* matches aws/access_key, aws/secret_key (single level)210secretctl run -k "aws/*" -- aws s3 ls211212# Output is automatically sanitized to prevent secret leakage213secretctl run -k DB_PASSWORD -- ./deploy.sh214# If deploy.sh prints DB_PASSWORD, it appears as [REDACTED:DB_PASSWORD]215216# With timeout and prefix217secretctl run -k API_KEY --timeout=30s --env-prefix=APP_ -- ./app218```219220> **Note**: Output sanitization uses exact string matching. Encoded secrets (Base64, hex) or partial matches are not detected.221222### Export Secrets223224Export secrets for use with Docker, CI/CD, or other tools:225226```bash227# Export as .env file (default)228secretctl export -o .env229230# Export specific keys as JSON231secretctl export --format=json -k "db/*" -o config.json232233# Export to stdout for piping234secretctl export --format=json | jq '.DB_HOST'235```236237### Import Secrets238239Import secrets from existing `.env` or JSON files:240241```bash242# Import from .env file243secretctl import .env244245# Import from JSON file246secretctl import config.json247248# Preview what would be imported (dry run)249secretctl import .env --dry-run250251# Handle conflicts: skip, overwrite, or error252secretctl import .env --on-conflict=skip253secretctl import .env --on-conflict=overwrite254```255256### Generate Passwords257258Create secure random passwords:259260```bash261# Generate a 24-character password (default)262secretctl generate263264# Generate a 32-character password without symbols265secretctl generate -l 32 --no-symbols266267# Generate multiple passwords268secretctl generate -n 5269```270271### Backup and Restore272273Create encrypted backups and restore your vault:274275```bash276# Create encrypted backup277secretctl backup -o vault-backup.enc278279# Create backup with audit logs280secretctl backup -o full-backup.enc --with-audit281282# Verify backup integrity283secretctl restore vault-backup.enc --verify-only284285# Restore to a new vault (dry run first)286secretctl restore vault-backup.enc --dry-run287288# Restore with conflict handling289secretctl restore vault-backup.enc --on-conflict=skip # Skip existing keys290secretctl restore vault-backup.enc --on-conflict=overwrite # Overwrite existing291292# Use key file instead of password (for automation)293secretctl backup -o backup.enc --key-file=backup.key294secretctl restore backup.enc --key-file=backup.key295```296297> **Security**: Backups are encrypted with AES-256-GCM using a fresh salt. The HMAC-SHA256 integrity check detects any tampering.298299### Audit Log300301```bash302# View recent audit events303secretctl audit list --limit=50304305# Verify log integrity306secretctl audit verify307308# Export audit logs309secretctl audit export --format=csv -o audit.csv310311# Prune old logs (preview first)312secretctl audit prune --older-than=12m --dry-run313```314315### AI-Safe Access316317secretctl implements **AI-Safe Access** β a security principle where AI agents never receive plaintext secrets.318319Unlike traditional secret managers that might expose credentials directly to AI, secretctl uses a fundamentally different approach:320321```mermaid322flowchart LR323 subgraph "Traditional Approach β"324 AI1[AI Agent] -->|"get secret"| SM1[Secret Manager]325 SM1 -->|"plaintext: sk-xxx..."| AI1326 end327328 subgraph "AI-Safe Access β "329 AI2[AI Agent] -->|"run command"| SM2[secretctl]330 SM2 -->|"inject env vars"| CMD[Command]331 CMD -->|"sanitized output"| SM2332 SM2 -->|"[REDACTED]"| AI2333 end334```335336This follows the **"Access Without Exposure"** philosophy used by industry leaders like 1Password and HashiCorp Vault.337338### AI Integration (MCP Server)339340secretctl includes an MCP server for secure integration with AI coding assistants like Claude Code:341342```bash343# Start MCP server (requires SECRETCTL_PASSWORD)344SECRETCTL_PASSWORD=your-password secretctl mcp-server345```346347**Available MCP Tools:**348- `secret_list` β List secret keys with metadata (no values exposed)349- `secret_exists` β Check if a secret exists with metadata350- `secret_get_masked` β Get masked value (e.g., `****WXYZ`)351- `secret_run` β Execute commands with secrets as environment variables352- `secret_list_fields` β List field names for multi-field secrets (no values)353- `secret_get_field` β Get non-sensitive field values only354- `secret_run_with_bindings` β Execute with predefined environment bindings355356**Configure in Claude Code** (`~/.claude.json`):357```json358{359 "mcpServers": {360 "secretctl": {361 "command": "/path/to/secretctl",362 "args": ["mcp-server"],363 "env": {364 "SECRETCTL_PASSWORD": "your-master-password"365 }366 }367 }368}369```370371**Policy Configuration** (`~/.secretctl/mcp-policy.yaml`):372```yaml373version: 1374default_action: deny375allowed_commands:376 - aws377 - gcloud378 - kubectl379```380381> **Security**: AI agents never receive plaintext secrets. The `secret_run` tool injects secrets as environment variables, and output is automatically sanitized.382383### Desktop App384385secretctl includes a native desktop application built with Wails v2:386387388389*Desktop app showing multi-field secrets with templates (Database, API Key, Login, SSH Key)*390391```bash392# Build the desktop app393cd desktop && wails build394395# Or run in development mode396cd desktop && wails dev397```398399**Features:**400- Native macOS/Windows/Linux application401- Create and unlock vaults with master password402- Full secret CRUD operations (Create, Read, Update, Delete)403- Search and filter secrets by key404- Copy secret values to clipboard (with auto-clear)405- Metadata support (URL, tags, notes)406- Password visibility toggle407- Auto-lock on idle timeout408- **Audit Log Viewer** β View and analyze all vault activity409 - Filter by action, source, key, and date range410 - Pagination for large log volumes411 - Chain integrity verification412 - Export to CSV/JSON formats413 - Detailed log entry modal414- Modern React + TypeScript + Tailwind CSS frontend415416**Development:**417```bash418# Run E2E tests (Playwright)419cd desktop/frontend420npm run test:e2e421422# Run with visible browser423npm run test:e2e:headed424425# Run with Playwright UI426npm run test:e2e:ui427```428429## Security430431secretctl takes security seriously:432433- **Zero-knowledge design** β Your master password is never stored or transmitted434- **AES-256-GCM encryption** β Industry-standard authenticated encryption435- **Argon2id key derivation** β Memory-hard protection against brute force436- **Secure file permissions** β Vault files are created with 0600 permissions437- **No network access** β Completely offline operation438- **Tamper-evident logs** β HMAC chain detects any log manipulation439- **Output sanitization** β Automatic redaction of secrets in command output440441For reporting security vulnerabilities, please see [SECURITY.md](SECURITY.md).442443## Documentation444445π **[Full Documentation](https://forest6511.github.io/secretctl/)** β Getting started, guides, and reference446447- [Getting Started](https://forest6511.github.io/secretctl/docs/getting-started/) - Installation and quick start448- [CLI Guide](https://forest6511.github.io/secretctl/docs/guides/cli/) - Command-line usage449- [MCP Integration](https://forest6511.github.io/secretctl/docs/guides/mcp/) - AI agent integration450- [Desktop App](https://forest6511.github.io/secretctl/docs/guides/desktop/) - Native application guide451- [Contributing Guide](CONTRIBUTING.md)452- [Security Policy](SECURITY.md)453454## License455456Apache License 2.0 β See [LICENSE](LICENSE) for details.457458---459460Built with care for developers who value simplicity and security.461
Full transparency β inspect the skill content before installing.