Análisis de código
El examen de código de GitHub Advanced Security para Azure DevOps permite analizar el código de un repositorio de Azure DevOps en busca de vulnerabilidades de seguridad y errores de codificación. Los problemas que se identifican en el análisis se generan como una alerta. El examen de código usa CodeQL para identificar vulnerabilidades.
CodeQL es el motor de análisis de código desarrollado por GitHub para automatizar las comprobaciones de seguridad. Puede analizar el código mediante CodeQL y mostrar los resultados como alertas de examen de código. Para obtener documentación más específica sobre CodeQL, consulte la Documentación de CodeQL.
GitHub Advanced Security para Azure DevOps funciona con Azure Repos. Si quiere usar GitHub Advanced Security con repositorios de GitHub, vea GitHub Advanced Security.
Configuraciones adicionales para el análisis de código
Compatibilidad con lenguajes y consultas
Las consultas de CodeQL predeterminadas que se usan para el examen de código están escritas y mantenidas por expertos de GitHub, investigadores de seguridad y colaboradores de la comunidad. Las consultas se actualizan frecuentemente para mejorar el análisis y reducir cualquier resultado falso positivo. Las consultas son de código abierto, por lo que puede verlas y contribuir a ellas en el repositorio github/codeql.
CodeQL admite y usa los siguientes identificadores de lenguaje:
Lenguaje | Identificador | Identificadores alternativos opcionales (si los hay) |
---|---|---|
C/C++ | c-cpp |
c o cpp |
C# | csharp |
|
Go | go |
|
Java/Kotlin | java-kotlin |
|
JavaScript/TypeScript | javascript |
|
Python | python |
|
Ruby | ruby |
|
Swift | swift |
Sugerencia
- Use
c-cpp
para analizar el código escrito en C. C++ o ambos. - Usa
java-kotlin
para analizar el código escrito en Java, Kotlin o ambos. - Usa
javascript
para analizar el código escrito en JavaScript, TypeScript o ambos.
Para obtener más información, consulte Lenguajes y marcos compatibles.
Puede ver las consultas específicas y los detalles de la tarea ejecutados por CodeQL en el registro de compilación.
Personalización del modo de compilación de análisis de código
El análisis de código admite dos modos de compilación al configurar una canalización para el análisis:
none
: la base de datos CodeQL se crea directamente desde el código base sin compilar el código base (compatible con todos los lenguajes interpretados y, además, compatible con C# y Java).manual
: define los pasos de compilación que se usarán para el código base en el flujo de trabajo (compatible con todos los lenguajes compilados).
Para obtener más información sobre los distintos modos de compilación, incluida una comparación sobre las ventajas de cada modo de compilación, consulte Análisis de código de CodeQL para lenguajes compilados.
Para ejecutar análisis de análisis de código mediante GitHub Advanced Security para Azure DevOps, el autobuild
modo de compilación es en su lugar una tarea de compilación independiente, AdvancedSecurity-CodeQL-Autobuild@1
.
Sugerencia
El modo de compilación none
se puede usar junto con otros lenguajes interpretados (por ejemplo, JavaScript, Python, Ruby).
Si se especifica el modo de compilación none
para C# o Java junto con otros lenguajes compilados que no admiten el modo de compilación none
, se producirá un error en la tarea de canalización.
Este es un ejemplo de una configuración válida con varios lenguajes y el modo de compilación none
:
trigger: none
pool:
vmImage: windows-latest
steps:
- task: AdvancedSecurity-Codeql-Init@1
displayName: Initialize CodeQL
inputs:
# build mode `none` is supported for C# and Java, and JavaScript is an interpreted language
# and build mode `none` has no impact on JavaScript analysis
languages: 'csharp, java, javascript'
buildtype: 'none'
- task: AdvancedSecurity-Codeql-Analyze@1
displayName: Perform CodeQL Analysis
Este es un ejemplo de una configuración no válida con varios lenguajes y el modo de compilación none
:
trigger: none
pool:
vmImage: windows-latest
steps:
- task: AdvancedSecurity-Codeql-Init@1
displayName: Initialize CodeQL
inputs:
# build mode `none` is supported for C# but build mode `none` is NOT supported for Swift
# so this pipeline definition will result in a failed run
languages: 'csharp, swift'
buildtype: 'none'
- task: AdvancedSecurity-Codeql-Analyze@1
displayName: Perform CodeQL Analysis
Uso de consultas personalizadas con CodeQL
De forma predeterminada, si no tiene un archivo de configuración personalizado especificado en la configuración de la canalización, CodeQL ejecutará el paquete de consultas security-extended
para analizar el código. Puede usar consultas de CodeQL personalizadas para escribir sus propias consultas para buscar vulnerabilidades y errores específicos. También deberá crear un archivo de configuración personalizado para modificar el análisis predeterminado de CodeQL.
Para buscar consultas personalizadas existentes o para contribuir con su propia consulta personalizada, consulte Contribución a CodeQL.
Análisis con consultas personalizadas
La forma más rápida de empezar con una consulta personalizada es escribir una consulta y guardarla en el repositorio local de Azure DevOps. Puede personalizar los detalles de una consulta personalizada según sus necesidades, pero debe tener al menos un ID de regla. Para obtener más información sobre cómo escribir su propia consulta de CodeQL, consulte Escritura de consultas de CodeQL. También puede agrupar varias consultas en un conjunto de consultas o usar paquetes publicados por otras personas. Para obtener más información, consulte Publicación y uso de paquetes de CodeQL.
Uso de un archivo de configuración personalizado
Un archivo de configuración personalizado es una manera de administrar las consultas que se ejecutan durante el análisis de CodeQL en el código. Puede especificar más consultas o paquetes de consultas que se van a ejecutar y cambiar o deshabilitar las consultas de CodeQL predeterminadas.
Para incluir una consulta específica que desee incluir, especifique la consulta con un nombre y una ruta de acceso a la ubicación del archivo de consulta (.ql) en el repositorio.
Para incluir un paquete específico que desee incluir, especifique el nombre del paquete. Puede especificar cualquier número de paquetes de consultas de CodeQL para ejecutarlas en el archivo de configuración.
El siguiente paso consiste en crear un archivo qlpack.yml
. Este archivo declara el paquete CodeQL e información sobre él. Los archivos *.ql
del mismo directorio (o subdirectorio) como qlpack.yml
se consideran parte del paquete.
Sugerencia
El filtro packs
del archivo de configuración admite la descarga de paquetes de repositorios hospedados en GitHub, pero el filtro queries
no.
Si el paquete es privado en GitHub, debe proporcionar un token de acceso de GitHub a través de la tarea AdvancedSecurity-Codeql-Init@1
como una variable de entorno y un nombre de variable como GITHUB_TOKEN
, con el ámbito del token read:packages
.
Este es un archivo de configuración de ejemplo:
name: "Run custom queries"
# When using a configuration file, if you do not disable default queries,
# then the default CodeQL queries in the `code-scanning` query suite will also execute upon analysis.
disable-default-queries: true
# To reference local queries saved to your repository,
# the path must start with `./` followed by the path to the custom query or queries.
# Names for each query referenced is optional.
queries:
- name: Use security-extended query suite
uses: security-extended
- name: Use local custom query (single query)
uses: ./customQueries/javascript/FindTestFunctions.ql
- name: Use local custom query (directory of queries)
uses: ./customQueries/javascript/MemoryLeakQueries
packs:
- mygithuborg/mypackname
paths:
- src
paths-ignore:
- src/node_modules
- '**/*.test.js'
query-filters:
- include:
kind: problem
- include:
precision: medium
- exclude:
id:
- js/angular/disabling-sce
- js/angular/insecure-url-allowlist
Sugerencia
Las especificaciones del archivo de configuración ignoran y tienen prioridad sobre las configuraciones en el nivel de canalización para la tarea AdvancedSecurity-Codeql-Init@1
.
includepaths
/ ignorepaths
se ignorarán o, si paths
/paths-ignore
existen, se sobrescribirán con los valores de paths
/paths-ignore
.
querysuite
se sobrescribirá con los valores especificados en queries
o packs
en el archivo de configuración.
Si usa cualquier consulta personalizada, este es un ejemplo de qlpack.yml
colocado en el directorio de las consultas personalizadas:
version: 1.0.1
dependencies:
codeql/javascript-all: "*"
codeql/javascript-queries: "*"
La variable dependencies
contiene todas las dependencias de este paquete y sus intervalos de versiones compatibles. Se hace referencia a cada dependencia como el scope/name
de un paquete de biblioteca de CodeQL. Al definir dependencies
, su qlpack.yml
depende exactamente de uno de los paquetes de idioma principales (por ejemplo, JavaScript, C#, Ruby, etc.), que determina el lenguaje que puede analizar la consulta.
Para obtener consejos y opciones de configuración más específicos con el archivo de configuración, consulte Personalización de la configuración avanzada para el análisis de códigos o, para la configuración de qlpack.yml
, consulte Estructura de paquetes CodeQL.
Una vez que tenga el archivo de configuración, deberá personalizar la canalización que ejecuta el análisis de CodeQL para usar el nuevo archivo. Esta es una canalización de ejemplo que apunta a un archivo de configuración:
trigger: none
pool:
vmImage: windows-latest
# You can either specify your CodeQL variables in a variable block...
variables:
# `configfilepath` must be an absolute file path relative to the repository root
advancedsecurity.codeql.configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml'
# Or you can specify variables as variables for the task. You do not need both definitions.
steps:
- task: AdvancedSecurity-Codeql-Init@1
displayName: Initialize CodeQL
inputs:
languages: 'javascript'
loglevel: '2'
configfilepath: '$(build.sourcesDirectory)/.pipelines/steps/configfile.yml'
# If downloading a pack from GitHub,
# you must include a GitHub access token with the scope of `read:packages`.
env:
GITHUB_TOKEN: $(githubtoken)
- task: AdvancedSecurity-Codeql-Analyze@1
displayName: Perform CodeQL Analysis
Alertas de examen de código
Las alertas de examen de código de GitHub Advanced Security para Azure DevOps incluyen marcas de examen de código por repositorio que alertan de vulnerabilidades de las aplicaciones de nivel de código.
A fin de usar el examen de código, primero debe configurar GitHub Advanced Security para Azure DevOps.
La pestaña Seguridad avanzada de Repositorios de Azure DevOps es el centro para ver las alertas de examen de código. Seleccione la pestaña Code scanning (Examen de código) para ver las alertas de examen. Puede filtrar por rama, estado, canalización, tipo de regla y gravedad. En este momento, el centro de alertas no muestra alertas para el análisis completado en las ramas de PR.
No hay ningún efecto en los resultados si se cambia el nombre de las canalizaciones o ramas; puede tardar hasta 24 horas antes de que se muestre el nuevo nombre.
Si decide ejecutar consultas CodeQL personalizadas, no hay de forma predeterminada un filtro independiente para las alertas generadas a partir de distintos paquetes de consultas. Puede filtrar por regla, que es distinto para cada consulta.
Si desactiva la Seguridad avanzada para el repositorio, perderá el acceso a los resultados en la pestaña Seguridad avanzada y la tarea de compilación. No se producirá un error en la tarea de compilación, pero los resultados de las compilaciones que se han ejecutado con la tarea mientras la Seguridad avanzada está deshabilitada se ocultan y no se conservan.
Detalles de alertas
Seleccione una alerta para obtener más detalles, incluidas instrucciones de corrección. Cada alerta incluye una ubicación, una descripción, un ejemplo y una gravedad.
Sección | Explicación |
---|---|
Location | En la sección Ubicaciones se detalla una instancia específica en la que CodeQL ha detectado una vulnerabilidad. Si hay varias instancias del código que infringen la misma regla, se genera una nueva alerta para cada ubicación distinta. La tarjeta Ubicaciones contiene un vínculo directo al fragmento de código afectado. De este modo, cuando seleccione el fragmento de código, se le dirigirá a la interfaz de usuario web de Azure DevOps para su edición. |
Description | La herramienta CodeQL proporciona la descripción en función del problema. |
Recomendación | La recomendación es la corrección que se sugiere para una alerta de examen de código determinada. |
Ejemplo | En la sección de ejemplo se muestra un ejemplo simplificado de la vulnerabilidad identificada en el código. |
severity | El nivel de gravedad puede ser bajo, medio, alto o crítico. La puntuación de gravedad se basa en la puntuación del sistema de puntuación de vulnerabilidades común (CVSS) determinada para la enumeración de vulnerabilidades comunes (CWE) identificada. Obtenga más información sobre cómo se puntúa la gravedad en esta entrada de blog de GitHub. |
Administración de las alertas de examen de código
Visualizar las alertas para un repositorio
Cualquier usuario con permisos de colaborador en un repositorio puede ver un resumen de todas las alertas de un repositorio en la pestaña Seguridad avanzada de Repositorios. Seleccione la pestaña Code scanning (Examen de código) para ver todas las alertas de examen de secretos.
Para mostrar los resultados, las tareas de examen de código deben ejecutarse primero. Una vez que ha finalizado el primer examen, las vulnerabilidades detectadas se muestran en la pestaña Seguridad avanzada.
De forma predeterminada, la página de alertas muestra los resultados del examen de dependencias de la rama predeterminada del repositorio.
El estado de una alerta determinada refleja el estado de la rama predeterminada y la canalización de ejecución más reciente, incluso si la alerta existe en otras ramas y canalizaciones.
Descarte de alertas de examen de código
Para descartar las alertas, necesita los permisos adecuados. De manera predeterminada, solo los administradores de proyectos pueden descartar alertas de seguridad avanzada.
Para descartar una alerta:
- Vaya a la alerta que quiere cerrar y selecciónela.
- Seleccione el menú desplegable Cerrar alerta.
- Si aún no está seleccionado, seleccione Riesgo aceptado o Falso positivo como motivo del cierre.
- Agregue un comentario opcional en el cuadro de texto Comentario.
- Seleccione Cerrar para enviar la alerta y cerrarla.
- El estado de la alerta cambia de Abierto a Cerrado y se muestra el motivo del descarte.
Esta acción solo descarta la alerta de la rama seleccionada. Las demás ramas que contengan la misma vulnerabilidad permanecerán activas hasta que se descarten. Cualquier alerta que se haya descartado anteriormente se puede volver a abrir de forma manual.
Solución de problemas del análisis de código
Por lo general, si se producen errores con la ejecución de CodeQL, la CLI de CodeQL notifica el estado de cada comando que se ejecuta como código de salida. El código de salida proporciona información para los comandos posteriores o para otras herramientas que se basan en la CLI de CodeQL. Para obtener más información sobre los detalles del código de salida, consulte Códigos de salida.
Error: comando de CodeQL "database finalize" (32)
Este error indica un problema al finalizar la creación de la base de datos de CodeQL, posiblemente debido a errores de extracción o a pasos de compilación que faltan.
Pasos para solucionar problemas:
- Comprobación de que el código existe y que está compilado
- En el caso de los lenguajes compilados, compruebe que el proceso de compilación está compilando código y que está ejecutando entre las tareas
AdvancedSecurity-Codeql-Init
yAdvancedSecurity-Codeql-Analyze
. Los comandos de compilación comunes y las marcas necesarias (como clean no-cache/no-daemon) se pueden encontrar aquí en Especificación de comandos de compilación. - En el caso de los lenguajes interpretados, confirme que hay código fuente para el idioma especificado en el proyecto.
- En el caso de los lenguajes compilados, compruebe que el proceso de compilación está compilando código y que está ejecutando entre las tareas
- Comprobación de errores de extracción
- Compruebe si los errores de extracción afectan al estado de la base de datos de CodeQL.
- Revise el archivo de registro para ver si hay errores y advertencias de extracción para evaluar el estado general de la base de datos.
- Investigación de errores abrumadores
- Si la mayoría de los archivos encuentran errores de extracción, investigue más para profundizar en la causa principal de la extracción incorrecta.
Error: script de autobuild (1)
Este error describe un error de compilación automática, lo que sugiere un problema con la configuración o definición del análisis de código.
Pasos para solucionar problemas:
- Configuración de pasos de compilación
- Quite el paso AutoBuild y, en su lugar, configure pasos de compilación específicos para los lenguajes compilados en las canalizaciones.
- Consulte las instrucciones de configuración que se indican en Configuración de GitHub Advanced Security para Azure DevOps.
Error: directorios de codeQL no encontrados en la caché de herramientas del agente
Este error indica un problema con la instalación de CodeQL para agentes autohospedados.
Pasos para solucionar problemas:
- Consulte las directrices o los scripts de configuración que se indican en Configuración de GitHub Advanced Security para Azure DevOps.
Error: no se ha establecido la variable de canalización de lenguaje
Este error se produce al intentar ejecutar CodeQL sin establecer la variable de canalización que especifica qué lenguajes se analizarán.
Pasos para solucionar problemas:
- Establecimiento de la variable de canalización de lenguaje
- Asegúrese de que la variable de canalización de lenguaje esté configurada correctamente. Consulte las instrucciones de configuración que se indican en Configuración de GitHub Advanced Security para Azure DevOps.
- Entre los lenguajes admitidos se encuentran los siguientes:
csharp
,cpp
,go
,java
,javascript
,python
,ruby
yswift
.
CodeQL no devuelve ningún resultado
En esta sección se proporcionan instrucciones para situaciones en las que el análisis de CodeQL no produce ningún resultado.
Pasos para solucionar problemas:
- Comprobación de vulnerabilidades detectadas
- Considere la posibilidad de que el código no tenga realmente ninguna vulnerabilidad. Si se esperan vulnerabilidades pero no se detectan, continúe con la comprobación.
- Revisión de la configuración del conjunto de consultas
- Confirme el conjunto de consultas que se está utilizando y considere la posibilidad de cambiar a un conjunto más completo si es necesario.
- Como alternativa, se pueden crear conjuntos de consultas personalizados para el análisis personalizado.
- Ajuste de los permisos para ver los resultados
- Asegúrese de que se conceden los permisos adecuados, al menos en el nivel de colaborador, para acceder a los resultados del análisis. Para obtener más información, consulte Permisos avanzados de seguridad.
Tiempo de espera de CodeQL
Si la tarea AdvancedSecurity-Codeql-Analyze@1
muestra This job was abandoned ... we lost contact with the agent
y usa un agente de Microsoft hospedado, la tarea alcanza el tiempo de espera integrado de seis horas para los agentes hospedados de pago. En su lugar, puede intentar ejecutar análisis en un agente autohospedado.
Permisos de tarea de examen de código
La tarea de compilación de análisis de código usa la identidad de canalización para llamar a las API de REST de Advanced Security. De forma predeterminada, las canalizaciones del mismo proyecto tienen acceso para cargar el archivo SARIF generado mediante la ejecución de análisis de CodeQL. Si quita esos permisos de la cuenta de servicio de compilación o si tiene una configuración personalizada (por ejemplo, una canalización hospedada en un proyecto diferente al repositorio), debe conceder estos permisos manualmente.
Pasos para solucionar problemas:
- Conceda el permiso
Advanced Security: View alerts
yAdvanced Security: Manage and dismiss alerts
a la cuenta de servicio de compilación que se usa en la canalización, que para las canalizaciones con ámbito de proyecto es[Project Name] Build Service ([Organization Name])
, y para canalizaciones con ámbito de recopilación esProject Collection Build Service ([Organization Name])
.
Instalación manual del lote CodeQL en el agente autohospedado
Instale la agrupación CodeQL en la caché de herramientas del agente mediante el script de instalación de la arquitectura, disponible en GitHub. Estos scripts requieren que la $AGENT_TOOLSDIRECTORY
variable de entorno se establezca en la ubicación del directorio de herramientas del agente en el mismo, por ejemplo, C:/agent/_work/_tool
. Como alternativa, puede implementar manualmente los pasos siguientes:
- Elija la última agrupación de versiones de CodeQL en GitHub.
- Descargue y descomprima la agrupación en el siguiente directorio dentro del directorio de herramientas del agente, normalmente ubicado en
_work/_tool
:./CodeQL/0.0.0-[codeql-release-bundle-tag]/x64/
. Con la versión actual dev2.16.0
, la carpeta se llamaría./CodeQL/0.0.0-codeql-bundle-v2.16.0/x64/
. Más información sobre el directorio de herramientas del agente. - Cree un archivo vacío llamado
x64.complete
dentro de la carpeta./CodeQL/0.0.0-[codeql-release-bundle-tag]
. Siguiendo el ejemplo anterior, la ruta de acceso del archivo final al archivox64.complete
debería ser./CodeQL/0.0.0-codeql-bundle-v2.16.0/x64.complete
.