Documentación — Instalación y guía CLI de StaticCodeAudit

Primeros pasos

Requisitos

Linux x86_64, macOS (Intel y Apple Silicon) o Windows x64. El binario es totalmente autónomo — sin runtime, sin dependencias que instalar.

Instalación

Descargue el binario para su sistema operativo desde su cuenta, colóquelo en cualquier carpeta y hágalo ejecutable.

# Extraer el archivo (o montar el .dmg en macOS)

$ tar -xzf staticcodeaudit-linux-x64.tar.gz

# Hacer el binario ejecutable (Linux / macOS)

$ chmod +x ./staticcodeaudit-linux-x64

# Verificar el binario

$ ./staticcodeaudit-linux-x64 --version

Primera auditoría

Inicialice un proyecto, luego ejecute la auditoría. El flag --init genera un audit.config.json con los parámetros autodetectados.

# Generar la configuración del proyecto (interactivo)

$ ./staticcodeaudit-linux-x64 /path/to/your/project --init

# Ejecutar la auditoría

$ ./staticcodeaudit-linux-x64 /path/to/your/project

# Abrir el informe HTML

$ open docs/audit-reports/SCA-REPORT-*.html

Configuración

Toda la configuración se almacena en audit.config.json en la raíz de su proyecto. El flag --init genera este archivo con los parámetros autodetectados. Dos claves son obligatorias.audit.config.json at the root of your project. The --init flag generates this file with auto-detected settings. Two keys are mandatory.

Claves obligatorias

Clave	Descripción
languages	Array de lenguajes a escanear. Controla qué reglas de detección se ejecutan.
paths.include	Array de directorios a escanear (relativos a la raíz del proyecto).

Ejemplo de configuración

audit.config.json

{
  "languages": ["python", "javascript", "html"],
  "paths": {
    "include": ["src/", "app/", "lib/"],
    "exclude": ["node_modules/", "vendor/", ".venv/"]
  },
  "brand": {
    "tool_name": "StaticCodeAudit",
    "company_name": "CodeFixture",
    "prefix": "SCA",
    "logo": null
  },
  "reports": {
    "output_dir": "audit-reports",
    "history_dir": "audit-reports/audit-datas",
    "max_history": 10,
    "language": "en"
  },
  "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 }
  },
  "retention": {
    "mode": null,
    "max_count": 10,
    "max_days": 90
  }
}

Opciones CLI

Todos los flags son opcionales. El único argumento requerido es la ruta a su proyecto.

$ ./staticcodeaudit-linux-x64 /path/to/project [options]

Flag	Descripción
--init	Inicializar un nuevo proyecto: registro con UUID y generación de audit.config.json.
--quick, -q	Modo rápido: omitir tests, validación de fixtures y escaneo de dependencias.
--config, -c	Ruta a un archivo de configuración personalizado (por defecto: audit.config.json en la raíz del proyecto).
--output, -o	Reemplazar el directorio de salida para los informes.
--project-name, -p	Reemplazar el nombre del proyecto mostrado en el informe.
--verbose, -v	Activar la salida de consola detallada con progreso.
--fail-on-high	Salir con código 1 si se detecta un hallazgo de severidad HIGH (útil para CI/CD).
--sarif	Generar una exportación SARIF 2.1.0 junto al informe HTML.
--sbom	Generar un SBOM CycloneDX 1.5 (Software Bill of Materials).
--git-blame	Resolver el autor de cada hallazgo mediante git blame.
--skip-tests	Omitir la ejecución de tests unitarios.
--skip-deps	Omitir el escaneo de vulnerabilidades de dependencias.
--skip-cicd	Omitir la auditoría del pipeline CI/CD.
--script-lang	Idioma de la consola: en, fr, es, de (por defecto: en).
--only-category	Ejecutar solo una categoría (ej.: --only-category security).
--disable-rule	Desactivar reglas específicas por clave (repetible).
--retention-dry-run	Previsualizar qué informes antiguos serían eliminados sin eliminarlos realmente.
--self-test	Validar todas las fixtures (vulnerable + limpia) contra las reglas de detección.
--install-hook	Instalar un hook git pre-commit que ejecute la auditoría automáticamente.
--list-rules	Listar todas las reglas de detección disponibles y salir.
--list-categories	Listar todas las categorías de auditoría con su estado y salir.
--list-projects	Listar todos los proyectos registrados y salir.
--debug	Nivel de depuración: info, detail o trace.

Categorías de auditoría

StaticCodeAudit organiza sus 698 reglas de detección en 7 categorías. Cada categoría tiene un peso que influye en la puntuación de salud global. Las categorías se pueden activar o desactivar en su configuración.

Categoría	Código	Peso	Por defecto	Cobertura
Seguridad	SECURITY	3	✓	Inyección SQL, XSS, SSRF, path traversal, secretos, LDAP, cookies, crypto, GDPR
Arquitectura	ARCH	2	✓	Rutas admin, DB en routers, consultas directas, N+1, tamaño de archivos
UI	UI	1	✓	Estilos inline, createElement, SVG inline, event listeners, bucles DOM
UX	UX	1	✓	ARIA, texto alt, foco, autoplay, i18n, console.log, WCAG 2.1
Mantenimiento	MAINTENANCE	1	✓	TODO/FIXME, APIs obsoletas (5 lenguajes), catch-all, instrucciones de depuración
Dependencias	DEPENDENCIES	2	Desactivado	Escaneo CVE (pip-audit, npm audit), versiones no fijadas, conformidad de licencias
CI/CD	CICD	2	Desactivado	GitHub Actions, GitLab CI, inyección de expresiones, permisos, acciones no fijadas

Dependencias y CI/CD están desactivadas por defecto. Actívelas en audit.config.json. El peso influye en el cálculo de la puntuación de salud: mayor peso significa mayor impacto de la categoría.

Lenguajes soportados

Declare los lenguajes usados en su proyecto mediante el array languages en audit.config.json. Cada lenguaje activa su conjunto dedicado de reglas de detección.languages array in audit.config.json. Each language activates its dedicated set of detection rules.

Lenguaje	Valor config	Extensiones de archivo
Python	"python"	.py
JavaScript / TypeScript	"javascript"	.js, .jsx, .ts, .tsx, .mjs
HTML / Templates	"html"	.html, .htm, .xhtml, .vue, .svelte, .ejs, .hbs, .njk, .jinja, .jinja2, .twig, .liquid, .mustache, .phtml, .erb, .jsp, .asp, .aspx, .cshtml
Java	"java"	.java
C#	"csharp"	.cs
PHP	"php"	.php, .inc
YAML	"yaml"	.yml, .yaml

El escaneo YAML se usa para las reglas CI/CD (GitHub Actions, GitLab CI). TypeScript está cubierto por el valor "javascript" — las mismas reglas se aplican a ambos.

Formatos de salida

Cada auditoría genera un informe HTML y un archivo de datos JSON. Se pueden activar formatos adicionales mediante flags CLI.

Informe HTML

Archivo HTML autónomo con CSS, JavaScript y Chart.js integrados. Abrir en cualquier navegador, compartir por email, imprimir como PDF. Sin servidor requerido.

SCA-REPORT-YYYY-MM-DD-HH-MM.html

Datos JSON

Datos de auditoría estructurados para consumo programático y comparación histórica. Contiene todos los hallazgos, puntuaciones, metadatos y estadísticas.

SCA-DATA-YYYY-MM-DD-HH-MM.json

SARIF 2.1.0

--sarif

Estándar OASIS para resultados de análisis estático. Compatible con GitHub Code Scanning, GitLab SAST y Azure DevOps.

SCA-SARIF-YYYY-MM-DD-HH-MM.sarif

SBOM CycloneDX 1.5

--sbom

Software Bill of Materials que lista cada componente y dependencia de su proyecto. Cada vez más requerido por regulaciones de seguridad de la cadena de suministro.

SCA-SBOM-YYYY-MM-DD-HH-MM.json

Marca blanca

Personalice los informes con su propia marca — gratis, sin licencia enterprise requerida. Toda la marca se configura en la sección brand de audit.config.json.brand section of audit.config.json.

Opción	Por defecto	Efecto
brand.tool_name	StaticCodeAudit	Se muestra en el encabezado del informe, pie de página, banner de consola y título de página.
brand.company_name	CodeFixture	Se muestra en el pie de página del informe.
brand.prefix	SCA	Prefijo de archivos de salida (ej.: SCA-REPORT-, SCA-DATA-).
brand.logo	null	Ruta a su logo (SVG, PNG, JPG). Reemplaza el favicon y el icono de encabezado predeterminados en el informe.
brand.primary_color	#1e3a5f	Color de inicio del gradiente del encabezado del informe.
brand.accent_color	#2c5282	Color de fin del gradiente del encabezado del informe.

audit.config.json

"brand": {
  "tool_name": "MyCompany Audit",
  "company_name": "MyCompany Inc.",
  "prefix": "MCA",
  "logo": "assets/my-logo.svg",
  "primary_color": "#1a1a2e",
  "accent_color": "#16213e"
}

Funcionalidades del informe

El informe HTML es completamente autónomo — un solo archivo con todos los CSS, JavaScript y gráficos integrados. Sin servidor, sin recursos externos.

12+ gráficos interactivos

Distribución de severidades, desglose por categoría, análisis de tiempos, tendencias históricas, niveles de confianza y más. Impulsado por Chart.js (integrado).

Agrupación por severidad

Hallazgos organizados por severidad (CRITICAL, HIGH, MEDIUM, LOW, INFO) con badges de colores, rutas de archivos, números de línea y contexto de código.

Puntuación de salud

Puntuación logarítmica (0-100) basada en hallazgos de seguridad, normalizada por tamaño del proyecto (LOC). Penalidades: CRITICAL ×10, HIGH ×5, MEDIUM ×2, LOW ×1.

Integración Git Blame

Cuando se activa (--git-blame), cada hallazgo muestra el nombre del committer, la fecha y el hash del commit para la responsabilidad del equipo.

Comparación baseline

Compare los resultados de auditoría contra hasta 10 snapshots anteriores (configurable). Seguimiento de hallazgos nuevos, resueltos y persistentes en el tiempo.

Retención de informes

Limpieza automática de informes antiguos por cantidad, edad en días o ambos. Use --retention-dry-run para previsualizar las eliminaciones. Mínimo 1 informe siempre conservado.

Informes en 4 idiomas

Localización completa en inglés, francés, español y alemán. Cada cadena traducida: nombres de reglas, riesgos, soluciones, beneficios, etiquetas de gráficos, términos del glosario.

Glosario integrado

36 acrónimos y términos técnicos con vista previa tooltip. Cada ocurrencia en el informe es un enlace clicable a la definición del glosario.

Resumen ejecutivo

Panel de control al inicio de cada informe: puntuación de salud, desglose por severidad, tendencia y Recomendaciones prioritarias a ancho completo para visibilidad inmediata.

Guía de usuario en 4 idiomas

Cada entrega al cliente incluye USER-GUIDE.md en inglés, francés, español y alemán — opciones CLI, audit.config.json, personalización del informe, supresión e integración CI/CD.