brokre — Agente de credenciales seguro para IA

English | 简体中文

brokre es un agente de credenciales local para agentes de IA y humanos. Úsalo con Cursor, Claude Code, Kimi Code, Trae, OpenClaw, Hermes Agent, ChatClaw y otros clientes compatibles con MCP para ejecutar ssh, mysql, psql y más — las contraseñas nunca entran en el contexto de la IA, en las variables de entorno ni en la salida de ps. Envuelve cualquier CLI en tu PATH — no solo SSH o MySQL — e inyecta las contraseñas guardadas en el prompt sin exponer texto plano al proceso de IA, al historial del shell ni al entorno del proceso.

Desarrollado por Techinone (成都同创合一科技有限公司).

Novedades en 0.2.17

0.2.17 es la versión actual: SessionRelay enrutado por SSH por defecto, rutas bastión de múltiples saltos, lista local por defecto y el flujo existente de instalación npm en un comando / registro MCP automático / actualización automática del binario.

npm — instalar, autoactualizar, configuración MCP automática

npm install -g brokre          # or: npx -y brokre@latest

Configuración MCP recomendada (también aplicada por la configuración automática):

{ "command": "npx", "args": ["-y", "brokre@latest"] }

Agente bastión — gestión de clústeres

La capa bastión permite a los agentes de IA operar muchos hosts detrás de un solo servidor de salto sin copiar contraseñas del vault al contexto ni dispersar secretos en el portátil.

Flujo típico para un clúster K8s / DB / batch detrás de un solo host de entrada:

brokre bastion enable b150
brokre bastion sync b150 --json          # pull inner alias catalog
brokre bastion unlock
brokre list --include-bastions --json    # b150::db, b150::worker-01, …
brokre ssh b150::db systemctl status   # MCP: brokre_exec with routed alias

Equivalente MCP:

{ "binary": "ssh", "args": ["b150::db", "uname", "-a"] }

Política de puerta (predeterminada vs estricta) — ver Política de puerta bastión más abajo. La puerta está inactiva hasta brokre bastion set-key; luego predeterminada desbloquea solo las rutas de salida del bastión; estricta requiere desbloqueo para cada ejecución mientras la lista permanece local a menos que se solicite descubrimiento de bastión.

Ver Herencia de lista entre redes y Proxy bastión más abajo para detalles de configuración.

Related MCP server: SSH Vault MCP

Seguridad CLI (núcleo)

brokre se basa en una regla: los secretos permanecen fuera del alcance de la IA y fuera del estado observable del proceso.

Modelo de amenazas completo: SECURITY.md, THREAT_MODEL.md.

Cualquier CLI en PATH (genérico por diseño)

brokre no es una lista fija de envoltorios de bases de datos/SSH. El modelo central es:

brokre <any-cli-on-PATH> [args...]

Primera conexión: ejecuta tal cual, captura la contraseña que escribes en el prompt, ofrece guardarla como alias.
Siguiente vez: brokre <cli> <alias> … auto-inyecta — la IA y los scripts solo ven el nombre del alias.

Patrones de prompt predefinidos se incluyen para herramientas comunes (ssh, mysql, psql, redis-cli, ftp, clickhouse, git, docker, kubectl, sudo, …). Todo lo demás usa un matcher genérico de password: / passphrase: — sin necesidad de cambios de código.

brokre gsql prod-cluster -c "SELECT 1"    # any proprietary CLI on PATH
brokre kubectl get pods                   # if your cluster CLI prompts for a password
brokre my-internal-tool --host db.internal

Personaliza cuando sea necesario:

• ~/.brokre/prompts.toml — anulaciones de regex de prompt por binario

• ~/.brokre/manage.toml — secciones personalizadas en la UI de gestión (p. ej. GaussDB, herramientas internas)

Las pestañas integradas de la UI de gestión (cuando el binario está instalado) incluyen SSH, FTP, MySQL, PostgreSQL, Redis, ClickHouse, MinIO — solo conveniencia; el envoltorio PTY funciona para cualquier CLI.

Instalar (MCP primero — recomendado para IA)

El paquete npm brokre lanza el servidor local brokre mcp sobre stdio para Cursor, Claude Code, Kimi Code, Trae, OpenClaw, Windsurf, VS Code y otros clientes MCP.

Elige tu ruta de instalación

Entrada MCP recomendada (también lo que escribe la configuración automática):

{ "command": "npx", "args": ["-y", "brokre@latest"] }

Sin Node — apunta MCP al binario nativo: { "command": "brokre", "args": ["mcp"] }.

Ruta A — npm en una línea (0.2.8+)

npm install -g brokre
# or without global install:
npx -y brokre@latest

En npm install, ocurren tres cosas automáticamente:

1. Lanzador MCP — brokre-mcp / npx -y brokre@latest genera brokre mcp.

2. Registro automático en IDEs — postinstall ejecuta brokre-setup-mcp: detecta solo los IDEs instalados (app, CLI o artefactos de uso real — no carpetas vacías) y fusiona la entrada MCP anterior en cada configuración global. Idempotente; conserva tus otros servidores MCP.

3. Actualización automática del binario — en cada inicio de MCP, si PATH o ~/.brokre/bin/brokre es más antiguo que el paquete npm, se descarga el GitHub Release correspondiente.

IDEs cubiertos por la configuración automática

Re-ejecutar registro (p. ej. instalaste brokre antes que Cursor, y luego instalaste Cursor más tarde):

brokre mcp setup              # via CLI — same logic as postinstall
npx brokre-setup-mcp          # via npm
brokre mcp setup --dry-run    # preview only
brokre mcp setup --force      # overwrite existing brokre entry

Omitir registro automático en npm install: BROKRE_MCP_SKIP_SETUP=1. Deshabilitar descarga automática del binario: BROKRE_SKIP_AUTO_INSTALL=1. Fijar un binario: BROKRE_BIN=/path/to/brokre.

Requiere Node.js 18+ para la ruta npm.

Ruta B — CLI nativa (install.sh / Homebrew, sin npm)

curl -fsSL https://raw.githubusercontent.com/Furowu/brokre/main/install.sh | bash

brew tap Furowu/brokre
brew install brokre

Versión y actualización (integrado en la CLI — sin necesidad de npm):

brokre version                # version, binary path, install type
brokre version --check        # compare with latest GitHub release
brokre version --check --json
brokre upgrade                # download latest release (curl + tar)
brokre upgrade --check        # exit 1 if an update is available
brokre upgrade 0.2.10         # install a specific version
brokre upgrade --force        # reinstall even when up to date

Re-ejecutar install.sh también actualiza cuando existe una versión más reciente.

Registrar MCP después de la instalación de CLI (necesita Node para el script de configuración, o respaldo con npx):

brokre mcp setup

Configuración manual por IDE (opcional)

Úsalo solo si omites la configuración automática o necesitas configuración a nivel de proyecto.

Cursor — instalación con un clic, o ~/.cursor/mcp.json:

{
  "mcpServers": {
    "brokre": { "command": "npx", "args": ["-y", "brokre@latest"] }
  }
}

Claude Code — ámbito de usuario en ~/.claude.json o claude mcp add --scope user brokre -- npx -y brokre@latest. Ámbito de proyecto: .mcp.json con "type": "stdio".

Más clientes y variables de entorno: packages/brokre-mcp/README.md. ID en MCP Registry: io.github.Furuwu/brokre.

Herramientas MCP y uso

MCP vs CLI (esencial para agentes de IA)

brokre no es un reemplazo directo para ssh / mysql — debes prefijar con brokre para la inyección de credenciales.

Errores comunes (agentes de IA)

Para SSH remoto: los tokens después del alias son segmentos argv, no un solo comando de shell. Usa tokens separados para comandos simples; usa shell_command para scripts complejos.

Sesiones elevadas MCP (sudo / su, Unix)

Por defecto, brokre mcp reutiliza un shell elevado en segundo plano por (alias, mode, user) para que las contraseñas de sudo no se vuelvan a pedir en cada llamada.

brokre_exec_elevated (preferido para escalada de privilegios):

{
  "alias": "prod",
  "command": "systemctl status nginx",
  "mode": "sudo_login",
  "session": "reuse"
}

Cuando el pool de sesiones está habilitado, las respuestas incluyen session_reused y session_idle_expires_at además de exit_code / stdout / stderr. session_idle_expires_at es una indicación de ventana de inactividad móvil que se actualiza en cada llamada, no una marca de expiración fija. stderr suele estar vacío en la ruta del pool. stdout es solo la salida del comando remoto — el eco TTY, el marco __BROKRE_* y los prompts de shell se eliminan.

brokre_exec: binary=ssh con sudo/su en args usa automáticamente el mismo pool (siempre reuse; sin session=new|close). Ejemplo: args=["prod","sudo","whoami"].

Escritura de scripts/archivos remotos (shell_command, solo binary=ssh): pasa solo el alias en args; pon el script completo en shell_command (brokre normaliza a sh -c). No incrustes sh -c '...' en args ni dividas printf/redirecciones entre tokens argv. Para rutas privilegiadas del sistema usa brokre_exec_elevated.command.

{
  "binary": "ssh",
  "args": ["prod"],
  "shell_command": "cat > /tmp/deploy.sh <<'EOF'\n#!/bin/sh\necho ok\nEOF"
}

Las rutas de bastión funcionan igual: args=["b150::db"] con shell_command como script remoto.

Túnel SessionRelay (por defecto)

brokre ssh b150::db usa la ruta SessionRelay por defecto: el portátil inicia brokre tunnel agent --stdio en b150 a través de SSH, y el agente ejecuta brokre ssh db en el bastión. Las rutas de múltiples saltos eliminan un salto por agente (b1::b2::db comienza en b1, luego b1 continúa con b2::db). Las credenciales internas permanecen en el vault del bastión; el portátil solo retransmite bytes de terminal. BROKRE_TUNNEL=0 es una vía de escape heredada temporal para rollback de emergencia.

brokre tunnel doctor b150
brokre ssh b150::db uname -a

Las respuestas de MCP brokre_exec para SSH enrutado incluyen tunnel: { mode, active }. TcpForward, sincronización de endpoints, controles de túnel en la interfaz de gestión y tunneld persistente son fases posteriores.

No compatible: sudo -i interactivo sin comando, vim/top, o contraseñas de sudo diferentes del campo password del vault. Ver THREAT_MODEL.md T12.

En la primera conexión con un vault vacío, brokre abre manage en tu navegador (http://127.0.0.1:56777/?t=…). Los tokens de sesión permanecen en localhost — nunca se devuelven a la IA. Establece BROKRE_MCP_NO_AUTO_OPEN=1 para desactivar la apertura automática.

| Herramienta MCP | Propósito |

Agregar credenciales

Después de la instalación de CLI, el administrador se abre en la primera ejecución (brokre manage --onboard --open). O en cualquier momento:

brokre manage --open

O guarda en la primera conexión interactiva (cualquier CLI):

brokre ssh root@10.0.0.1
brokre my-tool --host internal.corp

Uso (seguro para IA)

brokre mysql prod-db -e "SHOW TABLES"
brokre ssh prod-bastion uname -a
brokre <your-cli> <alias> [args...]

Listar metadatos (seguro para IA / scripts)

brokre list --json              # local aliases with reachability status (default probe)
brokre list --no-probe --json   # metadata only, skip TCP/SSH probes
brokre list --reachable-only    # hide unavailable aliases
brokre list --all --json        # compat: show all (same as default unless --reachable-only)
brokre list --no-bastion-discovery   # local only — no bastion SSH discovery

Cuando hay bastiones registrados, brokre list permanece solo local por defecto y no hace SSH a bastiones ni activa el desbloqueo de bastión. Usa brokre list --include-bastions (MCP: include_bastions=true) cuando realmente necesites alias enrutados como b150::db; ese descubrimiento remoto puede requerir desbloqueo.

Las sesiones OpenSSH inyectan ConnectTimeout=5 por defecto (BROKRE_SSH_CONNECT_TIMEOUT). Sobrescribe con -o ConnectTimeout=N o la variable de entorno. El RPC de bastión (brokre list --include-bastions / lista remota) expira después de 60s (BROKRE_BASTION_RPC_TIMEOUT). Los comandos remotos usan ControlPath=none para no adjuntarse a un maestro de multiplexación ControlPersist.

Herencia de lista entre redes (broker de bastión)

Para acceso entre redes — viajes, VPN, puntos de entrada públicos — cuando los alias LAN directos no son alcanzables localmente pero sí a través de un bastión que ejecuta brokre.

Requisitos previos

1. Portátil: brokre bastion enable b150 (b150 es un alias SSH guardado)

2. El host del bastión ejecuta brokre en ~/.brokre/bin/brokre (instalación estándar / ruta npx) con alias internos guardados (p. ej. db)

Lista enrutada

brokre bastion unlock            # if bastion key is set
brokre list --include-bastions   # includes b150::db (route=b150, access=via_b150)

Cuando estés entre redes, usa --include-bastions si necesitas alias enrutados. brokre list simple permanece solo local y no desbloquea ni hace SSH a bastiones.

Ejecutar

brokre ssh b150::db uname -a
# MCP: brokre_exec binary=ssh, args=["b150::db", "uname", "-a"]

Cuando ambas rutas funcionan, la lista muestra ambos db (direct) y b150::db (via_b150) — distínguelos por access.

Proxy de bastión (entrada entre redes / intranet)

Promueve cualquier alias SSH guardado cuyo host remoto ejecute brokre a un broker de bastión. Los secretos permanecen en el bastión; el portátil almacena en caché los metadatos y ejecuta mediante paso a través de SSH.

brokre bastion enable b150        # register ssh alias b150 as bastion
brokre bastion set-key              # set bastion unlock key (TTY)
brokre bastion unlock               # unlock outbound session (TTL, 30 min idle default)
brokre list --include-bastions --json # discover bastion-routed aliases
brokre ssh b150::db uname -a        # routed exec via b150 remote brokre
brokre bastion sync b150 --json     # fetch alias list from one bastion

• Separador de ruta :: (: es ilegal en nombres de alias): db (local), b150::db (vía bastión), b1::b2::inner (múltiples saltos, profundidad predeterminada ≤2).

• brokre remoto: la ejecución enrutada invoca ~/.brokre/bin/brokre en el bastión (con BROKRE_SOFT_MEMLOCK=1, BROKRE_ALLOW_FILE_KEYCHAIN=1, BROKRE_ROUTED_INNER=1 para Linux sin cabeza). Los comandos interactivos (p. ej. sudo -i) obtienen automáticamente -tt.

• Protecciones: límite de concurrencia de sondeo, timeouts en ms, caché corta, detección de bucles, auditoría route/bastion (HMAC v4).

• Interfaz de gestión: pestaña Bastion de brokre manage — registrar/deshabilitar bastiones, establecer clave y desbloquear/bloquear desde web, alternar modo estricto, sincronizar alias remotos; sin TTY aún se abre automáticamente /bastion-auth. La pestaña de auditoría filtra por bastion/source y muestra campos de ruta.

Política de puerta de bastión (predeterminada vs estricta)

El gate de bastión es un paso de desbloqueo humano antes de operaciones sensibles. Está desactivado hasta que establezcas una clave de bastión (brokre bastion set-key). Una vez que existe una clave, el desbloqueo establece una sesión TTL local (brokre bastion unlock, frase de contraseña TTY, UI de gestión /bastion-auth o elicitación del navegador MCP).

La política se almacena en ~/.brokre/bastion/policy.json (strict_mode, por defecto false).

Ejemplos (modo predeterminado, clave establecida, sesión bloqueada)

En modo estricto, las filas de ejecución requieren desbloqueo; brokre list solo de metadatos permanece solo local y no se desbloquea a menos que se use --include-bastions.

Establecer modo de gate

brokre bastion strict status    # default | strict
brokre bastion strict on        # strict — all exec gated; list stays local-only unless discovery is requested
brokre bastion strict off       # default — bastion outbound only

La respuesta de lectura MCP incluye strict_mode, gate_mode, key_set, unlocked. Las respuestas de listado/ejecución incluyen bastion_gate (required, unlocked_during_call, idle_expires_at).

TTL de sesión de desbloqueo (valores predeterminados): 30 min de inactividad (BROKRE_BASTION_IDLE_SECS), 8 h de vida máxima (BROKRE_BASTION_MAX_SECS). La ventana de inactividad se renueva en cada llamada con gate mientras está desbloqueada (compartida entre CLI, MCP y UI de gestión a través de ~/.brokre/run/bastion_session.json). La autenticación del gate de bastión es independiente del vencimiento por inactividad de la sesión de la UI de gestión. Desactiva la apertura automática del navegador en el desbloqueo MCP: BROKRE_BASTION_NO_AUTO_OPEN=1.

Revelar / eliminar (solo humano, TTY real)

brokre reveal mysql prod-db --field password
brokre rm ssh prod-bastion

Registro de auditoría (solo metadatos)

brokre audit list --profile ssh --action exec --json
brokre audit verify --json

Los eventos se almacenan en ~/.brokre/audit/audit.log (encadenado con HMAC). Los argumentos de comandos se redactan uniformemente como <REDACTED>. Los nuevos eventos incluyen un campo source (cli, mcp o manage). La pestaña Registro de auditoría de la UI de gestión y brokre_audit_list de MCP exponen los mismos metadatos.

Seguridad de la UI de gestión

• 127.0.0.1 solamente; token de sesión en la terminal

• Contraseñas: crear / rotar solamente — sin API de lectura

• Eliminar / rotar requieren frase de contraseña de revelación (o YES para registros guardados automáticamente)

• Tiempo de espera de inactividad de 15 minutos

Arquitectura

┌─────────┐     ┌──────────┐     ┌─────────────┐     ┌────────────┐
│ AI/User │────▶│ brokre CLI│────▶│ OS Keychain │────▶│ Vault File │
└─────────┘     └──────────┘     └─────────────┘     └────────────┘
                      │
                      ▼
               ┌─────────────┐
               │  PTY + inj. │──▶ any CLI on PATH (ssh, mysql, gsql, …)
               └─────────────┘

• Doble cifrado: DEK único por campo; envuelto para exec y reveal por separado.

• Metadatos de vault: profile, name, host_alias, saved_args en texto claro junto al texto cifrado (THREAT_MODEL.md T3).

• Claves privadas SSH: archivo temporal 0600 + -i para la sesión (docs/HARDENING.md).

Grupos predefinidos de la UI de gestión

Pestañas de conveniencia cuando el binario está en PATH:

Hoja de ruta

Hoy: envoltorio PTY genérico + grupos manage.toml + anulaciones prompts.toml.

Planificado: perfiles de conector TOML completos en ~/.brokre/profiles/ con estrategias de inyección por herramienta.

Entrada estándar canalizada y uso compartido de OpenSSH

• Entrada estándar canalizada (tar | brokre ssh host 'tar xf -'): los datos de la tubería se reenvían solo después de que se complete la inyección.

• Familia OpenSSH (ssh, scp, sftp): credenciales guardadas compartidas cuando el host coincide. Se requiere guardado interactivo primero (TTY).

Desarrollo

cargo test    # unit tests in src/ only (no tests/ integration suite in this repo)
cargo clippy --all-targets --all-features -- -D warnings
cargo build --release   # binary: target/release/brokre

La versión de lanzamiento se declara en VERSION (también reflejada en Cargo.toml y packages/brokre-mcp/package.json). Los binarios oficiales y los paquetes npm son publicados por TechinOne a través de GitHub Releases y CI — no forman parte de este árbol de código abierto.

Licencia

MIT — ver LICENSE.

Techinone · 成都同创合一科技有限公司