Reglas de Semgrep

Este es el repositorio central de reglas de Semgrep que alberga las reglas de Semgrep para el analizador Semgrep de GitLab.

El repositorio está estructurado de la siguiente manera:

.
├── mappings
│   ├── find_sec_bugs.yml
│   ├── eslint.yml
│   └── ...
├── rules
│   ├── lpgl
│   │   ├── java
│   │   │   ├── webview
│   │   │   │   ├── rule-ignore_ssl_certificate_error.yml
│   │   │   │   ├── rule-ignore_ssl_certificate_error.java
│   │   │   │   └── ...
│   │   │   └── ...
│   │   ├── python
│   │   │   └── ...
│   │   └── ...
│   ├── lpgl-cc
│   │   ├── java
│   │   │   └── ...
│   │   └── ...
│   └── ...
├── c
│   ├── buffer
│   │   ├── rule-strcpy.yml
│   │   ├── test-strcpy.c
│   │   ├── rule-memcpy.yml
│   │   └── test-memcpy.c
│   └── ...
└── javascript
│   └── ...
└── ...

La estructura anterior sigue el patrón:

rules/<license>/<language>/<ruleclass>/rule-<rulename>\.(yml|<ext>)

donde:

1. <license> es la licencia de todas las reglas debajo
2. <language> el lenguaje de programación objetivo
3. <ruleclass> un nombre descriptivo para la clase de reglas debajo
4. <rulename> un nombre descriptivo para la regla real
5. <ext> la extensión de archivo habitual para <language>

Las reglas antiguas siguen el patrón <language>/<ruleclass>/rule-..., y se debe preferir el nuevo patrón de arriba siempre que sea posible.

El directorio mappings incluye la configuración del paquete de reglas.

Makefile

El Makefile define algunos objetivos que son útiles al trabajar con reglas:

$ make help
TARGETS:
  test                  test all rules with Semgrep
  watch                 watch for file changes and auto-run affected tests
  help                  prints this message

Formatting guidelines

Las reglas contenidas en este repositorio deben adherirse al siguiente formato:

• Use " para cadenas, de lo contrario bloque literal YAML |
• No colapsar elementos de array
• longitud máxima de línea/ancho de texto: 100 caracteres
• sangría: 2 espacios
• cada regla debe tener un caso de prueba correspondiente
• si se proporciona, sección de comentarios en la parte superior del archivo de regla
• todos los archivos YAML comienzan con ---

Mappings

El directorio de mappings en este repositorio contiene archivos de configuración YAML que mapean los identificadores de analizadores nativos (p. ej. Bandit, Brakeman, etc.) a las reglas de Semgrep correspondientes.

La intención de los archivos de mapeo es, ante todo, separar la información específica del analizador de las reglas reales y, en segundo lugar, proporcionar una forma no intrusiva de generar paquetes de reglas o conjuntos de reglas (a través de límites de lenguaje o analizador) para diferentes propósitos.

Los archivos de mapeo se encuentran en el directorio mappings/, donde el nombre del archivo se refiere al paquete de reglas y/o analizador representado por el conjunto de reglas utilizado en el archivo respectivo. Si desea que las reglas se incluyan en el conjunto de reglas estándar de GitLab y la regla no encaja en ninguno de los paquetes de reglas (o analizadores) ya disponibles en el directorio mappings/, puede agregar sus mapeos al archivo mappings/gitlab_<license>_<language>.yml, donde <license> es una licencia adecuada dictada por la fuente de la que proviene la regla y <language> es un marcador de posición para el lenguaje al que se refiere la regla.

Si desea integrar una nueva regla que fue desarrollada desde cero, puede agregar un mapeo correspondiente al archivo mappings/gitlab_ee_<language>.yml.

Al determinar qué licencia debe aplicarse a una regla particular que está mapeando, consulte esta guía interna.

Los mapeos también se utilizan para ensamblar automáticamente paquetes de reglas. El fragmento a continuación ilustra un ejemplo con archivos de mapeo para el analizador bandit. La sección native_id incluye información sobre el identificador del analizador nativo, es decir, metainformación que el analizador original (en este caso bandit) adjunta al hallazgo que produce. Los mapeos de reglas reales se definen en la sección mappings. Cada mapeo asigna un identificador de regla de analizador nativo (en el ejemplo a continuación B301) a un conjunto de archivos de semgrep en este repositorio que se asemejan, o idealmente son de facto equivalentes, a esa regla nativa en particular.

bandit:
  native_id:
    type: "bandit_test_id"
    name: "Bandit Test ID: $ID"
    value: "$ID"
  mappings:
  - id: "B301"
    rules:
    - path: "python/deserialization/rule-pickle"
      primary_id: "bandit.B301-1"
      id: "bandit.B301-1"
    - path: "python/deserialization/rule-cpickle"
      primary_id: "bandit.B301-2"
      id: "bandit.B301-2"
    - path: "python/deserialization/rule-dill"
      primary_id: "bandit.B301-3"
      id: "bandit.B301-3"
    - path: "python/deserialization/rule-shelve"
      primary_id: "bandit.B301-4"
      id: "bandit.B301-4"
  # ...

La anatomía de un archivo de mapeo se explica con más detalle a continuación.

1. id se utiliza para generar identificadores de reglas semgrep estables y únicos en el paquete de reglas semgrep que corresponde a un archivo de mapeo.
2. primary_id ayuda a generar identificadores primarios de vulnerabilidad estables que se adjuntan a las vulnerabilidades tal como son generadas por el analizador Semgrep de GitLab (en el gl-sast-report.json) con fines de deduplicación.
3. native_id es la entrada que se asemeja exactamente a la estructura del identificador de vulnerabilidad tal como sería generado por el analizador nativo. Esto se agregará al gl-sast-report.json producido por el analizador Semgrep de GitLab y estará disponible en el Informe de Vulnerabilidades.
4. mappings incluye el identificador del analizador nativo (en el caso anterior B301 que se refiere a una de las reglas del analizador de python bandit). El array rules apunta a archivos en el repositorio a los que se refiere esta regla. En otras palabras, la lógica de B301 está implementada en los cuatro archivos listados en el fragmento anterior.

Usamos dos tipos diferentes de identificadores id y primary_id para soportar la división de reglas: múltiples reglas de semgrep (id) pueden ser mapeadas a una sola regla de analizador nativo (primary_id).

Data sources

Las reglas y casos de prueba en este repositorio provienen parcialmente de las fuentes listadas a continuación:

1. https://github.com/returntocorp/semgrep-rules
2. https://github.com/PyCQA/bandit
3. https://github.com/nodesecurity/eslint-plugin-security
4. https://github.com/jsx-eslint/eslint-plugin-react
5. https://github.com/david-a-wheeler/flawfinder/blob/master/flawfinder.py

Los detalles se listan en los encabezados de todos los archivos de reglas y pruebas, incluyendo la información de licencia y la atribución correspondiente.

Contributing

Si conoces un patrón que no está presente en este repositorio o refinamientos que podrían aplicarse a las reglas de este repositorio, puedes contribuir abriendo un issue, o incluso enviar una mejora a los archivos de reglas/casos de prueba en este repositorio.

Versioning

Aplicamos el siguiente esquema de versionado semántico a este repositorio:

1. incremento de versión patch: para reglas actualizadas/parcheadas/agregadas.
2. incremento de versión minor: cambios de esquema YAML compatibles hacia atrás (p. ej., agregar/eliminar campos opcionales).
3. incremento de versión major: cambios de esquema YAML no compatibles hacia atrás (p. ej., agregar/eliminar campos obligatorios)

SAST Rules release process

Las nuevas versiones de reglas SAST deben incorporarse al analizador semgrep para que surtan efecto. Para solicitar una nueva versión de semgrep, cree un issue de release siguiendo las instrucciones en la plantilla de issue de release de SAST.

Credits

Queremos agradecer mucho a los siguientes autores por sus valiosas contribuciones.