SecretScanner

Detecta credenciales antes de que lleguen al repositorio. SecretScanner es un escáner local y de código abierto para encontrar secretos hardcodeados mediante CLI, pre-commit, MCP y Visual Studio Code.

$ secret-scanner --path .
[HIGH] GitHub Token · src/config.py:12
[!] 1 posible secreto encontrado

Por qué SecretScanner

• Local primero: el código y los hallazgos permanecen en tu equipo.
• Un motor, varios flujos: CLI, hook de Git, servidor MCP y extensión para VS Code.
• Listo para automatización: códigos de salida apropiados y reportes JSON o CSV.
• Políticas por proyecto: exclusiones, allowlists y baseline versionables.
• Privacidad verificable: cada hallazgo tiene un fingerprint sin almacenar el secreto.
• Multiplataforma: compatible con Windows, Linux y macOS mediante Python 3.10 o posterior.

Inicio rápido

Instala el paquete desde PyPI:

pip install secret-scanner-cl
secret-scanner --path .

También puedes mantenerlo aislado con pipx install secret-scanner-cl.

Comandos

# Analizar un archivo o directorio
secret-scanner --path ./mi-proyecto

# Exportar los hallazgos
secret-scanner --path . --output json
secret-scanner --path . --output csv

# Mostrar cada archivo procesado
secret-scanner --path . --verbose

# Crear un baseline con los hallazgos existentes
secret-scanner --path . --update-baseline

El proceso termina con código 1 si encuentra posibles secretos y 0 si no encuentra ninguno, por lo que puede utilizarse como control en CI.

Configuración por proyecto

Copia .secretscanner.example.toml como .secretscanner.toml en la raíz del proyecto:

[scan]
exclude_paths = ["vendor/**", "docs/generated/**"]

[allowlist]
paths = ["tests/fixtures/**"]
patterns = ["EXAMPLE_ONLY_[A-Z0-9]+"]
fingerprints = []

[baseline]
path = ".secretscanner-baseline.json"

La configuración más cercana al archivo analizado se descubre automáticamente. Las rutas utilizan / y aceptan patrones glob. Las expresiones de allowlist.patterns se evalúan sobre la línea completa; deben reservarse para valores de ejemplo deliberados.

Baseline y fingerprints

Cada hallazgo contiene un fingerprint SHA-256 derivado del tipo, la ruta relativa y el valor detectado. El valor original nunca se guarda en el fingerprint ni en el baseline.

Para adoptar SecretScanner en un proyecto con hallazgos conocidos:

secret-scanner --path . --update-baseline
git add .secretscanner-baseline.json

Los análisis posteriores ocultarán esos hallazgos y fallarán únicamente ante secretos nuevos. Revisa siempre el archivo antes de confirmarlo y no uses el baseline para aceptar credenciales reales: deben revocarse y eliminarse.

Detectores incluidos

El escáner omite .git, node_modules, entornos virtuales, artefactos de construcción y formatos binarios comunes.

Pre-commit

Añade el hook al archivo .pre-commit-config.yaml. Sustituye v1.0.2 por el release estable que quieras fijar:

repos:
  - repo: https://github.com/Kiara1616/secretscanner
    rev: v1.1.0
    hooks:
      - id: secret-scanner

Después ejecuta pre-commit install. El hook analiza el repositorio antes de permitir el commit.

MCP

El comando secret-scanner-mcp expone el escáner mediante transporte estándar stdio:

{
  "mcpServers": {
    "secret-scanner": {
      "command": "secret-scanner-mcp",
      "args": []
    }
  }
}

Visual Studio Code

Instala SecretScanner desde Visual Studio Marketplace o ejecuta:

code --install-extension kiara.secret-scanner-pr

La extensión utiliza la CLI local, por lo que también debes instalar el paquete de Python:

pip install secret-scanner-cl

Para generar un VSIX durante el desarrollo:

cd vscode-extension
npm ci
npm run package

Desarrollo

git clone https://github.com/Kiara1616/secretscanner.git
cd secretscanner
python -m venv .venv
python -m pip install -e ".[dev]"
pytest
ruff check .

La matriz de CI valida Python 3.10–3.13, cobertura mínima de 80 %, estilo, compilación de la extensión y distribuciones para PyPI. Consulta CONTRIBUTING.md antes de enviar cambios.

Seguridad y soporte

No publiques credenciales reales en issues, ejemplos ni reportes. Las vulnerabilidades deben comunicarse en privado siguiendo SECURITY.md. Para preguntas de uso consulta SUPPORT.md.

Estado del proyecto

La hoja de ruta inmediata incluye historial Git, detección por entropía y salida SARIF. Consulta CHANGELOG.md para conocer los cambios publicados.

Licencia

SecretScanner se distribuye bajo la licencia MIT.