Cover

Gardez les valeurs sensibles hors des requêtes LLM sans interrompre la conversation.

Installation · Démarrage rapide · Politiques · Surveillance · Pi / OMP · Sécurité

Cover est un proxy de confidentialité local pour Codex, Claude Code, Cursor, les SDK et autres clients IA basés sur HTTP. Il analyse le JSON sortant, remplace localement les valeurs correspondantes et restaure les remplacements réversibles dans les réponses JSON et en streaming. Le LLM reçoit les valeurs protégées, tandis que l'agent peut continuer à utiliser les valeurs d'origine.

Cover fonctionne comme un proxy inverse transparent avec un remplacement piloté par des politiques, des pseudonymes déterministes, des contrôles opérationnels, la prise en charge de Codex et une gestion stricte des erreurs. Il est conçu pour rester local, observable et explicite sur ce qu'il ne peut pas inspecter.

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

Points clés

Installation

L'installeur clone Cover, le compile avec Go, l'installe dans ~/.local/bin/cover, configure les clients sélectionnés et démarre le proxy.

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

Prérequis : git et la version de Go déclarée dans go.mod.

Des archives précompilées pour Linux, macOS et Windows, ainsi que leurs sommes de contrôle, sont disponibles depuis GitHub Releases.

Pour une installation non interactive :

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

Démarrage rapide

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 demande de choisir entre OpenAI, Anthropic ou un upstream personnalisé. La configuration complète est documentée dans configs/config.example.yaml.

Référence des commandes

L'arrêt de Cover ne modifie pas la configuration des clients. Un client toujours pointé vers Cover ne pourra pas se connecter tant que Cover n'est pas redémarré ou que le client n'est pas repointé vers son fournisseur ou routeur direct.

Politiques de confidentialité

La détection intégrée par expressions régulières couvre les clés AWS et GCP, les jetons GitHub, GitLab, Slack, Stripe et Anthropic, les blocs de clés privées, les JWT, les assignations explicites de secrets génériques, les e-mails, les numéros de sécurité sociale (SSN), les cartes bancaires, les numéros de téléphone et les IBAN. Une valeur OpenAI brute sk-... n'est volontairement pas une catégorie intégrée dédiée. Définissez une règle explicite si votre environnement en a besoin.

Les règles se trouvent sous rules dans ~/.config/cover/config.yaml. Un sélecteur peut être une expression régulière, un détecteur builtin_* ou une liste de clés d'objets 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

Les sélecteurs par clé protègent les valeurs de chaîne complètes. Par exemple, {"password":"admin"} est protégé sans traiter un {"username":"admin"} sans rapport comme un mot de passe. Les groupes nommés (?P<value>...) permettent à une expression régulière de ne remplacer que la valeur capturée.

Générateurs de pseudonymes : ipv4, ipv6, hostname, domain, fqdn, email, username, password, secret, uuid, url et alias.

Les règles sont validées au démarrage. Des sélecteurs, expressions, actions, générateurs ou groupes de capture invalides empêchent Cover de démarrer. Les erreurs de détection, l'épuisement des correspondances, le JSON malformé, les corps compressés et les blocages explicites ne donnent pas lieu à un repli sur la transmission de la requête d'origine.

Pseudonymes stables et correspondances réversibles

Cover crée ~/.config/cover/pseudonym.key avec des permissions réservées au propriétaire. HMAC-SHA-256 dérive le même pseudonyme pour la même valeur d'origine à travers les sessions et les redémarrages. Des installations différentes produisent des pseudonymes différents.

La clé ne permet pas de récupérer les valeurs d'origine. La restauration utilise des correspondances bornées conservées uniquement dans la mémoire du processus. Les correspondances sont séparées par X-Cover-Session, expirent après le TTL configuré et sont supprimées lorsqu'une requête isolée se termine. Sauvegardez la clé uniquement si la continuité des pseudonymes stables est importante.

Inspecter, diagnostiquer et surveiller

Prévisualiser sans envoyer

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

Le rapport contient la requête transformée, les règles correspondantes, les catégories, les actions, les avertissements et l'état de blocage. Il n'envoie aucune requête réseau et n'affiche pas la correspondance réversible.

Vérifier l'installation

cover doctor
cover doctor --json

Doctor valide la configuration, la politique des écouteurs, les limites, la clé de pseudonyme, le cycle complet de masquage, la protection contre les boucles d'upstream, le démon, le comportement fail-closed, le journal d'audit, le routage d'environnement, le fournisseur Codex et la compression des requêtes Codex. Sa sonde en direct est rejetée localement et ne consomme pas de jetons de modèle.

Surveillance sûre par défaut

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

Le moniteur par défaut n'affiche que les métadonnées autorisées : heure, statut HTTP, nombre de transformations, nombre d'octets, latence, catégories et erreurs génériques. Les journaux d'audit ne contiennent jamais les corps de requêtes ou de réponses, les valeurs correspondantes, les correspondances, les chemins, les chaînes de requête ou les identifiants de l'upstream.

Vue sensible en direct explicite

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

Cette vue optionnelle affiche chaque valeur d'origine capturée et son remplacement, suivis du JSON transformé exact transmis au transport de l'upstream. Elle est exclusivement en direct et n'est jamais ajoutée au journal d'audit. La capture démarre après la connexion d'un visualiseur local authentifié et s'arrête à sa déconnexion. Le flux est limité au loopback, utilise un jeton dérivé de la clé d'installation et déconnecte les visualiseurs lents.

[!WARNING] Cette sortie terminal est sensible. N'utilisez pas --show-content dans des terminaux partagés, des sessions enregistrées, des journaux CI ou des transcriptions de support.

Connecter les clients

Cover transmet les méthodes, chemins, chaînes de requête et en-têtes de requête à l'upstream configuré. L'authentification existante du fournisseur continue de fonctionner car Cover ne réécrit pas les en-têtes d'authentification.

Codex et Codex Router

Codex utilise l'API Responses. Ajoutez un fournisseur au niveau utilisateur dans ~/.codex/config.toml et désactivez la compression des requêtes afin que Cover puisse inspecter le corps :

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

Ces clés suivent la référence de configuration officielle de Codex. Si [features] existe déjà, ajoutez le paramètre à cette table. Pour un routeur qui lit un jeton depuis l'environnement, remplacez requires_openai_auth par env_key = "YOUR_ROUTER_KEY_ENV_NAME".

Maintenez l'upstream de Cover pointé vers l'URL réelle du routeur. Utilisez configs/codex-router.example.yaml comme point de départ. Le modèle sélectionné peut être OpenAI, Anthropic, Gemini, DeepSeek ou un autre modèle, car Cover opère sur le trafic JSON générique du routeur.

Les champs encrypted_content de l'API Responses sont opaques et cryptographiquement vérifiés. Cover les laisse inchangés lors de l'analyse des requêtes et de la restauration des réponses.

Claude Code, SDK et autres clients

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

Claude Code utilise la première forme. Les SDK et clients compatibles OpenAI utilisent généralement la forme /v1. L'installeur peut conserver ces paramètres, et cover env affiche les exports pour les clients sélectionnés lors de l'installation.

Les constructeurs de SDK peuvent définir la même URL de base directement :

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 et d'autres applications peuvent utiliser le même point de terminaison lorsqu'ils exposent un paramètre d'URL de base d'API. Confirmez le routage avec cover doctor ou cover monitor.

Pi et Oh My Pi

L'extension officielle harness contrôle Cover depuis Pi ou Oh My Pi tout en conservant le moteur de confidentialité dans le proxy Go local :

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

Configurez uniquement les fournisseurs qui doivent passer par l'upstream Cover actuel :

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

Les fournisseurs de la famille OpenAI utilisent par défaut le chemin proxy /v1. =/ sélectionne la racine du proxy pour les transports comme DeepSeek qui ajoutent leur propre chemin de requête. Utilisez /cover status, /cover start, /cover stop et /cover monitor pour le fonctionnement normal. /cover off restaure le routage direct des fournisseurs.

La protection est fail-closed : lorsqu'elle est activée, les fournisseurs configurés restent pointés vers Cover même si son démon est indisponible, de sorte que les requêtes échouent localement plutôt que de contourner le proxy. L'état de l'extension est privé et local, dans ~/.config/cover/harness.json.

Le même paquet apparaît dans la galerie de paquets Pi. Les utilisateurs d'OMP peuvent également ajouter ce dépôt comme marketplace :

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

Détecteur LLM local optionnel

Les règles par expressions régulières et par clés ne peuvent pas identifier chaque nom, adresse, identifiant client ou nom de code interne. Cover peut exécuter un petit modèle local llama.cpp comme détecteur sémantique supplémentaire.

cover models pull
cover models status
cover restart

Le modèle par défaut est Qwen2.5-0.5B-Instruct au format Q4 GGUF d'environ 490 Mo. Cover démarre llama-server sur le loopback et applique des budgets de requête par appel et au total. Les binaires manquants, les échecs de démarrage, les délais d'attente et les erreurs de détection échouent en mode fermé (fail-closed) lorsque le détecteur est activé. Les segments retournés doivent apparaître textuellement dans l'entrée avant que Cover ne les accepte.

Laissez cette fonctionnalité désactivée sur les plateformes non prises en charge. Consultez la section detectors.llm_fallback dans configs/config.example.yaml pour les limites, le traitement par lots, la concurrence et les chemins des modèles.

Frontière de sécurité

Cover protège les valeurs de chaîne correspondantes dans les corps JSON qui passent effectivement par le proxy. Il ne prétend pas découvrir toutes les valeurs sensibles.

Des données peuvent encore quitter la machine lorsqu'elles apparaissent dans :

• une valeur qu'aucun détecteur ou règle activé ne reconnaît ;
• un champ couvert par une règle allow ;
• des en-têtes HTTP, des chemins d'URL ou des chaînes de requête ;
• des pixels d'image, des médias binaires ou des encodages non pris en charge ;
• des valeurs JSON non-chaîne ;
• des champs structurels de protocole tels que model, role, type, les ID et les noms d'outils ou de fonctions ;
• encrypted_content opaque, qui doit rester inchangé pour la sécurité du protocole ;
• le trafic d'un client qui contourne Cover.

La gestion des images en ligne est configurable avec media.images: allow, warn ou block. Cover n'inspecte pas les pixels et aucune politique média ne peut reconnaître tous les encodages possibles.

Cover rejette les écouteurs non-loopback sauf si network.allow_remote: true est explicitement configuré. Si Cover et son routeur upstream s'exécutent sur des hôtes différents, utilisez TLS ou un autre transport de confiance et appliquez des contrôles d'accès réseau séparés. Cover lui-même n'authentifie pas le trafic proxy ordinaire.

Des limites sur les requêtes, les réponses mises en mémoire tampon, les flux totaux et chaque événement SSE bornent l'utilisation de la mémoire. Les requêtes trop volumineuses renvoient HTTP 413, les réponses mises en mémoire tampon trop volumineuses renvoient HTTP 502 et les flux trop volumineux sont interrompus.

Lisez SECURITY.md avant de signaler une vulnérabilité. Veuillez utiliser la voie de signalement privée qui y est décrite plutôt que d'ouvrir un problème public.

Projet

• Développement et tests : CONTRIBUTING.md
• Code de conduite : CODE_OF_CONDUCT.md
• Licence : Apache License 2.0