StaticCodeAudit

by CodeFixture

Herramienta autónoma de auditoría de conformidad, seguridad y calidad de código para proyectos web (Python, JavaScript/TypeScript, HTML, Java, C#, PHP, YAML).

Tabla de contenidos

1. Instalación
2. Inicio rápido
3. Opciones CLI
4. Gestión de proyectos
5. Configuración
   • brand
   • project
   • languages
   • paths
   • reports
   • categories
   • rules
   • tests
   • thresholds
   • sla
   • retention
6. Categorías de auditoría
7. Informes
8. Integración CI/CD
9. Internacionalización (i18n)
10. Reglas personalizadas
11. Licencia

Instalación

Descargue el binario correspondiente a su plataforma desde su espacio cliente en codefixture.com, descomprima el archivo y colóquelo en un directorio accesible. El binario es completamente autónomo: no requiere instalar ningún intérprete, ni dependencias adicionales, ni acceso a Internet.

# Ejemplo (macOS)
tar -xzf staticcodeaudit-macos-arm64.tar.gz
chmod +x staticcodeaudit-macos-arm64
./staticcodeaudit-macos-arm64 --help

Inicio rápido

# Primera ejecución: genera automáticamente audit.config.json y registra el proyecto
./staticcodeaudit-<plataforma> /ruta/a/mi-proyecto --init

# Ejecutar la auditoría
./staticcodeaudit-<plataforma> /ruta/a/mi-proyecto

El flag --init crea interactivamente audit.config.json detectando:

• Lenguajes del proyecto (Python, JavaScript/TypeScript, HTML, Java, C#, PHP)
• Directorios de código fuente (app/, src/, etc.)

Importante: En tiempo de ejecución, el binario utiliza únicamente el archivo de configuración audit.config.json — sin detección automática.

Opciones CLI

Ejemplos:

# Auditoría completa
./staticcodeaudit-<plataforma> /ruta/a/proyecto

# Modo rápido (solo seguridad)
./staticcodeaudit-<plataforma> /ruta/a/proyecto --quick

# Modo CI/CD (exportación SARIF + código de salida 1 ante HIGH)
./staticcodeaudit-<plataforma> /ruta/a/proyecto --sarif --fail-on-high

# Con pruebas unitarias (detección automática de pytest, jest, mvn, etc.)
./staticcodeaudit-<plataforma> /ruta/a/proyecto --with-tests

# Con escaneo de vulnerabilidades de dependencias
./staticcodeaudit-<plataforma> /ruta/a/proyecto --with-deps

# Informe en español
./staticcodeaudit-<plataforma> /ruta/a/proyecto --lang=es

# Crear una regla personalizada (asistente interactivo)
./staticcodeaudit-<plataforma> /ruta/a/proyecto --create-rule

# Verificar la cobertura reglas/fixtures personalizadas
./staticcodeaudit-<plataforma> --custom-rules-match

# Gestión de proyectos
./staticcodeaudit-<plataforma> --list-projects                        # Lista todos los proyectos
./staticcodeaudit-<plataforma> /ruta/a/proyecto --project-info        # Información del proyecto
./staticcodeaudit-<plataforma> /ruta/a/proyecto --unregister          # Da de baja el proyecto

# Listar las categorías de auditoría
./staticcodeaudit-<plataforma> --list-categories
./staticcodeaudit-<plataforma> --list-categories --script-lang=es

# Listar todas las reglas por categoría
./staticcodeaudit-<plataforma> --list-rules
./staticcodeaudit-<plataforma> /ruta/a/proyecto --list-rules --script-lang=es

Formatos de salida

Cada ejecución de auditoría genera HTML + JSON por defecto. Otros formatos están disponibles bajo demanda:

# Generar HTML + JSON + informe demo anonimizado
./staticcodeaudit-<plataforma> /ruta/a/proyecto --demo

# Generar HTML + JSON + SARIF
./staticcodeaudit-<plataforma> /ruta/a/proyecto --sarif

# Generar HTML + JSON + SBOM
./staticcodeaudit-<plataforma> /ruta/a/proyecto --sbom

# Generar todos los formatos
./staticcodeaudit-<plataforma> /ruta/a/proyecto --sarif --sbom --demo

Modo demo: El flag --demo genera un informe anonimizado adicional (*-demo.html) junto con el informe completo. Las rutas de archivo se reemplazan por path_to/{filename}:##, el código fuente se oculta y las soluciones se truncan. Ideal para compartir con prospectos o publicar como muestra.

Gestión de proyectos

Cada proyecto auditado se identifica mediante un UUID único generado automáticamente durante la primera auditoría (--init). Este sistema le permite:

• Distinguir proyectos con el mismo nombre de directorio pero ubicados en lugares distintos
• Llevar un seguimiento del historial de auditorías por proyecto
• Detectar si un proyecto ha sido movido

Primera auditoría del proyecto

# El binario detecta automáticamente el proyecto y genera un UUID
./staticcodeaudit-<plataforma> /ruta/a/mi-proyecto --init

# Salida:
# Detección automática del proyecto "mi-proyecto"...
#    Tipo: Python + JavaScript
#    Rutas: app/, src/
# Identificador único generado: a1b2c3d4
# Configuración generada: /ruta/a/mi-proyecto/audit.config.json
# Proyecto registrado.

Listar los proyectos registrados

./staticcodeaudit-<plataforma> --list-projects

# Salida:
# Proyectos registrados (2):
#
# [a1b2c3d4] MyProject
#   Ruta: /ruta/a/mi-proyecto
#   Última auditoría: 2026-02-25 10:30
#   Auditorías: 15
#
# [b5c6d7e8] My-API
#   Ruta: /Users/dev/my-api
#   Última auditoría: Nunca
#   Auditorías: 0

Información detallada del proyecto

./staticcodeaudit-<plataforma> /ruta/a/proyecto --project-info

# Salida:
# Información del proyecto
#
# ID:          a1b2c3d4-e5f6-7890-abcd-ef1234567890
# Nombre:      MyProject
# Descripción: Aplicación web de ejemplo
# Versión:     3.0
# Ruta:        /ruta/a/mi-proyecto
#
# Registrado:  2026-01-15 14:30
# Última auditoría: 2026-02-25 10:30
# Total de auditorías: 15

Detección de proyecto movido

Si un proyecto se mueve a otra ubicación, el binario detecta automáticamente el cambio y actualiza la ruta registrada:

Aviso: la ruta ha cambiado para este proyecto
    Anterior: /Users/dev/old-path/mi-proyecto
    Nueva:    /Users/dev/new-path/mi-proyecto

    Registro actualizado.

Dar de baja un proyecto

./staticcodeaudit-<plataforma> /ruta/a/proyecto --unregister

# El registro del proyecto se elimina
# El audit.config.json del proyecto no se modifica

Configuración

El archivo audit.config.json se genera automáticamente en la raíz del proyecto objetivo durante la primera auditoría.

brand

Configuración de la marca. Permite personalizar la identidad de la herramienta por proyecto (p. ej., para informes destinados a clientes).

{
  "brand": {
    "tool_name": "Acme Code Audit",
    "company_name": "Acme Corp",
    "prefix": "ACM",
    "logo": "assets/acme-logo.svg"
  }
}

Nota: Si brand.logo apunta a un archivo inexistente o a un formato no soportado, la herramienta recurre a sus iconos por defecto y muestra una advertencia en consola. El logo se incrusta como base64 en el informe HTML para mantenerlo autónomo.

project

Información del proyecto mostrada en el informe.

{
  "project": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "My Project",
    "version": "1.0.0",
    "description": "Aplicación web FastAPI + Vue.js"
  }
}

Importante: El UUID (id) se genera automáticamente y no debe modificarse manualmente.

languages

OBLIGATORIO — Declara los lenguajes del proyecto. Controla qué reglas de auditoría se ejecutan.

{
  "languages": ["python", "javascript", "html", "java", "csharp", "php", "yaml"]
}

Importante: Si un lenguaje no se declara, las reglas correspondientes no se ejecutarán. Los archivos TypeScript (.ts, .tsx) y JSX (.jsx, .mjs) se tratan como JavaScript — se aplican las mismas reglas. No se necesita un lenguaje "typescript" separado.

paths

Configuración de las rutas de escaneo.

Nota: paths.include se utiliza para todos los lenguajes declarados. El filtrado por tipo de archivo se realiza por extensión. Durante --init, la configuración se genera automáticamente con las rutas detectadas.

{
  "paths": {
    "include": [
      "app/",
      "src/",
      "UI-FRONT/js/",
      "UI-ADMIN/js/"
    ],
    "exclude": [
      "**/node_modules/**",
      "**/vendor/**",
      "**/__pycache__/**",
      "**/.venv/**",
      "*.min.js",
      "*.bundle.js"
    ]
  }
}

reports

Configuración de la generación de informes.

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

categories

Activación y pesos de las categorías de auditoría.

{
  "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 }
  }
}

Pesos recomendados:

• security: 3 (crítico)
• architecture: 2 (importante)
• ui, ux, maintenance: 1 (estándar)

rules

Configuración de las reglas de detección.

{
  "rules": {
    "disabled": [
      "todo_fixme",
      "console_log_residual"
    ]
  }
}

Las reglas builtin (más de 465) se entregan con el binario y cubren las 7 categorías (Security, Architecture, UI, UX, Maintenance, Dependencies, CI/CD). Para la lista completa, consulte el resumen del producto o ejecute --list-rules.

tests

Configuración de las pruebas unitarias del proyecto auditado (opcional).

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

thresholds

Umbrales para la puntuación de salud y la integración CI/CD.

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

Códigos de salida:

• 0: Auditoría superada, umbrales respetados
• 1: Umbrales superados (vulnerabilidades HIGH o puntuación insuficiente)

sla

Configuración de SLA por severidad (opcional).

{
  "sla": {
    "enabled": true,
    "rules": {
      "CRITICAL": { "delay": "4h", "escalation": "CTO" },
      "HIGH": { "delay": "24h", "escalation": "Tech Lead" },
      "MEDIUM": { "delay": "1 sprint", "escalation": "Team Lead" },
      "LOW": { "delay": "Backlog", "escalation": "Developer" }
    }
  }
}

retention

Configuración de retención de informes (opcional). Controla la limpieza automática de informes antiguos.

{
  "retention": {
    "mode": "both",
    "max_count": 10,
    "max_days": 90
  }
}

Modos:

• "count": Conserva solo los N informes más recientes (max_count)
• "days": Elimina los informes con más de N días (max_days)
• "both": Aplica ambas reglas (el informe debe cumplir ambas para conservarse)
• null: Sin limpieza automática (por defecto)

Seguridad: Siempre se conserva al menos un informe. Los informes se eliminan en parejas HTML+JSON. Use --retention-dry-run para previsualizar qué archivos se eliminarían sin borrarlos realmente.

Nota: El parámetro existente reports.max_history controla únicamente los límites de visualización en los gráficos — no elimina archivos. Use retention para la limpieza efectiva de archivos.

Categorías de auditoría

Informes

Los informes se generan en <project>/docs/audit-reports/:

docs/audit-reports/
  SCA-REPORT-2026-02-22-15-30.html    # Informe HTML interactivo
  audit-datas/
    SCA-DATA-2026-02-22-15-30.json    # Datos JSON (historial)

Cada informe es un archivo HTML autónomo — todo el CSS, JavaScript, gráficos y favicons se incrustan en línea (sin dependencias externas). Ábralo en cualquier navegador, compártalo o archívelo.

El informe HTML incluye:

• Información del proyecto (nombre, versión, descripción, UUID, ruta)
• Parámetros de auditoría: lenguajes, extensiones escaneadas por lenguaje, rutas include/exclude, categorías
• Puntuación de salud global (logarítmica, ponderada por seguridad, normalizada por LOC) con indicador visual
• Desglose por severidad (CRITICAL, HIGH, MEDIUM, LOW, INFO)
• Desglose por categoría
• Lista detallada de hallazgos con código fuente
• Atribución del committer Git por hallazgo (cuando --git-blame está activado)
• Comparación con la auditoría anterior (nuevos/resueltos)
• Heatmap de los archivos más problemáticos

Integración CI/CD

# GitHub Actions
- name: Run Audit
  run: |
    ./staticcodeaudit-linux-x64 . --fail-on-high

# GitLab CI
audit:
  script:
    - ./staticcodeaudit-linux-x64 . --fail-on-high
  allow_failure: false

El binario devuelve un código de salida distinto de cero si:

• Se detectan vulnerabilidades HIGH (--fail-on-high o max_high: 0)
• La puntuación de salud está por debajo del umbral (min_health)

Internacionalización (i18n)

La herramienta de auditoría admite cuatro idiomas: francés (fr), inglés (en), español (es) y alemán (de).

Dos configuraciones independientes:

Idioma de la consola (CLI)

El idioma de los mensajes de consola se configura mediante la opción --script-lang:

# Mensajes en inglés (por defecto)
./staticcodeaudit-<plataforma> /ruta/a/proyecto

# Mensajes en español
./staticcodeaudit-<plataforma> /ruta/a/proyecto --script-lang=es

# Mensajes en francés
./staticcodeaudit-<plataforma> /ruta/a/proyecto --script-lang=fr

# Mensajes en alemán
./staticcodeaudit-<plataforma> /ruta/a/proyecto --script-lang=de

Idioma del informe (audit.config.json)

El idioma del informe HTML generado se configura en el archivo audit.config.json del proyecto:

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

Valores admitidos: fr (francés), en (inglés), es (español), de (alemán)

El informe muestra una insignia de idioma en la cabecera.

Fallback: Si se especifica un idioma no admitido, el binario recurre automáticamente al inglés (en).

Ejemplos de combinación

# Consola EN + Informe EN (por defecto)
./staticcodeaudit-<plataforma> /ruta/a/proyecto

# Consola ES + Informe EN
./staticcodeaudit-<plataforma> /ruta/a/proyecto --script-lang=es

# Consola EN + Informe ES (defina "language": "es" en audit.config.json)
./staticcodeaudit-<plataforma> /ruta/a/proyecto

# Consola ES + Informe ES
./staticcodeaudit-<plataforma> /ruta/a/proyecto --script-lang=es
# (con audit.config.json que contenga "language": "es")

Reglas personalizadas

Además de las más de 465 reglas integradas (builtin), usted puede crear sus propias reglas personalizadas, específicas para su proyecto o su organización. Las reglas personalizadas se almacenan en el directorio custom-rules/ (junto al binario) y nunca se ven afectadas por las actualizaciones del producto.

Asistente interactivo

La forma más rápida de crear una regla para su proyecto:

./staticcodeaudit-<plataforma> . --create-rule         # Crear o editar una regla personalizada
./staticcodeaudit-<plataforma> . --custom-rules-match  # Verificar la cobertura

El asistente interactivo le guía a través de 7 pasos: 1. Nombre, lenguaje, categoría, severidad — con verificación de duplicados (nombre + patrón) 2. Patrón a detectar (texto o regex) + lo que lo neutraliza (opcional) 3. Descripción del riesgo — EN obligatorio, FR/ES/DE opcionales 4. Solución — EN obligatorio, FR/ES/DE opcionales 5. Beneficio — opcional 6. Ejemplo de código antes/después — opcional 7. Vista previa → validación → escritura en custom-rules/{lang}/{cat}/{rule_id}.sca

Si ya existe una regla con el mismo nombre, el asistente propone editarla (precargada con los valores actuales).

Formato .sca

Las reglas personalizadas se almacenan en archivos texto con extensión .sca. El formato cubre:

• Patrones a detectar (texto bruto o regex)
• Condiciones de archivo (presencia/ausencia de otros patrones)
• Mensajes traducidos en 4 idiomas (riesgo, solución, beneficio)
• Ejemplos de código antes/después de la corrección

El asistente genera estos archivos automáticamente sin que necesite conocer la sintaxis interna.

Restricción por nivel (licencia)

Licencia

StaticCodeAudit se distribuye bajo licencia comercial. Consulte las condiciones específicas de su contrato. Para preguntas sobre licencia, contacte a soporte CodeFixture.