Credactor

Finde das Geheimnis. Behebe es. Committe sauber.

Secret-Scanner sind gut darin, Alarm zu schlagen, aber nicht besonders hilfreich beim Löschen des Feuers. Sie übergeben dir eine Liste durchgesickerter Zugangsdaten und überlassen dir die Bereinigung. Credactor schließt den Kreis: Es findet ein hartcodiertes Geheimnis und schreibt es direkt an Ort und Stelle neu, sodass ein Leck von der Erkennung bis zur Behebung mit einem einzigen Befehl geht.

Zugangsdaten aus dem Quellcode herauszuhalten ist eine grundlegende Sicherheitspraxis, keine optionale. Credactor macht diese Grundlage günstig einzuhalten – auf deinem Rechner vor einem Commit oder in CI vor einem Merge. Führe es eigenständig aus oder zusammen mit den Scannern, denen du bereits vertraust.

# Credactor findet das hier:
db_password = "h8Tq2vKp9mRz4Wd"

# Standardmäßig schreibt es das Geheimnis als Sentinel um, das zur Laufzeit laut scheitert:
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 Schwärzung schreibt Dateien in deinem Arbeitsbaum neu. Wenn ein Geheimnis bereits committet wurde, rotiere den Schlüssel und bereinige zusätzlich die Historie (zum Beispiel mit git filter-repo). Das Neuschreiben einer Datei ist kein Ersatz für das Widerrufen einer durchgesickerten Zugangsdaten.

Warum Credactor

• Schwärzung, nicht nur Erkennung. Die meisten Scanner hören beim Befund auf. Credactor ersetzt das Geheimnis direkt: ein lauter REDACTED_BY_CREDACTOR-Sentinel, der standardmäßig zur Laufzeit scheitert, oder eine sprachbewusste Umgebungsvariablen-Referenz (Python, JavaScript/TypeScript, Go, Java/Kotlin, Ruby, PHP und Shell) wie os.environ["KEY"]. Der Ersatz ist gültiger Code. Wenn die Datei den passenden Import (zum Beispiel import os) nicht bereits enthält, füge ihn hinzu.
• Standardmäßig sicher. Atomare Schreibvorgänge, automatische .bak-Backups, Schutzmechanismen für Symlink-Grenzen und Dateiberechtigungen sowie vollständige Maskierung von Geheimnissen in jeder Ausgabe. Wenn kein sicheres Backup geschrieben werden kann, überspringt Credactor die Datei, statt sie blind neu zu schreiben, und ein Absturz mitten im Schreibvorgang lässt das Original intakt.
• Null 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 (Beta) und die Aufnahme von Gitleaks- oder TruffleHog-Berichten. Erkenne mit Gitleaks oder TruffleHog, behebe mit Credactor.

Installation

pip install credactor

Erfordert Python 3.11+. Keine weiteren Abhängigkeiten. Läuft auf Linux, macOS und Windows (CI-getestet auf Linux und Windows).

Aus dem Quellcode:

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

credactor funktioniert dann von jedem Verzeichnis aus.

Schnellstart

Führe zuerst --dry-run aus und überprüfe die Befunde, bevor du schwärzt. Fehlalarme sind möglich, und unter --fix-all wird ein Fehlalarm neu geschrieben. Unterdrücke bekannte sichere Werte mit # credactor:ignore oder einem .credactorignore-Eintrag.

credactor --dry-run .                 # scannen, nichts ändern
credactor .                           # scannen, dann interaktiv schwärzen (j/n pro Befund)
credactor --fix-all .                 # alles nach einer Bestätigung schwärzen
credactor --fix-all --yes .           # nicht-interaktiv schwärzen (CI / Skripte)
credactor --ci .                      # schreibgeschütztes Gate: Exit 1 bei Befunden
credactor --replace-with env .        # zu Umgebungsvariablen-Referenzen statt Sentinel schwärzen

Pre-Commit-Hook (Beta)

Die Hook-Integration befindet sich in der Beta-Phase. Führe credactor --dry-run . manuell aus, bevor du dich allein darauf verlässt.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/rxb06/credactor
    rev: v2.6.0   # auf das neueste Release-Tag pinnen
    hooks:
      - id: credactor

Erkennung

Credactor erkennt die Zugangsdaten-Typen, die am häufigsten durchsickern, und weist jedem einen Schweregrad zu, damit du auf einen Blick priorisieren kannst.

Deterministische Provider-Tokens (die obigen Präfixe) werden unabhängig von der Entropie gekennzeichnet. Heuristische Detektoren (JWTs, Verbindungsstrings, Hex, Base64) müssen eine Entropie-Untergrenze überschreiten. Eigenständige Hex- oder Base64-Werte werden nur gekennzeichnet, wenn sie zitiert sind. Ein nicht zitierter Wert mit hoher Entropie wird nur bei einer Variable mit Zugangsdaten-Namen erfasst, was Git-SHAs und Prüfsummen verschont. Für die vollständigen Erkennungs- und Schweregradregeln siehe das Handbuch.

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 liegt in der Behebung: Kombiniere ihn mit Gitleaks oder TruffleHog für die breiteste Erkennung oder führe ihn eigenständig aus.

Mit einem anderen Scanner kombinieren, alles schwärzen

Credactor steht für sich allein und wird in Gesellschaft stärker. Läufst du bereits Gitleaks oder TruffleHog? Übergib ihren Bericht an Credactor, und es schwärzt die kombinierte Menge, dedupliziert gegen seine eigenen Befunde (bei Überschneidungen gewinnt der höhere Schweregrad). Ein einziger Behebungsdurchlauf deckt deinen Scan und ihren ab:

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

--from-gitleaks / --from-trufflehog (oder eine [ingest]-Tabelle in .credactor.toml) erfordern ein Verzeichnisziel – weise Credactor auf dieselbe Wurzel, gegen die der Scanner gelaufen ist. Berichtspfade werden relativ zum Arbeitsverzeichnis aufgelöst, und ein Bericht ist eine Momentaufnahme: Generiere ihn nach dem Schwärzen oder Ändern des Baums neu. Siehe den CI-Integrationsleitfaden.

Weitere Funktionen

• Interaktive oder Batch-Schwärzung; eine benutzerdefinierte Ersatzzeichenfolge über --replacement; --scan-history zum Scannen der Git-Commit-Historie
• Sichere Backups: --secure-delete (überschreibt und entfernt die .bak; erhöht die Hürde gegen beiläufige Wiederherstellung, keine forensische Garantie) oder --secure-backup-dir zum Speichern von Backups außerhalb des Repos
• Inline-# credactor:ignore- und .credactorignore-Allowlists (Globs, file:line, Wertliterale)
• Pro-Repo-Konfiguration über .credactor.toml
• 29 Quell-/Konfigurations-/Notizdateitypen standardmäßig (.txt inklusive); --scan-json zum Einbeziehen von JSON; --fail-on-error zum Scheitern, 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 nach Dateiname statt Erweiterung abgeglichen. JSON ist standardmäßig ausgeschlossen, da API-Antworten eine hohe Fehlalarmrate erzeugen; füge --scan-json hinzu, um es einzubeziehen. Eine direkt in der Befehlszeile benannte Datei wird gescannt, auch wenn ihre Erweiterung nicht in dieser Liste steht.

Exit-Codes

Härtung der Lieferkette

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.

• Null Laufzeitabhängigkeiten. Ein standardmäßiges pip install credactor zieht keine Drittanbieterpakete nach (nur das optionale [encoding]-Extra), sodass es zur Installationszeit nichts zu prüfen gibt.
• Hash-gepinnte Toolchain. CI- und Release-Builds installieren aus einer --require-hashes-Lockdatei, Build-Backend inklusive (python -m build --no-isolation gegen ein gepinntes setuptools), sodass eine manipulierte Abhängigkeit den Build scheitern lässt.
• Artefakte byteweise gegen den Quellcode 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 gegen git HEAD); jede hinzugefügte, fehlende oder veränderte Datei lässt das Gate scheitern, sodass ein Build-Schritt keinen Code unbemerkt einschleusen kann.
• SHA-gepinnte CI mit minimalen Rechten. GitHub Actions pinnen auf Commit-SHAs, und Workflow-Tokens bleiben eng – contents: read standardmäßig, id-token: write nur für den Publish-Job.

Dokumentation

Lizenz

Apache 2.0. Siehe LICENSE.