Configuración del examen de código
Puede configurar cómo examina GitHub el código del proyecto en busca de vulnerabilidades y errores. Al elegir su propia configuración, ahorra tiempo y decide la mejor frecuencia de examen de código para el proyecto. En esta unidad, aprenderá los conceptos básicos de la configuración del examen de código. También aprenderá a configurar la frecuencia de los análisis y a programarlos para que se adapten mejor a sus necesidades relativas al desarrollo y a los repositorios.
Como se ha comentado en las unidades anteriores, puede ejecutar el examen de código en GitHub, mediante Acciones de GitHub o desde el sistema de integración continua (CI). Al seleccionar la opción Configuración avanzada en GitHub, se genera un archivo de flujo de trabajo personalizable que puede confirmar directamente en el repositorio. Normalmente no es necesario editar este flujo de trabajo. Sin embargo, si es necesario, puede personalizar parte de la configuración.
Por ejemplo, puede editar el flujo de trabajo de análisis de CodeQL de GitHub para especificar la frecuencia de los exámenes, los lenguajes o directorios que se examinarán y lo que busca el examen de código de CodeQL en el código. También es posible que tenga que editar el flujo de trabajo de análisis de CodeQL si usa un conjunto específico de comandos para compilar el código. El análisis de CodeQL es solo un tipo de examen de código que puede realizar en GitHub. El Marketplace de GitHub contiene otros flujos de trabajo de examen de código.
Cambio de la configuración predeterminada al examen de código avanzado
Si ya tiene un repositorio configurado para utilizar el análisis de código utilizando el método de configuración predeterminado, puede cambiar a utilizar la configuración avanzada en el apartado de configuración. Vaya a la sección Análisis de código en Configuración seguridad > avanzada y, a continuación, seleccione el icono de desbordamiento de tres puntos (...). En la lista desplegable, seleccione Cambiar a avanzado. A continuación, siga las indicaciones para deshabilitar CodeQL y vuelva a habilitarla con el archivo de flujo de trabajo generado por la configuración avanzada.
Edición del flujo de trabajo de examen de código
GitHub guarda los archivos de flujo de trabajo en el directorio .github/workflows del repositorio. Para encontrar un flujo de trabajo que haya agregado, busque su nombre de archivo. Por ejemplo, de forma predeterminada, el archivo de flujo de trabajo para el análisis de código CodeQL se denomina codeql-analysis.yml.
Siga estos pasos para editar un archivo de flujo de trabajo:
- Para abrir el editor de flujo de trabajo, seleccione el icono Editar en la esquina superior derecha de la vista de archivo.
Realice las modificaciones.
Después de editar el archivo, seleccione Confirmar cambios y complete el formulario Confirmar cambios. Puede elegir entre confirmar directamente en la rama actual o crear una rama e iniciar una solicitud de incorporación de cambios.
Revise las secciones siguientes para ver algunas opciones comunes de configuración del examen de código.
Configuración de la frecuencia
Una edición común del archivo de flujo de trabajo es ajustar la frecuencia con la que se produce el examen de código. Puede configurar el flujo de trabajo de análisis de CodeQL para examinar el código según una programación o cuando se producen eventos específicos en un repositorio. También puede editar el archivo de flujo de trabajo para examinar el código cuando alguien inserta un cambio y cada vez que se crea una solicitud de incorporación de cambios. Ajustar esta frecuencia evita que los desarrolladores introduzcan nuevas vulnerabilidades y errores en el código. El examen del código según una programación le informa sobre las vulnerabilidades y errores más recientes que detectan GitHub, los investigadores de seguridad y la comunidad. Incluso cuando los desarrolladores no mantienen activamente el repositorio.
Examen al enviar cambios
De forma predeterminada, el flujo de trabajo de análisis de CodeQL usa el evento on:push para desencadenar un examen de código en cada envío de cambios en la rama predeterminada del repositorio y en cualquier rama protegida. Para que el examen de código se desencadene en una rama especificada, el flujo de trabajo debe existir en esa rama. Si escanea al realizar un push, los resultados aparecen en la pestaña Seguridad de su repositorio.
Además, cuando un examen on:push devuelve un resultado que se puede asignar a una solicitud de incorporación de cambios abierta, estas alertas aparecen automáticamente en una solicitud de incorporación de cambios en el mismo lugar que otras alertas de solicitud de incorporación de cambios. Las alertas se identifican comparando el análisis existente del encabezado de la rama con el análisis de la rama de destino.
Examen al solicitar incorporación de cambios
El flujo de trabajo de análisis de CodeQL predeterminado usa el evento pull_request para desencadenar un examen de código al solicitar incorporaciones de cambios en la rama predeterminada. Si una solicitud de incorporación de cambios procede de una bifurcación privada, el evento pull_request solo se desencadena si ha seleccionado la opción "Ejecutar flujos de trabajo desde solicitudes de incorporación de cambios de bifurcación" en la configuración del repositorio. Si examina las solicitudes de incorporación de cambios, los resultados aparecen como alertas en una comprobación de solicitudes de incorporación de cambios.
Si usa el desencadenador pull_request, configurado para examinar la confirmación de combinación de la solicitud de incorporación de cambios en lugar de la confirmación principal, genera resultados más eficaces y precisos que examinar el encabezado de rama en cada inserción. Sin embargo, si usa un sistema de CI/CD que no se puede configurar para que se desencadene en las solicitudes de incorporación de cambios, todavía puede usar el desencadenador on:push para que el examen de código asigne los resultados para abrir las solicitudes de incorporación de cambios en la rama y agregar las alertas como anotaciones en la solicitud de incorporación de cambios.
Definición de los niveles de gravedad que provoca un error de comprobación de solicitud de incorporación de cambios
De forma predeterminada, solo las alertas con el nivel de gravedad Error o el nivel de gravedad de seguridad Critical o High provocan un error de comprobación de solicitud de incorporación de cambios.
Estos fallos no impiden que se ejecute el análisis de código, pero pueden bloquear la fusión según las reglas del repositorio. Puede consultar los detalles de los fallos de la solicitud de extracción en la pestaña Alertas de análisis de código, en la sección Seguridad.
Puede configurar qué niveles de gravedad provocan fallos en las comprobaciones de las solicitudes de extracción en la configuración del repositorio o mediante conjuntos de reglas del repositorio, usando la regla Exigir resultados del análisis de código. Ambos mecanismos funcionan, pero los conjuntos de reglas son el método de configuración moderno y preferido.
- En GitHub.com, vaya a la página principal del repositorio. En el nombre del repositorio, seleccione Configuración.
- En la barra lateral izquierda, seleccione Seguridad avanzada.
- En la sección Examen de código bajo Normas de protección, use el menú desplegable para seleccionar el nivel de gravedad con el que le gustaría desencadenar un error de comprobación de una solicitud de incorporación de cambios.
captura de pantalla del menú desplegable de la gravedad de la alerta de análisis de código.
Evaluar y descartar alertas de análisis de código de forma responsable
Corregir el código es la manera preferida de resolver una alerta de examen de código. Sin embargo, es posible que algunas alertas no requieran un cambio de código. Por ejemplo, la alerta puede ser un falso positivo, solo aparece en el código de prueba o representa un riesgo que el equipo ha decidido no corregir.
Descarte las alertas solo después de revisar los detalles de la alerta y confirmar el motivo. Al descartar una alerta, GitHub registra el motivo del descarte, quita la alerta del recuento de alertas actual, la mueve a la lista cerrada y evita que el mismo código genere la misma alerta en exámenes futuros. El despido se aplica en todas las ramas.
Elija el motivo del despido cuidadosamente porque se convierte en parte del registro de seguridad del repositorio. También puede agregar un comentario de despido para explicar la decisión. Este comentario se añade a la cronología de la alerta y puede servir de apoyo para futuras auditorías, informes y revisiones de cumplimiento.
Use comentarios para capturar detalles como:
Por qué la alerta no necesita un cambio de código
Quién revisó la decisión
Si la decisión es temporal o permanente
Cualquier control de compensación o trabajo de seguimiento
Para una gobernanza más sólida, las organizaciones pueden usar el descarte de alertas delegadas para controlar quién puede descartar las alertas de examen de código. Esto ayuda a evitar que los desarrolladores cierren los resultados de seguridad sin revisar y crear un proceso de evaluación de prioridades más responsable.
Evitar exámenes innecesarios de solicitudes de incorporación de cambios
Es posible que quiera evitar que se desencadene un examen de código en solicitudes de incorporación de cambios específicas destinadas a la rama predeterminada, independientemente de los archivos que se hayan cambiado. Para realizar esta configuración, especifique on:pull_request:paths-ignore o on:pull_request:paths en el flujo de trabajo de examen de código. Por ejemplo, si los únicos cambios en una solicitud de incorporación de cambios se realizan en archivos con las extensiones .md o .txt, puede usar la matriz paths-ignore siguiente.
on:
push:
branches: [main, protected]
pull_request:
branches: [main]
paths-ignore:
- '**/*.md'
- '**/*.txt'
Ajuste de la programación del examen
Si usa el flujo de trabajo de análisis de CodeQL predeterminado, el flujo de trabajo analiza el código del repositorio una vez a la semana en un día y hora generados aleatoriamente, además de los exámenes desencadenados por eventos. Para ajustar esta programación, edite el valor cron en el flujo de trabajo.
En el ejemplo siguiente se muestra un flujo de trabajo de análisis de CodeQL para un repositorio con una rama predeterminada denominada main y una rama protegida denominada protected:
on:
push:
branches: [main, protected]
pull_request:
branches: [main]
schedule:
- cron: '20 14 * * 1'
Este flujo de trabajo examina lo siguiente:
Cada envío de cambios a la rama predeterminada y a la rama protegida
Cada solicitud de incorporación de cambios a la rama predeterminada
La rama predeterminada todos los lunes a las 14:20 UTC
Usar las sugerencias de corrección automática de Copilot
GitHub Copilot Autofix ayuda a los desarrolladores a resolver alertas de análisis de código mediante la sugerencia de cambios de código de destino. Autofix usa información de la alerta, la base de código y la pull request para generar una posible corrección. No necesita una suscripción aparte a GitHub Copilot para usar Copilot Autofix. Está disponible para los repositorios públicos de GitHub.com y para los repositorios que pertenecen a una organización con GitHub Code Security habilitado.
Las sugerencias de autocorrección no son correcciones automáticas. Son cambios propuestos que deben revisarse, probarse y aprobarse como cualquier otro cambio de código.
Al revisar una sugerencia de Autofix:
Lea la alerta y comprenda el problema de seguridad.
Revise los cambios de código sugeridos.
Confirme que la corrección soluciona la alerta sin cambiar el comportamiento previsto.
Ejecute las pruebas del proyecto y las comprobaciones de seguridad necesarias.
Modifique la sugerencia si es necesario.
Confirme la corrección en la solicitud de incorporación de cambios.
Confirme que la alerta de examen de código se resuelve después de que las comprobaciones se vuelvan a ejecutar.
Si una sugerencia de Autofix no es adecuada, descártela en lugar de aplicarla. Si no es necesario corregir la propia alerta, descarte la alerta con el motivo correcto y un comentario claro.