Uso del editor de modelos de CodeQL

Acerca del editor de modelos CodeQL

Con CodeQL los paquetes de modelos, puede expandir el CodeQLcode scanning análisis para reconocer bibliotecas y marcos personalizados usados por el código base que no son compatibles de forma predeterminada. Con el editor de CodeQL modelos, 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 code scanning análisis con paquetes de modelos, consulte Editar la configuración predeterminada y Opciones de configuración de flujo de trabajo para el examen de código.

Al abrir el editor de modelos, analiza la base de datos seleccionada CodeQL actualmente e identifica dónde usa 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 CodeQL base de datos seleccionada.

El editor de modelos tiene dos modos diferentes:

•         **Modo de aplicación (vista predeterminada):** el editor enumera cada marco externo usado por la base de datos seleccionada CodeQL . 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 CodeQL resultados de un código base específico.
  

•         **Modo de dependencia:** El editor identifica todas las API accesibles públicamente en la base de datos seleccionada CodeQL . 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 CodeQL análisis de todos los código base que usan la dependencia.
  

En el resto de este artículo se tratan los aspectos prácticos de modelar dependencias utilizando el editor de modelos CodeQL. Para obtener información técnica, consulte Personalización de modelos de biblioteca para Java y Kotlin, Personalización de modelos de biblioteca para Python, Personalización de modelos de biblioteca para Ruby y Personalización de modelos de biblioteca para C# en la documentación del CodeQL lenguaje.

Visualización del editor de modelos CodeQL

1. Abra su CodeQL área de trabajo en VS Code. Por ejemplo, el área de trabajo de vscode-codeql-starter. 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 mostrar la CodeQL extensión.

3. En la vista "Bases de datos", seleccione la base de datos CodeQL que desea modelar.

4. En la CodeQL vista "Modelado de métodos", haga clic en Iniciar modelado para mostrar el editor de modelos. Como alternativa, use VS Code Command Palette para ejecutar el CodeQLcomando : Open Model Editor (Beta).

5. El CodeQL editor de modelos 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, se utiliza este enfoque al examinar una base de código específica donde se 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 biblioteca no se incluye en el análisis.

En esta sección se usa un proyecto de open source Java 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 para la que desea mejorar la CodeQLCodeQL cobertura.

2. Muestra el editor de modelos 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. Se abre el archivo que contiene la primera llamada desde el código base a la API y se muestra una CodeQL vista "Uso de métodos" en VS Code (donde normalmente se muestran las vistas "Problemas" y "Terminal"). La CodeQL vista "Uso de métodos" muestra 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 el menú desplegable bajo "Tipo de modelo" en la vista CodeQL "Modelado de métodos" de la extensión 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 CodeQL base de datos seleccionada. Es decir, el nombre del repositorio, guion medio, el idioma 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 CodeQL en GitHubContainer registry para que toda la organización lo use.

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

1. Seleccione la CodeQL base de datos que desea modelar.

2. Muestra el editor de modelos 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 CodeQL base de datos seleccionada. Es decir, el nombre del repositorio, guion, el idioma 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.

Probando CodeQL paquetes de modelos en VS Code

Puede probar los CodeQL paquetes de modelos que cree con la configuración "Running Queries: Use Extension Packs" (Consultas en VS Code ejecución: 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 CodeQL base de datos con los paquetes de modelos almacenados en el .github/codeql/extensions directorio del área de trabajo, actualice settings.json el archivo con: "codeQL.runningQueries.useExtensionPacks": "all",

• Para ejecutar consultas en una CodeQL base de datos sin usar paquetes de modelos, actualice el settings.json archivo 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.

Lectura adicional

•         [AUTOTITLE](/code-security/code-scanning/managing-your-code-scanning-configuration/editing-your-configuration-of-default-setup#extending-codeql-coverage-with-codeql-model-packs-in-default-setup)
  

•         [AUTOTITLE](/code-security/code-scanning/creating-an-advanced-setup-for-code-scanning/customizing-your-advanced-setup-for-code-scanning#codeql-model-packs)[AUTOTITLE](/code-security/codeql-cli/getting-started-with-the-codeql-cli/customizing-analysis-with-codeql-packs#using-model-packs-to-analyze-calls-to-custom-dependencies).