Cover

Mantieni i valori sensibili fuori dalle richieste agli LLM senza interrompere la conversazione.

Installa · Avvio rapido · Politiche · Monitoraggio · Pi / OMP · Sicurezza

Cover è un proxy locale per la privacy per Codex, Claude Code, Cursor, SDK e altri client AI basati su HTTP. Analizza il JSON in uscita, sostituisce i valori corrispondenti localmente e ripristina le sostituzioni reversibili nelle risposte JSON e in streaming. L'LLM riceve i valori protetti, mentre l'agente può continuare a usare gli originali.

Cover funziona come un proxy inverso trasparente con sostituzione guidata da politiche, pseudonimi deterministici, controlli operativi, supporto per Codex e gestione rigorosa degli errori. È progettato per rimanere locale, osservabile ed esplicito su ciò che non può ispezionare.

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

Caratteristiche principali

Install

Lo script di installazione clona Cover, lo compila con Go, lo installa in ~/.local/bin/cover, configura i client selezionati e avvia il proxy.

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

Requisiti: git e la versione di Go dichiarata in go.mod.

Archivi precompilati per Linux, macOS e Windows e i relativi checksum sono disponibili nella pagina GitHub Releases.

Per un'installazione non interattiva:

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

Quick start

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 chiede di scegliere OpenAI, Anthropic o un upstream personalizzato. La configurazione completa è documentata in configs/config.example.yaml.

Riferimento ai comandi

Fermare Cover non modifica la configurazione dei client. Un client ancora configurato per puntare a Cover non riuscirà a connettersi finché Cover non viene riavviato o il client non viene reindirizzato al suo provider o router diretto.

Privacy policies

Il rilevamento regex integrato copre chiavi AWS e GCP, token GitHub, GitLab, Slack, Stripe e Anthropic, blocchi di chiavi private, JWT, assegnazioni esplicite generiche di segreti, email, SSN, carte di credito, numeri di telefono e IBAN. Un valore OpenAI sk-... spoglio non è volutamente una categoria integrata dedicata. Definisci una regola esplicita se il tuo ambiente ne ha bisogno.

Le regole si trovano sotto rules in ~/.config/cover/config.yaml. Un selettore può essere un'espressione regolare, un rilevatore builtin_* o un elenco di chiavi 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

I selettori per chiave proteggono interi valori stringa. Ad esempio, {"password":"admin"} viene protetto senza trattare un {"username":"admin"} non correlato come password. I gruppi con nome (?P<value>...) consentono a una regex di sostituire solo il valore catturato.

Generatori di pseudonimi: ipv4, ipv6, hostname, domain, fqdn, email, username, password, secret, uuid, url e alias.

Le regole vengono validate all'avvio. Selettori, espressioni, azioni, generatori o gruppi di cattura non validi impediscono l'avvio di Cover. Errori del rilevatore, esaurimento delle mappature, JSON malformato, corpo compresso e blocchi espliciti non ricadono nell'inoltro della richiesta originale.

Pseudonimi stabili e mappature reversibili

Cover crea ~/.config/cover/pseudonym.key con permessi di solo proprietario. HMAC-SHA-256 deriva lo stesso pseudonimo per lo stesso valore originale tra sessioni e riavvii. Installazioni diverse producono pseudonimi diversi.

La chiave non può recuperare i valori originali. Il ripristino utilizza mappature limitate tenute solo nella memoria del processo. Le mappature sono separate da X-Cover-Session, scadono dopo il TTL configurato e vengono eliminate quando una richiesta isolata termina. Esegui un backup della chiave solo se la continuità degli pseudonimi è importante.

Inspect, diagnose, and monitor

Anteprima senza invio

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

Il report contiene la richiesta trasformata, le regole corrispondenti, le categorie, le azioni, gli avvisi e lo stato di blocco. Non invia una richiesta di rete né stampa la mappatura reversibile.

Verifica dell'installazione

cover doctor
cover doctor --json

Doctor valida la configurazione, la politica del listener, i limiti, la chiave degli pseudonimi, il ciclo di oscuramento, la protezione dal loop verso l'upstream, il demone, il comportamento fail-closed, il registro di audit, il routing ambientale, il provider Codex e la compressione delle richieste Codex. La sua sonda live viene rifiutata localmente e non consuma token del modello.

Monitoraggio sicuro predefinito

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

Il monitor predefinito mostra solo metadati consentiti: ora, stato HTTP, numero di trasformazioni, conteggi di byte, latenza, categorie ed errori generici. I log di audit non contengono mai corpo di richieste o risposte, valori corrispondenti, mappature, percorsi, query o credenziali dell'upstream.

Vista live esplicita dei dati sensibili

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

Questa vista opzionale mostra ogni originale intercettato e la relativa sostituzione, seguiti dal JSON trasformato esatto consegnato al trasporto upstream. È solo live e non viene mai aggiunta al registro di audit. La cattura inizia dopo che un visualizzatore locale autenticato si connette e termina quando si disconnette. Lo stream è solo su loopback, usa un token derivato dalla chiave di installazione e disconnette i visualizzatori lenti.

[!WARNING] Questo output di terminale è sensibile. Non usare --show-content in terminali condivisi, sessioni registrate, log CI o trascrizioni di supporto.

Connetti i client

Cover inoltra metodi, percorsi, query e header delle richieste all'upstream configurato. L'autenticazione esistente del provider continua a funzionare perché Cover non riscrive gli header di autenticazione.

Codex e Codex Router

Codex usa l'API Responses. Aggiungi un provider a livello utente in ~/.codex/config.toml e disabilita la compressione delle richieste in modo che Cover possa ispezionare il 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

Queste chiavi seguono il riferimento di configurazione ufficiale di Codex. Se [features] esiste già, aggiungi l'impostazione a quella tabella. Per un router che legge un token dall'ambiente, sostituisci requires_openai_auth con env_key = "YOUR_ROUTER_KEY_ENV_NAME".

Mantieni upstream di Cover puntato all'URL reale del router. Usa configs/codex-router.example.yaml come punto di partenza. Il modello selezionato può essere OpenAI, Anthropic, Gemini, DeepSeek o un altro modello, perché Cover opera sul traffico JSON generico del router.

I campi encrypted_content dell'API Responses sono opachi e verificati crittograficamente. Cover li lascia invariati durante la scansione delle richieste e il ripristino delle risposte.

Claude Code, SDK e altri client

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 prima forma. Gli SDK e i client compatibili con OpenAI usano generalmente la forma /v1. L'installer può salvare queste impostazioni e cover env stampa gli export per i client selezionati durante l'installazione.

I costruttori degli SDK possono impostare direttamente lo stesso base URL:

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 e altre applicazioni possono usare lo stesso endpoint quando espongono un'impostazione per l'URL di base dell'API. Conferma il routing con cover doctor o cover monitor.

Pi and Oh My Pi

L'estensione ufficiale dell'harness controlla Cover da Pi o Oh My Pi mantenendo il motore di privacy nel proxy Go locale:

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

Configura solo i provider che devono passare attraverso l'attuale upstream di Cover:

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

I provider della famiglia OpenAI usano di default il percorso proxy /v1. =/ seleziona la radice del proxy per trasporti come DeepSeek che aggiungono il proprio percorso di richiesta. Usa /cover status, /cover start, /cover stop e /cover monitor per il normale funzionamento. /cover off ripristina il routing diretto del provider.

La protezione è fail-closed: quando è attiva, i provider configurati restano puntati su Cover anche se il suo demone non è disponibile, quindi le richieste falliscono localmente invece di bypassare il proxy. Lo stato dell'estensione è privato e locale in ~/.config/cover/harness.json.

Lo stesso pacchetto appare nella libreria di pacchetti Pi. Gli utenti di OMP possono anche aggiungere questo repository come marketplace:

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

Rilevatore LLM locale opzionale

Le regole basate su regex e chiavi non possono identificare ogni nome, indirizzo, ID cliente o nome in codice interno. Cover può eseguire un piccolo modello locale llama.cpp come rilevatore semantico aggiuntivo.

cover models pull
cover models status
cover restart

Il modello predefinito è Qwen2.5-0.5B-Instruct in circa 490 MB di Q4 GGUF. Cover avvia llama-server su loopback e applica budget per chiamata e complessivi. Binari mancanti, errori di avvio, timeout ed errori del rilevatore falliscono in modalità chiusa quando il rilevatore è abilitato. Gli span restituiti devono comparire esattamente (verbatim) nell'input prima che Cover li accetti.

Lascia questa funzionalità disabilitata su piattaforme non supportate. Vedi la sezione detectors.llm_fallback in configs/config.example.yaml per limiti, batching, concorrenza e percorsi dei modelli.

Security boundary

Cover protegge i valori stringa corrispondenti nei corpi JSON che passano effettivamente attraverso il proxy. Non pretende di individuare ogni valore sensibile.

I dati possono comunque lasciare la macchina quando compaiono in:

• un valore che nessun rilevatore o regola abilitata riconosce;
• un campo coperto da una regola allow;
• header HTTP, percorsi URL o query string;
• pixel di immagini, contenuti binari o codifiche non supportate;
• valori JSON non stringa;
• campi strutturali del protocollo come model, role, type, ID e nomi di tool o funzioni;
• encrypted_content opaco, che deve rimanere invariato per la sicurezza del protocollo;
• traffico proveniente da un client che bypassa Cover.

La gestione delle immagini inline è configurabile con media.images: allow, warn o block. Cover non ispeziona i pixel e nessuna politica sui media può riconoscere ogni possibile codifica.

Cover rifiuta listener non-loopback a meno che network.allow_remote: true non sia configurato esplicitamente. Se Cover e il suo router upstream sono su host diversi, usa TLS o un altro trasporto affidabile e applica controlli di accesso di rete separati. Cover stesso non autentica il traffico proxy ordinario.

I limiti su richiesta, risposta bufferizzata, stream totale e singolo evento SSE limitano l'uso della memoria. Le richieste troppo grandi restituiscono HTTP 413, le risposte bufferizzate troppo grandi HTTP 502 e gli stream troppo grandi vengono terminati.

Leggi SECURITY.md prima di segnalare una vulnerabilità. Usa il canale di segnalazione privato descritto lì piuttosto che aprire una issue pubblica.

Progetto

• Sviluppo e test: CONTRIBUTING.md
• Condotta: CODE_OF_CONDUCT.md
• Licenza: Apache License 2.0