Credactor

Encuentra el secreto. Corrígelo. Haz un commit limpio.

Los escáneres de secretos son buenos para hacer sonar la alarma, pero no ayudan mucho a apagarla. Te entregan una lista de credenciales filtradas y te dejan la limpieza a ti. Credactor cierra el círculo: encuentra un secreto hardcodeado y lo reescribe en su lugar, de modo que una filtración pasa de la detección a la corrección con un solo comando.

Mantener las credenciales fuera del código fuente es una práctica de seguridad básica, no opcional. Credactor hace que esa base sea fácil de mantener, en tu máquina antes de un commit o en CI antes de un merge. Ejecútalo por sí solo, o junto con los escáneres en los que ya confías.

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

El reemplazo reescribe archivos en tu árbol de trabajo. Si un secreto ya ha sido commiteado, rota la clave y depura también el historial (por ejemplo, con git filter-repo). Reescribir un archivo no es un sustituto de revocar una credencial filtrada.

Por qué Credactor

• Reemplazo, 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 de forma evidente en tiempo de ejecución por defecto, o una referencia a variable de entorno acorde al 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 no incluye ya 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 symlinks y de 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 de Python 3.11+ puro, más un extra opcional para codificaciones que no son UTF-8.

• Diseñado para el pipeline. Salida SARIF para GitHub Code Scanning, una compuerta de solo lectura --ci con códigos de salida precisos, un hook de pre-commit (beta) e ingesta de informes de Gitleaks o TruffleHog (BETA, con más en camino). Detecta con Gitleaks o TruffleHog, corrige con Credactor.

Instalación

pip install credactor

Requiere Python 3.11+. Sin otras dependencias. Funciona en Linux, macOS y Windows (probado en CI en Linux y Windows).

Desde el código fuente:

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

credactor funciona entonces desde cualquier directorio.

Inicio rápido

Ejecuta --dry-run primero y revisa los hallazgos antes de reemplazar. Los falsos positivos son posibles, y con --fix-all un falso positivo se reescribe. Suprime los valores conocidos como seguros con # credactor:ignore o una entrada en .credactorignore.

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 (beta)

La integración del hook está en beta. Ejecuta credactor --dry-run . manualmente antes de confiar solo en él.

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/rxb06/credactor
    rev: v2.5.0   # pin to the latest release tag
    hooks:
      - id: credactor

Detección

Credactor detecta los tipos de credenciales que más se filtran y asigna a cada uno una severidad para que puedas priorizar de un vistazo.

Los tokens de proveedor deterministas (los prefijos de arriba) se marcan independientemente de la entropía. Los detectores heurísticos (JWT, cadenas de conexión, hex, Base64) deben superar un umbral mínimo de entropía. El hex o Base64 independiente solo se marca 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 marcar los SHAs de git y las sumas de verificación. Para ver las reglas completas de detección y severidad, consulta el Manual.

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 los webhooks de Slack) no se detectan. Su punto fuerte es la remediación: combínalo con Gitleaks o TruffleHog para la detección más amplia, o ejecútalo por sí solo.

Combínalo con otro escáner, reemplaza todo el lote (BETA)

Credactor se sostiene por sí solo y se vuelve más fuerte en compañía. ¿Ya ejecutas Gitleaks o TruffleHog? Pasa su informe a Credactor y reemplazará el conjunto combinado, deduplicado frente a sus propios hallazgos (en caso de solapamiento, gana la mayor severidad). Una sola pasada de remediación cubre tu escaneo y el de ellos:

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

--from-gitleaks / --from-trufflehog (o una tabla [ingest] en .credactor.toml) requieren un directorio como destino. Consulta la guía de integración con CI.

Más funciones

• Reemplazo interactivo 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 frente a la recuperación casual, no es una garantía forense) o --secure-backup-dir para almacenar las copias de seguridad fuera del repositorio

• Listas de permitidos # credactor:ignore en línea y .credactorignore (globs, file:line, literales de valor)

• Configuración por repositorio mediante .credactor.toml

• 29 tipos de archivo de código/configuración/notas listos para usar (.txt incluido); --scan-json para incluir JSON; --fail-on-error para fallar cuando un archivo no se puede leer

Tipos de archivo 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

Más las variantes .env.* / .env-* (.env.local, .env.production) y los archivos SSH / de clave privada (id_rsa, id_dsa, id_ecdsa, id_ed25519), todos se reconocen por el nombre de archivo en lugar de por la extensión. JSON está excluido por defecto 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

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.

• Cero dependencias en tiempo de ejecución. Un pip install credactor por defecto no trae ningún paquete de terceros (solo el extra opcional [encoding]), por lo que no hay nada que auditar en el momento de la instalación.

• Cadena de herramientas fijada por hash. CI y las compilaciones de publicación se instalan desde un lockfile --require-hashes, backend de compilación incluido (python -m build --no-isolation contra un setuptools fijado), de modo 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 la wheel y el sdist con el código fuente commiteado byte a byte (sha256 vs git HEAD); cualquier archivo añadido, faltante o alterado hace fallar la compuerta, de modo que un paso de compilación no puede inyectar código sin que se note.

• CI fijado por SHA y con mínimos privilegios. GitHub Actions fijan los SHAs de commit, y los tokens de workflow se mantienen limitados — contents: read por defecto, id-token: write solo para el trabajo de publicación.

Documentación

Licencia

Apache 2.0. Consulta LICENSE.