Cover

Mantén los valores sensibles fuera de las solicitudes a LLM sin romper la conversación.

Instalación · Inicio rápido · Políticas · Monitoreo · Pi / OMP · Seguridad

Cover es un proxy de privacidad local para Codex, Claude Code, Cursor, SDKs y otros clientes de IA basados en HTTP. Escanea el JSON saliente, reemplaza los valores coincidentes localmente y restaura los reemplazos reversibles en respuestas JSON y de streaming. El LLM recibe los valores protegidos, mientras que el agente puede seguir usando los originales.

Cover se ejecuta como un proxy inverso transparente con reemplazo basado en políticas, seudónimos deterministas, comprobaciones operativas, soporte de Codex y manejo estricto de fallos. Está diseñado para mantenerse local, observable y explícito sobre lo que no puede inspeccionar.

flowchart LR
    A["Agent"] -->|"JSON request"| C["Cover<br/>detect · transform · enforce"]
    C -->|"protected request"| L["LLM or router"]
    L -->|"JSON or SSE response"| C
    C -->|"restored response"| A

Aspectos destacados

Instalación

El instalador clona Cover, lo compila con Go, lo instala en ~/.local/bin/cover, configura los clientes seleccionados e inicia el proxy.

curl -fsSL https://raw.githubusercontent.com/DavidCarliez/cover/main/scripts/install.sh | bash

Requisitos: git y la versión de Go declarada en go.mod.

Los archivos precompilados para Linux, macOS y Windows y sus sumas de verificación están disponibles en GitHub Releases.

Para una instalación no interactiva:

COVER_AGENTS=openai,claude \
  curl -fsSL https://raw.githubusercontent.com/DavidCarliez/cover/main/scripts/install.sh | bash

git clone https://github.com/DavidCarliez/cover.git
cd cover
go build -o cover ./cmd/cover
install -m 0755 cover ~/.local/bin/cover

GOOS=linux GOARCH=arm64 go build -o cover-linux-arm64 ./cmd/cover
GOOS=windows GOARCH=amd64 go build -o cover.exe ./cmd/cover

Inicio rápido

cover init             # write ~/.config/cover/config.yaml
cover start --detach   # run in the background
cover doctor           # verify the local setup
cover test             # local redaction round trip, no network call
cover monitor          # watch privacy-safe request metadata

cover init solicita OpenAI, Anthropic o un upstream personalizado. La configuración completa está documentada en configs/config.example.yaml.

Referencia de comandos

Detener Cover no cambia la configuración del cliente. Un cliente que aún apunte a Cover no podrá conectarse hasta que Cover se reinicie o el cliente vuelva a apuntar a su proveedor o router directo.

Políticas de privacidad

La detección regex integrada cubre claves de AWS y GCP, tokens de GitHub, GitLab, Slack, Stripe y Anthropic, bloques de claves privadas, JWTs, asignaciones explícitas de secretos genéricos, correos electrónicos, SSNs, tarjetas de crédito, números de teléfono e IBANs. Un valor OpenAI sk-... aislado no es deliberadamente una categoría integrada dedicada. Define una regla explícita si tu entorno lo necesita.

Las reglas se encuentran bajo rules en ~/.config/cover/config.yaml. Un selector puede ser una expresión regular, un detector builtin_* o una lista de claves de objetos JSON.

rules:
  password_fields:
    keys: [password, passwd, pwd, passphrase, user_password, database_password]
    category: password
    action: pseudonymize
    generator: password
    priority: 220

  ipv4_addresses:
    detector: builtin_ipv4
    category: ip_address
    action: pseudonymize
    generator: ipv4
    priority: 100

  customer_name:
    pattern: '(?i)\bNIKE\b'
    category: customer
    action: pseudonymize
    generator: alias
    priority: 80

  forbidden_secret:
    pattern: '(?i)secret\s*[:=]\s*(?P<value>[^\s,;]+)'
    action: block
    priority: 200

Los selectores de clave protegen valores de cadena completos. Por ejemplo, {"password":"admin"} se protege sin tratar un {"username":"admin"} no relacionado como contraseña. Los grupos nombrados (?P<value>...) permiten que una regex reemplace solo el valor capturado.

Generadores de seudónimos: ipv4, ipv6, hostname, domain, fqdn, email, username, password, secret, uuid, url y alias.

Las reglas se validan al iniciar. Selectores, expresiones, acciones, generadores o grupos de captura inválidos impiden que Cover se inicie. Los errores del detector, el agotamiento del mapeo, el JSON malformado, los cuerpos comprimidos y los bloqueos explícitos no recurren a reenviar la solicitud original.

Seudónimos estables y mapeos reversibles

Cover crea ~/.config/cover/pseudonym.key con permisos de solo propietario. HMAC-SHA-256 deriva el mismo seudónimo para el mismo valor original entre sesiones y reinicios. Instalaciones diferentes producen seudónimos diferentes.

La clave no permite recuperar los valores originales. La restauración utiliza mapeos limitados mantenidos solo en la memoria del proceso. Los mapeos se separan por X-Cover-Session, expiran después del TTL configurado y se eliminan cuando se completa una solicitud aislada. Haz una copia de seguridad de la clave solo si la continuidad de los seudónimos estables es importante.

Inspeccionar, diagnosticar y monitorear

Previsualizar sin enviar

cover inspect request.json
cover inspect request.json --session demo

El informe contiene la solicitud transformada, las reglas coincidentes, las categorías, las acciones, las advertencias y el estado de bloqueo. No envía una solicitud de red ni imprime el mapeo reversible.

Comprobar la instalación

cover doctor
cover doctor --json

Doctor valida la configuración, la política del listener, los límites, la clave de seudónimos, el ciclo de redacción, la protección contra bucles de upstream, el daemon, el comportamiento de cierre ante fallos, el registro de auditoría, el enrutamiento de entorno, el proveedor de Codex y la compresión de solicitudes de Codex. Su sonda en vivo se rechaza localmente y no gasta tokens del modelo.

Monitoreo seguro por defecto

cover monitor
cover monitor --follow=false -n 50
cover monitor --json

El monitor por defecto solo muestra metadatos en lista blanca: hora, estado HTTP, cantidad de transformaciones, conteos de bytes, latencia, categorías y errores genéricos. Los registros de auditoría nunca contienen cuerpos de solicitudes o respuestas, valores coincidentes, mapeos, rutas, consultas o credenciales del upstream.

Vista explícita de contenido sensible en vivo

cover monitor --show-content
cover monitor --show-content --once
cover monitor --show-content --json

Esta vista, que se activa explícitamente, muestra cada original y reemplazo capturados, seguidos del JSON transformado exacto que se entrega al transporte upstream. Es solo en vivo y nunca se añade al registro de auditoría. La captura comienza después de que un visor local autenticado se conecta y se detiene cuando se desconecta. El flujo es solo de bucle local, utiliza un token derivado de la clave de instalación y desconecta a los visores lentos.

[!WARNING] Esta salida de terminal es sensible. No uses --show-content en terminales compartidas, sesiones grabadas, registros de CI o transcripciones de soporte.

Conectar clientes

Cover reenvía los métodos de solicitud, rutas, consultas y encabezados al upstream configurado. La autenticación existente del proveedor sigue funcionando porque Cover no reescribe los encabezados de autenticación.

Codex y Codex Router

Codex usa la API de Responses. Añade un proveedor a nivel de usuario en ~/.codex/config.toml y desactiva la compresión de solicitudes para que Cover pueda inspeccionar el cuerpo:

model_provider = "cover"

[model_providers.cover]
name = "Cover"
base_url = "http://127.0.0.1:8317"
wire_api = "responses"
requires_openai_auth = true
supports_websockets = false

[features]
enable_request_compression = false

Estas claves siguen la referencia de configuración oficial de Codex. Si [features] ya existe, añade la configuración a esa tabla. Para un router que lee un token del entorno, reemplaza requires_openai_auth con env_key = "YOUR_ROUTER_KEY_ENV_NAME".

Mantén el upstream de Cover apuntando a la URL real del router. Usa configs/codex-router.example.yaml como punto de partida. El modelo seleccionado puede ser OpenAI, Anthropic, Gemini, DeepSeek u otro modelo porque Cover opera sobre el tráfico JSON genérico del router.

Los campos encrypted_content de la API de Responses son opacos y se verifican criptográficamente. Cover los deja sin cambios durante el escaneo de solicitudes y la restauración de respuestas.

Claude Code, SDKs y otros clientes

export ANTHROPIC_BASE_URL=http://127.0.0.1:8317
export OPENAI_BASE_URL=http://127.0.0.1:8317/v1

Claude Code usa la primera forma. Los SDK y clientes compatibles con OpenAI generalmente usan la forma /v1. El instalador puede persistir estos ajustes, y cover env imprime las exportaciones para los clientes seleccionados durante la instalación.

Los constructores de SDK pueden establecer la misma URL base directamente:

client = OpenAI(base_url="http://127.0.0.1:8317/v1", api_key=os.environ["OPENAI_API_KEY"])
client = anthropic.Anthropic(base_url="http://127.0.0.1:8317", api_key=os.environ["ANTHROPIC_API_KEY"])

Cursor y otras aplicaciones pueden usar el mismo endpoint cuando exponen un ajuste de URL base de API. Confirma el enrutamiento con cover doctor o cover monitor.

Pi y Oh My Pi

La extensión oficial de harness controla Cover desde Pi u Oh My Pi mientras mantiene el motor de privacidad en el proxy Go local:

pi install npm:cover-harness
# or
omp plugin install cover-harness

Configura solo los proveedores que deben pasar por el upstream actual de Cover:

/cover providers openai-codex,deepseek=/
/cover on
/cover doctor

Los proveedores de la familia OpenAI usan por defecto la ruta /v1 del proxy. =/ selecciona la raíz del proxy para transportes como DeepSeek que añaden su propia ruta de solicitud. Usa /cover status, /cover start, /cover stop y /cover monitor para la operación normal. /cover off restaura el enrutamiento directo al proveedor.

La protección es de cierre ante fallos: mientras está habilitada, los proveedores configurados permanecen apuntando a Cover cuando su daemon no está disponible, por lo que las solicitudes fallan localmente en lugar de eludir el proxy. El estado de la extensión es privado y local en ~/.config/cover/harness.json.

El mismo paquete aparece en la galería de paquetes de Pi. Los usuarios de OMP también pueden añadir este repositorio como marketplace:

omp plugin marketplace add DavidCarliez/cover
omp plugin install cover-harness@cover

Detector LLM local opcional

Las reglas de regex y sensibles a claves no pueden identificar todos los nombres, direcciones, ID de clientes o nombres en clave internos. Cover puede ejecutar un pequeño modelo local llama.cpp como detector semántico adicional.

cover models pull
cover models status
cover restart

El modelo por defecto es Qwen2.5-0.5B-Instruct en un GGUF Q4 de aproximadamente 490 MB. Cover inicia llama-server en bucle local y aplica presupuestos por llamada y generales de solicitud. Los binarios faltantes, los fallos de inicio, los tiempos de espera y los errores del detector provocan un cierre ante fallos cuando el detector está habilitado. Los fragmentos devueltos deben aparecer textualmente en la entrada antes de que Cover los acepte.

Deja esta función desactivada en plataformas no compatibles. Consulta la sección detectors.llm_fallback en configs/config.example.yaml para límites, procesamiento por lotes, concurrencia y rutas de modelos.

Límite de seguridad

Cover protege los valores de cadena coincidentes en cuerpos JSON que realmente pasan por el proxy. No afirma descubrir todos los valores sensibles.

Los datos aún pueden salir de la máquina cuando aparecen en:

• un valor que ningún detector o regla habilitada reconoce;
• un campo cubierto por una regla allow;
• encabezados HTTP, rutas de URL o cadenas de consulta;
• píxeles de imagen, medios binarios o codificaciones no compatibles;
• valores JSON que no son cadenas;
• campos estructurales del protocolo como modelo, rol, tipo, IDs y nombres de herramientas o funciones;
• encrypted_content opaco, que debe permanecer sin cambios para la seguridad del protocolo;
• tráfico de un cliente que elude Cover.

El manejo de imágenes en línea es configurable con media.images: allow, warn o block. Cover no inspecciona píxeles, y ninguna política de medios puede reconocer todas las codificaciones posibles.

Cover rechaza los listeners que no sean de bucle local a menos que network.allow_remote: true esté explícitamente configurado. Si Cover y su router upstream se ejecutan en hosts diferentes, usa TLS u otro transporte confiable y aplica controles de acceso de red separados. Cover mismo no autentica el tráfico proxy ordinario.

Los límites de solicitud, respuesta almacenada, flujo total y por evento SSE acotan el uso de memoria. Las solicitudes sobredimensionadas devuelven HTTP 413, las respuestas almacenadas sobredimensionadas devuelven HTTP 502 y los flujos sobredimensionados se terminan.

Lee SECURITY.md antes de reportar una vulnerabilidad. Usa la ruta de reporte privada descrita allí en lugar de abrir un issue público.

Proyecto

• Desarrollo y pruebas: CONTRIBUTING.md
• Conducta: CODE_OF_CONDUCT.md
• Licencia: Apache License 2.0