Credactor

Trova il segreto. Correggilo. Commit pulito.

Gli scanner di segreti sono bravi a suonare l'allarme ma non aiutano molto a spegnerlo. Ti consegnano un elenco di credenziali compromesse e lasciano a te la pulizia. Credactor chiude il cerchio: trova un segreto hardcoded e lo riscrive sul posto, così una fuga passa dalla rilevazione alla correzione con un solo comando.

Tenere le credenziali fuori dal codice sorgente è una pratica di sicurezza di base, non opzionale. Credactor rende economico mantenere questa base, sulla tua macchina prima di un commit o in CI prima di un merge. Eseguilo da solo, oppure insieme agli scanner di cui già ti fidi.

# Credactor trova questo:
db_password = "h8Tq2vKp9mRz4Wd"

# Di default riscrive il segreto come un sentinella che fallisce rumorosamente a runtime:
db_password = "REDACTED_BY_CREDACTOR"

# Con --replace-with env, scrive un riferimento che legge dall'ambiente:
db_password = os.environ["DB_PASSWORD"]

La redazione riscrive i file nel tuo working tree. Se un segreto è già stato committato, ruota la chiave e ripulisci anche la cronologia (ad esempio con git filter-repo). Riscrivere un file non sostituisce la revoca di una credenziale compromessa.

Perché Credactor

• Redazione, non solo rilevazione. La maggior parte degli scanner si ferma al rilevamento. Credactor sostituisce il segreto sul posto: una sentinella rumorosa REDACTED_BY_CREDACTOR che fallisce a runtime di default, oppure un riferimento a variabile d'ambiente consapevole del linguaggio (Python, JavaScript/TypeScript, Go, Java/Kotlin, Ruby, PHP e shell) come os.environ["KEY"]. La sostituzione è codice valido. Se il file non include già l'import corrispondente (ad esempio import os), aggiungilo.
• Sicuro di default. Scritture atomiche, backup automatici .bak, protezioni sui symlink e sui permessi dei file, e mascheramento completo dei segreti in ogni output. Se non è possibile scrivere un backup sicuro, Credactor salta il file piuttosto che riscriverlo alla cieca, e un crash a metà scrittura lascia l'originale intatto.
• Zero dipendenze runtime. Libreria standard Python 3.11+ pura, più un extra opzionale per codifiche non UTF-8.
• Progettato per la pipeline. Output SARIF per GitHub Code Scanning, un gate --ci di sola lettura con codici di uscita precisi, un hook pre-commit (beta) e l'ingestione di report Gitleaks o TruffleHog. Rileva con Gitleaks o TruffleHog, correggi con Credactor.

Installazione

pip install credactor

Richiede Python 3.11+. Nessun'altra dipendenza. Funziona su Linux, macOS e Windows (testato in CI su Linux e Windows).

Dal sorgente:

git clone https://github.com/rxb06/credactor.git
cd credactor
pip install -e .

credactor funziona quindi da qualsiasi directory.

Avvio rapido

Esegui prima --dry-run e rivedi i risultati prima di redarre. Sono possibili falsi positivi, e con --fix-all un falso positivo viene riscritto. Sopprimi i valori noti come sicuri con # credactor:ignore o una voce .credactorignore.

credactor --dry-run .                 # scansiona, non modifica nulla
credactor .                           # scansiona, poi redige in modo interattivo (sì/no per ogni risultato)
credactor --fix-all .                 # redige tutto dopo una conferma
credactor --fix-all --yes .           # redige in modo non interattivo (CI / script)
credactor --ci .                      # gate di sola lettura: esce con 1 se ci sono risultati
credactor --replace-with env .        # redige con riferimenti a variabili d'ambiente invece della sentinella

Hook pre-commit (beta)

L'integrazione dell'hook è in beta. Esegui manualmente credactor --dry-run . prima di affidarti solo ad essa.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/rxb06/credactor
    rev: v2.6.0   # fissa il tag dell'ultima release
    hooks:
      - id: credactor

Rilevazione

Credactor rileva i tipi di credenziali che si perdono più spesso e assegna a ciascuno una gravità per un triage immediato.

I token provider deterministici (i prefissi sopra) vengono segnalati indipendentemente dall'entropia. I rilevatori euristici (JWT, stringhe di connessione, hex, Base64) devono superare una soglia di entropia. Hex o Base64 isolati vengono segnalati solo se tra virgolette. Un valore ad alta entropia senza virgolette viene rilevato solo su una variabile con nome di credenziale, il che risparmia gli SHA di git e i checksum. Per le regole complete di rilevazione e gravità, consulta il Manuale.

Il set di regole nativo di Credactor è più ristretto di quello di uno scanner dedicato, e alcuni formati provider (ad esempio SendGrid, Twilio e webhook Slack) non vengono rilevati. Il suo punto di forza è la correzione: abbinalo a Gitleaks o TruffleHog per la rilevazione più ampia, oppure eseguilo da solo.

Abbinalo a un altro scanner, redigi tutto

Credactor funziona da solo e diventa più forte in compagnia. Usi già Gitleaks o TruffleHog? Passa il loro report a Credactor e redige il set combinato, deduplicato rispetto ai propri risultati (in caso di sovrapposizione, vince la gravità più alta). Un solo passaggio di correzione copre la tua scansione e la loro:

gitleaks dir . -f json -r gitleaks.json
credactor --from-gitleaks gitleaks.json --fix-all --yes .

--from-gitleaks / --from-trufflehog (o una tabella [ingest] in .credactor.toml) richiedono una directory come destinazione — punta Credactor alla stessa radice su cui lo scanner ha operato. I percorsi dei report vengono risolti rispetto alla directory di lavoro, e un report è un'istantanea: rigeneralo dopo la redazione o la modifica dell'albero. Consulta la guida Integrazione CI.

Altre funzionalità

• Redazione interattiva o batch; una stringa di sostituzione personalizzata tramite --replacement; --scan-history per scansionare la cronologia dei commit git
• Backup sicuri: --secure-delete (sovrascrive e rimuove il .bak; alza l'asticella contro il recupero casuale, non è una garanzia forense) oppure --secure-backup-dir per archiviare i backup fuori dal repository
• Liste bianche inline # credactor:ignore e .credactorignore (glob, file:line, valori letterali)
• Configurazione per repository tramite .credactor.toml
• 29 tipi di file sorgente/config/note inclusi di default (.txt incluso); --scan-json per includere JSON; --fail-on-error per fallire quando un file non può essere letto

Tipi di file scansionati

.py .js .ts .jsx .tsx .sh .bash .env .cfg .ini .toml .yaml .yml .rb .go .java .php .cs .kt .tf .hcl .conf .config .properties .xml .pem .key .crt .txt

Più le varianti .env.* / .env-* (.env.local, .env.production) e i file SSH / chiave privata (id_rsa, id_dsa, id_ecdsa, id_ed25519), tutti individuati per nome file piuttosto che per estensione. JSON è escluso di default perché le risposte API producono un alto tasso di falsi positivi; aggiungi --scan-json per includerlo. Un file indicato direttamente sulla riga di comando viene scansionato anche se la sua estensione non è in questo elenco.

Codici di uscita

Hardening della supply chain

Uno strumento di sicurezza dovrebbe essere sicuro da installare, non solo da eseguire. La pipeline di build e release di Credactor è indurita da cima a fondo; dettagli completi nel documento Sicurezza.

• Zero dipendenze runtime. Un pip install credactor di default non tira dentro pacchetti di terze parti (solo l'extra opzionale [encoding]), quindi non c'è nulla da verificare al momento dell'installazione.
• Toolchain con hash fissati. CI e build di release installano da un lockfile --require-hashes, backend di build incluso (python -m build --no-isolation contro un setuptools fissato), così una dipendenza manomessa fa fallire la build.
• Artefatti verificati byte per byte contro il sorgente. A ogni push e prima di ogni pubblicazione, scripts/audit_wheel.py confronta la wheel e l'sdist con il sorgente committato byte per byte (sha256 vs git HEAD); qualsiasi file aggiunto, mancante o alterato fa fallire il gate, quindi un passaggio di build non può iniettare codice inosservato.
• CI con SHA fissati e privilegi minimi. GitHub Actions fissa i commit agli SHA, e i token dei workflow restano ristretti — contents: read di default, id-token: write solo per il job di pubblicazione.

Documentazione

Licenza

Apache 2.0. Vedi LICENSE.