Credactor

Trova il segreto. Risolvilo. Commit pulito.

Gli scanner di segreti sono bravi a suonare l'allarme, ma non aiutano molto a spegnerlo. Ti danno una lista di credenziali esposte e lasciano a te la pulizia. Credactor chiude il cerchio: trova un segreto hardcodato e lo riscrive sul posto, in modo che una fuga passi dalla rilevazione alla correzione in un unico comando.

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

# Credactor trova questo:
db_password = "h8Tq2vKp9mRz4Wd"

# Di default riscrive il segreto come una 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 la cronologia (ad esempio con git filter-repo). Riscrivere un file non sostituisce la revoca di una credenziale esposta.

Perché Credactor

• Redazione, non solo rilevazione. La maggior parte degli scanner si ferma alla scoperta. Credactor sostituisce il segreto sul posto: una sentinella rumorosa REDACTED_BY_CREDACTOR che fallisce a runtime di default, o 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 per impostazione predefinita. Scritture atomiche, backup automatici .bak, protezioni da symlink e permessi 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. Solo libreria standard Python 3.11+, con un extra opzionale per codifiche non UTF-8.
• Costruito per la pipeline. Output SARIF per GitHub Code Scanning, un gate --ci in sola lettura con codici di uscita precisi, un hook pre-commit (beta) e ingestione di report Gitleaks o TruffleHog (BETA, altri in arrivo). 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 redigere. Sono possibili falsi positivi, e con --fix-all un falso positivo viene riscritto. Sopprimi valori noti come sicuri con # credactor:ignore o una voce .credactorignore.

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

Hook pre-commit (beta)

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

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/rxb06/credactor
    rev: v2.5.0   # fissa al tag di release più recente
    hooks:
      - id: credactor

Rilevazione

Credactor rileva i tipi di credenziali che 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 standalone vengono segnalati solo se quotati. Un valore ad alta entropia non quotato viene rilevato solo su una variabile con nome di credenziale, risparmiando SHA git e 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, o eseguilo da solo.

Abbinalo a un altro scanner, redigi il lotto (BETA)

Credactor funziona da solo, e diventa più forte in compagnia. Usi già Gitleaks o TruffleHog? Passa il loro report a Credactor e redige l'insieme combinato, deduplicato rispetto ai propri risultati (in caso di sovrapposizione, vince la gravità maggiore). Un unico 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 di destinazione. Vedi la Guida all'integrazione CI.

Altre funzionalità

• Redazione interattiva o batch; 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 la barra contro il recupero occasionale, non una garanzia forense) o --secure-backup-dir per archiviare i backup fuori dal repository
• Liste bianche inline # credactor:ignore e .credactorignore (globbing, file:line, valori letterali)
• Configurazione per repository tramite .credactor.toml
• 29 tipi di file sorgente/config/note già pronti (incluso .txt); --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

Più varianti .env.* / .env-* (.env.local, .env.production) e file SSH/chiave privata (id_rsa, id_dsa, id_ecdsa, id_ed25519), tutti abbinati per nome file anziché 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 è nell'elenco.

Codici di uscita

Rafforzamento della supply chain

Uno strumento di sicurezza dovrebbe essere sicuro da installare, non solo da eseguire. La pipeline di build e rilascio di Credactor è rafforzata end-to-end; dettagli completi nel Documento sulla sicurezza.

• Zero dipendenze runtime. Una pip install credactor predefinita non installa 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 rilascio installano da un lockfile --require-hashes, incluso il backend di build (python -m build --no-isolation contro un setuptools fissato), quindi una dipendenza manomessa fa fallire la build.
• Artefatti verificati byte per byte contro il sorgente. Ad ogni push e prima di ogni pubblicazione, scripts/audit_wheel.py confronta la wheel e lo sdist con il sorgente committato byte per byte (sha256 rispetto a git HEAD); qualsiasi file aggiunto, mancante o alterato fa fallire il gate, quindi un passo di build non può iniettare codice inosservato.
• CI con SHA fissati e privilegi minimi. Le GitHub Actions fissano a commit SHA, e i token dei workflow rimangono stretti — contents: read di default, id-token: write solo per il job di pubblicazione.

Documenti

Licenza

Apache 2.0. Vedi LICENSE.