Il problema

Claude Code (e ogni altra CLI di codifica AI) memorizza l'intera cronologia della conversazione come file JSONL in chiaro sul disco — sotto ~/.claude/projects/ per Claude Code, ~/.codex/sessions/ per OpenAI Codex. Qualunque cosa incolli — una chiave AWS, un file .env, un URL di database — rimane in chiaro a tempo indeterminato. La cronologia di uno sviluppatore tipico accumula dozzine di segreti in mesi, spesso senza che lui se ne accorga.

agentsweep scansiona quella cronologia, ti dice cosa è trapelato e può oscurare i valori dei segreti sul posto preservando la struttura JSONL byte per byte. Inoltre, ti dice quali chiavi ruotare, con l'URL di revoca corretto per ogni provider.

Ambito di protezione: agentsweep è completamente locale e offline — legge e scrive solo file sulla tua macchina e non effettua alcuna chiamata di rete. Rimuove un vettore d'attacco: i segreti che risiedono nei file di cronologia locali. Non influisce su ciò che il tuo provider AI ha già ricevuto: quando incolli una chiave in Claude Code, Cursor o qualsiasi agente basato su cloud, quella chiave ha già transitato attraverso i server del provider prima di arrivare sul disco. Se questo ti preoccupa, considera un modello ospitato localmente (Ollama, LM Studio, OpenCode) dove nulla lascia la tua macchina — agentsweep si abbina particolarmente bene con configurazioni a modello locale.

Perché è importante adesso

Gli attacchi alla supply chain stanno accelerando. Nel 2024-2025 un'ondata di pacchetti npm e PyPI dannosi — sha256-universal, shailulid, centinaia di typosquat — sono stati sorpresi a fare una cosa: esfiltrare le credenziali degli sviluppatori dalla macchina su cui erano stati installati. Prendono di mira variabili d'ambiente, file .env, cronologia della shell, chiavi SSH e ora i file di cronologia degli agenti AI.

Gli assistenti di codifica AI hanno creato una nuova categoria di esposizione delle credenziali che non esisteva due anni fa:

• Incolli una chiave API di produzione in Claude Code per fare debug → ora è in ~/.claude/projects/*/conversations/*.jsonl per sempre
• Un pacchetto npm compromesso esegue postinstall → scansiona i percorsi comuni → trova i tuoi file JSONL di cronologia → esfiltra 50 chiavi API in una sola richiesta
• Ruoti la chiave che hai usato pubblicamente ma dimentichi le altre dozzine nella tua cronologia
• Nel frattempo la tua cronologia cresce: ogni .env per cui hai chiesto aiuto all'AI, ogni URL di DB condiviso per il debug, ogni token incollato per un one-liner

La cronologia degli agenti AI è il nuovo .bash_history — ma contiene contesto completo, non solo comandi. I tool degli attaccanti lo sanno già. agentsweep esiste per fare pulizia prima che venga sfruttato.

Avvio rapido

pip install uv                  # ottieni uv (salta se già lo hai)
uv tool install agentsweep      # installa — aggiunge `agentsweep` e `asweep` al PATH
asweep                          # esegui — il menu interattivo ti guida attraverso tutto

Tutto qui. Nessun virtualenv da attivare, nessun ritocco al PATH — uv tool install dà al comando il proprio ambiente isolato.

Come funziona

agentsweep esegue una pipeline fissa a 5 fasi. scan si ferma dopo la fase 3; fix continua fino all'oscuramento.

flowchart LR
    A("🔍 SCOPRI\nscansiona le directory di cronologia\nstream della lista dei file") --> B("⚡ SCANSIONA\npre-filtro Aho-Corasick\n191 regole regex + BIP-39")
    B --> C{"segreti\ntrovati?"}
    C -- "nessuno" --> D("✅ PULITO\nexit 0")
    C -- "trovati" --> E("📋 RISULTATI\nmostra report\nexit 1")
    E -. "solo scan" .-> F("⚠️ RUOTA\nchiavi ancora attive")
    E -- "digita OSCURA" --> G("✏️ OSCURA\nscrittura atomica · backup .bak\nvalidazione JSON post-scrittura")
    G --> H("🔑 RUOTA\nper provider\nlink di revoca")

    style A fill:#1e3a5f,color:#fff,stroke:#2d5986
    style B fill:#1e3a5f,color:#fff,stroke:#2d5986
    style C fill:#4a3728,color:#fff,stroke:#7a5c3f
    style D fill:#1a4731,color:#fff,stroke:#2d7a52
    style E fill:#4a3a1e,color:#fff,stroke:#7a6030
    style F fill:#4a2020,color:#fff,stroke:#8b3a3a
    style G fill:#1e3a5f,color:#fff,stroke:#2d5986
    style H fill:#2d1e4a,color:#fff,stroke:#5a3a8b

Ogni scrittura è protetta da 8 invarianti di sicurezza — sostituzione atomica, backup .bak obbligatorio, rifiuto dei link simbolici, barriere mtime/processo e validazione JSONL post-scrittura. agentsweep undo ripristina dai backup.

Installa

Consigliato — isolato, nessun conflitto di venv:

uv tool install agentsweep      # installazione singola
uv tool upgrade agentsweep      # aggiorna all'ultima versione

Prova senza installare (esegue sempre l'ultima versione):

uvx agentsweep@latest

Pip classico:

pip install agentsweep
pip install --upgrade agentsweep

Non hai uv? pip install uv o vedi astral.sh/uv. Richiede Python 3.11+.

Utilizzo

Modalità interattiva

Eseguilo senza argomenti in un terminale e ottieni l'esperienza completa — banner, menu numerato, conferme digitate prima di qualsiasi operazione distruttiva e undo con un tasto (ripristina i backup .bak). Qualsiasi scansione interattiva che trovi segreti termina con un'offerta di oscurarli sul posto (digita OSCURA per confermare):

agentsweep

Lo scripting non è influenzato: qualsiasi flag, o un flusso piped/redirected, salta il menu e si comporta esattamente come documentato sotto.

Verbi

La forma del flag legacy agentsweep --fix è ancora accettata e si comporta in modo identico a agentsweep fix.

Selezione della fonte

Scegli la cronologia di quale agente colpire con --source. Il valore predefinito è claude-code.

agentsweep scan --source claude-code          # ~/.claude/projects/ (predefinito)
agentsweep scan --source codex                # ~/.codex/sessions/
agentsweep scan --source opencode             # Archivio SQLite di OpenCode
agentsweep scan --source cursor               # Cronologia di Cursor
agentsweep scan --source windsurf             # Cronologia di Windsurf
agentsweep scan --source aider                # ~/.aider/
agentsweep scan --source cline                # Cronologia di Cline
agentsweep scan --source gemini-cli           # Cronologia di Gemini CLI
agentsweep scan --source continue-vscode      # Cronologia di Continue (VS Code)
agentsweep scan --source github-copilot-chat  # Cronologia di GitHub Copilot Chat
agentsweep scan --source openclaw             # ~/.openclaw/ di OpenClaw
agentsweep scan --source hermes               # ~/.hermes/state.db di Hermes Agent
agentsweep scan --source goose                # ~/.local/share/goose/ di Goose

Non sei sicuro di quali agenti hai installati? list-sources stampa ogni fonte supportata, la sua posizione della cronologia e se tale cronologia esiste su questa macchina — così sai quali valori di --source vale la pena scansionare. Non legge nulla e non scrive nulla.

agentsweep list-sources             # tutte le 29 fonti + quali sono su disco
agentsweep list-sources --detected  # solo quelle trovate su questa macchina
agentsweep list-sources --json      # leggibile da macchina (per script/CI)

Scansiona ogni agente registrato in un unico passaggio (risultati aggregati; l'oscuramento rimane per fonte):

agentsweep scan --all                 # tutte le fonti registrate
agentsweep scan --all --detected      # solo fonti con una root di cronologia su disco
agentsweep scan --all --json          # JSON aggregato (ogni risultato ha "source")
agentsweep scan --all --json -o out.json

Sovrascrivi la directory root predefinita per scansionare qualsiasi cartella arbitraria:

agentsweep scan --root ~/backups/claude-history
agentsweep fix  --root /tmp/history-copy --allow-production

Flag di scansione / fix

# JSON leggibile da macchina su stdout (exit 0 = pulito, 1 = risultati trovati, 2 = errore)
agentsweep scan --json

# Scrivi i risultati JSON in un file invece che su stdout
agentsweep scan --json -o findings.json
agentsweep scan --json --output /tmp/report.json

# Salta i file .agentsweepignore
agentsweep scan --no-ignore

Flag solo per fix

# Oscura la cronologia di Claude Code sul posto (--allow-production richiesto per le root predefinite durante l'alpha)
agentsweep fix --allow-production

# Salta la creazione di backup .bak (non consigliato)
agentsweep fix --allow-production --no-backup

# Bypassa i controlli di sicurezza soft: barriera mtime (file modificati <60 s fa) e barriera del processo in esecuzione
agentsweep fix --allow-production --force

# Combina: oscuramento in modalità JSON non interattiva contro una root personalizzata
agentsweep fix --root ~/history-copy --json

Flag di undo

# Annulla gli oscuramenti per una fonte specifica
agentsweep undo --source codex

# Annulla contro una root personalizzata
agentsweep undo --root ~/history-copy

Garanzie di prevenzione della corruzione

Un oscuratore che corrompe la tua cronologia è strettamente peggiore della perdita che sta risolvendo. agentsweep applica questi invarianti su ogni --fix:

1. L'oscuramento avviene su JSON analizzato, non su byte grezzi. I segreti vengono sostituiti come valori di stringa all'interno della struttura analizzata, poi re-serializzati. Il danno strutturale è impossibile per costruzione.
2. Scritture atomiche. Ogni riscrittura va: file temporaneo → fsync() → os.replace() sull'originale. Un crash in qualsiasi istante lascia o il file vecchio completo o il file nuovo completo — mai una scrittura incompleta.
3. Validazione post-scrittura. Prima di impegnare, il nuovo contenuto deve superare un controllo sensibile al formato: JSONL — ogni riga non vuota viene analizzata come JSON e il conteggio delle righe corrisponde all'originale; JSON come file intero — il documento viene analizzato; markdown/testo semplice — il conteggio delle righe corrisponde all'originale; SQLite — la copia riscritta supera PRAGMA integrity_check. Se il controllo fallisce, la scrittura viene annullata e l'originale rimane intatto.
4. Backup .bak predefinito. Creato leggibile solo dal proprietario (modalità 0600) poiché contiene i segreti pre-oscuramento; rifiuta di essere eseguito se un .bak esiste già (così i backup precedenti non possono essere sovrascritti).
5. Contenimento del percorso. Rifiuta qualsiasi destinazione che non si risolva all'interno di uno degli alberi di cronologia della fonte (ad esempio, la directory User di Windsurf e la sua ~/.codeium/windsurf/memories/).
6. Rifiuto dei link simbolici. Rifiuta i link simbolici completamente.
7. Rifiuta i file modificati negli ultimi 60 secondi (probabilmente una sessione attiva). sovrascrive.

Recupero

Ogni file oscurato ha un file .bak fratello con i byte originali. Il modo più semplice per annullare tutti gli oscuramenti per una fonte è:

agentsweep undo                        # annulla per Claude Code (predefinito)
agentsweep undo --source codex         # annulla per una fonte specifica
agentsweep undo --root ~/history-copy  # annulla contro una root personalizzata

Se devi ripristinare manualmente un singolo file (ad esempio, hai eliminato la fonte del comando undo):

mv session.jsonl.bak session.jsonl

I backup contengono gli originali pre-oscuramento — segreti in chiaro, quindi la pulizia non è finita finché le chiavi trapelate non vengono ruotate e i backup non vengono eliminati. Una volta ruotate:

agentsweep purge                       # elimina i backup di Claude Code (chiede prima)
agentsweep purge --source windsurf     # elimina i backup di una fonte specifica
agentsweep purge --yes                 # non interattivo (script / CI)

Cosa viene rilevato

191 pattern ad alta confidenza più un rilevatore di frasi seed crittografiche convalidato da checksum — mnemonici BIP-39 (12/15/18/21/24 parole; il formato portafoglio dietro BTC, ETH, SOL, BNB, ADA, DOGE, LTC, DOT, AVAX e praticamente ogni catena principale) e semi Electrum sono confermati crittograficamente (checksum BIP-39 / tag versione Electrum), quindi la prosa inglese che usa parole del portafoglio non genera mai falsi positivi.

I pattern: chiavi di accesso AWS, token GitHub (PAT/OAuth/App/granulari), Stripe live/test, OpenAI, Anthropic, Google API, Slack bot/user/webhook, Hugging Face, JWT, chiavi private PEM, URL di database con password incorporate, token npm/PyPI/SendGrid/Twilio — più 167 regole importate dal pacchetto gitleaks che coprono GitLab, Grafana, HashiCorp Vault/Terraform, DigitalOcean, Shopify, PlanetScale, Databricks, Atlassian, Azure AD, 1Password, Sentry, New Relic, Mailgun, Datadog, Twilio, Twitter/X, Twitch, Yandex, JFrog, Snyk, Mailchimp, credenziali curl sulla riga di comando e molte altre. I pattern sono ad alta precisione — i falsi positivi sono rari e le regole con contesto del provider sono bloccate da parole chiave, quindi gli incollaggi grandi rimangono veloci.

Cosa NON viene rilevato

• Segreti personalizzati/proprietari senza un prefisso riconoscibile.
• Frasi seed Monero (25 parole dalla propria wordlist di Monero — in programma).
• Token sconosciuti che sembrano base64 arbitrario.
• Segreti suddivisi in più messaggi.
• Qualsiasi cosa all'interno di un file binario/non UTF-8.

Per un rilevamento più approfondito, esegui gitleaks o trufflehog insieme ad agentsweep — i loro pacchetti di regole sono più esaustivi. Il valore di agentsweep è la superficie specifica della cronologia dell'agente, non il motore di rilevamento.

FAQ

Perché uvx agentsweep mostra una versione vecchia? uvx mette in cache i tool localmente. Usa uvx agentsweep@latest per eseguire sempre la versione più recente (consigliato), o forza un refresh della cache con uvx --reinstall agentsweep.

Dov'è OpenCode nel menu? Il supporto per OpenCode è stato aggiunto nella v0.1.1. Esegui pip install --upgrade agentsweep o uvx agentsweep@latest per ottenerlo.

agentsweep invia i miei dati da qualche parte? No. È completamente offline — zero chiamate di rete durante la scansione o l'oscuramento. L'unica chiamata di rete opzionale è il controllo di aggiornamento in background, che recupera solo il numero di versione più recente da PyPI.

Contributori

Grazie a tutti coloro che hanno contribuito con codice, segnalazioni di bug e idee.

Licenza

MIT. Vedi LICENSE.