Reglas personalizadas — Guía del cliente

Objetivo

Permitirle crear, probar y desplegar sus propias reglas de detección sin necesidad de conocer un formato interno, la sintaxis de las expresiones regulares ni la arquitectura del motor de análisis.

1. Visión general

Tres herramientas complementarias están a su disposición:

Herramienta	Comando	Función
Asistente	`--create-rule`	Creación guiada paso a paso, sin requerir conocimientos técnicos
Prueba rápida	`--test-rule <id>`	Retorno inmediato sobre una regla, sin auditoría completa
Ejemplos	`--init-rule --examples`	Aprendizaje mediante ejemplos (archivos `.sca` comentados)

Herramientas adicionales:

Herramienta	Comando	Función
Validación	`--rules-validate`	Valida todas sus reglas personalizadas (sintaxis, regex, campos)
Listado	`--rules-list`	Muestra todas las reglas cargadas (builtin + personalizadas)

Las reglas personalizadas se almacenan en el directorio custom-rules/ (junto al binario) y se conservan entre actualizaciones.

2. Asistente interactivo (`--create-rule`)

2.1 Flujo de trabajo

$ ./staticcodeaudit-<plataforma> /mi/proyecto --create-rule

  StaticCodeAudit — Creación de regla

? Nombre de la regla (snake_case): detect_console_error

? Lenguaje destino:
  > python
    javascript
    java
    csharp
    php
    html
    yaml

? ¿Qué buscar en el código?
  Introduzca el texto o patrón que se desea detectar.
  Ejemplos: "TODO", "console.error", "SELECT.*FROM.*WHERE"
  > console.error(

? Ámbito de búsqueda:
  > Cada línea de forma independiente (line)
    Ventana de 4 líneas (context-4)
    Ventana de 6 líneas (context-6)

? Severidad:
  > LOW — Buena práctica, mejora sugerida
    MEDIUM — Problema que debe corregirse en un plazo razonable
    HIGH — Problema crítico, debe corregirse de inmediato

? ¿El archivo debe contener un patrón específico?
  (Condición previa — dejar vacío para omitir)
  >

? ¿El archivo NO debe contener?
  (Exclusión — dejar vacío para omitir)
  >

? Descripción breve (inglés): Residual console.error call
? Descripción breve (español): Llamada console.error residual
? Riesgo (inglés): Error logging in production exposes internal state.
? Solución (inglés): Remove console.error or use a proper logging framework.

  Vista previa de la regla:

  rule detect_console_error
    language  javascript
    severity  LOW

    match
      pattern  console\.error\(
      scope    line
    end

    message
      en "Residual console.error call"
      es "Llamada console.error residual"
    end
  end

? ¿Crear esta regla? (S/n): S

  Regla creada: custom-rules/javascript/maintenance/detect_console_error.sca
  Validada: 1 pattern, scope line, LOW

  Próximos pasos:
  1. Pruébela: ./staticcodeaudit-<plataforma> /mi/proyecto --test-rule detect_console_error
  2. Lance la auditoría completa para incluir esta regla en el informe

2.2 Comportamiento del asistente

Escape automático de expresiones regulares

Usted introduce texto sin formato. El asistente escapa automáticamente los caracteres especiales de regex:

Su entrada	Patrón generado	Explicación
`console.error(`	`console\.error\(`	Punto y paréntesis escapados
`System.out.println`	`System\.out\.println`	Puntos escapados
`SELECT.*FROM`	`SELECT.*FROM`	`.*` reconocido como intencional
`\bfoo\b`	`\bfoo\b`	Construcción regex preservada

Reglas de escape:

Los caracteres (, ), [, ], {, }, ., +, ?, ^, $, |, \ se escapan automáticamente
EXCEPTO si usted utiliza construcciones regex explícitas: .*, .+, \s, \w, \d, \b, [...], (a|b)
El asistente detecta estas construcciones y las preserva
En caso de duda, el asistente le pregunta: "Esto parece una regex. ¿Usarla tal cual? (S/n)"

Validación en tiempo real

Cada respuesta se valida de inmediato:

Nombre: [a-z][a-z0-9_]* — en caso contrario, mensaje de error y nueva petición
Pattern: se compila como regex — si hay error, se muestra el error y se solicita de nuevo
Severidad: elección entre los 3 valores — sin entrada libre

Modo avanzado (opcional)

Si usted escribe --create-rule --advanced, aparecen preguntas adicionales:

Confidence (0-100, valor por defecto 80)
Pattern-not (patrón de exclusión — "NO detectar si esta línea contiene...")
Ámbito codebase (verificar sobre el conjunto de archivos, no archivo por archivo)
Metadatos CWE/OWASP (cumplimiento normativo)

2.3 Gestión de errores

Situación	Comportamiento
Nombre ya en uso	"Este nombre ya existe. Elija otro nombre."
Regex inválida	"Pattern inválido: [error]. Corríjalo o introduzca texto simple."
Ctrl+C	"Cancelado. No se creó ningún archivo."
Directorio `custom-rules/` ausente	Se crea automáticamente

3. Prueba rápida (`--test-rule <id>`)

3.1 Flujo de trabajo

$ ./staticcodeaudit-<plataforma> /mi/proyecto --test-rule detect_console_error

  Probando la regla 'detect_console_error' sobre 42 archivos...

  src/components/App.jsx:18      — console.error("Failed to load", err);
  src/utils/api.js:67            — console.error(response.statusText);
  src/utils/api.js:102           — console.error("Network error:", e);

  3 hallazgos detectados en 2 archivos (0.2s)

3.2 Comportamiento

Carga ÚNICAMENTE la regla solicitada (ni las builtin ni el resto de personalizadas)
Escanea los archivos del lenguaje correspondiente en paths.include
Muestra cada hallazgo: archivo, línea, código
Sin informe HTML, sin baseline, sin exportación JSON
Cronometra el tiempo de ejecución
Código de salida: 0 si hay al menos 1 hallazgo, 1 si hay 0 hallazgos

3.3 Opciones

Opción	Comportamiento
`--test-rule <id>`	Prueba la regla en `custom-rules/`
`--test-rule <id> --file src/app.py`	Prueba sobre un único archivo
`--test-rule <id> --verbose`	Muestra también los archivos escaneados sin coincidencias

3.4 Casos de error

Situación	Comportamiento
Regla no encontrada	"Regla 'xxx' no encontrada en custom-rules/. Reglas disponibles: ..."
Regla inválida	Muestra los errores de validación (igual que `--rules-validate`)
0 archivos del lenguaje	"No se encontró ningún archivo .py en las rutas configuradas."

4. Ejemplos comentados (`--init-rule --examples`)

4.1 Instalación

$ ./staticcodeaudit-<plataforma> /mi/proyecto --init-rule --examples

  5 ejemplos instalados en custom-rules/_examples/
    01_simple_pattern.sca       — Detección de una palabra clave simple
    02_multiline_context.sca    — Pattern sobre varias líneas
    03_file_condition.sca       — match + requires (combinación)
    04_exclusion_pattern.sca    — Detectar salvo si es seguro
    05_requires_only.sca        — Condición de archivo solamente

    Lance: ./staticcodeaudit-<plataforma> /mi/proyecto --rules-validate
    para verificar que los ejemplos sean válidos.

4.2 Contenido de los ejemplos

01_simple_pattern.sca

Detecta console.log() en JavaScript.
Formato más básico: un pattern en una sola línea.

02_multiline_context.sca

Detecta .execute(f"...") en Python sobre 4 líneas (scope context-4).
La palabra clave "with" añade una condición AND sobre la misma ventana.

03_file_condition.sca

Combina match + requires: detecta Flask() únicamente en los
archivos que no importan CSRFProtect.
El hallazgo se sitúa en la línea exacta de Flask(), no en la línea 1.

04_exclusion_pattern.sca

Detecta hashlib.md5() SALVO si "usedforsecurity=False" está presente.
La palabra clave "pattern-not" excluye las líneas que contienen el patrón seguro.

05_requires_only.sca

Un bloque requires solo (sin match) produce un hallazgo a nivel de archivo (línea 1).
Detecta los archivos Django con MIDDLEWARE pero sin HSTS.

5. Restricción por nivel (licencia)

Nivel	Reglas personalizadas	Funcionalidades
Demo	0	Sin reglas personalizadas
Solo	20 regex	`--create-rule`, `--test-rule`, `--rules-validate`
Team	100 regex + 30 taint	Igual + ejemplos avanzados
Enterprise	Ilimitado	Todo + reglas cifradas

6. Verificación

Tras la creación de sus reglas:

--create-rule → responder a las preguntas → archivo creado y válido
--test-rule <id> → hallazgos mostrados con rapidez
--init-rule --examples → ejemplos instalados y válidos
Auditoría completa → reglas personalizadas presentes en el informe HTML y JSON