rxb06/credactorScansiona. Oscura. Commit pulito.
[](https://pypi.org/project/credactor/)
[](https://github.com/rxb06/credactor/actions/workflows/ci.yml)
[](https://github.com/rxb06/credactor/blob/main/LICENSE)
# Credactor
**Trova il segreto. Correggilo. Esegui il commit pulito.**
Gli scanner di segreti sono bravi a lanciare l'allarme e non molto utili 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 di dati passa dal rilevamento alla correzione con un singolo comando.
<img alt="Credactor: scan, redact, commit clean" src="https://assets.kitploit.com/production/public/readmes/9024/3abc948c69d942141474c93431f182cf98a738ebbd43f94eef8f92fda2498f18.png" width="1280" height="320" />
Tenere le credenziali fuori dal codice sorgente è una pratica di sicurezza di base, non opzionale. Credactor rende quella base economica da mantenere, sulla tua macchina prima di un commit o in CI prima di un merge. Eseguilo da solo, o insieme agli scanner di cui ti fidi già.
```python
# Credactor finds this:
db_password = "h8Tq2vKp9mRz4Wd"
# By default it rewrites the secret as a sentinel that fails loudly at runtime:
db_password = "REDACTED_BY_CREDACTOR"
# With --replace-with env, it writes a reference that reads from the environment:
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 rilevamento.** La maggior parte degli scanner si ferma alla scoperta. Credactor sostituisce il segreto sul posto: un sentinella `REDACTED_BY_CREDACTOR` ben visibile che fallisce a runtime per impostazione predefinita, 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 per impostazione predefinita.** Scritture atomiche, backup `.bak` automatici, protezioni sui confini dei 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 invece di riscriverlo alla cieca, e un crash durante la scrittura lascia l'originale intatto.
- **Zero dipendenze a runtime.** Solo libreria standard di Python 3.11+, più un extra opzionale per le codifiche non UTF-8.
- **Progettato per la pipeline.** Output SARIF per GitHub Code Scanning, un gate `--ci` in sola lettura con codici di uscita precisi, un hook pre-commit e l'importazione dei report di Gitleaks, TruffleHog o Betterleaks. Rileva con lo scanner che già esegui, correggi con Credactor.
## Installazione
```bash
pip install credactor
```
Richiede Python 3.11+. Nessun'altra dipendenza. Funziona su Linux, macOS e
Windows (testato in CI su Linux e Windows).
Su macOS e Linux puoi installarlo con Homebrew:
```bash
brew install rxb06/tap/credactor
```
La formula installa in un proprio virtualenv e include l'extra opzionale
`[encoding]`, quindi un'installazione con Homebrew rileva i segreti anche nei file
non UTF-8. Un semplice `pip install credactor` omette quell'extra; aggiungilo con
`pip install 'credactor[encoding]'` se vuoi la stessa copertura.
Dal sorgente:
```bash
git clone https://github.com/rxb06/credactor.git
cd credactor
pip install -e .
```
`credactor` funziona poi da qualsiasi directory.
## Avvio rapido
> Esegui prima `--dry-run` e rivedi i risultati prima di redigere. I falsi positivi sono possibili, e con `--fix-all` un falso positivo viene riscritto. Sopprimi i valori noti come sicuri con `# credactor:ignore` o una voce in `.credactorignore`.
```bash
credactor --dry-run . # scan, change nothing
credactor . # scan, then redact interactively (y/n per finding)
credactor --fix-all . # redact everything after one confirmation
credactor --fix-all --yes . # redact non-interactively (CI / scripts)
credactor --ci . # read-only gate: exit 1 on findings
credactor --replace-with env . # redact to env-var references instead of the sentinel
```
### Hook pre-commit
> L'hook controlla solo il contenuto in stage, quindi un segreto già committato non
> viene segnalato di nuovo. Usa `credactor --scan-history .` per controllare ciò che è già nel repo.
```yaml
# .pre-commit-config.yaml
repos:
- repo: https://github.com/rxb06/credactor
rev: v2.7.4 # pin to the latest release tag
hooks:
- id: credactor
```
### GitHub Action
```yaml
- uses: rxb06/[email protected]
```
L'action passa sempre `--ci`, quindi segnala e fa da gate ma non riscrive mai il
checkout. I risultati fanno fallire lo step; imposta `fail-on-findings: false` per segnalare
senza fare da gate. Un errore fa fallire lo step in ogni caso.
Carica su Code Scanning invece di fallire sui risultati:
```yaml
- uses: rxb06/[email protected]
with:
format: sarif
upload-sarif: true
fail-on-findings: false
```
Il job necessita di `permissions: security-events: write` per il caricamento. Vedi la
[guida all'integrazione CI](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md#github-action) per ogni input,
inclusa l'importazione dei report di Gitleaks, TruffleHog e Betterleaks.
## Rilevamento
Credactor rileva i tipi di credenziali che trapelano più spesso e assegna a ciascuno una gravità per consentirti di fare triage a colpo d'occhio.
| Categoria | Esempi | Gravità |
|---|---|---|
| Chiavi di provider cloud | AWS (`AKIA…`), GCP (`AIza…`), Stripe (`sk_live_…`), Slack (`xoxb-…`) | Critica |
| Token di piattaforma | GitHub (`ghp_`, `github_pat_`), GitLab (`glpat-`), npm (`npm_`), PyPI (`pypi-`) | Critica |
| Chiavi private | Blocchi PEM (`-----BEGIN … PRIVATE KEY-----`) | Critica |
| JWT | Token a tre segmenti `eyJ…` | Alta |
| Stringhe di connessione | URL con credenziali inline (`scheme://user:pass@host`) | Alta |
| Variabili di credenziali | `password = "…"`, `api_key = "…"`, `secret_key = "…"` | Alta/Media/Bassa |
| Attributi XML | `<add key="Password" value="…" />` | Alta/Media/Bassa |
| Stringhe ad alta entropia | hex tra virgolette (32–64 caratteri) / Base64 (60+ caratteri) | Media/Bassa |
I token deterministici dei provider (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 non tra virgolette viene catturato solo su una variabile con nome di credenziale, il che risparmia gli SHA di git e i checksum. Per le regole complete di rilevamento e gravità, vedi il [Manuale](https://github.com/rxb06/credactor/blob/main/docs/manual.md#detection--severity).
> Il set di regole native di Credactor è più ristretto di quello di uno scanner dedicato, e alcuni formati di provider (ad esempio SendGrid, Twilio e i webhook di Slack) non vengono rilevati. Il suo punto di forza è la correzione: abbinalo a Gitleaks, TruffleHog o Betterleaks per il rilevamento più ampio, oppure eseguilo da solo.
## Abbinalo a un altro scanner, redigi tutto
Credactor è autonomo, e diventa più forte in compagnia. Esegui già Gitleaks, TruffleHog o Betterleaks? Passa il loro report a Credactor e redigerà l'insieme combinato, deduplicato rispetto ai propri risultati (in caso di sovrapposizione, vince la gravità più alta). Una sola passata di correzione copre la tua scansione e la loro:
```bash
gitleaks dir . -f json -r gitleaks.json
credactor --from-gitleaks gitleaks.json --fix-all --yes .
betterleaks dir . -f json -r betterleaks.json
credactor --from-betterleaks betterleaks.json --fix-all --yes .
```
`--from-gitleaks` / `--from-trufflehog` / `--from-betterleaks` (o una tabella `[ingest]` in `.credactor.toml`) richiedono una directory come target — punta Credactor alla stessa radice su cui è stato eseguito lo scanner. I percorsi dei report vengono risolti rispetto alla directory di lavoro, e un report è un'istantanea: rigeneralo dopo aver redatto o modificato l'albero. Vedi la [guida all'integrazione CI](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md).
## Altre funzionalità
- Redazione interattiva o in batch; una stringa di sostituzione personalizzata tramite `--replacement`; `--scan-history` per scansionare la cronologia dei commit di git
- Backup sicuri: `--secure-delete` (sovrascrive e rimuove il `.bak`; alza l'asticella contro il recupero casuale, non è una garanzia forense) o `--secure-backup-dir` per conservare i backup fuori dal repo
- Allowlist inline `# credactor:ignore` e `.credactorignore` (glob, `file:line`, valori letterali)
- Configurazione per repo tramite `.credactor.toml`
- 29 tipi di file sorgente/configurazione/note out of the box (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` `.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 abbinati per nome file anziché per estensione. JSON è escluso per impostazione predefinita 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
| Codice | Significato |
|---|---|
| `0` | Nessun risultato, o tutti risolti |
| `1` | Risultati non risolti |
| `2` | Errore (ad esempio: percorso errato, `--replacement` pericoloso, `--ci --fix-all`, un report di importazione mancante o non valido, o `--fail-on-error` con un file illeggibile) |
## Rafforzamento della supply chain
Uno strumento di sicurezza dovrebbe essere sicuro da installare, non solo sicuro da eseguire. La pipeline di build e rilascio di Credactor è rafforzata end to end; dettagli completi nel [documento sulla sicurezza](https://github.com/rxb06/credactor/blob/main/docs/security.md#supply-chain-hardening).
- **Zero dipendenze a runtime.** Un `pip install credactor` predefinito non tira dentro alcun pacchetto di terze parti (solo l'extra opzionale `[encoding]`), quindi non c'è nulla da verificare al momento dell'installazione.
- **Toolchain con hash bloccati.** Le build di CI e rilascio installano da un lockfile `--require-hashes`, incluso il backend di build (`python -m build --no-isolation` contro un setuptools bloccato), quindi una dipendenza manomessa fa fallire la build.
- **Artefatti verificati byte per byte rispetto al sorgente.** A ogni push e prima di ogni pubblicazione, `scripts/audit_wheel.py` confronta il 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 uno step di build non può iniettare codice inosservato.
- **CI con SHA bloccati e privilegi minimi.** Le GitHub Actions sono bloccate a SHA di commit, e i token dei workflow restano ristretti — `contents: read` per impostazione predefinita, `id-token: write` solo per il job di pubblicazione.
## Documentazione
| Documento | Descrizione |
|----------|-------------|
| [Guida all'installazione](https://github.com/rxb06/credactor/blob/main/docs/setup.md) | Installazione, configurazione, integrazione CI/CD |
| [Manuale](https://github.com/rxb06/credactor/blob/main/docs/manual.md) | Riferimento completo: ogni flag, modalità e combinazione, comportamento di sostituzione e backup, rilevamento e gravità, codici di uscita e limitazioni (comportamento verificato dai test) |
| [Esempi](https://github.com/rxb06/credactor/blob/main/docs/examples.md) | Workflow comuni con output |
| [Integrazione CI](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md) | Hook pre-commit, pipeline CI |
| [Sicurezza](https://github.com/rxb06/credactor/blob/main/docs/security.md) | Modello di minaccia, misure di rafforzamento, limitazioni note |
| [Changelog](https://github.com/rxb06/credactor/blob/main/CHANGELOG.md) | Cronologia delle versioni |
| [Contribuire](https://github.com/rxb06/credactor/blob/main/CONTRIBUTING.md) | Setup di sviluppo, stile del codice, processo PR |
| [Disclaimer](https://github.com/rxb06/credactor/blob/main/docs/DISCLAIMER.md) | Limitazioni, uso sicuro, garanzia |
## Licenza
Apache 2.0. Vedi [LICENSE](https://github.com/rxb06/credactor/blob/main/LICENSE).