Metadata-Version: 2.4
Name: security-pr-guardian
Version: 0.1.0
Summary: CLI tool that analyzes Pull Requests combining SAST, CVE scanning, and LLM reasoning to filter false positives before reporting.
Author: Security PR Guardian Team
License: MIT
Project-URL: Homepage, https://github.com/security-pr-guardian/security-pr-guardian
Project-URL: Repository, https://github.com/security-pr-guardian/security-pr-guardian
Keywords: security,pull-request,sast,cve,llm,code-review
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: pydantic<3,>=2.7.2
Requires-Dist: pydantic-settings<3,>=2.5.2
Requires-Dist: click==8.1.7
Requires-Dist: rich==13.7.1
Requires-Dist: httpx<1,>=0.27.1
Requires-Dist: boto3==1.34.110
Requires-Dist: anthropic==0.28.0
Requires-Dist: mcp==1.9.4
Requires-Dist: chromadb<0.6.0,>=0.5.23
Requires-Dist: sentence-transformers==3.0.1
Requires-Dist: jinja2==3.1.4
Requires-Dist: pyyaml==6.0.1
Provides-Extra: dev
Requires-Dist: pytest==8.2.2; extra == "dev"
Requires-Dist: pytest-asyncio==0.23.7; extra == "dev"
Requires-Dist: pytest-cov==5.0.0; extra == "dev"
Requires-Dist: pytest-httpx==0.30.0; extra == "dev"
Requires-Dist: hypothesis==6.103.1; extra == "dev"
Requires-Dist: moto==5.0.9; extra == "dev"

# Security PR Guardian

Herramienta CLI y GitHub Action que analiza Pull Requests combinando **SAST** (análisis estático con regex sobre 7 CWEs), **escaneo de CVEs** vía OSV.dev, **RAG** sobre una base de conocimiento OWASP/CWE, y **razonamiento LLM** vía Amazon Bedrock para filtrar falsos positivos antes de publicar un comentario estructurado en el PR.

## Requisitos previos

- Python 3.11+
- Cuenta AWS con acceso a Amazon Bedrock y el modelo habilitado en tu región
- Token de GitHub con permisos `repo` (lectura) y `pull-requests` (escritura)

## Instalación

```bash
pip install security-pr-guardian
```

## Configuración

### Variables de entorno obligatorias

```bash
export GITHUB_TOKEN=ghp_...              # Token GitHub
export BEDROCK_REGION=us-east-1          # Región AWS de Bedrock
export BEDROCK_MODEL_ID=anthropic.claude-sonnet-4-20250514-v1:0
```

Copia `.env.example` como `.env` y rellena los valores:

```bash
cp .env.example .env
```

### Configuración opcional (`config.yaml`)

```yaml
# config.yaml — opcional, en la raíz del proyecto
llm_backend: bedrock       # "bedrock" (default) | "anthropic"
osv_timeout_seconds: 10    # Timeout para OSV.dev (1-300)
max_diff_lines: 10000      # Máximo de líneas del diff a analizar
max_dependencies: 50       # Máximo de dependencias a escanear
```

## Uso

### Analizar un PR

```bash
security-guardian check --repo owner/repo --pr 42
```

Con opciones adicionales:

```bash
# Modo dry-run — no publica comentario en el PR
security-guardian check --repo owner/repo --pr 42 --no-comment

# Salida en JSON (útil para integración con otras herramientas)
security-guardian check --repo owner/repo --pr 42 --output json
```

### Códigos de salida

| Código | Significado |
|--------|-------------|
| `0` | Análisis completado, sin vulnerabilidades explotables |
| `1` | Análisis completado, al menos una vulnerabilidad explotable encontrada |
| `2` | Error de configuración o argumentos inválidos |

### Inicializar configuración

```bash
# Genera .env.example y valida las credenciales configuradas
security-guardian init

# Genera .security-guardian.yml con el perfil de convenciones del equipo
security-guardian init --profile

# Auto-detecta frameworks y librerías desde los manifiestos del proyecto
security-guardian init --profile --auto-detect
```

### Perfil de equipo (`.security-guardian.yml`)

Archivo opcional que personaliza el razonamiento del LLM para tu equipo:

```yaml
team_profile:
  frameworks:
    - django
    - react
  auth_libraries:
    - bcrypt
  allowed_patterns:
    - cwe_id: CWE-502
      razon: pickle usado solo en cache interno, nunca con input de usuario
    - cwe_id: CWE-327
      razon: md5 solo para ETags HTTP, no para datos sensibles
  min_severity: medium
  custom_exceptions:
    - Los logs internos pueden contener IDs de usuario por diseño
```

## Integración como GitHub Action

Agrega este step a tu workflow:

```yaml
- name: Security PR Guardian
  uses: Juanescuaran2041/security-sentinel@v0.1.0
  with:
    repo: ${{ github.repository }}
    pr-number: ${{ github.event.pull_request.number }}
    github-token: ${{ secrets.GITHUB_TOKEN }}
    bedrock-region: ${{ secrets.BEDROCK_REGION }}
    bedrock-model-id: ${{ secrets.BEDROCK_MODEL_ID }}
```

Configura los secrets en tu repositorio:
- `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` — credenciales AWS IAM
- `BEDROCK_REGION` — región de Bedrock (ej. `us-east-1`)
- `BEDROCK_MODEL_ID` — ID del modelo (ej. `anthropic.claude-3-5-haiku-20241022-v1:0`)

Ver el workflow de ejemplo completo en [`.github/workflows/security-guardian.yml`](.github/workflows/security-guardian.yml).

## Vulnerabilidades detectadas

| CWE | Tipo |
|-----|------|
| CWE-89 | Inyección SQL |
| CWE-78 | Inyección de comandos OS |
| CWE-79 | Cross-Site Scripting (XSS) |
| CWE-502 | Deserialización insegura |
| CWE-798 | Credenciales hardcodeadas |
| CWE-327 | Algoritmos criptográficos débiles (MD5, SHA1, DES) |
| CWE-552 | Referencias a rutas sensibles |

Además de CVEs conocidos en dependencias via [OSV.dev](https://osv.dev).

## Licencia

MIT
