Ejecución de consultas de CodeQL

Acerca de la ejecución de consultas de CodeQL

El repositorio github/codeql contiene un gran número de consultas de ejemplo. Puede acceder a las consultas existentes en el área de trabajo a través de la vista “Consultas”.

Requisitos previos

Para analizar un código base, puede ejecutar consultas en una base de datos de CodeQL extraída de código, de manera que tendrá que seleccionar una base de datos con la que trabajar en la extensión. Puede seleccionar una base de datos localmente (desde un archivo ZIP o una carpeta no archivada), desde una dirección URL pública o desde la dirección URL de un proyecto en GitHub.com. Para obtener más información, vea «Administración de bases de datos de CodeQL».

Ejecución de una sola consulta

1. En la barra lateral, abra la vista “Consultas”.

2. Para ejecutar una consulta en la base de datos seleccionada, mantenga el puntero sobre la consulta deseada y, a continuación, haga clic en el icono Ejecutar consulta local.

La extensión CodeQL ejecuta la consulta en la base de datos actual e informa del progreso en la esquina inferior derecha de la aplicación. Cuando los resultados estén listos, se muestran en la vista CodeQL “Resultados de la consulta”.

Si hay algún problema al ejecutar una consulta, se muestra una notificación en la esquina inferior derecha de la aplicación. Además del mensaje de error, la notificación incluye detalles sobre cómo corregir el problema.

Ejecución de todas las consultas en un directorio

Puede ejecutar cada consulta en un directorio.

1. En la barra lateral, abra la vista “Consultas”.

2. Mantenga el puntero sobre el directorio deseado de consultas y, a continuación, haga clic en el icono Ejecutar consultas locales.

Ejecución de una selección de consultas

Puede ejecutar varias consultas con un solo comando.

1. Vaya al Explorador de archivos.

2. Seleccione varios archivos o carpetas que contengan consultas.

3. Haga clic con el botón derecho y seleccione CodeQL: Ejecutar consultas en archivos seleccionados.

Ejecución de una consulta sin configuración

Al trabajar en una nueva consulta, puede abrir una pestaña “Quick Query” para ejecutar fácilmente el código y ver los resultados, sin tener que guardar un archivo .ql en el área de trabajo. Seleccione CodeQL: Quick Query en los datos VS Code Command Palette y, a continuación, para ejecutar la consulta, use CodeQL: Ejecutar consulta en la base de datos seleccionada.

Puede ver todas las consultas rápidas que ha ejecutado en la sesión actual en la vista “Historial de consultas”. Haga clic en una entrada para ver el texto exacto de la consulta rápida que generó los resultados. Para obtener más información, vea Ver su historial de consultas.

Una vez que esté satisfecho con la consulta rápida, debe guardarla en un paquete CodeQL para poder acceder a ella más adelante. Para obtener más información, vea «Personalización del análisis con paquetes de CodeQL».

Ejecución de una parte específica de una consulta o biblioteca

Esta opción puede resultar útil si está depurando una consulta o biblioteca y desea buscar la parte incorrecta.

En lugar de usar CodeQL: Ejecutar consulta en la base de datos seleccionada para ejecutar toda la consulta (la cláusula select y los predicados de consulta), puede usar CodeQL: Evaluación rápida para ejecutar una parte específica de un archivo .ql o .qll.

CodeQL: Evaluación rápida evalúa un fragmento de código que ha seleccionado, en lugar de toda la consulta, y muestra los resultados de esa selección en la vista “Resultados”.

Entre los posibles destinos para la evaluación rápida se incluyen:

• Seleccionar el nombre de una entidad CodeQL (por ejemplo, una clase o un predicado) para evaluar esa entidad.

• Selección de una fórmula o expresión con variables independientes para evaluar esa fórmula o expresión.

Por ejemplo, en el siguiente fragmento de código, puede seleccionar el nombre del predicado foo o la fórmula s = "bar" para la evaluación rápida:

predicate foo(string s) { s = "bar" }

Ejecución de una consulta en varias bases de datos

Esto puede resultar útil si desea probar la consulta en varios código base o encontrar una vulnerabilidad en varios proyectos.

1. Abra un archivo de consulta (.ql).

2. Haga clic con el botón derecho y seleccione CodeQL: Ejecutar consulta en varias bases de datos.

3. En el menú desplegable puede seleccionar las bases de datos en las que quiere ejecutar la consulta.

Visualización del historial de consultas

Para ver las consultas que ha ejecutado en la sesión actual, abra la vista “Historial de consultas”.

La vista “Historial de consultas” contiene información que incluye la fecha y la hora en que se ejecutó la consulta, el nombre de la consulta, la base de datos en la que se ejecutó y cuánto tiempo tardó en ejecutarse la consulta:

• Para personalizar la información que se muestra, haga clic con el botón derecho en una entrada y seleccione Cambiar nombre.

• Opcionalmente, filtre la vista por idioma mediante el selector de idioma. Para obtener más información, vea “Filtrado de bases de datos y consultas por idioma”.

• Haga clic en una entrada para mostrar los resultados correspondientes y haga doble clic para mostrar la propia consulta en el editor (o haga clic con el botón derecho y seleccione Ver consulta).

• Para mostrar el texto exacto que generó los resultados de una entrada determinada, haga clic con el botón derecho en él y seleccione Ver texto de consulta. Esto puede diferir de la opción Ver consulta, ya que es posible que el archivo de consulta se haya modificado desde la última vez que lo ejecutó.

• Para eliminar consultas de la vista, seleccione todas las consultas que desea eliminar y, a continuación, haga clic con el botón derecho y seleccione Eliminar.

Descripción de los resultados de consulta

1. Haga clic en una consulta en la vista “Historial de consultas” para mostrar sus resultados en la vista “Resultados”.

   Nota: Dependiendo de la consulta, también puede elegir diferentes vistas, como CSV, Salida SARIF de la CLI de CodeQL o formato DIL. Por ejemplo, para ver el formato DIL, haga clic con el botón derecho en un resultado y seleccione Ver DIL. Las vistas de resultados disponibles están determinadas por el formato y los metadatos de la consulta. Para obtener más información, consulte “Consultas de CodeQL¨.

2. Use el menú desplegable de la vista “Resultados” para elegir qué resultados mostrar y en qué formulario mostrarlos, como un mensaje de alerta con formato o una tabla de resultados sin procesar.

3. Para ordenar los resultados por las entradas de una columna determinada, haga clic en el encabezado de la columna.

Si un resultado se vincula a un elemento de código fuente, puede hacer clic en él para mostrarlo en el origen.

Para usar las características de navegación de código estándar en el código fuente, puede hacer clic con el botón derecho en un elemento y usar los comandos Ir a definición o Ir a referencias. Esto ejecuta una consulta CodeQL en el archivo activo, lo que puede tardar unos segundos. Esta consulta debe ejecutarse una vez para cada archivo, por lo que cualquier referencia adicional del mismo archivo será rápida.

Comparación de los resultados de consulta

Al escribir o depurar una consulta, resulta útil ver cómo afectan los cambios a los resultados. Puede comparar dos conjuntos de resultados para ver exactamente lo que ha cambiado. Para comparar los resultados, las dos consultas deben ejecutarse en la misma base de datos.

1. Haga clic con el botón derecho en una consulta en la vista “Historial de consultas” y seleccione Comparar resultados.

2. Un menú Selección rápida muestra todas las consultas válidas con las que comparar. Seleccione una consulta.

3. La vista “Comparar” muestra las diferencias en los resultados de las dos consultas.

Solución de problemas

Para ver los registros desde la ejecución de una consulta determinada, haga clic con el botón derecho en la consulta en la vista “Historial de consultas” y seleccione Mostrar registro de consultas. Si el archivo de registro es demasiado grande para que la extensión se abra en VS Code, el archivo se mostrará en el explorador de archivos para que pueda abrirlo con un programa externo.

Para obtener más información sobre la compilación y la ejecución de consultas, así como sobre las actualizaciones de bases de datos, compruebe el registro del servidor de consultas de CodeQL. Para obtener más información, vea «Acceso a los registros».

De forma predeterminada, la extensión elimina los registros después de cada sesión del área de trabajo. Para invalidar este comportamiento, puede especificar un directorio personalizado para los registros del servidor de consultas. Para obtener más información, vea «Personalización de la configuración».

Puede usar el comando CodeQL: Reiniciar servidor de consultas para reiniciar el servidor de consultas. De esta manera, se reinicia el servidor sin afectar al historial de sesiones de CodeQL. Es probable que tenga que reiniciar el servidor de consultas si realiza cambios externos en los archivos que usa la extensión. Por ejemplo, regenerando una base de datos CodeQL que está abierta en VS Code. Además de los problemas del registro, también puede ver: errores en el resaltado de código, totales de resultados incorrectos o notificaciones duplicadas de que se está ejecutando una consulta.

Pasos siguientes

Opcionalmente, puede usar la extensión para crear sus propias consultas personalizadas. Para obtener más información, vea «Creación de una consulta personalizada».

Para obtener información sobre cómo ejecutar análisis a gran escala en muchas bases de datos CodeQL, vea “Ejecución de consultas CodeQL a gran escala con análisis de variantes de varios repositorios”.