Veil

Un agente de IA puede orquestar la colocación de una credencial sin recibir nunca el valor de la credencial, al mismo tiempo que una interfaz confiable controlada por humanos autoriza de forma independiente hacia dónde puede ir esa credencial.

Esa frase es la promesa completa. Veil es un servidor MCP más un intermediario de entrada seguro: el agente dice "poner una clave de producción de Stripe en Google Secret Manager", el humano ve exactamente qué proyecto y secreto se escribirán y escribe el valor en la ventana propia de Veil, y el valor va directamente al destino. El modelo nunca lo tiene.

Implementado a partir de SPEC.md.

Lo que Veil resuelve

Elimina toda una clase de fallos causados por el agente conociendo el secreto. Con Veil en el bucle, una credencial no pasa a través de:

• Prompts de LLM o historial de conversación

• Argumentos de herramientas MCP o resultados de herramientas

• Memoria del agente o código generado

• Argumentos de comandos de shell o argv de proceso

• Registros, trazas de depuración o telemetría

• URLs

• Salida de comandos visible por el modelo

Lo que Veil no resuelve

Veil no hace que un agente de IA sea confiable, y no es "IA segura". No garantiza que el agente haya elegido el destino correcto, que te haya entendido, que esté libre de inyección de prompts, que el destino en sí mismo sea seguro, que tu máquina no esté comprometida, o que una credencial no pueda ser mal utilizada posteriormente por software que la reciba legítimamente.

Hay dos problemas separados aquí:

Veil responde esas dos. No afirma responder el resto.

Modelo de confianza

Trusted with the credential value:

  The human at the keyboard
  Veil's secure input UI          (loopback only, in your control)
  Veil's secure input broker      (this process)
  The selected destination adapter
  The destination provider        (e.g. Google Secret Manager)

NOT trusted with the credential value:

  The LLM
  The agent / MCP client
  The conversation
  The prompt and any repository content it read
  Generated code
  Logs, telemetry, crash reports

Este diagrama no afirma que los componentes confiables sean invulnerables. Dice dónde se permite que exista la credencial. Veil es software sensible a la seguridad: si el propio Veil es malicioso o está comprometido, el límite desaparece. Su código fuente, dependencias y lanzamientos merecen el escrutinio que darías a cualquier herramienta de manejo de credenciales.

Los dos flujos

El flujo secreto — la ruta del humano, que el modelo no puede observar:

Human ─▶ Veil secure UI (127.0.0.1) ─▶ Broker ─▶ Adapter ─▶ Destination

El flujo del agente — todo lo que el modelo ve:

LLM ─▶ MCP client ─▶ Veil MCP server ─▶ non-sensitive result metadata

El esquema de la herramienta MCP no tiene ninguna propiedad capaz de transportar una credencial. Eso es estructural, no una instrucción de prompt: no hay ningún campo value, secret_value, password, token, content o raw_secret que abusar, los esquemas cerrados rechazan propiedades desconocidas, y los argumentos se filtran buscando valores con forma de credencial antes de ser parseados.

Lo que el agente llama

{
  "destination": "gcp-secret-manager",
  "name": "STRIPE_SECRET_KEY",
  "target": { "project": "my-production-project", "secret": "STRIPE_SECRET_KEY" },
  "write_mode": "new-version",
  "environment": "production",
  "description": "Stripe production API key"
}

Veil responde con un request_id, una clasificación de riesgo y el destino normalizado — y abre su propia ventana de autorización en tu máquina. El agente consulta secret.status.

El agente no recibe el enlace de autorización. Ese enlace es una capacidad: cualquier cosa que lo tenga puede completar la mitad humana del flujo, y un agente con un shell o una herramienta HTTP es precisamente el modelo de amenaza. Veil lo entrega a tu navegador y lo imprime en su propia consola. Establece VEIL_DISCLOSE_AUTHORIZATION_URL=true si tu configuración necesita que el agente retransmita el enlace (por ejemplo, una sesión remota o sin cabeza) — y entiende que esto permite que un agente comprometido autorice su propia solicitud.

Lo que el humano ve

La Etapa A muestra el nombre de la credencial, proveedor de destino, proyecto/cuenta, recurso, operación y riesgo antes de que se ingrese el valor. Las operaciones de alto riesgo (sobrescritura en producción, almacenamiento en texto plano, bases de datos de aplicaciones, reemplazo de una credencial) requieren una segunda confirmación en la Etapa B, después del ingreso y antes de la escritura. El valor nunca se muestra de vuelta.

La página que el humano lee y la operación que el ejecutor realiza son el mismo objeto inmutable — no hay un "destino de visualización" separado. Cualquier cambio en el destino, proyecto, nombre del secreto, operación, modo de escritura o adaptador invalida la autorización y requiere una nueva.

Adaptadores compatibles

Los destinos arbitrary-network (HTTP POST genérico, webhooks) no están implementados, y el registro de adaptadores se niega a registrar uno.

Supuestos y limitaciones de seguridad

Dicho claramente, porque una herramienta de seguridad que se sobrevende es peor que ninguna:

• El proceso intermediario ve el secreto. Ese es el punto: algo debe hacerlo, o el almacenamiento es imposible. La garantía es que solo los componentes de transporte y destino mínimos y confiables lo hacen.

• CPython no puede borrar la memoria de manera confiable. SecretBuffer limpia el búfer mutable que posee, pero la decodificación de porcentaje, las conversiones de str/bytes y los SDK de proveedores crean copias inmutables que el intérprete puede conservar hasta el GC. Veil minimiza y no fabrica esta garantía.

• La interfaz de usuario es HTTP de loopback. Cualquier proceso que se ejecute como tu usuario en tu máquina puede alcanzarla, y cualquier proceso de ese tipo también podría imitarla. Cada proceso de Veil imprime una frase de identidad aleatoria que sus páginas muestran (ayuda antisuplantación, no un control criptográfico). Ocultar el enlace al agente eleva la barrera; no detiene a un proceso que pueda leer la salida de la consola de Veil, listar el argv del navegador o escanear puertos de loopback.

• Veil no audita el destino. Si autorizas una credencial en un documento de Firestore, Veil la escribe allí y te dice que es una mala idea; no te detiene.

• La verificación previa es de mejor esfuerzo. Un proveedor que no es accesible en la verificación previa se reporta como no disponible, no se adivina.

• Semántica de fallos. Un fallo entre la escritura del proveedor y la respuesta puede dejar una credencial escrita sin registro local de éxito. Veil reporta la solicitud como fallida; el destino es la fuente de verdad.

Desarrollo local

uv venv
uv pip install -e ".[dev]"

# run the server the way an MCP client would
uv run veil serve

# with optional providers
uv pip install -e ".[dev,gcp,firestore]"

La configuración se lee del propio entorno de Veil — nunca de argumentos de herramientas:

Configuración del cliente MCP

{
  "mcpServers": {
    "veil": { "command": "uv", "args": ["run", "veil", "serve"] }
  }
}

Pruebas

uv run pytest                  # everything
uv run pytest tests/security   # the adversarial suite only
uv run ruff check .
uv run mypy

El conjunto de pruebas de seguridad es un requisito del producto, no un lujo. Contiene detección de fugas de canario en cada canal observable, pruebas de agente malicioso, fixtures de inyección de prompts, pruebas TOCTOU y de repetición, estrés de concurrencia de 100 vías, condiciones de carrera, rutas de fallo, simulación de fallo de proveedor, comprobaciones de interfaz de usuario y fuzzing. Un lanzamiento se bloquea si algún canario filtra, si alguna elusión de autorización tiene éxito, si alguna mutación posterior a la aprobación tiene éxito, si alguna solicitud completada es repetible, si algún secreto cruza un límite de solicitud, si algún error de proveedor sin procesar llega a MCP, o si alguna operación de alto riesgo omite la confirmación.

Consulta docs/SECURITY_MODEL.md para el mapa de invariantes a pruebas.

Estado del proyecto

Versión 0.1.0, construida según SPEC.md, que permanece en el repositorio como la descripción autorizada del comportamiento previsto. Cada módulo y prueba sustancial cita la sección que implementa, para que un revisor pueda verificar el código contra el requisito en lugar de contra un resumen del mismo.

El MVP está completo y el conjunto completo — incluido el adversarial — pasa. Lo que queda antes de que alguien deba confiar en él en serio: revisión independiente, pruebas de factor humano de la interfaz de confirmación (SPEC.md §35), y artefactos de lanzamiento firmados (§43).

Contribuciones

La seguridad es el producto aquí, por lo que el estándar para los cambios es específico en lugar de burocrático:

• Un cambio que toque el manejo de credenciales, la autorización o la superficie MCP necesita una prueba que intente romper el invariante que afecta, no solo una que demuestre que funciona.

• Nunca debilitar una prueba de seguridad para que pase una suite. Si una prueba revela un defecto arquitectónico, la arquitectura es lo que cambia.

• Las nuevas dependencias de tiempo de ejecución en el núcleo se oponen por defecto. El intermediario es la base de computación confiable para el material de credenciales; los SDK de proveedores pertenecen detrás de un extra opcional.

• Ejecuta ruff check ., ruff format --check ., mypy y pytest antes de abrir una solicitud de incorporación de cambios.

¿Encontraste una vulnerabilidad? Por favor, repórtala de forma privada a través de los avisos de seguridad de GitHub en lugar de abrir un problema público.

Licencia

Licencia Apache 2.0 © 2026 Eduardo Rosostolato.