Cover

Mantenha valores sensíveis fora das solicitações de LLM sem quebrar a conversa.

Instalação · Início rápido · Políticas · Monitoramento · Pi / OMP · Segurança

Cover é um proxy de privacidade local para Codex, Claude Code, Cursor, SDKs e outros clientes de IA baseados em HTTP. Ele examina o JSON de saída, substitui valores correspondentes localmente e restaura substituições reversíveis em respostas JSON e de streaming. O LLM recebe os valores protegidos, enquanto o agente pode continuar usando os originais.

O Cover atua como um proxy reverso transparente, com substituição orientada por políticas, pseudônimos determinísticos, verificações operacionais, suporte ao Codex e tratamento estrito de falhas. Ele é projetado para permanecer local, observável e explícito sobre o que não consegue inspecionar.

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

Destaques

Instalação

O instalador clona o Cover, compila com Go, instala em ~/.local/bin/cover, configura os clientes selecionados e inicia o proxy.

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

Requisitos: git e a versão do Go declarada em go.mod.

Arquivos pré-compilados para Linux, macOS e Windows e suas somas de verificação estão disponíveis em GitHub Releases.

Para uma instalação não interativa:

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

Início 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 ou um upstream personalizado. A configuração completa está documentada em configs/config.example.yaml.

Referência de comandos

Parar o Cover não altera a configuração do cliente. Um cliente que ainda aponte para o Cover não conseguirá se conectar até que o Cover seja reiniciado ou o cliente seja apontado novamente para seu provedor ou roteador direto.

Políticas de privacidade

A detecção integrada por regex cobre chaves da AWS e do GCP, tokens do GitHub, GitLab, Slack, Stripe e Anthropic, blocos de chave privada, JWTs, atribuições explícitas de segredos genéricos, e-mails, SSNs, cartões de crédito, números de telefone e IBANs. Um valor OpenAI sk-... isolado deliberadamente não é uma categoria integrada dedicada. Defina uma regra explícita se o seu ambiente precisar de uma.

As regras ficam em rules em ~/.config/cover/config.yaml. Um seletor pode ser uma expressão regular, um detector builtin_* ou uma lista de chaves de objeto 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

Seletores de chave protegem valores de string completos. Por exemplo, {"password":"admin"} é protegido sem tratar um {"username":"admin"} não relacionado como senha. Grupos nomeados (?P<value>...) permitem que uma regex substitua apenas o valor capturado.

Geradores de pseudônimos: ipv4, ipv6, hostname, domain, fqdn, email, username, password, secret, uuid, url e alias.

As regras são validadas na inicialização. Seletores, expressões, ações, geradores ou grupos de captura inválidos impedem o Cover de iniciar. Erros de detector, esgotamento de mapeamento, JSON malformado, corpos compactados e bloqueios explícitos não recorrem ao encaminhamento da solicitação original.

Pseudônimos estáveis e mapeamentos reversíveis

O Cover cria ~/.config/cover/pseudonym.key com permissões somente para o proprietário. O HMAC-SHA-256 deriva o mesmo pseudônimo para o mesmo valor original entre sessões e reinicializações. Instalações diferentes produzem pseudônimos diferentes.

A chave não pode recuperar valores originais. A restauração usa mapeamentos limitados mantidos apenas na memória do processo. Os mapeamentos são separados por X-Cover-Session, expiram após o TTL configurado e são excluídos quando uma solicitação isolada é concluída. Faça backup da chave somente se a continuidade estável de pseudônimos for importante.

Inspecionar, diagnosticar e monitorar

Pré-visualizar sem enviar

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

O relatório contém a solicitação transformada, regras correspondentes, categorias, ações, avisos e estado de bloqueio. Ele não envia uma solicitação de rede nem imprime o mapeamento reversível.

Verificar a instalação

cover doctor
cover doctor --json

O Doctor valida a configuração, a política do listener, os limites, a chave de pseudônimo, o ciclo de redação, a proteção contra loop de upstream, o daemon, o comportamento fail-closed, o log de auditoria, o roteamento de ambiente, o provedor do Codex e a compressão de solicitações do Codex. A sonda ao vivo é rejeitada localmente e não gasta tokens do modelo.

Monitoramento seguro por padrão

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

O monitor padrão mostra apenas metadados na lista de permissões: hora, status HTTP, contagem de transformações, contagens de bytes, latência, categorias e erros genéricos. Os logs de auditoria nunca contêm corpos de solicitação ou resposta, valores correspondentes, mapeamentos, caminhos, consultas ou credenciais de upstream.

Visualização sensível explícita ao vivo

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

Esta visualização opcional mostra cada original capturado e sua substituição, seguidos pelo JSON transformado exato entregue ao transporte upstream. É somente ao vivo e nunca é adicionada ao log de auditoria. A captura começa depois que um visualizador local autenticado se conecta e para quando ele se desconecta. O fluxo é somente loopback, usa um token derivado da chave de instalação e desconecta visualizadores lentos.

[!WARNING] Esta saída de terminal é sensível. Não use --show-content em terminais compartilhados, sessões gravadas, logs de CI ou transcrições de suporte.

Conectar clientes

O Cover encaminha métodos, caminhos, consultas e cabeçalhos de solicitação para o upstream configurado. A autenticação existente do provedor continua funcionando porque o Cover não reescreve cabeçalhos de autenticação.

Codex e Codex Router

O Codex usa a API Responses. Adicione um provedor de nível de usuário em ~/.codex/config.toml e desative a compressão de solicitações para que o Cover possa inspecionar o corpo:

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

Essas chaves seguem a referência de configuração oficial do Codex. Se [features] já existir, adicione a configuração a essa tabela. Para um roteador que lê um token do ambiente, substitua requires_openai_auth por env_key = "YOUR_ROUTER_KEY_ENV_NAME".

Mantenha o upstream do Cover apontando para a URL real do roteador. Use configs/codex-router.example.yaml como ponto de partida. O modelo selecionado pode ser OpenAI, Anthropic, Gemini, DeepSeek ou outro, porque o Cover opera no tráfego JSON genérico do roteador.

Os campos encrypted_content da API Responses são opacos e verificados criptograficamente. O Cover os deixa inalterados durante a varredura da solicitação e a restauração da resposta.

Claude Code, SDKs e outros clientes

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

O Claude Code usa a primeira forma. SDKs e clientes compatíveis com OpenAI geralmente usam a forma /v1. O instalador pode persistir essas configurações, e cover env imprime os exports para os clientes selecionados durante a instalação.

Os construtores de SDK podem definir a mesma URL base diretamente:

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"])

O Cursor e outros aplicativos podem usar o mesmo endpoint quando expõem uma configuração de URL base da API. Confirme o roteamento com cover doctor ou cover monitor.

Pi e Oh My Pi

A extensão oficial do harness controla o Cover a partir do Pi ou do Oh My Pi, mantendo o mecanismo de privacidade no proxy Go local:

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

Configure apenas os provedores que precisam passar pelo upstream atual do Cover:

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

Provedores da família OpenAI usam por padrão o caminho de proxy /v1. =/ seleciona a raiz do proxy para transportes como DeepSeek que adicionam seu próprio caminho de solicitação. Use /cover status, /cover start, /cover stop e /cover monitor para operação normal. /cover off restaura o roteamento direto do provedor.

A proteção é fail-closed: enquanto habilitada, os provedores configurados permanecem apontando para o Cover quando seu daemon está indisponível, então as solicitações falham localmente em vez de contornar o proxy. O estado da extensão é privado e local em ~/.config/cover/harness.json.

O mesmo pacote aparece na galeria de pacotes do Pi. Usuários do OMP também podem adicionar este repositório como um marketplace:

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

Detector LLM local opcional

Regras baseadas em regex e em chaves não conseguem identificar todo nome, endereço, ID de cliente ou codinome interno. O Cover pode executar um pequeno modelo local llama.cpp como detector semântico adicional.

cover models pull
cover models status
cover restart

O modelo padrão é Qwen2.5-0.5B-Instruct em um Q4 GGUF de aproximadamente 490 MB. O Cover inicia llama-server em loopback e aplica orçamentos de solicitação por chamada e gerais. Binários ausentes, falhas de inicialização, timeouts e erros do detector falham de forma fechada (fail-closed) quando o detector está habilitado. Os trechos retornados devem ocorrer literalmente na entrada antes que o Cover os aceite.

Mantenha esse recurso desativado em plataformas sem suporte. Consulte a seção detectors.llm_fallback em configs/config.example.yaml para limites, agrupamento, concorrência e caminhos de modelo.

Fronteira de segurança

O Cover protege valores de string correspondentes em corpos JSON que realmente passam pelo proxy. Ele não afirma descobrir todos os valores sensíveis.

Os dados ainda podem sair da máquina quando aparecem em:

• um valor que nenhum detector ou regra habilitada reconhece;
• um campo coberto por uma regra allow;
• cabeçalhos HTTP, caminhos de URL ou strings de consulta;
• pixels de imagem, mídia binária ou codificações sem suporte;
• valores JSON que não são strings;
• campos estruturais do protocolo, como model, role, type, IDs e nomes de ferramentas ou funções;
• encrypted_content opaco, que deve permanecer inalterado para a segurança do protocolo;
• tráfego de um cliente que contorna o Cover.

O tratamento de imagens inline é configurável com media.images: allow, warn ou block. O Cover não inspeciona pixels, e nenhuma política de mídia consegue reconhecer todas as codificações possíveis.

O Cover rejeita listeners que não sejam de loopback, a menos que network.allow_remote: true esteja configurado explicitamente. Se o Cover e seu roteador upstream forem executados em hosts diferentes, use TLS ou outro transporte confiável e aplique controles de acesso de rede separados. O Cover em si não autentica tráfego de proxy comum.

Limites de solicitação, resposta em buffer, fluxo total e por evento SSE limitam o uso de memória. Solicitações grandes demais retornam HTTP 413, respostas em buffer grandes demais retornam HTTP 502 e fluxos grandes demais são encerrados.

Leia SECURITY.md antes de relatar uma vulnerabilidade. Use a rota de relato privada descrita lá em vez de abrir uma issue pública.

Projeto

• Desenvolvimento e testes: CONTRIBUTING.md
• Conduta: CODE_OF_CONDUCT.md
• Licença: Apache License 2.0