rxb06/credactorEscanea. 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.**
Los escáneres de secretos son buenos para dar la alarma y no ayudan mucho a apagarla. Te entregan una lista de credenciales filtradas y te dejan la limpieza a ti. Credactor cierra el ciclo: encuentra un secreto codificado y lo reescribe en su lugar, de modo que una filtración pasa de la detección a la corrección en un solo comando.
<img alt="Credactor: scan, redact, commit clean" src="https://assets.kitploit.com/production/public/readmes/9024/3abc948c69d942141474c93431f182cf98a738ebbd43f94eef8f92fda2498f18.png" width="1280" height="320" />
Mantener las credenciales fuera del código fuente es una práctica de seguridad básica, no opcional. Credactor hace que esa base sea barata de mantener, en tu máquina antes de un commit o en CI antes de un merge. Ejecútalo por sí solo, o junto a los escáneres en los que ya confías.
```python
# 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"]
```
> La redacción reescribe archivos en tu **árbol de trabajo**. Si un secreto ya se ha confirmado en un commit, rota la clave y limpia también el historial (por ejemplo, con `git filter-repo`). Reescribir un archivo no sustituye la revocación de una credencial filtrada.
---
## Por qué Credactor
- **Redacción, no solo detección.** La mayoría de los escáneres se detienen en el hallazgo. Credactor reemplaza el secreto en su lugar: un centinela `REDACTED_BY_CREDACTOR` que falla en tiempo de ejecución de forma predeterminada, o una referencia a variable de entorno consciente del lenguaje (Python, JavaScript/TypeScript, Go, Java/Kotlin, Ruby, PHP y shell) como `os.environ["KEY"]`. El reemplazo es código válido. Si el archivo aún no incluye la importación correspondiente (por ejemplo `import os`), añádela.
- **Seguro por defecto.** Escrituras atómicas, copias de seguridad `.bak` automáticas, protecciones de límites de enlaces simbólicos y permisos de archivo, y enmascaramiento completo de secretos en cada salida. Si no se puede escribir una copia de seguridad segura, Credactor omite el archivo en lugar de reescribirlo a ciegas, y un fallo a mitad de escritura deja el original intacto.
- **Cero dependencias en tiempo de ejecución.** Biblioteca estándar pura de Python 3.11+, más un extra opcional para codificaciones no UTF-8.
- **Diseñado para el pipeline.** Salida SARIF para GitHub Code Scanning, una puerta `--ci` de solo lectura con códigos de salida precisos, un hook de pre-commit e ingesta de informes de Gitleaks, TruffleHog o Betterleaks. Detecta con el escáner que ya ejecutas, remedia con Credactor.
## Instalación
```bash
pip install credactor
```
Requiere Python 3.11+. Sin otras dependencias. Funciona en Linux, macOS y
Windows (probado en CI en Linux y Windows).
En macOS y Linux puedes instalarlo con Homebrew en su lugar:
```bash
brew install rxb06/tap/credactor
```
La fórmula se instala en su propio virtualenv e incluye el extra opcional
`[encoding]`, por lo que una instalación con Homebrew también detecta secretos en archivos
no UTF-8. Un simple `pip install credactor` deja fuera ese extra; añádelo con
`pip install 'credactor[encoding]'` si quieres la misma cobertura.
Desde el código fuente:
```bash
git clone https://github.com/rxb06/credactor.git
cd credactor
pip install -e .
```
`credactor` entonces funciona desde cualquier directorio.
## Inicio rápido
> Ejecuta `--dry-run` primero y revisa los hallazgos antes de redactar. Los falsos positivos son posibles, y bajo `--fix-all` un falso positivo se reescribe. Suprime valores conocidos como seguros con `# credactor:ignore` o una entrada en `.credactorignore`.
```bash
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
```
### Hook de pre-commit
> El hook solo controla el contenido preparado, por lo que un secreto que ya está confirmado no se
> vuelve a marcar. Usa `credactor --scan-history .` para comprobar lo que ya está en el repositorio.
```yaml
# .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
```yaml
- uses: rxb06/[email protected]
```
La acción siempre pasa `--ci`, por lo que informa y controla pero nunca reescribe el
checkout. Los hallazgos hacen fallar el paso; establece `fail-on-findings: false` para informar
sin controlar. Un error hace fallar el paso de cualquier manera.
Sube a Code Scanning en lugar de fallar por hallazgos:
```yaml
- uses: rxb06/[email protected]
with:
format: sarif
upload-sarif: true
fail-on-findings: false
```
El job necesita `permissions: security-events: write` para la subida. Consulta la
[guía de integración de CI](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md#github-action) para cada entrada,
incluida la ingesta de informes de Gitleaks, TruffleHog y Betterleaks.
## Detección
Credactor detecta los tipos de credenciales que se filtran con más frecuencia y asigna a cada una una severidad para que puedas hacer triaje de un vistazo.
| Categoría | Ejemplos | Severidad |
|---|---|---|
| Claves de proveedores cloud | AWS (`AKIA…`), GCP (`AIza…`), Stripe (`sk_live_…`), Slack (`xoxb-…`) | Crítica |
| Tokens de plataformas | GitHub (`ghp_`, `github_pat_`), GitLab (`glpat-`), npm (`npm_`), PyPI (`pypi-`) | Crítica |
| Claves privadas | Bloques PEM (`-----BEGIN … PRIVATE KEY-----`) | 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/Baja |
| Atributos XML | `<add key="Password" value="…" />` | Alta/Media/Baja |
| Cadenas de alta entropía | hex entre comillas (32–64 caracteres) / Base64 (60+ caracteres) | Media/Baja |
Los tokens deterministas de proveedores (los prefijos anteriores) se marcan independientemente de la entropía. Los detectores heurísticos (JWT, cadenas de conexión, hex, Base64) deben superar un umbral de entropía. El hex o Base64 aislado se marca solo cuando está entre comillas. Un valor de alta entropía sin comillas solo se detecta en una variable con nombre de credencial, lo que evita los SHA de git y las sumas de comprobación. Para las reglas completas de detección y severidad, consulta el [Manual](https://github.com/rxb06/credactor/blob/main/docs/manual.md#detection--severity).
> El conjunto de reglas nativo de Credactor es más limitado que el de un escáner dedicado, y algunos formatos de proveedores (por ejemplo, SendGrid, Twilio y webhooks de Slack) no se detectan. Su ventaja es la remediación: combínalo con Gitleaks, TruffleHog o Betterleaks para la detección más amplia, o ejecútalo por sí solo.
## Combínalo con otro escáner, redacta todo
Credactor se sostiene por sí solo, y se vuelve más fuerte en compañía. ¿Ya ejecutas Gitleaks, TruffleHog o Betterleaks? Pasa su informe a Credactor y redacta el conjunto combinado, deduplicado contra sus propios hallazgos (en caso de solapamiento, gana la severidad más alta). Una sola pasada de remediación cubre tu escaneo y el suyo:
```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` (o una tabla `[ingest]` en `.credactor.toml`) requieren un objetivo de directorio: apunta Credactor a la misma raíz contra la que se ejecutó el escáner. Las rutas de los informes se resuelven contra el directorio de trabajo, y un informe es una instantánea: regenéralo después de redactar o cambiar el árbol. Consulta la [guía de integración de CI](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md).
## Más funciones
- Redacción interactiva o por lotes; una cadena de reemplazo personalizada mediante `--replacement`; `--scan-history` para escanear el historial de commits de git
- Copias de seguridad seguras: `--secure-delete` (sobrescribe y elimina el `.bak`; eleva el listón contra la recuperación casual, no es una garantía forense) o `--secure-backup-dir` para almacenar copias de seguridad fuera del repositorio
- Listas de permitidos en línea `# credactor:ignore` y `.credactorignore` (globs, `file:line`, literales de valor)
- Configuración por repositorio mediante `.credactor.toml`
- 29 tipos de archivos de código/configuración/notas listos para usar (incluido `.txt`); `--scan-json` para incluir JSON; `--fail-on-error` para fallar cuando un archivo no se puede leer
## Tipos de archivos escaneados
> `.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`
Además de las variantes `.env.*` / `.env-*` (`.env.local`, `.env.production`) y los archivos SSH / de clave privada (`id_rsa`, `id_dsa`, `id_ecdsa`, `id_ed25519`), todos coincidentes por nombre de archivo en lugar de extensión. JSON se excluye de forma predeterminada porque las respuestas de API producen una alta tasa de falsos positivos; añade `--scan-json` para incluirlo. Un archivo nombrado directamente en la línea de comandos se escanea aunque su extensión no esté en esta lista.
## Códigos de salida
| Código | Significado |
|---|---|
| `0` | Sin hallazgos, o todos resueltos |
| `1` | Hallazgos sin resolver |
| `2` | Error (por ejemplo: ruta incorrecta, `--replacement` peligroso, `--ci --fix-all`, un informe de ingesta ausente o inválido, o `--fail-on-error` con un archivo ilegible) |
## Endurecimiento de la cadena de suministro
Una herramienta de seguridad debería ser segura de instalar, no solo segura de ejecutar. El pipeline de compilación y publicación de Credactor está endurecido de extremo a extremo; todos los detalles en el [documento de Seguridad](https://github.com/rxb06/credactor/blob/main/docs/security.md#supply-chain-hardening).
- **Cero dependencias en tiempo de ejecución.** Un `pip install credactor` predeterminado no incorpora paquetes de terceros (solo el extra opcional `[encoding]`), por lo que no hay nada que verificar en el momento de la instalación.
- **Cadena de herramientas fijada por hash.** Las compilaciones de CI y de publicación se instalan desde un lockfile `--require-hashes`, incluido el backend de compilación (`python -m build --no-isolation` contra un setuptools fijado), por lo que una dependencia manipulada hace fallar la compilación.
- **Artefactos verificados byte a byte contra el código fuente.** En cada push y antes de cada publicación, `scripts/audit_wheel.py` compara el wheel y el sdist con el código fuente confirmado byte a byte (sha256 vs `git HEAD`); cualquier archivo añadido, faltante o alterado hace fallar la puerta, por lo que un paso de compilación no puede inyectar código sin ser detectado.
- **CI fijada por SHA y con privilegios mínimos.** Las GitHub Actions se fijan a SHAs de commit, y los tokens de los workflows se mantienen limitados: `contents: read` de forma predeterminada, `id-token: write` solo para el job de publicación.
## Documentación
| Documento | Descripción |
|----------|-------------|
| [Guía de configuración](https://github.com/rxb06/credactor/blob/main/docs/setup.md) | Instalación, configuración, integración CI/CD |
| [Manual](https://github.com/rxb06/credactor/blob/main/docs/manual.md) | Referencia completa: cada flag, modo y combinación, comportamiento de reemplazo y copia de seguridad, detección y severidad, códigos de salida y limitaciones (comportamiento verificado por pruebas) |
| [Ejemplos](https://github.com/rxb06/credactor/blob/main/docs/examples.md) | Flujos de trabajo comunes con salida |
| [Integración de CI](https://github.com/rxb06/credactor/blob/main/docs/ci_integration.md) | Hooks de pre-commit, pipelines de CI |
| [Seguridad](https://github.com/rxb06/credactor/blob/main/docs/security.md) | Modelo de amenazas, medidas de endurecimiento, limitaciones conocidas |
| [Changelog](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, estilo de código, proceso de PR |
| [Aviso legal](https://github.com/rxb06/credactor/blob/main/docs/DISCLAIMER.md) | Limitaciones, uso seguro, garantía |
## Licencia
Apache 2.0. Consulta [LICENSE](https://github.com/rxb06/credactor/blob/main/LICENSE).