
Scansiona. 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 in modo pulito.**
La maggior parte degli scanner di segreti si ferma all'avviso: ottieni un elenco di credenziali compromesse
e la pulizia spetta a te. Credactor trova i segreti hardcoded e li riscrive
sul posto, così una fuga nel tuo working tree passa da trovata a corretta con un solo
comando. Funziona sulla tua macchina, come hook pre-commit o come gate CI, e
può anche correggere ciò che Gitleaks, TruffleHog o Betterleaks trovano.
<img alt="Credactor: scansiona, oscura, esegui il commit in modo pulito" src="https://assets.kitploit.com/production/public/readmes/9024/3abc948c69d942141474c93431f182cf98a738ebbd43f94eef8f92fda2498f18.png" width="100%" />
```python
# Before
db_password = "h8Tq2vKp9mRz4Wd"
# credactor --fix-all . (default: a sentinel that fails loudly at runtime)
db_password = "REDACTED_BY_CREDACTOR"
# credactor --replace-with env --fix-all . (read it from the environment)
db_password = os.environ["DB_PASSWORD"]
```
> **La redazione ripulisce il tuo albero di lavoro.** Non revoca la credenziale e
> non tocca la cronologia git. Se un segreto è stato committato o condiviso, ruotalo,
> e riscrivi la cronologia se devi rimuoverlo anche da lì (ad esempio con
> `git filter-repo`).
## Perché Credactor
- **Corregge, non solo segnala.** Ogni rilevamento viene sostituito sul posto con un
sentinel, un tuo marcatore, o una lookup di variabile d'ambiente nel linguaggio
stesso del file.
- **Scritture accurate.** Ogni modifica è pianificata in memoria, salvata prima in backup (modalità
`0600`), scritta su un file temporaneo e rinominata nella posizione finale. Un file che è cambiato
durante l'esecuzione, un percorso che esce dalla radice della scansione, o un blocco di chiave privata viene
saltato con un avviso, e il suo rilevamento resta segnalato.
- **Funziona con lo scanner che già usi.** Passagli un report di Gitleaks, TruffleHog o
Betterleaks e corregge i loro rilevamenti e i propri in un'unica
passata deduplicata.
- **Pensato per le pipeline.** Un gate `--ci` in sola lettura con codici di uscita chiari, SARIF
2.1.0 con posizioni di riga e colonna per GitHub Code Scanning, una GitHub Action
e un hook pre-commit. I segreti sono mascherati in ogni formato di report, e l'output
testuale è ripulito così che un file scansionato non possa iniettare sequenze di escape o comandi
di workflow CI nel tuo terminale o nel log.
- **Release verificate rispetto al loro sorgente.** Libreria standard Python 3.11+ pura
senza dipendenze a runtime. Prima che una release raggiunga PyPI, ogni
file di Credactor nella wheel e nella sdist è confrontato byte per byte con il
sorgente taggato, e i metadati del pacchetto devono corrispondere a `pyproject.toml` (vedi
[Rafforzamento della supply chain](#supply-chain-hardening)).
Dove non è lo strumento giusto da solo: le sue regole integrate coprono i
formati di credenziali che trapelano più spesso piuttosto che centinaia di provider, e
non verifica se un segreto è attivo. Un'esecuzione pulita significa che nulla ha corrisposto
alle sue regole, non che il codice non contenga segreti. Abbinalo a uno scanner dedicato
per l'ampiezza (vedi [Porta il tuo scanner](#bring-your-own-scanner)).
## Installazione
```bash
pip install credactor
```
Con [uv](https://docs.astral.sh/uv/), installalo come strumento, oppure eseguilo una volta
senza installarlo:
```bash
uv tool install credactor
uvx credactor --dry-run .
```
Oppure con Homebrew su macOS e Linux:
```bash
brew install rxb06/tap/credactor
```
Richiede Python 3.11 o superiore. Testato in CI su Linux e Windows, da Python 3.11 a
3.13. Per file con codifiche diverse da UTF-8, Latin-1 o UTF-16 semplice, aggiungi
l'extra opzionale: `pip install 'credactor[encoding]'` o
`uv tool install 'credactor[encoding]'` (la formula Homebrew lo include).
## Avvio rapido
**1. Guarda cosa trova.** Nulla viene modificato.
```bash
credactor --dry-run .
```
```text
======================================================================
CREDENTIAL SCAN REPORT -- 2 finding(s) in 1 file(s)
======================================================================
FILE: config.py
────────────────────────────────────────────────────────────
Line 3 [HIGH] [variable:db_password]
db_password = "h8Tq[REDACTED]"
Line 4 [CRITICAL] [pattern:AWS access key]
aws_key = "AKIA[REDACTED]"
```
I report mostrano solo i primi quattro caratteri di ogni segreto.
**2. Correggili.** Esamina prima i risultati: `--fix-all` riscrive tutti, inclusi i falsi positivi. Per mantenerne uno, aggiungi `# credactor:ignore` alla sua riga
(vedi [Suppress false positives](#suppress-false-positives)) oppure correggi
in modo interattivo e rispondi `n`. Prima che ogni file venga modificato, viene scritta una copia `.bak`
accanto ad esso così puoi annullare.
```bash
credactor . # ask y/N for each finding (needs a terminal)
credactor --fix-all . # fix all after one confirmation
credactor --fix-all --yes . # fix all, no prompt (scripts)
credactor --replace-with env --fix-all . # environment lookups instead of the sentinel
```
La modalità Env scrive il lookup, non l'import: aggiungi `import os` o l'equivalente del tuo linguaggio se il file ne è privo. Su Windows Git Bash, esegui la modalità interattiva come `winpty credactor .`.
**3. Verifica, poi elimina i backup.** Ogni `.bak` contiene ancora il segreto originale, e Credactor non modifica mai il tuo `.gitignore`, quindi un semplice `git add .` lo metterebbe in staging.
```bash
diff config.py.bak config.py # check what changed
cp config.py.bak config.py # undo
```
Aggiungi `*.bak` e `*.credactor.tmp` a `.gitignore` ed elimina i backup una
volta soddisfatto. Per tenere i backup fuori dall'albero fin dall'inizio, passa
`--secure-backup-dir DIR` (una directory esterna al repository) durante l'esecuzione di correzione.
`--secure-delete` cancella invece ciascun backup, lasciando git come unica
possibilità di annullamento.
## Comandi in breve
| Comando | Cosa fa | Modifica i file |
|---|---|---|
| `credactor --dry-run .` | Segnala i risultati | No |
| `credactor .` | Rivedi e correggi un risultato alla volta | Sì, con `y` |
| `credactor --fix-all .` | Correggi ogni risultato dopo una conferma | Sì |
| `credactor --ci .` | Gate: esce con 1 in caso di risultati | Mai |
| `credactor --staged --ci .` | Gate solo su ciò che è in stage per il commit | Mai |
| `credactor --scan-history .` | Analizza gli ultimi 100 commit che modificano file | Mai |
| `credactor --ci -f sarif . > results.sarif` | SARIF 2.1.0 per Code Scanning | Mai |
| `credactor --ci -f json . > findings.json` | Report leggibile da macchina | Mai |
Ogni flag e combinazione è nel
[Manuale](https://github.com/rxb06/credactor/blob/main/docs/manual.md).
## Usalo in pre-commit e CI
### Hook pre-commit
```yaml
# .pre-commit-config.yaml
repos:
- repo: https://github.com/rxb06/credactor
rev: v2.7.5
hooks:
- id: credactor
```
```bash
pre-commit install
```
Ogni `git commit` esegue quindi la scansione del contenuto in staging e viene bloccato se contiene una
credenziale. L'hook non riscrive mai i file. Richiede pre-commit 3.2.0 o versione successiva;
senza il framework, consulta l'
[hook standalone](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md#standalone-git-hook).
### GitHub Action
```yaml
steps:
- uses: actions/checkout@v7
- uses: rxb06/[email protected]
```
L'Action viene sempre eseguita con `--ci`, quindi non riscrive mai il checkout. I risultati fanno fallire lo step, e lo stesso vale per qualsiasi errore. Per segnalare a Code Scanning invece di far fallire:
```yaml
permissions:
contents: read
security-events: write
steps:
- uses: actions/checkout@v7
- uses: rxb06/[email protected]
with:
format: sarif
upload-sarif: true
fail-on-findings: false
```
La [guida all'integrazione CI](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md)
elenca tutti gli input e gli output dell'Action e copre GitLab CI e i passaggi con shell semplice.
## Usa il tuo scanner
Stai già usando Gitleaks, TruffleHog o Betterleaks? Passa il report a Credactor
e questo correggerà le loro segnalazioni insieme alle proprie, deduplicate (in caso di
duplicato, viene mantenuta la severità più alta). Visualizza prima l'anteprima con `--dry-run`, come per
una scansione nativa.
```bash
gitleaks dir . -f json -r gl.json
credactor --from-gitleaks gl.json --fix-all --yes .
trufflehog filesystem . --no-verification --json > th.json
credactor --from-trufflehog th.json --fix-all --yes .
betterleaks dir . -f json -r bl.json
credactor --from-betterleaks bl.json --fix-all --yes .
```
Punta Credactor alla stessa directory su cui è stato eseguito lo scanner e rigenera il report dopo che l'albero è cambiato. Un report contiene ogni segreto trovato in chiaro e non viene scansionato esso stesso (`.json` richiede `--scan-json`), quindi scrivilo fuori dal repository o eliminalo dopo l'esecuzione. Un finding che Credactor non riesce a collocare in modo sicuro (nessun numero di riga valido, un percorso sotto `.git`, un valore troppo corto per essere confrontato da solo) resta segnalato e non viene mai scritto. I dettagli e le versioni supportate sono nel
[Manuale](https://github.com/rxb06/credactor/blob/main/docs/manual.md#external-scanner-ingestion).
## Cosa rileva
| Categoria | Esempi | Gravità |
|---|---|---|
| Chiavi cloud e SaaS | AWS (`AKIA…`, `ASIA…`), GCP (`AIza…`), Stripe live (`sk_live_…`, `rk_live_…`), Slack (`xoxb-…`, `xoxp-…`) | Critica |
| Token di piattaforma | GitHub (`ghp_`, `gho_`, `ghs_`, `github_pat_`), GitLab (`glpat-`), npm (`npm_`), PyPI (`pypi-`) | Critica |
| Chiavi private | Blocchi PEM (`-----BEGIN … PRIVATE KEY-----`, inclusi quelli cifrati), blocchi di chiavi private PGP | Critica |
| JWT | Token `eyJ…` a tre segmenti | Alta |
| Stringhe di connessione | URL con credenziali inline (`scheme://user:pass@host`) | Alta |
| Variabili di credenziali | `password = "…"`, `api_key = "…"`, `secret_key = "…"` | Alta, Media o Bassa |
| Attributi XML | `<add key="Password" value="…" />` | Alta, Media o Bassa |
| Chiavi di test Stripe | `sk_test_…` | Media |
| Stringhe ad alta entropia | hex tra virgolette (da 32 a 64 caratteri) o Base64 (60 o più) | Media o Bassa |
I token dei provider vengono confrontati in base al loro formato, quindi vengono trovati anche nei commenti e indipendentemente dalla loro casualità. Le corrispondenze euristiche devono anche sembrare sufficientemente casuali, e un valore hex o Base64 nudo viene segnalato solo quando è tra virgolette o assegnato a una variabile con nome di credenziale, il che risparmia gli SHA di git e i checksum. I segnaposto come `changeme`, le ricerche nell'ambiente e i riferimenti ai template non vengono segnalati.
**Da sapere:**
- **Le chiavi private vengono segnalate, mai riscritte.** Ruota la chiave ed elimina il blocco manualmente; `--fix-all` lo conta come fallito.
- **La cronologia è in sola lettura e limitata.** `--scan-history` copre i 100 commit più recenti che modificano file e avvisa quando il repository ha più di 100 commit.
- **Viene scansionato un insieme fisso di tipi di file**: 29 estensioni di codice, configurazione e testo più `.env.*` e i file di chiavi SSH (`id_rsa` e simili). JSON richiede `--scan-json`, e qualsiasi altro tipo richiede `extra_extensions` in `.credactor.toml`. Un file indicato direttamente viene sempre scansionato.
- **I file ignorati da git vengono saltati durante l'attraversamento di una directory**, e questo di solito include un `.env` locale. Il report testuale li elenca, ma `-f json` e `-f sarif` non ne dicono nulla. Per controllarne uno, indicalo direttamente:
`credactor --dry-run .env`.
- **Alcuni formati sono fuori ambito nativamente**, ad esempio le chiavi SendGrid e Twilio e i webhook Slack, così come i segreti costruiti a runtime e i valori sotto gli 8 caratteri.
Le regole complete sono nel
[Manuale](https://github.com/rxb06/credactor/blob/main/docs/manual.md#detection--severity),
e il modello di minaccia è nel
[documento Security](https://github.com/rxb06/credactor/blob/main/docs/security.md).
## Come riscrive
| `--replace-with` | Risultato | Usalo quando |
|---|---|---|
| `sentinel` (predefinito) | `"REDACTED_BY_CREDACTOR"` | Vuoi che qualsiasi cosa usi ancora il segreto fallisca in modo evidente |
| `env` | `os.environ["DB_PASSWORD"]` | Il valore dovrebbe provenire dall'ambiente |
| `custom` | `"<il tuo marcatore>"` tramite `--replacement` | Hai una tua convenzione |
La modalità Env scrive la lookup nella lingua del file: `os.environ[…]` in Python,
`process.env[…]` in JavaScript e TypeScript, `ENV[…]` in Ruby, e la forma
nativa in Go, Java, Kotlin e PHP. Ogni altro tipo di file riceve un segnaposto
`${VAR}`, che è una lookup reale solo dove qualcosa lo espande (uno script
shell, un loader `.env`, molti strumenti di configurazione). In C# rimane una
stringa semplice, e in Terraform viene letto come un riferimento che non esiste,
quindi la configurazione non supera la validazione; usa il sentinel per entrambi.
Il nome deriva dal finding: `db_password` diventa `DB_PASSWORD`, e un tipo di
token noto riceve il proprio nome, quindi una chiave AWS diventa `AWS_ACCESS_KEY`
indipendentemente da come si chiamava la variabile. Dove una lookup romperebbe
il codice (all'interno di una stringa più grande, ad esempio), viene usato
invece il sentinel.
## Sopprimere i falsi positivi
Sulla riga stessa, in un commento `#`, `//`, `/* */` o `<!-- -->`:
```python
example_key = "AKIAIOSFODNN7EXAMPLE" # credactor:ignore
```
Oppure in un file `.credactorignore` nella radice della scansione:
```text
tests/fixtures/*
app/settings.py:42
```
Una voce può essere un glob, un `file:line` o un valore esatto. Un valore che contiene
`.`, `/`, `?` o `*` (un URL, un JWT, Base64) deve essere scritto come
`value:<literal>`, altrimenti viene letto come un glob e non ha effetto. I risultati di un
report importato vengono filtrati solo da `.credactorignore`: un inline
`credactor:ignore` non li blocca. Le soglie, le directory saltate e i
tipi di file aggiuntivi vanno in un
[`.credactor.toml`](https://github.com/rxb06/credactor/blob/main/docs/setup.md).
## Codici di uscita
| Codice | Significato |
|---|---|
| `0` | Nessun risultato, o tutti risolti |
| `1` | Risultati rimasti irrisolti |
| `2` | Errore, come un percorso errato, una combinazione di flag non valida, un report illeggibile o un `--config` esplicito, oppure `--staged` / `--scan-history` al di fuori di un repository git |
Un risultato irrisolto non esce mai con 0. Un file che Credactor non è riuscito a leggere è solo un
avviso per impostazione predefinita, quindi aggiungi `--fail-on-error` a un gate che deve leggere ogni
file; in tal caso esce con 2. L'elenco completo è nel
[Manuale](https://github.com/rxb06/credactor/blob/main/docs/manual.md#exit-codes).
## Rafforzamento della supply chain
Uno strumento che legge ogni segreto nel tuo repository dovrebbe essere sicuro da installare,
non solo sicuro da eseguire. Diversi pacchetti popolari hanno distribuito release malevole
dopo che un attaccante è entrato nella loro pipeline di build o pubblicazione: una
dipendenza di build manomessa, un token di upload rubato o un file inserito nell'archivio
di release. La pipeline di release di Credactor ha un controllo specifico per ciascuno di questi casi.
- **Nessuna dipendenza a runtime.** `pip install credactor` installa Credactor e
nient'altro (l'extra opzionale `[encoding]` aggiunge `charset-normalizer`), quindi
non c'è codice di terze parti da verificare al momento dell'installazione.
- **Ogni release viene confrontata con il suo codice sorgente.** In CI e di nuovo prima della
pubblicazione, `scripts/audit_wheel.py` confronta ogni file nel wheel e
nello sdist che proviene dal repository byte per byte (sha256) con il
codice sorgente committato, e rifiuta qualsiasi altra cosa a parte i metadati del pacchetto,
che devono corrispondere a `pyproject.toml`. Un modulo aggiuntivo o alterato, una dipendenza
iniettata, un comando riassegnato o un file presente nel tarball ma non in
git fa fallire la release.
- **Build con hash bloccati.** Le build di CI e release installano i loro strumenti con
`pip install --require-hashes`, incluso il backend di build, così una dipendenza
manomessa fa fallire la build invece di raggiungere il pacchetto.
- **Nessun token di upload nella pipeline.** Le release vanno su PyPI tramite OIDC trusted
publishing da un ambiente `pypi` dedicato, con attestazioni Sigstore,
e solo quando la versione del pacchetto corrisponde al tag di release. La pipeline
non memorizza alcun token PyPI a lunga durata.
- **CI bloccata.** Ogni GitHub Action è fissata a uno SHA di commit, i token dei workflow
sono di sola lettura per impostazione predefinita, i checkout non mantengono credenziali e Dependabot
propone aggiornamenti mensilmente.
- **L'Action si installa al di fuori del tuo checkout.** La GitHub Action installa
Credactor dalla directory temporanea del runner con pip in modalità isolata
(`python -I`), quindi esegue il comando installato.
Questi controlli dimostrano che ciò che viene pubblicato corrisponde al codice sorgente committato al
tag di release. Non possono rendere quel codice sorgente affidabile né proteggere una macchina di build
già compromessa; il
[documento sulla Sicurezza](https://github.com/rxb06/credactor/blob/main/docs/security.md#supply-chain-hardening)
contiene tutti i dettagli e i limiti.
## Sicurezza
Segnala una vulnerabilità privatamente tramite
[GitHub Security Advisories](https://github.com/rxb06/credactor/security/advisories/new),
non con una issue pubblica. [SECURITY.md](https://github.com/rxb06/credactor/blob/main/SECURITY.md)
elenca le versioni supportate, e il
[documento sulla Sicurezza](https://github.com/rxb06/credactor/blob/main/docs/security.md)
copre il modello di minaccia, ogni misura di rafforzamento e i limiti noti.
## Documentazione
| Documento | Contenuto |
|---|---|
| [Manuale](https://github.com/rxb06/credactor/blob/main/docs/manual.md) | Ogni flag, modalità e combinazione, con comportamento verificato |
| [Configurazione](https://github.com/rxb06/credactor/blob/main/docs/setup.md) | Installazione e `.credactor.toml` |
| [Integrazione CI](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md) | Pre-commit, la GitHub Action, altri sistemi CI, ingestion |
| [Esempi](https://github.com/rxb06/credactor/blob/main/docs/examples.md) | Flussi di lavoro comuni con output |
| [Sicurezza](https://github.com/rxb06/credactor/blob/main/docs/security.md) | Modello di minaccia, hardening, limiti noti |
| [Disclaimer](https://github.com/rxb06/credactor/blob/main/docs/DISCLAIMER.md) | Utilizzo sicuro e garanzia |
| [Changelog](https://github.com/rxb06/credactor/blob/main/CHANGELOG.md) | Cronologia delle versioni |
| [Contribuire](https://github.com/rxb06/credactor/blob/main/CONTRIBUTING.md) | Configurazione per lo sviluppo e pull request |
## Licenza
Apache 2.0. Vedi [LICENSE](https://github.com/rxb06/credactor/blob/main/LICENSE).