
Escanea. Redacta. Haz commit limpio.
[](https://pypi.org/project/credactor/)
[](https://github.com/rxb06/credactor/actions/workflows/ci.yml)
[](https://github.com/rxb06/credactor/blob/main/LICENSE)
# Credactor
**Encuentra el secreto. Corrígelo. Haz commit limpio.**
La mayoría de los escáneres de secretos se detienen en la alerta: obtienes una lista de credenciales filtradas
y la limpieza corre de tu cuenta. Credactor encuentra secretos codificados directamente y los reescribe
en su lugar, de modo que una filtración en tu árbol de trabajo pasa de encontrada a corregida con un solo
comando. Se ejecuta en tu máquina, como hook de pre-commit o como puerta de CI, y también
puede corregir lo que encuentren Gitleaks, TruffleHog o Betterleaks.
<img alt="Credactor: escanea, redacta, haz commit limpio" 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 redacción limpia tu árbol de trabajo.** No revoca la credencial y
> no toca el historial de git. Si un secreto llegó a commitearse o compartirse, rótalo,
> y reescribe el historial si necesitas que desaparezca de allí también (por ejemplo con
> `git filter-repo`).
## Por qué Credactor
- **Corrige, no solo señala.** Cada hallazgo se reemplaza en su lugar con un
centinela, tu propio marcador o una búsqueda de variable de entorno en el propio
lenguaje del archivo.
- **Escrituras cuidadosas.** Cada edición se planifica en memoria, se respalda primero (modo
`0600`), se escribe en un archivo temporal y se renombra a su ubicación. Un archivo que cambió
durante la ejecución, una ruta que sale de la raíz de escaneo o un bloque de clave privada se
omite con una advertencia, y su hallazgo sigue reportándose.
- **Funciona con el escáner que ya ejecutas.** Aliméntalo con un informe de Gitleaks, TruffleHog o
Betterleaks y corrige sus hallazgos y los propios en una sola
pasada deduplicada.
- **Diseñado para pipelines.** Una puerta `--ci` de solo lectura con códigos de salida claros, SARIF
2.1.0 con ubicaciones de línea y columna para GitHub Code Scanning, una GitHub Action
y un hook de pre-commit. Los secretos se enmascaran en todos los formatos de informe, y la salida
de texto se limpia para que un archivo escaneado no pueda inyectar secuencias de escape o comandos
de flujo de trabajo de CI en tu terminal o registro.
- **Versiones verificadas contra su código fuente.** Biblioteca estándar pura de Python 3.11+ sin
dependencias en tiempo de ejecución. Antes de que una versión llegue a PyPI, cada
archivo de Credactor en el wheel y el sdist se compara byte por byte con el
código fuente etiquetado, y los metadatos del paquete deben coincidir con `pyproject.toml` (ver
[Endurecimiento de la cadena de suministro](#supply-chain-hardening)).
Dónde no es la herramienta adecuada por sí sola: sus reglas integradas cubren los
formatos de credenciales que se filtran con más frecuencia en lugar de cientos de proveedores, y
no comprueba si un secreto está activo. Una ejecución limpia significa que nada coincidió con
sus reglas, no que el código no contenga secretos. Combínalo con un escáner dedicado
para mayor amplitud (ver [Trae tu propio escáner](#bring-your-own-scanner)).
## Instalación
```bash
pip install credactor
```
Con [uv](https://docs.astral.sh/uv/), instálalo como herramienta o ejecútalo una vez
sin instalarlo:
```bash
uv tool install credactor
uvx credactor --dry-run .
```
O con Homebrew en macOS y Linux:
```bash
brew install rxb06/tap/credactor
```
Requiere Python 3.11 o superior. Probado en CI en Linux y Windows, Python 3.11 a
3.13. Para archivos en codificaciones distintas de UTF-8, Latin-1 o UTF-16 simple, añade
el extra opcional: `pip install 'credactor[encoding]'` o
`uv tool install 'credactor[encoding]'` (la fórmula de Homebrew lo incluye).
## Inicio rápido
**1. Observa lo que encuentra.** No se modifica nada.
```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]"
```
Los informes muestran solo los primeros cuatro caracteres de cada secreto.
**2. Corrígelos.** Revisa primero los hallazgos: `--fix-all` reescribe todos,
incluidos los falsos positivos. Para conservar uno, añade `# credactor:ignore` a su línea
(consulta [Suprimir falsos positivos](#suppress-false-positives)) o corrige
de forma interactiva y responde `n`. Antes de modificar cada archivo, se escribe
una copia `.bak` junto a él para que puedas deshacer los cambios.
```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
```
El modo Env escribe la búsqueda, no la importación: añade `import os` o el
equivalente de tu lenguaje si el archivo no lo tiene. En Windows Git Bash, ejecuta el modo interactivo
como `winpty credactor .`.
**3. Verifica, luego limpia las copias de seguridad.** Cada `.bak` todavía contiene el secreto
original, y Credactor nunca edita tu `.gitignore`, por lo que un simple `git add .`
lo prepararía para el commit.
```bash
diff config.py.bak config.py # check what changed
cp config.py.bak config.py # undo
```
Añade `*.bak` y `*.credactor.tmp` a `.gitignore` y elimina las copias de seguridad una vez
que estés conforme. Para mantener las copias de seguridad fuera del árbol desde el principio, pasa
`--secure-backup-dir DIR` (un directorio fuera del repositorio) en la ejecución de corrección.
`--secure-delete` borra cada copia de seguridad en su lugar, lo que deja a git como tu única
forma de deshacer.
## Comandos de un vistazo
| Comando | Qué hace | Modifica archivos |
|---|---|---|
| `credactor --dry-run .` | Informa de los hallazgos | No |
| `credactor .` | Revisa y corrige un hallazgo a la vez | Sí, con `y` |
| `credactor --fix-all .` | Corrige todos los hallazgos tras una confirmación | Sí |
| `credactor --ci .` | Barrera: sale con 1 si hay hallazgos | Nunca |
| `credactor --staged --ci .` | Barrera solo para lo que está en stage para el commit | Nunca |
| `credactor --scan-history .` | Escanea los últimos 100 commits que modifican archivos | Nunca |
| `credactor --ci -f sarif . > results.sarif` | SARIF 2.1.0 para Code Scanning | Nunca |
| `credactor --ci -f json . > findings.json` | Informe legible por máquina | Nunca |
Cada flag y combinación está en el
[Manual](https://github.com/rxb06/credactor/blob/main/docs/manual.md).
## Úsalo en pre-commit y CI
### Hook de 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
```
Cada `git commit` escanea entonces el contenido preparado y se bloquea si contiene una credencial. El hook nunca reescribe archivos. Requiere pre-commit 3.2.0 o superior; sin el framework, consulte el [hook independiente](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]
```
La Action siempre se ejecuta con `--ci`, por lo que nunca reescribe el checkout. Los hallazgos hacen fallar el paso, y también cualquier error. Para reportar a Code Scanning en lugar de fallar:
```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 [guía de integración con CI](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md)
enumera cada entrada y salida de la Action y cubre GitLab CI y pasos de shell simples.
## Usa tu propio escáner
¿Ya estás ejecutando Gitleaks, TruffleHog o Betterleaks? Pásale el informe a Credactor
y este corrige sus hallazgos junto con los propios, deduplicados (en caso de
duplicado, se conserva la severidad más alta). Previsualiza primero con `--dry-run`, igual que para
un escaneo nativo.
```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 .
```
Apunta Credactor al mismo directorio sobre el que se ejecutó el escáner y regenera el informe después de que el árbol cambie. Un informe contiene en texto plano cada secreto que encontró y no se escanea a sí mismo (`.json` requiere `--scan-json`), así que escríbelo fuera del repositorio o elimínalo después de la ejecución. Un hallazgo que Credactor no puede colocar de forma segura (sin un número de línea válido, una ruta bajo `.git`, un valor demasiado corto para coincidir por sí solo) permanece reportado y nunca se escribe. Los detalles y las versiones compatibles están en el
[Manual](https://github.com/rxb06/credactor/blob/main/docs/manual.md#external-scanner-ingestion).
## Qué detecta
| Categoría | Ejemplos | Severidad |
|---|---|---|
| Claves de nube y SaaS | AWS (`AKIA…`, `ASIA…`), GCP (`AIza…`), Stripe live (`sk_live_…`, `rk_live_…`), Slack (`xoxb-…`, `xoxp-…`) | Crítica |
| Tokens de plataforma | GitHub (`ghp_`, `gho_`, `ghs_`, `github_pat_`), GitLab (`glpat-`), npm (`npm_`), PyPI (`pypi-`) | Crítica |
| Claves privadas | Bloques PEM (`-----BEGIN … PRIVATE KEY-----`, incluidos los cifrados), bloques de clave privada PGP | Crítica |
| JWT | Tokens de tres segmentos `eyJ…` | Alta |
| Cadenas de conexión | URLs con credenciales en línea (`scheme://user:pass@host`) | Alta |
| Variables de credenciales | `password = "…"`, `api_key = "…"`, `secret_key = "…"` | Alta, Media o Baja |
| Atributos XML | `<add key="Password" value="…" />` | Alta, Media o Baja |
| Claves de prueba de Stripe | `sk_test_…` | Media |
| Cadenas de alta entropía | hex entre comillas (32 a 64 caracteres) o Base64 (60 o más) | Media o Baja |
Los tokens de proveedores se detectan por su formato, por lo que se encuentran incluso en comentarios y sea cual sea su aleatoriedad. Las coincidencias heurísticas también deben parecer suficientemente aleatorias, y un valor hex o Base64 sin más se reporta solo cuando está entre comillas o asignado a una variable con nombre de credencial, lo que evita los SHAs de git y las sumas de comprobación. Los marcadores de posición como `changeme`, las consultas al entorno y las referencias a plantillas no se marcan.
**Conviene saber:**
- **Las claves privadas se reportan, nunca se reescriben.** Rota la clave y elimina el bloque a mano; `--fix-all` lo cuenta como fallido.
- **El historial es de solo lectura y está limitado.** `--scan-history` cubre los 100 commits más recientes que modifican archivos, y advierte cuando el repositorio tiene más de 100 commits.
- **Se escanea un conjunto fijo de tipos de archivo**: 29 extensiones de código, configuración y texto, además de `.env.*` y archivos de claves SSH (`id_rsa` y similares). JSON requiere `--scan-json`, y cualquier otra cosa requiere `extra_extensions` en `.credactor.toml`. Un archivo que nombres directamente siempre se escanea.
- **Los archivos ignorados por git se omiten al recorrer un directorio**, y eso normalmente incluye un `.env` local. El informe de texto los lista, pero `-f json` y `-f sarif` no dicen nada sobre ellos. Para comprobar uno, nómbralo directamente:
`credactor --dry-run .env`.
- **Algunos formatos quedan fuera del alcance de forma nativa**, por ejemplo las claves de SendGrid y Twilio y los webhooks de Slack, al igual que los secretos construidos en tiempo de ejecución y los valores de menos de 8 caracteres.
Las reglas completas están en el
[Manual](https://github.com/rxb06/credactor/blob/main/docs/manual.md#detection--severity),
y el modelo de amenazas está en el
[documento de Seguridad](https://github.com/rxb06/credactor/blob/main/docs/security.md).
## Cómo reescribe
| `--replace-with` | Resultado | Úsalo cuando |
|---|---|---|
| `sentinel` (predeterminado) | `"REDACTED_BY_CREDACTOR"` | Quieras que cualquier cosa que aún use el secreto falle de forma ruidosa |
| `env` | `os.environ["DB_PASSWORD"]` | El valor deba provenir del entorno |
| `custom` | `"<tu marcador>"` mediante `--replacement` | Tengas tu propia convención |
El modo Env escribe la búsqueda en el lenguaje del archivo: `os.environ[…]` en Python,
`process.env[…]` en JavaScript y TypeScript, `ENV[…]` en Ruby, y la forma
nativa en Go, Java, Kotlin y PHP. Cualquier otro tipo de archivo recibe un
marcador de posición `${VAR}`, que es una búsqueda real solo donde algo lo expande (un script
de shell, un cargador de `.env`, muchas herramientas de configuración). En C# sigue siendo una cadena simple,
y en Terraform se lee como una referencia que no existe, por lo que la configuración
falla al validarse; usa el centinela para ambos. El nombre proviene del hallazgo:
`db_password` se convierte en `DB_PASSWORD`, y un tipo de token conocido recibe su propio nombre,
así que una clave de AWS se convierte en `AWS_ACCESS_KEY` sin importar cómo se llamara la variable. Donde
una búsqueda rompería el código (dentro de una cadena más grande, por ejemplo), se
usa el centinela en su lugar.
## Suprimir falsos positivos
En la propia línea, en un comentario `#`, `//`, `/* */` o `<!-- -->`:
```python
example_key = "AKIAIOSFODNN7EXAMPLE" # credactor:ignore
```
O en un `.credactorignore` en la raíz del escaneo:
```text
tests/fixtures/*
app/settings.py:42
```
Una entrada puede ser un glob, un `file:line` o un valor exacto. Un valor que contenga
`.`, `/`, `?` o `*` (una URL, un JWT, Base64) debe escribirse como
`value:<literal>`, o se interpreta como un glob y no tiene efecto. Los hallazgos de un
informe ingerido se filtran solo mediante `.credactorignore`: un
`credactor:ignore` en línea no los detiene. Los umbrales, los directorios omitidos y
los tipos de archivo adicionales se configuran en un
[`.credactor.toml`](https://github.com/rxb06/credactor/blob/main/docs/setup.md).
## Códigos de salida
| Código | Significado |
|---|---|
| `0` | Sin hallazgos, o todos ellos corregidos |
| `1` | Hallazgos sin resolver |
| `2` | Error, como una ruta incorrecta, una combinación de flags no válida, un informe ilegible o un `--config` explícito, o `--staged` / `--scan-history` fuera de un repositorio git |
Un hallazgo sin resolver nunca sale con 0. Un archivo que Credactor no pudo leer es solo una
advertencia de forma predeterminada, así que añade `--fail-on-error` a una compuerta que deba leer cada
archivo; entonces sale con 2. La lista completa está en el
[Manual](https://github.com/rxb06/credactor/blob/main/docs/manual.md#exit-codes).
## Endurecimiento de la cadena de suministro
Una herramienta que lee cada secreto de tu repositorio debería ser segura de instalar,
no solo segura de ejecutar. Varios paquetes populares han publicado versiones maliciosas
después de que un atacante entrara en su canal de compilación o publicación: una
dependencia de compilación manipulada, un token de carga robado o un archivo colado en el archivo
de la versión. El canal de publicación de Credactor tiene una comprobación específica para cada uno de esos casos.
- **Sin dependencias en tiempo de ejecución.** `pip install credactor` instala Credactor y
nada más (el extra opcional `[encoding]` añade `charset-normalizer`), por lo que
no hay código de terceros que auditar en el momento de la instalación.
- **Cada versión se verifica contra su código fuente.** En CI y de nuevo antes de
publicar, `scripts/audit_wheel.py` compara cada archivo del wheel y
sdist que proviene del repositorio byte a byte (sha256) con el
código fuente confirmado, y rechaza cualquier otra cosa aparte de los metadatos del paquete,
que deben coincidir con `pyproject.toml`. Un módulo adicional o alterado, una dependencia
inyectada, un comando redirigido o un archivo que está en el tarball pero no en
git hacen fallar la versión.
- **Compilaciones fijadas por hash.** Las compilaciones de CI y de versión instalan sus herramientas con
`pip install --require-hashes`, incluido el backend de compilación, de modo que una
dependencia manipulada hace fallar la compilación en lugar de llegar al paquete.
- **Sin token de carga en el canal.** Las versiones se publican en PyPI mediante
publicación de confianza OIDC desde un entorno `pypi` dedicado, con atestaciones de Sigstore,
y solo cuando la versión del paquete coincide con la etiqueta de la versión. El canal
no almacena ningún token de PyPI de larga duración.
- **CI bloqueada.** Cada GitHub Action está fijada a un SHA de commit, los tokens de los flujos de trabajo
son de solo lectura de forma predeterminada, los checkouts no conservan credenciales y Dependabot
propone actualizaciones mensualmente.
- **La Action se instala fuera de tu checkout.** La GitHub Action instala
Credactor desde el directorio temporal del runner con pip en modo aislado
(`python -I`), y luego ejecuta el comando instalado.
Estas comprobaciones demuestran que lo publicado coincide con el código fuente confirmado en la
etiqueta de la versión. No pueden hacer que ese código fuente sea confiable ni proteger una máquina de compilación
que ya esté comprometida; el
[documento de Seguridad](https://github.com/rxb06/credactor/blob/main/docs/security.md#supply-chain-hardening)
tiene todos los detalles y límites.
## Seguridad
Informa de una vulnerabilidad de forma privada a través de
[GitHub Security Advisories](https://github.com/rxb06/credactor/security/advisories/new),
no mediante un issue público. [SECURITY.md](https://github.com/rxb06/credactor/blob/main/SECURITY.md)
enumera las versiones compatibles, y el
[documento de Seguridad](https://github.com/rxb06/credactor/blob/main/docs/security.md)
cubre el modelo de amenazas, cada medida de endurecimiento y los límites conocidos.
## Documentación
| Documento | Qué contiene |
|---|---|
| [Manual](https://github.com/rxb06/credactor/blob/main/docs/manual.md) | Cada flag, modo y combinación, con comportamiento verificado |
| [Configuración](https://github.com/rxb06/credactor/blob/main/docs/setup.md) | Instalación y `.credactor.toml` |
| [Integración con CI](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md) | Pre-commit, la GitHub Action, otros sistemas de CI, ingesta |
| [Ejemplos](https://github.com/rxb06/credactor/blob/main/docs/examples.md) | Flujos de trabajo comunes con salida |
| [Seguridad](https://github.com/rxb06/credactor/blob/main/docs/security.md) | Modelo de amenazas, endurecimiento, límites conocidos |
| [Descargo de responsabilidad](https://github.com/rxb06/credactor/blob/main/docs/DISCLAIMER.md) | Uso seguro y garantía |
| [Registro de cambios](https://github.com/rxb06/credactor/blob/main/CHANGELOG.md) | Historial de versiones |
| [Contribuir](https://github.com/rxb06/credactor/blob/main/CONTRIBUTING.md) | Configuración de desarrollo y pull requests |
## Licencia
Apache 2.0. Consulte [LICENSE](https://github.com/rxb06/credactor/blob/main/LICENSE).