Metadata-Version: 2.4
Name: secret-scanner-cl
Version: 1.0.2
Summary: Local-first CLI, pre-commit hook and MCP server for detecting hardcoded secrets.
Author: Kiara Zapana
License-Expression: MIT
Project-URL: Homepage, https://github.com/Kiara1616/secretscanner
Project-URL: Documentation, https://github.com/Kiara1616/secretscanner#readme
Project-URL: Repository, https://github.com/Kiara1616/secretscanner
Project-URL: Issues, https://github.com/Kiara1616/secretscanner/issues
Project-URL: Changelog, https://github.com/Kiara1616/secretscanner/blob/main/CHANGELOG.md
Keywords: security,secrets,devsecops,pre-commit,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: colorama<1,>=0.4.6
Requires-Dist: mcp<2,>=1.0.0
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: pytest-cov<8,>=5; extra == "dev"
Requires-Dist: ruff<1,>=0.8; extra == "dev"
Requires-Dist: twine<7,>=5; extra == "dev"
Dynamic: license-file

# SecretScanner

[![CI](https://github.com/Kiara1616/secretscanner/actions/workflows/ci.yml/badge.svg)](https://github.com/Kiara1616/secretscanner/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/secret-scanner-cl.svg)](https://pypi.org/project/secret-scanner-cl/)
[![Python](https://img.shields.io/pypi/pyversions/secret-scanner-cl.svg)](https://pypi.org/project/secret-scanner-cl/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Security policy](https://img.shields.io/badge/security-policy-green.svg)](SECURITY.md)

**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.

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

> [!IMPORTANT]
> SecretScanner está en fase beta. Sus hallazgos requieren revisión humana: puede producir falsos positivos y no reemplaza la rotación inmediata de una credencial expuesta.

## 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.
- **Multiplataforma:** compatible con Windows, Linux y macOS mediante Python 3.10 o posterior.

## Inicio rápido

Instala el paquete desde PyPI:

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

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

### Comandos

```bash
# 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
```

| Opción | Descripción |
| --- | --- |
| `--path PATH` | Archivo o directorio que se analizará. |
| `--output json` | Guarda los hallazgos en `output/report.json`. |
| `--output csv` | Guarda los hallazgos en `output/report.csv`. |
| `--verbose` | Muestra los archivos a medida que se procesan. |

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.

## Detectores incluidos

| Tipo | Severidad |
| --- | --- |
| Token de GitHub | Alta |
| AWS Access Key | Alta |
| API key genérica | Media |
| Contraseña hardcodeada | Alta |
| JSON Web Token | Alta |
| Token de Slack | Alta |
| Clave privada RSA | Alta |
| URL con credenciales | Media |

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:

```yaml
repos:
  - repo: https://github.com/Kiara1616/secretscanner
    rev: v1.0.2
    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`:

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

## Visual Studio Code

La extensión se encuentra en [`vscode-extension/`](vscode-extension/). Mientras se completa su publicación en Marketplace, puede generarse localmente:

```bash
pip install secret-scanner-cl
cd vscode-extension
npm ci
npm run package
```

Instala el archivo VSIX resultante desde **Extensions → ··· → Install from VSIX...**. El VSIX es un artefacto de release y no se almacena en Git.

## Desarrollo

```bash
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](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](SECURITY.md). Para preguntas de uso consulta [SUPPORT.md](SUPPORT.md).

## Estado del proyecto

La hoja de ruta inmediata incluye configuración por proyecto, allowlists, baseline, fingerprints, historial Git y salida SARIF. Consulta [CHANGELOG.md](CHANGELOG.md) para conocer los cambios publicados.

## Licencia

SecretScanner se distribuye bajo la [licencia MIT](LICENSE).
