secretctl

Gestor de secretos seguro para IA: inyecta credenciales como variables de entorno, la IA nunca ve el texto plano

GitHub
10
Prueba este MCPPatrocinado

Documentación

secretctl

English 日本語

Deja de pegar claves API en el chat de IA.

Cuando pegas sk-proj-xxx en Claude Code, ese secreto ahora está en tu historial de conversación, en los registros de Anthropic y potencialmente expuesto a ataques de inyección de prompts.

secretctl soluciona esto. Tu IA recibe resultados de comandos, nunca valores secretos.

Go Version License Documentation Codecov

secretctl demo

El Problema

Todos los días, los desarrolladores pegan secretos en asistentes de codificación con IA:

You: "Help me debug this AWS error"
You: "Here's my config: AWS_ACCESS_KEY_ID=AKIA..."

Esto es un incidente de seguridad a punto de ocurrir.

  • Secretos en el historial de conversación
  • Secretos en registros en la nube
  • Secretos expuestos a inyección de prompts
  • Sin forma de rotar o revocar

La Solución

secretctl inyecta secretos como variables de entorno. Tu IA ejecuta comandos y ve resultados, pero nunca ve las credenciales reales.

  • Binario único — Sin servidores, sin configuración, sin suscripción
  • Local primero — Los secretos nunca salen de tu máquina
  • Integración MCP — Funciona con Claude Code de inmediato
  • Defensa en profundidad — AES-256-GCM + Argon2id + saneamiento de salida
# That's it. You're done.
secretctl init
secretctl set API_KEY
secretctl get API_KEY

¿Por qué Local-Primero y Seguro para IA?

  1. Tus secretos, tu máquina — Sin sincronización en la nube, sin servidores de terceros, sin tarifas de suscripción. Tus credenciales permanecen en tu dispositivo, punto.

  2. Los agentes de IA no necesitan texto plano — Cuando Claude ejecuta aws s3 ls, necesita el resultado, no tus claves de AWS. secretctl inyecta credenciales directamente en los comandos—la IA nunca las ve.

  3. Defensa en profundidad — Cifrado AES-256-GCM en reposo, derivación de claves Argon2id, controles de política MCP y saneamiento automático de salida. Múltiples capas, no un único punto de fallo.

flowchart LR
    subgraph Flow["How It Works"]
        AI["🤖 AI Agent<br/>(Claude)"]
        MCP["🔐 secretctl<br/>MCP Server"]
        CMD["⚡ Command<br/>(aws, etc)"]

        AI -->|"1. Run aws s3 ls<br/>with aws/*"| MCP
        MCP -->|"2. Inject secrets<br/>as env vars"| CMD
        CMD -->|"3. Execute"| MCP
        MCP -->|"4. Sanitized output<br/>[REDACTED]"| AI
    end

    AI ~~~ NOTE["✓ Gets command results<br/>✗ Never sees secret values"]

Instalación

Desde el Código Fuente

# Requires Go 1.24+
git clone https://github.com/forest6511/secretctl.git
cd secretctl
go build -o secretctl ./cmd/secretctl

Lanzamientos Binarios

Descarga la última versión desde GitHub Releases.

CLI:

  • secretctl-linux-amd64 — Linux (x86_64)
  • secretctl-linux-arm64 — Linux (ARM64)
  • secretctl-darwin-amd64 — macOS (Intel)
  • secretctl-darwin-arm64 — macOS (Apple Silicon)
  • secretctl-windows-amd64.exe — Windows (x86_64)

Aplicación de Escritorio:

  • secretctl-desktop-macos — macOS (Universal)
  • secretctl-desktop-linux — Linux (AppImage)
  • secretctl-desktop-windows.exe — Windows (Instalador)

Verificar Descargas

# Download checksums.txt and verify
sha256sum -c checksums.txt

macOS: Advertencia de Gatekeeper

macOS puede mostrar una advertencia de seguridad para aplicaciones sin firmar. Para permitir:

# Option 1: Remove quarantine attribute
xattr -d com.apple.quarantine secretctl-darwin-arm64

# Option 2: Right-click the app and select "Open"

Windows: Advertencia de SmartScreen

Windows SmartScreen puede mostrar una advertencia. Para permitir:

  1. Haz clic en "Más información"
  2. Haz clic en "Ejecutar de todos modos"

Inicio Rápido

1. Inicializa tu bóveda

secretctl init
# Enter your master password (min 8 characters)

2. Almacena un secreto

echo "sk-your-api-key" | secretctl set OPENAI_API_KEY

3. Recupera un secreto

secretctl get OPENAI_API_KEY

4. Lista todos los secretos

secretctl list

5. Elimina un secreto

secretctl delete OPENAI_API_KEY

Características

Núcleo

  • Cifrado AES-256-GCM — Cifrado autenticado estándar de la industria
  • Derivación de claves Argon2id — Protección resistente a memoria contra fuerza bruta
  • Almacenamiento SQLite — Confiable, portátil, sin dependencias externas
  • Registro de auditoría — Registros encadenados con HMAC para detección de manipulación
  • Seguro para IA por diseño — La integración MCP nunca expone secretos en texto plano a agentes de IA

Soporte de Metadatos

# Add notes and tags to secrets
secretctl set DB_PASSWORD --notes="Production database" --tags="prod,db"

# Add URL reference
secretctl set API_KEY --url="https://console.example.com/api-keys"

# Set expiration
secretctl set TEMP_TOKEN --expires="30d"

# Filter by tag
secretctl list --tag=prod

# Show expiring secrets
secretctl list --expiring=7d

# View full metadata
secretctl get API_KEY --show-metadata

Ejecutar Comandos con Secretos

Inyecta secretos como variables de entorno sin exponerlos en tu historial de shell:

# Run a command with a single secret
secretctl run -k API_KEY -- curl -H "Authorization: Bearer $API_KEY" https://api.example.com

# Use wildcards to inject multiple secrets
# Pattern aws/* matches aws/access_key, aws/secret_key (single level)
secretctl run -k "aws/*" -- aws s3 ls

# Output is automatically sanitized to prevent secret leakage
secretctl run -k DB_PASSWORD -- ./deploy.sh
# If deploy.sh prints DB_PASSWORD, it appears as [REDACTED:DB_PASSWORD]

# With timeout and prefix
secretctl run -k API_KEY --timeout=30s --env-prefix=APP_ -- ./app

Nota: El saneamiento de salida utiliza coincidencia exacta de cadenas. Los secretos codificados (Base64, hexadecimal) o coincidencias parciales no se detectan.

Exportar Secretos

Exporta secretos para usar con Docker, CI/CD u otras herramientas:

# Export as .env file (default)
secretctl export -o .env

# Export specific keys as JSON
secretctl export --format=json -k "db/*" -o config.json

# Export to stdout for piping
secretctl export --format=json | jq '.DB_HOST'

Importar Secretos

Importa secretos desde archivos .env o JSON existentes:

# Import from .env file
secretctl import .env

# Import from JSON file
secretctl import config.json

# Preview what would be imported (dry run)
secretctl import .env --dry-run

# Handle conflicts: skip, overwrite, or error
secretctl import .env --on-conflict=skip
secretctl import .env --on-conflict=overwrite

Generar Contraseñas

Crea contraseñas aleatorias seguras:

# Generate a 24-character password (default)
secretctl generate

# Generate a 32-character password without symbols
secretctl generate -l 32 --no-symbols

# Generate multiple passwords
secretctl generate -n 5

Respaldo y Restauración

Crea respaldos cifrados y restaura tu bóveda:

# Create encrypted backup
secretctl backup -o vault-backup.enc

# Create backup with audit logs
secretctl backup -o full-backup.enc --with-audit

# Verify backup integrity
secretctl restore vault-backup.enc --verify-only

# Restore to a new vault (dry run first)
secretctl restore vault-backup.enc --dry-run

# Restore with conflict handling
secretctl restore vault-backup.enc --on-conflict=skip    # Skip existing keys
secretctl restore vault-backup.enc --on-conflict=overwrite  # Overwrite existing

# Use key file instead of password (for automation)
secretctl backup -o backup.enc --key-file=backup.key
secretctl restore backup.enc --key-file=backup.key

Seguridad: Los respaldos están cifrados con AES-256-GCM usando una sal nueva. La verificación de integridad HMAC-SHA256 detecta cualquier manipulación.

Registro de Auditoría

# View recent audit events
secretctl audit list --limit=50

# Verify log integrity
secretctl audit verify

# Export audit logs
secretctl audit export --format=csv -o audit.csv

# Prune old logs (preview first)
secretctl audit prune --older-than=12m --dry-run

Acceso Seguro para IA

secretctl implementa Acceso Seguro para IA — un principio de seguridad donde los agentes de IA nunca reciben secretos en texto plano.

A diferencia de los administradores de secretos tradicionales que podrían exponer credenciales directamente a la IA, secretctl utiliza un enfoque fundamentalmente diferente:

flowchart LR
    subgraph "Traditional Approach ❌"
        AI1[AI Agent] -->|"get secret"| SM1[Secret Manager]
        SM1 -->|"plaintext: sk-xxx..."| AI1
    end

    subgraph "AI-Safe Access ✅"
        AI2[AI Agent] -->|"run command"| SM2[secretctl]
        SM2 -->|"inject env vars"| CMD[Command]
        CMD -->|"sanitized output"| SM2
        SM2 -->|"[REDACTED]"| AI2
    end

Esto sigue la filosofía de "Acceso Sin Exposición" utilizada por líderes de la industria como 1Password y HashiCorp Vault.

Integración con IA (Servidor MCP)

secretctl incluye un servidor MCP para integración segura con asistentes de codificación con IA como Claude Code:

# Start MCP server (requires SECRETCTL_PASSWORD)
SECRETCTL_PASSWORD=your-password secretctl mcp-server

Herramientas MCP Disponibles:

  • secret_list — Lista claves de secretos con metadatos (sin exponer valores)
  • secret_exists — Verifica si un secreto existe con metadatos
  • secret_get_masked — Obtiene valor enmascarado (ej., ****WXYZ)
  • secret_run — Ejecuta comandos con secretos como variables de entorno
  • secret_list_fields — Lista nombres de campos para secretos de múltiples campos (sin valores)
  • secret_get_field — Obtiene solo valores de campos no sensibles
  • secret_run_with_bindings — Ejecuta con enlaces de entorno predefinidos

Configurar en Claude Code (~/.claude.json):

{
  "mcpServers": {
    "secretctl": {
      "command": "/path/to/secretctl",
      "args": ["mcp-server"],
      "env": {
        "SECRETCTL_PASSWORD": "your-master-password"
      }
    }
  }
}

Configuración de Políticas (~/.secretctl/mcp-policy.yaml):

version: 1
default_action: deny
allowed_commands:
  - aws
  - gcloud
  - kubectl

Seguridad: Los agentes de IA nunca reciben secretos en texto plano. La herramienta secret_run inyecta secretos como variables de entorno, y la salida se sanea automáticamente.

Aplicación de Escritorio

secretctl incluye una aplicación de escritorio nativa construida con Wails v2:

secretctl Desktop App

Aplicación de escritorio mostrando secretos de múltiples campos con plantillas (Base de Datos, Clave API, Inicio de Sesión, Clave SSH)

# Build the desktop app
cd desktop && wails build

# Or run in development mode
cd desktop && wails dev

Características:

  • Aplicación nativa para macOS/Windows/Linux
  • Crear y desbloquear bóvedas con contraseña maestra
  • Operaciones CRUD completas de secretos (Crear, Leer, Actualizar, Eliminar)
  • Buscar y filtrar secretos por clave
  • Copiar valores de secretos al portapapeles (con auto-borrado)
  • Soporte de metadatos (URL, etiquetas, notas)
  • Alternar visibilidad de contraseña
  • Bloqueo automático por tiempo de inactividad
  • Visor de Registro de Auditoría — Ver y analizar toda la actividad de la bóveda
    • Filtrar por acción, fuente, clave y rango de fechas
    • Paginación para grandes volúmenes de registros
    • Verificación de integridad de la cadena
    • Exportar a formatos CSV/JSON
    • Modal de entrada de registro detallado
  • Frontend moderno con React + TypeScript + Tailwind CSS

Desarrollo:

# Run E2E tests (Playwright)
cd desktop/frontend
npm run test:e2e

# Run with visible browser
npm run test:e2e:headed

# Run with Playwright UI
npm run test:e2e:ui

Seguridad

secretctl se toma la seguridad en serio:

  • Diseño de conocimiento cero — Tu contraseña maestra nunca se almacena ni se transmite
  • Cifrado AES-256-GCM — Cifrado autenticado estándar de la industria
  • Derivación de claves Argon2id — Protección resistente a memoria contra fuerza bruta
  • Permisos de archivo seguros — Los archivos de bóveda se crean con permisos 0600
  • Sin acceso a red — Operación completamente fuera de línea
  • Registros a prueba de manipulación — La cadena HMAC detecta cualquier manipulación de registros
  • Saneamiento de salida — Redacción automática de secretos en la salida de comandos

Para reportar vulnerabilidades de seguridad, consulta SECURITY.md.

Documentación

📚 Documentación Completa — Primeros pasos, guías y referencia

Licencia

Licencia Apache 2.0 — Consulta LICENSE para más detalles.

Construido con cuidado para desarrolladores que valoran la simplicidad y la seguridad.