Uso del editor de modelos de CodeQL

Acerca del editor de modelos de CodeQL

Con los paquetes de modelos de CodeQL, puede expandir los análisis de code scanning de CodeQL para reconocer bibliotecas y marcos personalizados usados por el código base que no son compatibles de forma predeterminada. Con el editor de modelos de CodeQL, puede crear sus propios paquetes de modelos. El editor de modelos le orienta a través del modelado de las llamadas a dependencias externas de la aplicación o el modelado completo de todos los puntos de entrada y salida públicos en una dependencia externa.

Para obtener más información sobre cómo personalizar el análisis de code scanning con paquetes de modelos, incluida la descarga de paquetes de otros usuarios para que se ejecuten en su propio análisis, consulte “Personalización del análisis con paquetes de CodeQL”.

Al abrir el editor de modelos, analiza la base de datos de CodeQL seleccionada actualmente e identifica dónde usa la aplicación las API externas y todos los métodos públicos. Una API externa (o de terceros) es cualquier API que no forme parte de la base de datos de CodeQL que haya seleccionado.

El editor de modelos tiene dos modos diferentes:

• Modo de aplicación (vista predeterminada): el editor muestra cada marco externo usado por la base de datos de CodeQL seleccionada. Al expandir un marco, se muestra una lista de todas las llamadas a y desde la API externa con las opciones disponibles para modelar el flujo de datos a través de cada llamada. Este modo es más útil para mejorar los resultados de CodeQL de un código base específico.

• Modo de dependencia: el editor identifica todas las API accesibles públicamente en la base de datos de CodeQL seleccionada. Esta vista le orienta a través del modelado de cada API pública que el código base pone a disposición. Cuando haya terminado de modelar toda la API, puede guardar el modelo y usarlo para mejorar el análisis de CodeQL para todos los código base que usan la dependencia.

Visualización del editor de modelos de CodeQL

1. Abra el área de trabajo de CodeQL en VS Code. Por ejemplo, el vscode-codeql-starter área de trabajo. Si usa el área de trabajo de inicio, actualice el submódulo ql de main para asegurarse de que tiene las consultas usadas para recopilar datos para el editor de modelos.

2. En Visual Studio Code, haga clic en QL en la barra lateral izquierda para que se muestre la extensión de CodeQL.

3. En la vista “Bases de datos”, seleccione la base de datos de CodeQL desde la que desea modelar.

4. En la vista “Modelado de métodos” de CodeQL, haga clic en Iniciar modelado para mostrar el editor de modelos. Como alternativa, use el comando VS Code Command Palette para ejecutar el comando CodeQL: Abrir editor de modelos (beta).

5. El editor de modelos de CodeQL ejecuta una serie de consultas de telemetría para identificar las API en el código y el editor se muestra en una nueva pestaña.

6. Una vez completadas las consultas de telemetría, las API que se han identificado se muestran en el editor.

Modelado de las llamadas que realiza el código base a API externas

Normalmente, este método se usa cuando se examina un código base específico en el que desea mejorar la precisión de los resultados de CodeQL. Esto resulta útil cuando el código base usa marcos o bibliotecas que no son compatibles con CodeQL y si el código fuente del marco o de la biblioteca no se incluye en el análisis.

En esta sección se usa un proyecto Java de código abierto denominado “sofa-jraft” como ejemplo. La experiencia de modelado de llamadas a API externas escritas en otros lenguajes compilados es similar.

1. En Visual Studio Code, seleccione la base de datos de CodeQL para la cual desea mejorar la cobertura de CodeQL.

2. Visualización del editor de modelos de CodeQL. De forma predeterminada, el editor se ejecuta en modo de aplicación, por lo que se muestra la lista de API externas usadas por el código base seleccionado.

   

3. Haga clic para expandir una API externa y ver la lista de llamadas del código base a la dependencia externa.

   

4. Haga clic en Ver asociado a un método o una llamada API para mostrar dónde se usa en el código base.

5. El archivo que contiene la primera llamada desde el código base a la API se abre y se muestra una vista “Uso de métodos” de CodeQL en VS Code (donde normalmente se muestran las vistas “Problemas” y “Terminal”). La vista “Uso de métodos” de CodeQL enumera todas las llamadas del código a la API, agrupadas por método. Puede hacer clic en cada uso para decidir cómo modelar el uso del método.

6. Cuando haya determinado cómo modelar el uso del método, puede seleccionar otro tipo de modelo. Haga clic en la lista desplegable de “Tipo de modelo” en la vista “Modelado de métodos” de CodeQL de la extensión de CodeQL. Este cambio se refleja automáticamente en el editor de modelos principal.

7. Los campos restantes de esa fila se actualizan con las opciones disponibles para el tipo de modelo elegido:

   • “Origen”: elija el elemento “Salida” para modelar.
   • “Receptor”: elija el elemento “Entrada” para modelar.
   • “Resumen de flujo”: elija los elementos “Entrada” y “Salida” para modelar.

8. Defina el “Tipo” de flujo de datos para el modelo.

9. Cuando haya terminado de modelar, muestre el editor de modelos principal y haga clic en Guardar todo o Guardar (que se muestra en la parte inferior derecha de cada lista expandida de métodos). El porcentaje de métodos modelados en el editor se actualiza.

Los modelos se almacenan en el área de trabajo en .github/codeql/extensions/CODEQL-MODEl-PACK, donde CODEQL-MODEL-PACK es el nombre de la base de datos de CodeQL que seleccionó. Es decir, el nombre del repositorio, el guion, el lenguaje analizado por CodeQL. Para obtener más información, vea «Creación y uso de paquetes de CodeQL».

Los modelos se almacenan en una serie de archivos de extensión de datos YAML, uno para cada API externa. Por ejemplo:

.github/codeql/extensions/sofa-jraft-java # the model pack directory
    models
        jmh-core.model.yml                  # models calls to jmh-core@1.20
        rocksdbjni.model.yml                # models calls to rocksdbjni@7.7.3

Modelado de la API pública de un código base

Normalmente, se usa este método cuando se desea modelar un marco o una biblioteca que la organización usa en más de un código base. Una vez que haya terminado de crear y probar el modelo, puede publicar el paquete de modelos de CodeQL en el Container registry de GitHub para que toda la organización lo use.

En esta sección se usa un proyecto Java de código abierto denominado “sofa-jraft” como ejemplo. La experiencia de modelado de llamadas a API externas escritas en otros lenguajes compilados es similar.

1. Seleccione la ruta de acceso a la base de datos de CodeQL que desee modelar.

2. Visualización del editor de modelos de CodeQL. De forma predeterminada, el editor se ejecuta en modo de aplicación. Haga clic en Modelar como dependencia para mostrar el modo de dependencia. La pantalla cambia para mostrar la API pública del marco o de la biblioteca.

   

3. Haga clic para expandir un paquete y ver la lista de métodos disponibles.

4. Haga clic en Ver asociado a un método para mostrar su definición.

   

5. Cuando haya determinado cómo modelar el método, defina el “Tipo de modelo”.

6. Los campos restantes de esa fila se actualizan con las opciones disponibles para el tipo de modelo elegido:

   • “Origen”: elija el elemento “Salida” para modelar.
   • “Receptor”: elija el elemento “Entrada” para modelar.
   • “Resumen de flujo”: elija los elementos “Entrada” y “Salida” para modelar.

7. Defina el “Tipo” de flujo de datos para el modelo.

8. Cuando haya terminado de modelar, haga clic en Guardar todo o en Guardar (que se muestra en la parte inferior derecha de cada lista expandida de llamadas). El porcentaje de llamadas modeladas en el editor se actualiza.

Los modelos se almacenan en el área de trabajo en .github/codeql/extensions/CODEQL-MODEL-PACK, donde CODEQL-MODEL-PACK es el nombre de la base de datos de CodeQL que seleccionó. Es decir, el nombre del repositorio, el guion, el lenguaje analizado por CodeQL. Para obtener más información, vea «Creación y uso de paquetes de CodeQL».

Los modelos se almacenan en una serie de archivos de extensión de datos YAML, uno para cada método público. Por ejemplo:

.github/codeql/extensions/sofa-jraft-java          # the model pack directory
    models
        com.alipay.sofa.jraft.option.model.yml # models public methods in package
        com.alipay.sofa.jraft.rhea.options.model.yml

El editor creará un archivo de modelo independiente para cada paquete que modele.

Modelado de métodos con varios flujos potenciales

Algunos métodos admiten más de un flujo de datos. Es importante modelar todos los flujos de datos de un método; de lo contrario, no se pueden detectar todos los posibles problemas asociados al uso del método. En primer lugar, modele un flujo de datos para el método y, a continuación, use el botón + de la fila del método para especificar un segundo modelo de flujo de datos.

Pruebas de paquetes de modelos de consultas CodeQL en VS Code

Puede probar cualquier paquete de modelos de CodeQL que cree en VS Code con la configuración “Ejecución de consultas: usar paquetes de extensión”. Para obtener más información, vea «Personalización de la configuración». Este método funciona tanto para bases de datos como para repositorios de análisis de variantes.

• Para ejecutar consultas en una base de datos de CodeQL con los paquetes de modelos que se almacenan en el directorio .github/codeql/extensions del área de trabajo, actualice el archivo settings.json con: "codeQL.runningQueries.useExtensionPacks": "all",

• Para ejecutar consultas en una base de datos de CodeQL sin usar paquetes de modelos, actualice el archivo settings.json con: "codeQL.runningQueries.useExtensionPacks": "none",

Si el modelo funciona correctamente, debería ver una diferencia en los resultados de las dos ejecuciones diferentes. Si no ve ninguna diferencia en los resultados, es posible que tenga que introducir un error conocido para comprobar que el modelo se comporta según lo previsto.

Información adicional

• Editar la configuración predeterminada

• Personalizar la configuración avanzado de para el análisis de código