Preparación de una base de datos para CodeQL

Completado

CodeQL trata el código como los datos. Cree una base de datos mediante datos consultables que extraiga del código base. A continuación, puede ejecutar consultas codeQL en esta base de datos para identificar vulnerabilidades de seguridad, errores y otros errores. Puede escribir sus propias consultas o ejecutar consultas codeQL estándar escritas por investigadores de GitHub y colaboradores de la comunidad.

En esta unidad, aprenderá a crear una base de datos. Este paso es necesario para poder analizar el código. Debe crear una base de datos CodeQL que contenga todos los datos necesarios para ejecutar consultas en el código.

El análisis de CodeQL se basa en la extracción de datos relacionales del código y su uso para crear una base de datos CodeQL. Estas bases de datos contienen toda la información importante sobre un código base.

Puede usar el producto independiente de la CLI de CodeQL para analizar el código y generar una representación de base de datos de un código base. Una vez lista la base de datos, puede consultar la base de datos o ejecutar un conjunto de consultas para generar un conjunto de resultados en formato de intercambio de resultados de análisis estáticos (SARIF).

Preparación de la base de datos para CodeQL

Antes de generar una base de datos CodeQL, debe instalar y configurar la CLI de CodeQL. A continuación, debe consultar la versión del código base que desea analizar.

En el caso de los lenguajes compilados, el directorio debe estar listo para compilarse, con todas las dependencias ya instaladas. CodeQL comienza extrayendo una única representación relacional de cada archivo de código fuente en el código base para crear una base de datos. Use esta base de datos para analizar el código.

En el caso de los lenguajes interpretados, el extractor se ejecuta directamente en el código fuente. Esta funcionalidad proporciona una representación precisa del código base y resuelve las dependencias.

La extracción de archivos de código fuente del código base funciona supervisando el proceso de compilación normal de los lenguajes compilados. CodeQL realiza una copia del archivo de origen cada vez que invoca un compilador para procesar un archivo de origen. Recopila toda la información relevante sobre el código fuente con cada archivo de código fuente.

Configuración de la CLI

Siga estos pasos para configurar la CLI de CodeQL.

1. Descargue el paquete de .zip de la CLI de CodeQL

Se recomienda instalar la CLI de CodeQL y las consultas mediante la descarga del paquete agrupado. Este método ayuda a garantizar la compatibilidad y el rendimiento mejorado, en lugar de descargar la CLI y las consultas por separado.

El paquete de descarga de la CLI de CodeQL es un archivo .zip que contiene herramientas, scripts y varios archivos específicos de CodeQL. La agrupación incluye: la CLI de CodeQL, las versiones compatibles de las consultas y bibliotecas del repositorio de GitHub de CodeQL y las versiones precompiladas de las consultas incluidas.

1. Vaya a la página de lanzamientos del repositorio público de CodeQL.
2. Descargue el paquete específico de la plataforma en Recursos.

En la página Versiones, también puede ver el registro de cambios de las versiones, junto con las descargas de versiones previas del paquete CodeQL. Si es necesario, puede descargar codeql-bundle.tar.gz, que contiene la CLI para todas las plataformas compatibles.

2. Extraer el archivo .zip

Si usa Linux, Windows o macOS, puede extraer el .zip archivo en el directorio que prefiera.

Los usuarios de macOS Catalina (o versiones más recientes) deben seguir pasos adicionales. Para más información, consulte la documentación de CodeQL sobre cómo empezar a trabajar con la CLI.

3. Ejecutar procesos de CodeQL

Después de la extracción, siga uno de los pasos siguientes para usar el codeql archivo ejecutable para ejecutar los procesos de CodeQL:

• Ejecute <extraction-root>/codeql/codeql, donde <extraction-root> es la carpeta en la que extrajo el paquete de la CLI de CodeQL.
• Agregue <extraction-root>/codeql a la PATH entrada para que pueda ejecutar el archivo ejecutable como simplemente codeql.

Ahora puede ejecutar comandos codeQL.

Comprobación de la configuración de la CLI

Puede ejecutar subcomandos de la CLI de CodeQL para comprobar que configuró correctamente la CLI y puede analizar las bases de datos:

• Ejecute codeql resolve packs (si agregó codeql a PATH) para mostrar qué paquetes de CodeQL puede encontrar la CLI. De lo contrario, use /<extraction-root>/codeql/codeql resolve packs. Este comando muestra los nombres de los paquetes de CodeQL incluidos en el paquete de la CLI de CodeQL, que se muestra en los pasos anteriores como <extraction-root>.

  Si la CLI de CodeQL no encuentra los paquetes de CodeQL para los idiomas esperados, compruebe que descargó el paquete CodeQL y no una copia independiente de la CLI de CodeQL.

• Ejecute codeql resolve languages para mostrar qué idiomas admite el paquete de la CLI de CodeQL de forma predeterminada.

Creación de base de datos

Las bases de datos de CodeQL se crean mediante la ejecución de este comando desde la raíz de extracción del proyecto:

codeql database create <database> --language=<language-identifier>

En el comando:

• Reemplace por <database> la ruta de acceso a la nueva base de datos que se va a crear.
• Reemplace por <language-identifier> el identificador del idioma que usa para crear la base de datos. Puede usar este identificador con --db-cluster para aceptar listas separadas por comas o puede especificarlo más de una vez.

También puede especificar las siguientes opciones. Estas opciones dependen de la ubicación del archivo de origen, tanto si el código debe compilarse como si desea crear bases de datos CodeQL para más de un lenguaje.

• Use --source-root para identificar la carpeta raíz de los archivos de origen principales para la creación de la base de datos.
• Use --db-cluster para los códigos base de varios idiomas cuando quiera crear bases de datos para más de un idioma.
• Úselo --command al crear una base de datos para uno o varios lenguajes compilados. No necesita esta opción si solo usa Python y JavaScript.
• Use --no-run-unnecessary-builds junto con --db-cluster para suprimir el comando de compilación para los lenguajes en los que la CLI de CodeQL no necesita supervisar la compilación.

Después de crear correctamente la base de datos, aparece un nuevo directorio en la ruta de acceso especificada en el comando . Si usó la --db-cluster opción para crear más de una base de datos, se crea un subdirectorio para cada idioma.

Cada directorio de base de datos CodeQL contiene varios subdirectorios, incluidos los datos relacionales que se usan para el análisis y un archivo de origen. El archivo fuente es una copia de los archivos originales creada cuando se generó la base de datos. CodeQL lo usa para mostrar los resultados del análisis.

Extractores

Un extractor es una herramienta que genera los datos relacionales y la referencia de origen para cada archivo de entrada, a partir del cual se puede crear una base de datos de CodeQL. Cada lenguaje compatible con CodeQL tiene un extractor. Esta estructura garantiza que el proceso de extracción sea lo más preciso posible.

Cada extractor define su propio conjunto de opciones de configuración. Al introducir codeql resolve extractor --format=betterjson, los datos se formatean de manera similar al siguiente ejemplo:

{
    "extractor_root" : "/home/user/codeql/java",
    "extractor_options" : {
        "option1" : {
            "title" : "Java extractor option 1",
            "description" : "An example string option for the Java extractor.",
            "type" : "string",
            "pattern" : "[a-z]+"
        },
        "group1" : {
            "title" : "Java extractor group 1",
            "description" : "An example option group for the Java extractor.",
            "type" : "object",
            "properties" : {
                "option2" : {
                    "title" : "Java extractor option 2",
                    "description" : "An example array option for the Java extractor",
                    "type" : "array",
                    "pattern" : "[1-9][0-9]*"
                }
            }
        }
    }
}

Para averiguar qué opciones están disponibles para el extractor del idioma, escriba codeql resolve languages --format=betterjson o codeql resolve extractor --format=betterjson. El betterjson formato de salida también proporciona la raíz del extractor y otras opciones específicas del lenguaje.

Datos de una base de datos CodeQL

Una base de datos CodeQL es un único directorio que contiene todos los datos necesarios para el análisis. Estos datos incluyen datos relacionales, archivos de origen copiados y un esquema de base de datos específico del lenguaje que especifica las relaciones mutuas en los datos. CodeQL importa estos datos después de la extracción.

Las bases de datos CodeQL proporcionan una instantánea de los datos consultables de un idioma determinado que se extrajo de un código base. Estos datos son una representación jerárquica completa del código. Incluye una representación del árbol de sintaxis abstracta, el gráfico de flujo de datos y el gráfico de flujo de control.

Las bases de datos se generan un idioma a la vez para los códigos base de varios idiomas. Cada idioma tiene su propio esquema de base de datos único. El esquema proporciona una interfaz entre el análisis léxico inicial durante el proceso de extracción y el análisis complejo a través de CodeQL.

Una base de datos CodeQL incluye dos tablas principales:

• La expressions tabla contiene una fila para cada expresión del código fuente que CodeQL analizó durante el proceso de compilación.
• La statements tabla contiene una fila para cada instrucción del código fuente que CodeQL analizó durante el proceso de compilación.

La biblioteca CodeQL define clases para proporcionar una capa de abstracción sobre cada una de estas tablas. Esta capa incluye las tablas Expr auxiliares relacionadas y Stmt.

Posibles errores de CodeQL

La creación de bases de datos en el flujo de trabajo de análisis de código tiene algunas posibles deficiencias. En esta sección se describe específicamente el uso de la acción CodeQL de GitHub.

Debe usar una matriz de idiomas para autobuild para compilar cada uno de los idiomas listados en la matriz. Puede usar una matriz para crear trabajos para más de una versión compatible de un lenguaje de programación, sistema operativo o herramienta.

Si no usa una matriz, autobuild intenta compilar el lenguaje compilado compatible con la mayoría de los archivos de origen del repositorio. A menudo se produce un error en el análisis de lenguajes compilados, aparte de Go, a menos que proporcione comandos explícitos para compilar el código antes de realizar el paso de análisis.

El comportamiento del autobuild paso varía en función del sistema operativo en el que se ejecuta el extractor de lenguaje. El autobuild paso intenta detectar automáticamente un método de compilación adecuado para el lenguaje en función del sistema operativo. Este comportamiento puede dar lugar a resultados poco confiables para los lenguajes compilados y, a menudo, puede dar lugar a una ejecución con errores.

Se recomienda configurar un paso de compilación dentro del archivo de flujo de trabajo de análisis de código que se ejecuta antes del análisis, en lugar de permitir que autobuild intente compilar lenguajes compilados. De este modo, el archivo de flujo de trabajo se adapta a los requisitos de compilación del sistema y del proyecto para análisis más confiables.

Puede leer más sobre lenguajes específicos y los pasos de autobuild descritos en la Documentación de AutoBuild de CodeQL.

Extensión de VS Code

Puede usar Visual Studio Code (VS Code) y la extensión CodeQL para compilar y ejecutar consultas, siempre y cuando use VS Code 1.39 o posterior. Puede descargar la extensión desde Marketplace de Visual Studio Code o descargar el archivo VSIX de CodeQL.

La extensión usa la CLI instalada que se encuentra en PATH si está disponible. Si no es así, la extensión administra automáticamente el acceso al archivo ejecutable de la CLI. La administración automática garantiza que la CLI sea compatible con la extensión CodeQL.