# StaticCodeAudit — Guía de usuario

## Tabla de contenidos

1. [Inicio rápido](#1-inicio-rápido)
2. [Referencia CLI](#2-referencia-cli)
3. [Configuración del proyecto](#3-configuración-del-proyecto-auditconfigjson)
4. [Personalizar el informe](#4-personalizar-el-informe)
5. [Suprimir falsos positivos](#5-suprimir-falsos-positivos)
6. [Reglas personalizadas](#6-reglas-personalizadas)
7. [Integración CI/CD](#7-integración-cicd)
8. [Formatos de exportación](#8-formatos-de-exportación)

---

## 1. Inicio rápido

### Primera auditoría — sin configuración previa

```bash
./staticcodeaudit-windows-x64.exe /ruta/a/su/proyecto
```

El informe se genera en `docs/audit-reports/` dentro del proyecto.
Abra `SCA-REPORT-*.html` en cualquier navegador.

### Inicializar la configuración (recomendado)

```bash
./staticcodeaudit-windows-x64.exe /ruta/a/su/proyecto --init
```

Crea `audit.config.json` en la raíz del proyecto con todas las opciones disponibles,
pre-rellenadas y comentadas. Configúrelo una sola vez.

### Verificar la licencia

```bash
./staticcodeaudit-windows-x64.exe --license-info
```

---

## 2. Referencia CLI

El nombre del binario en su sistema incluye el sufijo de plataforma
(p. ej. `staticcodeaudit-windows-x64.exe`). Todos los ejemplos usan `./staticcodeaudit-windows-x64.exe`.

### Opciones de análisis

| Opción | Descripción | Valor predeterminado |
|--------|-------------|---------------------|
| `project_path` | Ruta del proyecto a auditar | `.` (directorio actual) |
| `--lang` | Idioma del informe y la consola: `fr`, `en`, `es`, `de` | `en` |
| `--version` | Muestra la versión y sale | — |
| `--license-info` | Muestra el estado de la licencia y sale | — |
| `--no-cache` | Desactiva la caché de compilación de reglas (rebuild completo) | off |
| `--no-incremental` | Desactiva el análisis incremental (re-escanea todos los archivos) | off |
| `--no-parallel` | Desactiva el escaneo paralelo (modo secuencial forzado) | off |

### Opciones de salida

| Opción | Descripción |
|--------|-------------|
| `--fail-on-high` | Código de salida 1 si existen hallazgos ALTOS/CRÍTICOS (puerta CI/CD) |
| `--sarif` | Genera un archivo SARIF 2.1.0 junto al informe HTML |
| `--sbom` | Genera un SBOM CycloneDX 1.5 (inventario de dependencias) |
| `--with-logs` | Guarda la salida de consola en un archivo `.log` |
| `--quiet` | Modo silencioso — solo se muestran errores y el resultado final |

### Características del cliente

| Opción | Descripción |
|--------|-------------|
| `--init` | Crea o edita `audit.config.json` de forma interactiva |
| `--create-rule` | Lanza el asistente para crear una regla personalizada |
| `--custom-rules-match` | Verifica que cada regla personalizada tenga sus fixtures de prueba |
| `--with-tests` | Detecta y ejecuta automáticamente los tests unitarios del proyecto |
| `--with-deps` | Ejecuta un análisis de vulnerabilidades en dependencias (`pip-audit`, `npm audit`) |

### Invocaciones frecuentes

```bash
# Informe en español
./staticcodeaudit-windows-x64.exe /ruta/proyecto --lang=es

# Auditoría + exportación SARIF (GitHub / GitLab)
./staticcodeaudit-windows-x64.exe /ruta/proyecto --sarif

# Auditoría + análisis de dependencias
./staticcodeaudit-windows-x64.exe /ruta/proyecto --with-deps

# Auditoría + tests unitarios
./staticcodeaudit-windows-x64.exe /ruta/proyecto --with-tests

# Modo silencioso para scripts
./staticcodeaudit-windows-x64.exe /ruta/proyecto --quiet

# Detener el pipeline CI ante hallazgos ALTOS o CRÍTICOS
./staticcodeaudit-windows-x64.exe /ruta/proyecto --fail-on-high

# Combinación completa para CI
./staticcodeaudit-windows-x64.exe /ruta/proyecto --sarif --fail-on-high --quiet --lang=es

# Guardar la salida de consola en un archivo log
./staticcodeaudit-windows-x64.exe /ruta/proyecto --with-logs
```

---

## 3. Configuración del proyecto (`audit.config.json`)

Coloque `audit.config.json` en la raíz del proyecto a auditar.
Genere una plantilla pre-rellenada con `--init` o créela manualmente.

### Ejemplo mínimo

```json
{
  "project": {
    "name": "Mi API",
    "version": "2.0"
  },
  "languages": ["python", "javascript"],
  "paths": {
    "include": ["src/", "api/"],
    "exclude": ["node_modules/", ".venv/", "*.min.js"]
  },
  "reports": {
    "output_dir": "docs/audit-reports",
    "language": "es"
  }
}
```

### Lenguajes

Controla qué conjuntos de reglas se activan.

| Valor | Archivos analizados |
|-------|---------------------|
| `python` | `.py` |
| `javascript` | `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs` |
| `html` | `.html`, `.htm` |
| `java` | `.java` |
| `csharp` | `.cs` |
| `php` | `.php`, `.inc` |
| `yaml` | `.yml`, `.yaml` (reglas CI/CD — activar la categoría `cicd`) |

### Rutas

```json
"paths": {
  "include": ["src/", "app/", "lib/"],
  "exclude": [
    "node_modules/",
    "vendor/",
    ".venv/",
    "__pycache__/",
    "*.min.js",
    "dist/"
  ]
}
```

`include` lista las carpetas a analizar (rutas relativas desde la raíz).
`exclude` admite nombres de carpetas, rutas relativas y patrones glob.

### Categorías

Cada categoría puede activarse o desactivarse de forma independiente. `weight` controla
su contribución a la puntuación de salud (1 = baja, 5 = alta).

```json
"categories": {
  "security":      { "enabled": true,  "weight": 3 },
  "architecture":  { "enabled": true,  "weight": 2 },
  "ui":            { "enabled": true,  "weight": 1 },
  "ux":            { "enabled": true,  "weight": 1 },
  "maintenance":   { "enabled": true,  "weight": 1 },
  "dependencies":  { "enabled": false, "weight": 2 },
  "cicd":          { "enabled": false, "weight": 2 }
}
```

Active `dependencies` para ejecutar `pip-audit` / `npm audit` automáticamente.
Active `cicd` para auditar pipelines de GitHub Actions / GitLab CI
(requiere `yaml` en `languages`).

### Informes

```json
"reports": {
  "output_dir":   "docs/audit-reports",
  "history_dir":  "docs/audit-reports/audit-datas",
  "max_history":  10,
  "language":     "es"
}
```

`language` controla el idioma del informe independientemente de `--lang`
(la opción CLI tiene prioridad si ambas están definidas).
`max_history` es el número de auditorías pasadas usadas para los gráficos de tendencia.

### Retención de informes

```json
"retention": {
  "mode":      "count",
  "max_count": 20,
  "max_days":  90
}
```

| Valor `mode` | Comportamiento |
|--------------|---------------|
| `"count"` | Conserva los `max_count` informes más recientes |
| `"days"` | Elimina informes con más de `max_days` días de antigüedad |
| `"both"` | Aplica ambas reglas |
| `null` | Sin eliminación automática (predeterminado) |

### Umbrales

```json
"thresholds": {
  "max_high":       0,
  "max_medium":     10,
  "min_health":     80,
  "health_good":    90,
  "health_warning": 70
}
```

### Integración de tests

```json
"tests": {
  "enabled":   true,
  "tests_dir": "tests/",
  "command":   "python -m pytest {tests_dir} -v --tb=short"
}
```

Actívelo con `--with-tests`. `{tests_dir}` se reemplaza en tiempo de ejecución.

---

## 4. Personalizar el informe

### Identidad visual

```json
"brand": {
  "tool_name":     "StaticCodeAudit",
  "company_name":  "Acme Corp",
  "prefix":        "SCA",
  "logo":          "assets/logo.svg",
  "primary_color": "#1e3a5f",
  "accent_color":  "#2c5282",
  "website_url":   "https://acme.example.com"
}
```

`logo` acepta una ruta relativa a la raíz del proyecto o una ruta absoluta.
Formatos admitidos: SVG, PNG, JPG.

### Encabezado del informe

```json
"project": {
  "name":        "Acme Backend",
  "version":     "3.1",
  "description": "API REST — servicio de procesamiento de pagos"
}
```

### Directorio de salida

```json
"reports": {
  "output_dir": "docs/audit-reports"
}
```

El directorio se crea automáticamente. Los informes se nombran
`SCA-REPORT-YYYY-MM-DD-HH-MM.html`.

---

## 5. Suprimir falsos positivos

### Método 1 — Comentario en línea

Añada `# sca-ignore` al final de la línea marcada para suprimir todas las reglas:

```python
password = hashlib.md5(token).hexdigest()  # sca-ignore
```

Para suprimir solo una regla específica:

```python
password = hashlib.md5(token).hexdigest()  # sca-ignore:weak_hash
```

Funciona en archivos Python, JavaScript, TypeScript, Java, C#, PHP.

### Método 2 — Archivo de configuración (persistente)

```json
"rules": {
  "suppress": [
    {
      "rule": "weak_hash",
      "file": "src/legacy/auth.py",
      "reason": "MD5 usado solo como clave de caché sin fines de seguridad"
    },
    {
      "rule": "console.log",
      "file": "src/debug/logger.js"
    }
  ]
}
```

### Método 3 — Reglas desactivadas (global)

```json
"rules": {
  "disabled": ["TODO/FIXME", "console.log", "hardcoded_secret"]
}
```

Las reglas desactivadas no aparecen en ningún informe. Usar con precaución.

---

## 6. Reglas personalizadas

Escriba reglas específicas para su proyecto sin modificar las reglas integradas.
Las reglas personalizadas se almacenan en `custom-rules/` junto al binario
y nunca son sobreescritas por las actualizaciones.

### Lanzar el asistente

```bash
./staticcodeaudit-windows-x64.exe /ruta/proyecto --create-rule
```

El asistente le guía a través de: nombre de la regla, categoría, lenguaje de destino,
severidad, patrón de detección, descripciones en 4 idiomas y ejemplos de corrección.
Ejecutar `--create-rule` sobre una regla existente abre el editor pre-rellenado.

### Verificar la cobertura de reglas

```bash
./staticcodeaudit-windows-x64.exe /ruta/proyecto --custom-rules-match
```

---

## 7. Integración CI/CD

### GitHub Actions

```yaml
- name: Static Code Audit
  run: |
    chmod +x ./staticcodeaudit-linux-x64
    ./staticcodeaudit-linux-x64 . --sarif --fail-on-high --quiet
  continue-on-error: false

- name: Upload SARIF
  uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: docs/audit-reports/SCA-REPORT-*.sarif
```

### GitLab CI

```yaml
sca:
  script:
    - chmod +x ./staticcodeaudit-linux-x64
    - ./staticcodeaudit-linux-x64 . --sarif --fail-on-high --quiet
  artifacts:
    reports:
      sast: docs/audit-reports/SCA-REPORT-*.sarif
```

### Códigos de salida

| Código | Significado |
|--------|-------------|
| `0` | Auditoría superada |
| `1` | Hallazgos ALTOS/CRÍTICOS detectados (solo con `--fail-on-high`) |
| `2` | Error de configuración o archivo requerido faltante |

---

## 8. Formatos de exportación

### HTML (siempre generado)

Informe interactivo con gráficos, desglose por severidad, historial de tendencias
y guías de corrección por hallazgo. Ábralo en cualquier navegador — sin servidor.

Ubicación: `docs/audit-reports/SCA-REPORT-YYYY-MM-DD-HH-MM.html`

### SARIF 2.1.0

```bash
./staticcodeaudit-windows-x64.exe /ruta/proyecto --sarif
```

Compatible con GitHub Code Scanning, GitLab SAST, VS Code (extensión SARIF Viewer),
Azure DevOps, SonarQube y Checkmarx.

Ubicación: `docs/audit-reports/SCA-REPORT-YYYY-MM-DD-HH-MM.sarif`

### SBOM CycloneDX

```bash
./staticcodeaudit-windows-x64.exe /ruta/proyecto --sbom
```

Software Bill of Materials en formato CycloneDX 1.5 JSON. Lista todas las dependencias
detectadas con su versión — útil para auditorías de cadena de suministro,
conformidad y gestión de licencias.

Ubicación: `docs/audit-reports/SCA-SBOM-YYYY-MM-DD-HH-MM.json`

> La disponibilidad de SARIF y SBOM depende de su tier de licencia.
> Contacte support@codefixture.com para más información.

---

*StaticCodeAudit por CodeFixture — Building Trust in Every Line.*
Soporte: support@codefixture.com
