Credactor

Find the secret. Fix it. Commit clean.

Secret scanners are good at sounding the alarm and not much help putting it out. They hand you a list of leaked credentials and leave the cleanup to you. Credactor closes the loop: it finds a hardcoded secret and rewrites it in place, so a leak goes from detection to fix in a single command.

Keeping credentials out of source code is a baseline security practice, not an optional one. Credactor makes that baseline cheap to hold, on your machine before a commit or in CI before a merge. Run it on its own, or alongside the scanners you already trust.

# 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"]

Redaction rewrites files in your working tree. If a secret has already been committed, rotate the key and scrub history as well (for example, with git filter-repo). Rewriting a file is not a substitute for revoking a leaked credential.

---

Why Credactor

• Redaction, not just detection. Most scanners stop at the finding. Credactor replaces the secret in place: a loud REDACTED_BY_CREDACTOR sentinel that fails at runtime by default, or a language-aware environment-variable reference (Python, JavaScript/TypeScript, Go, Java/Kotlin, Ruby, PHP, and shell) such as os.environ["KEY"]. The replacement is valid code. If the file does not already include the matching import (for example import os), add it.
• Safe by default. Atomic writes, automatic .bak backups, symlink-boundary and file-permission guards, and full-secret masking in every output. If a safe backup cannot be written, Credactor skips the file rather than rewrite it blind, and a crash mid-write leaves the original intact.
• Zero runtime dependencies. Pure Python 3.11+ standard library, plus an optional extra for non-UTF-8 encodings.
• Built for the pipeline. SARIF output for GitHub Code Scanning, a read-only --ci gate with precise exit codes, a pre-commit hook, and ingestion of Gitleaks, TruffleHog or Betterleaks reports. Detect with the scanner you already run, remediate with Credactor.

Install

pip install credactor

Requires Python 3.11+. No other dependencies. Runs on Linux, macOS, and Windows (CI-tested on Linux and Windows).

On macOS and Linux you can install it with Homebrew instead:

brew install rxb06/tap/credactor

The formula installs into its own virtualenv and includes the optional [encoding] extra, so a Homebrew install also detects secrets in non-UTF-8 files. A plain pip install credactor leaves that extra out; add it with pip install 'credactor[encoding]' if you want the same coverage.

From source:

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

credactor then works from any directory.

Quick start

Run --dry-run first and review the findings before redacting. False positives are possible, and under --fix-all a false positive gets rewritten. Suppress known-safe values with # credactor:ignore or a .credactorignore entry.

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

Pre-commit hook

The hook gates staged content only, so a secret that is already committed is not re-flagged. Use credactor --scan-history . to check what is already in the repo.

# .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

- uses: rxb06/credactor@v2.7.4

The action always passes --ci, so it reports and gates but never rewrites the checkout. Findings fail the step; set fail-on-findings: false to report without gating. An error fails the step either way.

Upload to Code Scanning instead of failing on findings:

- uses: rxb06/credactor@v2.7.4
  with:
    format: sarif
    upload-sarif: true
    fail-on-findings: false

The job needs permissions: security-events: write for the upload. See the CI integration guide for every input, including ingestion of Gitleaks, TruffleHog and Betterleaks reports.

Detection

Credactor detects the credential types that leak most often, and assigns each a severity so you can triage at a glance.

Category	Examples	Severity
Cloud provider keys	AWS (AKIA…), GCP (AIza…), Stripe (sk_live_…), Slack (xoxb-…)	Critical
Platform tokens	GitHub (ghp_, github_pat_), GitLab (glpat-), npm (npm_), PyPI (pypi-)	Critical
Private keys	PEM blocks (-----BEGIN … PRIVATE KEY-----)	Critical
JWTs	eyJ… three-segment tokens	High
Connection strings	URLs with inline credentials (scheme://user:pass@host)	High
Credential variables	password = "…", api_key = "…", secret_key = "…"	High/Medium/Low
XML attributes	<add key="Password" value="…" />	High/Medium/Low
High-entropy strings	quoted hex (32–64 chars) / Base64 (60+ chars)	Medium/Low

Deterministic provider tokens (the prefixes above) are flagged regardless of entropy. Heuristic detectors (JWTs, connection strings, hex, Base64) must clear an entropy floor. Standalone hex or Base64 is flagged only when quoted. An unquoted high-entropy value is caught only on a credential-named variable, which spares git SHAs and checksums. For the full detection and severity rules, see the Manual.

Credactor's native rule set is narrower than a dedicated scanner's, and some provider formats (for example SendGrid, Twilio, and Slack webhooks) are not detected. Its edge is remediation: pair it with Gitleaks, TruffleHog or Betterleaks for the broadest detection, or run it on its own.

Pair it with another scanner, redact the lot

Credactor stands on its own, and it gets stronger in company. Already run Gitleaks, TruffleHog or Betterleaks? Pass their report to Credactor and it redacts the combined set, deduplicated against its own findings (on overlap, the higher severity wins). One remediation pass covers your scan and theirs:

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 (or an [ingest] table in .credactor.toml) require a directory target — point Credactor at the same root the scanner ran against. Report paths resolve against the working directory, and a report is a snapshot: regenerate it after redacting or changing the tree. See the CI Integration guide.

More features

• Interactive or batch redaction; a custom replacement string via --replacement; --scan-history to scan git commit history
• Secure backups: --secure-delete (overwrite and remove the .bak; raises the bar against casual recovery, not a forensic guarantee) or --secure-backup-dir to store backups outside the repo
• Inline # credactor:ignore and .credactorignore allowlists (globs, file:line, value literals)
• Per-repo config via .credactor.toml
• 29 source/config/notes file types out of the box (.txt included); --scan-json to include JSON; --fail-on-error to fail when a file cannot be read

Scanned file types

.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-* variants (.env.local, .env.production) and SSH / private-key files (id_rsa, id_dsa, id_ecdsa, id_ed25519), all matched by filename rather than extension. JSON is excluded by default because API responses produce a high false-positive rate; add --scan-json to include it. A file named directly on the command line is scanned even if its extension is not in this list.

Exit codes

Code	Meaning
0	No findings, or all resolved
1	Unresolved findings
2	Error (for example: bad path, dangerous --replacement, --ci --fix-all, a missing or invalid ingestion report, or --fail-on-error with an unreadable file)

Supply-chain hardening

A security tool should be safe to install, not only safe to run. Credactor's build and release pipeline is hardened end to end; full detail in the Security doc.

• Zero runtime dependencies. A default pip install credactor pulls in no third-party packages (only the optional [encoding] extra), so there is nothing to vet at install time.
• Hash-pinned toolchain. CI and release builds install from a --require-hashes lockfile, build backend included (python -m build --no-isolation against a pinned setuptools), so a tampered dependency fails the build.
• Artifacts byte-checked against source. On every push and before every publish, scripts/audit_wheel.py compares the wheel and sdist to the committed source byte for byte (sha256 vs git HEAD); any added, missing, or altered file fails the gate, so a build step cannot inject code unnoticed.
• SHA-pinned, least-privilege CI. GitHub Actions pin to commit SHAs, and workflow tokens stay narrow — contents: read by default, id-token: write only for the publish job.

Docs

Document	Description
Setup Guide	Installation, configuration, CI/CD integration
Manual	Complete reference: every flag, mode, and combination, replacement and backup behaviour, detection and severity, exit codes, and limitations (behaviour test-verified)
Examples	Common workflows with output
CI Integration	Pre-commit hooks, CI pipelines
Security	Threat model, hardening measures, known limitations
Changelog	Version history
Contributing	Development setup, code style, PR process
Disclaimer	Limitations, safe usage, warranty

Licence

Apache 2.0. See LICENSE.