rxb06/credactorScannen. Schwärzen. Sauber committen.
[](https://pypi.org/project/credactor/)
[](https://github.com/rxb06/credactor/actions/workflows/ci.yml)
[](https://github.com/rxb06/credactor/blob/main/LICENSE)
# Credactor
**Finde das Secret. Behebe es. Committe sauber.**
Secret-Scanner sind gut darin, Alarm zu schlagen, und wenig hilfreich beim Löschen desselben. Sie liefern dir eine Liste geleakter Zugangsdaten und überlassen dir die Aufräumarbeit. Credactor schließt den Kreis: Es findet ein fest codiertes Secret und schreibt es direkt an Ort und Stelle um, sodass aus einem Leak mit einem einzigen Befehl von der Erkennung zur Behebung wird.
<img alt="Credactor: scannen, redigieren, sauber committen" src="https://assets.kitploit.com/production/public/readmes/9024/3abc948c69d942141474c93431f182cf98a738ebbd43f94eef8f92fda2498f18.png" width="1280" height="320" />
Zugangsdaten aus dem Quellcode herauszuhalten ist eine grundlegende Sicherheitspraxis, keine optionale. Credactor macht es günstig, diese Grundlage einzuhalten – auf deiner Maschine vor einem Commit oder in der CI vor einem Merge. Führe es eigenständig aus oder zusammen mit den Scannern, denen du bereits vertraust.
```python
# Credactor findet dies:
db_password = "h8Tq2vKp9mRz4Wd"
# Standardmäßig schreibt es das Secret als Sentinel um, der zur Laufzeit laut fehlschlägt:
db_password = "REDACTED_BY_CREDACTOR"
# Mit --replace-with env schreibt es eine Referenz, die aus der Umgebung liest:
db_password = os.environ["DB_PASSWORD"]
```
> Die Redaktion schreibt Dateien in deinem **Arbeitsverzeichnis** um. Wenn ein Secret bereits committet wurde, rotiere den Schlüssel und bereinige zusätzlich die Historie (zum Beispiel mit `git filter-repo`). Das Umschreiben einer Datei ist kein Ersatz für das Widerrufen eines geleakten Zugangsdatums.
---
## Warum Credactor
- **Redaktion, nicht nur Erkennung.** Die meisten Scanner hören beim Fund auf. Credactor ersetzt das Secret direkt an Ort und Stelle: standardmäßig durch einen lauten `REDACTED_BY_CREDACTOR`-Sentinel, der zur Laufzeit fehlschlägt, oder durch eine sprachbewusste Umgebungsvariablen-Referenz (Python, JavaScript/TypeScript, Go, Java/Kotlin, Ruby, PHP und Shell) wie `os.environ["KEY"]`. Die Ersetzung ist gültiger Code. Wenn die Datei den passenden Import (zum Beispiel `import os`) noch nicht enthält, füge ihn hinzu.
- **Standardmäßig sicher.** Atomare Schreibvorgänge, automatische `.bak`-Backups, Schutz vor Symlink-Grenzen und Dateiberechtigungen sowie vollständige Maskierung von Secrets in jeder Ausgabe. Wenn kein sicheres Backup geschrieben werden kann, überspringt Credactor die Datei, statt sie blind umzuschreiben, und ein Absturz mitten im Schreibvorgang lässt das Original intakt.
- **Keine Laufzeitabhängigkeiten.** Reine Python-3.11+-Standardbibliothek, plus ein optionales Extra für Nicht-UTF-8-Kodierungen.
- **Für die Pipeline gebaut.** SARIF-Ausgabe für GitHub Code Scanning, ein schreibgeschütztes `--ci`-Gate mit präzisen Exit-Codes, ein Pre-Commit-Hook und die Einbindung von Gitleaks-, TruffleHog- oder Betterleaks-Berichten. Erkenne mit dem Scanner, den du bereits ausführst, behebe mit Credactor.
## Installation
```bash
pip install credactor
```
Erfordert Python 3.11+. Keine weiteren Abhängigkeiten. Läuft auf Linux, macOS und
Windows (CI-getestet auf Linux und Windows).
Auf macOS und Linux kannst du es stattdessen mit Homebrew installieren:
```bash
brew install rxb06/tap/credactor
```
Die Formel installiert in eine eigene virtuelle Umgebung und enthält das optionale
`[encoding]`-Extra, sodass eine Homebrew-Installation auch Secrets in Nicht-UTF-8-
Dateien erkennt. Ein einfaches `pip install credactor` lässt dieses Extra weg; füge es mit
`pip install 'credactor[encoding]'` hinzu, wenn du dieselbe Abdeckung möchtest.
Aus dem Quellcode:
```bash
git clone https://github.com/rxb06/credactor.git
cd credactor
pip install -e .
```
`credactor` funktioniert dann aus jedem Verzeichnis.
## Schnellstart
> Führe zuerst `--dry-run` aus und prüfe die Funde, bevor du redigierst. Falsch-Positive sind möglich, und unter `--fix-all` wird ein Falsch-Positiv umgeschrieben. Unterdrücke bekannt sichere Werte mit `# credactor:ignore` oder einem `.credactorignore`-Eintrag.
```bash
credactor --dry-run . # scannen, nichts ändern
credactor . # scannen, dann interaktiv redigieren (y/n pro Fund)
credactor --fix-all . # alles nach einer Bestätigung redigieren
credactor --fix-all --yes . # nicht-interaktiv redigieren (CI / Skripte)
credactor --ci . # schreibgeschütztes Gate: Exit 1 bei Funden
credactor --replace-with env . # zu Umgebungsvariablen-Referenzen statt zum Sentinel redigieren
```
### Pre-Commit-Hook
> Der Hook prüft nur gestagte Inhalte, sodass ein bereits committetes Secret nicht
> erneut gemeldet wird. Verwende `credactor --scan-history .`, um zu prüfen, was bereits im Repo ist.
```yaml
# .pre-commit-config.yaml
repos:
- repo: https://github.com/rxb06/credactor
rev: v2.7.4 # auf den neuesten Release-Tag pinnen
hooks:
- id: credactor
```
### GitHub Action
```yaml
- uses: rxb06/[email protected]
```
Die Action übergibt immer `--ci`, sodass sie meldet und gated, aber niemals den
Checkout umschreibt. Funde lassen den Schritt fehlschlagen; setze `fail-on-findings: false`, um
ohne Gate zu melden. Ein Fehler lässt den Schritt in jedem Fall fehlschlagen.
Statt bei Funden fehlzuschlagen, zu Code Scanning hochladen:
```yaml
- uses: rxb06/[email protected]
with:
format: sarif
upload-sarif: true
fail-on-findings: false
```
Der Job benötigt `permissions: security-events: write` für den Upload. Siehe den
[CI-Integrationsleitfaden](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md#github-action) für jeden Input,
einschließlich der Einbindung von Gitleaks-, TruffleHog- und Betterleaks-Berichten.
## Erkennung
Credactor erkennt die Zugangsdatentypen, die am häufigsten leaken, und weist jedem eine Schweregradstufe zu, damit du auf einen Blick triagieren kannst.
| Kategorie | Beispiele | Schweregrad |
|---|---|---|
| Cloud-Provider-Schlüssel | AWS (`AKIA…`), GCP (`AIza…`), Stripe (`sk_live_…`), Slack (`xoxb-…`) | Kritisch |
| Plattform-Token | GitHub (`ghp_`, `github_pat_`), GitLab (`glpat-`), npm (`npm_`), PyPI (`pypi-`) | Kritisch |
| Private Keys | PEM-Blöcke (`-----BEGIN … PRIVATE KEY-----`) | Kritisch |
| JWTs | `eyJ…` dreisegmentige Token | Hoch |
| Verbindungszeichenfolgen | URLs mit Inline-Zugangsdaten (`scheme://user:pass@host`) | Hoch |
| Zugangsdaten-Variablen | `password = "…"`, `api_key = "…"`, `secret_key = "…"` | Hoch/Mittel/Niedrig |
| XML-Attribute | `<add key="Password" value="…" />` | Hoch/Mittel/Niedrig |
| Strings mit hoher Entropie | in Anführungszeichen gesetztes Hex (32–64 Zeichen) / Base64 (60+ Zeichen) | Mittel/Niedrig |
Deterministische Provider-Token (die oben genannten Präfixe) werden unabhängig von der Entropie gemeldet. Heuristische Detektoren (JWTs, Verbindungszeichenfolgen, Hex, Base64) müssen eine Entropie-Untergrenze überschreiten. Eigenständiges Hex oder Base64 wird nur gemeldet, wenn es in Anführungszeichen steht. Ein nicht in Anführungszeichen gesetzter Wert mit hoher Entropie wird nur bei einer Variable mit Zugangsdaten-Namen erfasst, was git-SHAs und Prüfsummen verschont. Die vollständigen Erkennungs- und Schweregradregeln findest du im [Handbuch](https://github.com/rxb06/credactor/blob/main/docs/manual.md#detection--severity).
> Credactors nativer Regelsatz ist enger als der eines dedizierten Scanners, und einige Provider-Formate (zum Beispiel SendGrid, Twilio und Slack-Webhooks) werden nicht erkannt. Seine Stärke ist die Behebung: Kombiniere es mit Gitleaks, TruffleHog oder Betterleaks für die breiteste Erkennung, oder führe es eigenständig aus.
## Kombiniere es mit einem anderen Scanner und redigiere alles
Credactor steht für sich allein und wird in Gesellschaft stärker. Führst du bereits Gitleaks, TruffleHog oder Betterleaks aus? Übergib ihren Bericht an Credactor, und es redigiert die kombinierte Menge, dedupliziert gegen seine eigenen Funde (bei Überschneidung gewinnt der höhere Schweregrad). Ein Behebungsdurchlauf deckt deinen Scan und ihren ab:
```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` (oder eine `[ingest]`-Tabelle in `.credactor.toml`) erfordern ein Verzeichnisziel – richte Credactor auf dasselbe Root-Verzeichnis, gegen das der Scanner lief. Berichtspfade werden relativ zum Arbeitsverzeichnis aufgelöst, und ein Bericht ist eine Momentaufnahme: Generiere ihn nach dem Redigieren oder Ändern des Baums neu. Siehe den [CI-Integrationsleitfaden](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md).
## Weitere Funktionen
- Interaktive oder Batch-Redaktion; ein benutzerdefinierter Ersetzungsstring über `--replacement`; `--scan-history` zum Scannen der Git-Commit-Historie
- Sichere Backups: `--secure-delete` (überschreiben und die `.bak` entfernen; erhöht die Hürde gegen beiläufige Wiederherstellung, keine forensische Garantie) oder `--secure-backup-dir`, um Backups außerhalb des Repos zu speichern
- Inline-`# credactor:ignore`- und `.credactorignore`-Allowlists (Globs, `file:line`, Wert-Literale)
- Konfiguration pro Repo über `.credactor.toml`
- 29 Quell-/Konfig-/Notizdateitypen ab Werk (`.txt` inklusive); `--scan-json` zum Einbeziehen von JSON; `--fail-on-error`, um fehlzuschlagen, wenn eine Datei nicht gelesen werden kann
## Gescannte Dateitypen
> `.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`
Plus `.env.*`- / `.env-*`-Varianten (`.env.local`, `.env.production`) und SSH-/Private-Key-Dateien (`id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519`), alle über den Dateinamen statt über die Erweiterung abgeglichen. JSON ist standardmäßig ausgeschlossen, weil API-Antworten eine hohe Falsch-Positiv-Rate erzeugen; füge `--scan-json` hinzu, um es einzubeziehen. Eine direkt auf der Kommandozeile benannte Datei wird gescannt, auch wenn ihre Erweiterung nicht in dieser Liste steht.
## Exit-Codes
| Code | Bedeutung |
|---|---|
| `0` | Keine Funde oder alle behoben |
| `1` | Unbehobene Funde |
| `2` | Fehler (zum Beispiel: ungültiger Pfad, gefährliches `--replacement`, `--ci --fix-all`, ein fehlender oder ungültiger Ingestion-Bericht oder `--fail-on-error` bei einer unlesbaren Datei) |
## Supply-Chain-Härtung
Ein Sicherheitstool sollte sicher zu installieren sein, nicht nur sicher auszuführen. Credactors Build- und Release-Pipeline ist durchgängig gehärtet; vollständige Details im [Sicherheitsdokument](https://github.com/rxb06/credactor/blob/main/docs/security.md#supply-chain-hardening).
- **Keine Laufzeitabhängigkeiten.** Ein standardmäßiges `pip install credactor` zieht keine Drittanbieter-Pakete ein (nur das optionale `[encoding]`-Extra), sodass zur Installationszeit nichts zu prüfen ist.
- **Hash-gepinnte Toolchain.** CI- und Release-Builds installieren aus einer `--require-hashes`-Lockdatei, einschließlich Build-Backend (`python -m build --no-isolation` gegen ein gepinntes setuptools), sodass eine manipulierte Abhängigkeit den Build fehlschlagen lässt.
- **Artefakte byteweise gegen die Quelle geprüft.** Bei jedem Push und vor jeder Veröffentlichung vergleicht `scripts/audit_wheel.py` das Wheel und das sdist byteweise mit dem committeten Quellcode (sha256 vs. `git HEAD`); jede hinzugefügte, fehlende oder veränderte Datei lässt das Gate fehlschlagen, sodass ein Build-Schritt keinen Code unbemerkt einschleusen kann.
- **SHA-gepinnte CI mit minimalen Rechten.** GitHub Actions werden auf Commit-SHAs gepinnt, und Workflow-Token bleiben eng begrenzt – `contents: read` standardmäßig, `id-token: write` nur für den Publish-Job.
## Dokumentation
| Dokument | Beschreibung |
|----------|-------------|
| [Setup-Leitfaden](https://github.com/rxb06/credactor/blob/main/docs/setup.md) | Installation, Konfiguration, CI/CD-Integration |
| [Handbuch](https://github.com/rxb06/credactor/blob/main/docs/manual.md) | Vollständige Referenz: jedes Flag, jeder Modus und jede Kombination, Ersetzungs- und Backup-Verhalten, Erkennung und Schweregrad, Exit-Codes und Einschränkungen (Verhalten testverifiziert) |
| [Beispiele](https://github.com/rxb06/credactor/blob/main/docs/examples.md) | Häufige Workflows mit Ausgabe |
| [CI-Integration](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md) | Pre-Commit-Hooks, CI-Pipelines |
| [Sicherheit](https://github.com/rxb06/credactor/blob/main/docs/security.md) | Bedrohungsmodell, Härtungsmaßnahmen, bekannte Einschränkungen |
| [Changelog](https://github.com/rxb06/credactor/blob/main/CHANGELOG.md) | Versionshistorie |
| [Mitwirken](https://github.com/rxb06/credactor/blob/main/CONTRIBUTING.md) | Entwicklungsumgebung, Code-Stil, PR-Prozess |
| [Haftungsausschluss](https://github.com/rxb06/credactor/blob/main/docs/DISCLAIMER.md) | Einschränkungen, sichere Nutzung, Gewährleistung |
## Lizenz
Apache 2.0. Siehe [LICENSE](https://github.com/rxb06/credactor/blob/main/LICENSE).