Credactor

Encuentra el secreto. Arrégialo. Haz un commit limpio.

Los escáneres de secretos son buenos dando la alarma y de poca ayuda para apagarla. Te entregan una lista de credenciales filtradas y te dejan la limpieza a ti. Credactor cierra el ciclo: encuentra un secreto hardcodeado y lo reescribe en su lugar, de modo que una fuga pasa de la detección a la corrección en 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 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.

# Credactor encuentra esto:
db_password = "h8Tq2vKp9mRz4Wd"

# Por defecto reescribe el secreto como un centinela que falla ruidosamente en tiempo de ejecución:
db_password = "REDACTED_BY_CREDACTOR"

# Con --replace-with env, escribe una referencia que lee desde el entorno:
db_password = os.environ["DB_PASSWORD"]

La redacción reescribe archivos en tu árbol de trabajo. Si un secreto ya ha sido commiteado, rota la clave y limpia también el historial (por ejemplo, con git filter-repo). Reescribir un archivo no sustituye a revocar 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 ruidoso REDACTED_BY_CREDACTOR que falla en tiempo de ejecución por defecto, 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 no incluye ya el import correspondiente (por ejemplo import os), añádelo.
• Seguro por defecto. Escrituras atómicas, copias de seguridad .bak automáticas, protecciones de límites de symlinks y permisos de archivos, 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 no UTF-8.
• Diseñado para el pipeline. Salida SARIF para GitHub Code Scanning, una puerta de --ci de solo lectura con códigos de salida precisos, un hook de pre-commit (beta) e ingesta de informes de Gitleaks o TruffleHog. Detecta con Gitleaks o TruffleHog, remedia 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 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.

credactor --dry-run .                 # escanea, no cambia nada
credactor .                           # escanea y luego redacta interactivamente (sí/no por hallazgo)
credactor --fix-all .                 # redacta todo tras una confirmación
credactor --fix-all --yes .           # redacta de forma no interactiva (CI / scripts)
credactor --ci .                      # puerta de solo lectura: salida 1 si hay hallazgos
credactor --replace-with env .        # redacta a referencias de variables de entorno en lugar del centinela

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.6.0   # fija la etiqueta de la última versión
    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 hacer triaje de un vistazo.

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 independiente se marca solo cuando está entre comillas. Un valor de alta entropía sin comillas se detecta solo en una variable con nombre de credencial, lo que evita los SHAs de git y las sumas de verificación. Para 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, webhooks de SendGrid, Twilio y Slack) no se detectan. Su ventaja 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, redacta todo

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 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:

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: apunta Credactor a la misma raíz contra la que ejecutó el escáner. Las rutas del informe 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 con CI.

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 las 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 (.txt incluido); --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 archivos SSH / de claves privadas (id_rsa, id_dsa, id_ecdsa, id_ed25519), todos coincidentes por nombre de archivo en lugar de 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 incluso si su extensión no está en esta lista.

Códigos de salida

Endurecimiento de la cadena de suministro

Una herramienta de seguridad debe 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; detalles completos en el documento de Seguridad.

• Cero dependencias en tiempo de ejecución. Un pip install credactor por defecto no incorpora paquetes 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 con hashes fijados. 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), 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 puerta, de modo que un paso de compilación no puede inyectar código sin ser detectado.
• CI con SHA fijados y privilegios mínimos. GitHub Actions fija los SHAs de los commits, y los tokens de los flujos de trabajo 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.