Credactor

Finde das Geheimnis. Behebe es. Committe sauber.

Geheimnis-Scanner schlagen Alarm, helfen aber kaum beim Löschen. Sie übergeben eine Liste geleakter Zugangsdaten und überlassen dir die Bereinigung. Credactor schließt den Kreislauf: Es findet ein hartcodiertes Geheimnis und schreibt es direkt um, sodass ein Leck in einem einzigen Befehl von Erkennung zur Behebung gelangt.

Zugangsdaten aus dem Quellcode fernzuhalten, ist eine grundlegende Sicherheitspraxis, keine optionale. Credactor macht es günstig, diese Grundregel einzuhalten – auf deinem Rechner vor einem Commit oder in CI vor einem Merge. Nutze es allein oder zusammen mit den Scannern, denen du bereits vertraust.

# Credactor findet das hier:
db_password = "h8Tq2vKp9mRz4Wd"

# Standardmäßig wird das Geheimnis durch einen Sentinel ersetzt, der zur Laufzeit lautstark fehlschlägt:
db_password = "REDACTED_BY_CREDACTOR"

# Mit --replace-with env wird ein Verweis geschrieben, der aus der Umgebung liest:
db_password = os.environ["DB_PASSWORD"]

Das Schwärzen überschreibt Dateien in deinem Arbeitsverzeichnis. Falls ein Geheimnis bereits committed wurde, rotiere den Schlüssel und bereinige die Historie (z. B. mit git filter-repo). Das Überschreiben einer Datei ersetzt nicht das Widerrufen eines geleakten Zugangsdaten.

Warum Credactor

• Schwärzung, nicht nur Erkennung. Die meisten Scanner bleiben beim Fund stehen. Credactor ersetzt das Geheimnis direkt: ein lauter REDACTED_BY_CREDACTOR-Sentinel, der standardmäßig zur Laufzeit fehlschlägt, oder ein sprachspezifischer Umgebungsvariablen-Verweis (Python, JavaScript/TypeScript, Go, Java/Kotlin, Ruby, PHP und Shell) wie os.environ["KEY"]. Der Ersatz ist gültiger Code. Falls die Datei den passenden Import (z. B. import os) noch nicht enthält, wird er hinzugefügt.
• Standardmäßig sicher. Atomare Schreibvorgänge, automatische .bak-Backups, Schutz vor Symlink-Grenzen und Dateiberechtigungen sowie vollständige Maskierung von Geheimnissen in jeder Ausgabe. Falls ein sicheres Backup nicht geschrieben werden kann, überspringt Credactor die Datei, anstatt blind zu überschreiben, und ein Absturz während des Schreibvorgangs hinterlä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 entwickelt. SARIF-Ausgabe für GitHub Code Scanning, ein schreibgeschütztes --ci-Tor mit präzisen Exit-Codes, ein Pre-Commit-Hook (Beta) und die Aufnahme von Gitleaks- oder TruffleHog-Berichten (BETA, weitere folgen). 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 Funde, bevor du schwärzt. Fehlalarme sind möglich, und unter --fix-all wird ein Fehlalarm überschrieben. Unterdrücke bekannte sichere Werte mit # credactor:ignore oder einem Eintrag in .credactorignore.

credactor --dry-run .                 # scannen, nichts ändern
credactor .                           # scannen, dann interaktiv schwärzen (j/n pro Fund)
credactor --fix-all .                 # alles nach einer Bestätigung schwärzen
credactor --fix-all --yes .           # nicht-interaktiv schwärzen (CI / Skripte)
credactor --ci .                      # schreibgeschütztes Tor: Exit 1 bei Funden
credactor --replace-with env .        # Schwärzung durch Umgebungsvariablen-Verweise statt Sentinel

Pre-Commit-Hook (Beta)

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

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/rxb06/credactor
    rev: v2.5.0   # auf den neuesten Release-Tag festlegen
    hooks:
      - id: credactor

Erkennung

Credactor erkennt die Credential-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 markiert. Heuristische Detektoren (JWTs, Verbindungsstrings, Hex, Base64) müssen eine Entropie-Schwelle überschreiten. Eigenständige Hex- oder Base64-Werte werden nur markiert, wenn sie in Anführungszeichen stehen. Ein nicht in Anführungszeichen stehender hochentropischer Wert wird nur bei einer nach Credential benannten Variable erfasst, sodass Git-SHAs und Prüfsummen verschont bleiben. Die vollständigen Erkennungs- und Schweregradregeln findest du im Handbuch.

Credactors eigener Regelsatz ist enger als der eines dedizierten Scanners, und einige Provider-Formate (z. B. 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 verwende ihn eigenständig.

Mit einem anderen Scanner kombinieren, alles auf einmal schwärzen (BETA)

Credactor kann eigenständig arbeiten und wird in Kombination noch stärker. Führst du bereits Gitleaks oder TruffleHog aus? Übergib deren Bericht an Credactor, und es schwärzt die kombinierte Menge, dedupliziert gegenüber den eigenen Funden (bei Überschneidungen gewinnt der höhere Schweregrad). Ein einziger Behebungslauf deckt deinen Scan und den des anderen 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 Zielverzeichnis. Siehe die CI-Integrationsanleitung.

Weitere Funktionen

• Interaktive oder Batch-Schwärzung; eine benutzerdefinierte Ersatzzeichenkette über --replacement; --scan-history zum Scannen des Git-Commit-Verlaufs
• Sichere Backups: --secure-delete (Überschreiben und Entfernen der .bak-Datei; erhöht die Hürde gegen gelegentliche Wiederherstellung, keine forensische Garantie) oder --secure-backup-dir zum Speichern von Backups außerhalb des Repositorys
• Inline-# credactor:ignore und .credactorignore-Positivlisten (Globs, datei:zeile, Werte-Literale)
• Pro-Repo-Konfiguration über .credactor.toml
• 29 Quell-/Konfigurations-/Notiz-Dateitypen standardmäßig (inklusive .txt); --scan-json zum Einbeziehen von JSON; --fail-on-error, um bei einer nicht lesbaren Datei zu scheitern

Scannbare 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

Zusätzlich .env.* / .env-*-Varianten (.env.local, .env.production) sowie SSH-/Private-Key-Dateien (id_rsa, id_dsa, id_ecdsa, id_ed25519), alle nach Dateiname statt Erweiterung erkannt. JSON ist standardmäßig ausgeschlossen, da API-Antworten eine hohe Fehlalarmrate erzeugen; füge --scan-json hinzu, um es einzubeziehen. Eine direkt auf der Kommandozeile angegebene Datei wird auch dann gescannt, wenn ihre Erweiterung nicht in dieser Liste ist.

Exit-Codes

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.

• Keine Laufzeitabhängigkeiten. Eine Standardinstallation (pip install credactor) zieht keine Drittanbieter-Pakete nach sich (nur das optionale [encoding]-Extra), sodass zum Installationszeitpunkt nichts überprüft werden muss.
• Hash-pinned-Toolchain. CI- und Release-Builds installieren aus einer Lockfile mit --require-hashes, inklusive Build-Backend (python -m build --no-isolation gegen ein gepinntes setuptools), sodass eine manipulierte Abhängigkeit den Build scheitern lässt.
• Artefakte byteweise gegen Quellcode geprüft. Bei jedem Push und vor jeder Veröffentlichung vergleicht scripts/audit_wheel.py das Wheel und den Sdist Byte für Byte mit dem committed Quellcode (sha256 gegen git HEAD); jede hinzugefügte, fehlende oder veränderte Datei lässt das Tor zuschlagen, sodass kein Build-Schritt unbemerkt Code injizieren kann.
• SHA-gepinnte, minimale Berechtigungen in CI. GitHub-Actions-Pins 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.