Esta guía le ayuda a evaluar si el flujo de trabajo debe usar el pull_request_target evento y comprender los riesgos de seguridad implicados. También se explica que la protección GitHub se aplica a actions/checkout v7 y versiones posteriores para reducir estos riesgos de forma predeterminada y cuándo no participar en esa protección si es necesario.
Lea pull_request_target antes de extraer el código de solicitud de incorporación de cambios de uno de estos flujos de trabajo o antes de establecer la allow-unsafe-pr-checkout entrada en actions/checkout.
Riesgos del evento pull_request_target
Los flujos de trabajo desencadenados por pull_request_target se ejecutan con confianza elevada: el trabajo recibe el GITHUB_TOKEN del repositorio base, acceso a los secretos del repositorio y de la organización, y acceso de escritura a la caché de la rama predeterminada. Esta es la misma confianza que se otorga a eventos como los de tipo push, que solo los colaboradores pueden desencadenar, y es lo que hace que pull_request_target sea útil para la automatización que responde a pull requests desde forks, como el etiquetado, el triaje o la publicación de comprobaciones de estado autenticadas.
Para comprender por qué esto es seguro de forma predeterminada y cómo se interrumpe normalmente esa seguridad, revise pull_request_target en pull_request.
El pull_request evento (junto con pull_request_review y pull_request_review_comment) es inusual: ejecuta el archivo de flujo de trabajo desde la confirmación de combinación de la solicitud de incorporación de cambios. Para una solicitud de incorporación de cambios abierta desde una bifurcación, esa confirmación se controla mediante alguien sin acceso de escritura al repositorio base. Para ejecutar de forma segura código de flujo de trabajo no fiable, GitHub restringe estos eventos a un GITHUB_TOKEN de solo lectura, impide el acceso a otros secretos y aplica políticas de aprobación para bifurcaciones a fin de evitar el abuso de recursos de cómputo. Para obtener más información, vea Eventos que desencadenan flujos de trabajo. De forma predeterminada, actions/checkout en un flujo de trabajo de pull_request también extrae el commit de fusión de la solicitud de extracción, por lo que el código extraído y el flujo de trabajo que se ejecuta son coherentes.
pull_request_target introduce un cambio sutil pero importante: el flujo de trabajo y cualquier llamada posterior a actions/checkout que no especifique un ref se toman de la rama predeterminada del repositorio base, no de la solicitud de extracción. Dado que solo se ejecuta código de confianza de la rama predeterminada, es seguro conceder secretos y un token de lectura y escritura. No se ejecuta ningún código de la bifurcación de forma predeterminada.
Se introduce un riesgo cuando un autor de un flujo de trabajo anula este valor predeterminado para ejecutar el código de la bifurcación. Los desarrolladores suelen elegir pull_request_target porque quieren ejecutar la pull request de un fork en CI y tener acceso a secretos, por ejemplo, para ejecutar pruebas que necesitan un registro privado. Para ello, apuntan actions/checkout al encabezado de la solicitud de incorporación de cambios en lugar de a la rama predeterminada, que no es segura:
# INSECURE. Provided as an example only.
on:
pull_request_target:
jobs:
build:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
with:
ref: ${{ github.event.pull_request.head.sha }}
- name: Test
run: make test
El paso de checkout por sí solo no ejecuta código no confiable. El propio archivo de flujo de trabajo sigue viniendo de la rama predeterminada. La vulnerabilidad se completa con el siguiente paso, que ejecuta el código extraído en el directorio de trabajo actual. Aquí, make test ejecuta un Makefile elemento tomado del encabezado de solicitud de incorporación de cambios. Un atacante solo necesita abrir una solicitud de extracción desde un fork cuyo Makefile (o script de compilación, comando de prueba, dependencia o archivo de configuración) contenga comandos maliciosos. A continuación, esos comandos se ejecutan con los secretos y el token del repositorio base.
Este patrón se conoce como "pwn request" y ha sido la causa raíz de múltiples compromisos de la cadena de suministro. Para obtener más información, vea Impedir solicitudes pwn de GitHub Security Lab. Entre las formas vulnerables comunes se incluyen las siguientes:
- Extraer el HEAD o el commit de combinación de una solicitud de extracción en
actions/checkout(ref: ${{ github.event.pull_request.head.sha }},ref: refs/pull/${{ github.event.pull_request.number }}/merge) y luego compilar, probar o ejecutar de otro modo el resultado. - Establecer
repository:en la bifurcación (repository: ${{ github.event.pull_request.head.repo.full_name }}) para extraer directamente la rama de la bifurcación. - Obtener el código de la pull request fuera de
actions/checkout(por ejemplo, congit fetch,gh pr checkouto descargando un artefacto de la ejecución depull_requestde una bifurcación) y luego ejecutarlo.
Las solicitudes pwn tampoco son exclusivas de pull_request_target. Cualquier evento que se ejecute con secretos puede dar lugar a una vulneración si extrae o descarga y ejecuta código no fiable. Por ejemplo, un flujo de trabajo de issue_comment o workflow_run que obtiene y ejecuta el código de una solicitud de extracción de un fork es vulnerable de la misma manera. Un workflow_run flujo de trabajo debe tratar los artefactos cargados por otros flujos de trabajo como datos que no son de confianza, ya que su contenido puede provenir de una bifurcación.
Decidir si se va a usar pull_request_target
Algunos flujos de trabajo necesitan hacer checkout del código de un pull request de un fork con un nivel de confianza elevado, y por eso se creó pull_request_target en primer lugar. Por ejemplo, generar informes de cobertura que requieran un registro privado de artefactos o producir y ejecutar verificaciones autenticadas de los cambios introducidos en la pull request. Considere las siguientes preguntas antes de usar pull_request_target o activar el indicador allow-unsafe-pr-checkout en actions/checkout.
-
¿Puede usar
pull_requesten su lugar?pull_requestse activa con los mismos eventos quepull_request_targety ejecuta el código del flujo de trabajo desde la rama de combinaciónpull_request. Esto se realiza de forma segura en las solicitudes de extracción de bifurcaciones con las protecciones detalladas anteriormente. Si no se necesita acceso a secretos adicionales, usepull_request. Los flujos de trabajo más complejos pueden reestructurarse para separar el manejo potencialmente peligroso del código de las solicitudes de extracción del acceso a secretos. Para obtener más información, consulte Cómo evitar las solicitudes de tipo pwn en GitHub Security Lab. -
¿Se ejecuta alguna vez el código extraído? Este es el fallo que introduce vulnerabilidades de solicitudes pwn. Normalmente, se introduce con
actions/checkoutextrayendo la cabecera de una solicitud de incorporación de cambios al directorio de trabajo y ejecutándola a continuación. A menos que se configure la entradapath,actions/checkoutescribe el código en el directorio$GITHUB_WORKSPACE, que suele ser el directorio de trabajo donde se ejecutan los comandos siguientes. La ejecución no se limita a sus propios pasos: los comandos de compilación y prueba, comonpm installynpm run build, así como los archivos de configuración y las dependencias que aporta el código, pueden ejecutar código controlado por atacantes. La ejecución no requiere un paso de compilación obvio. Debe asegurarse de que el código extraído se examine únicamente como datos y nunca se ejecute antes de usar un eventopull_request_target.
Refuerzo de un flujo de trabajo de pull_request_target
Si ha confirmado que necesita pull_request_target, aplique estos controles para limitar el impacto de este evento de alto riesgo. Se aplican si el flujo de trabajo comprueba o no el código de solicitud de incorporación de cambios.
-
Restringir secretos. Confirme que los permisos establecidos en
GITHUB_TOKENtienen los privilegios mínimos y que solo se usan los secretos de la organización y del repositorio necesarios para el flujo de trabajo. Para obtener más información, vea Uso de GITHUB_TOKEN para la autenticación en flujos de trabajo. -
Comprenda el impacto en el almacenamiento en caché. Aparte de
GITHUB_TOKENy de los secretos configurados, los flujos de trabajo que se ejecuten enpull_request_targettambién tienen permiso de escritura en la caché compartida con otros flujos de trabajo de la rama predeterminada. Los cambios malintencionados en esta memoria caché depull_request_targeteventos podrían afectar a la ejecución de otros flujos de trabajo, no relacionados. -
Asegúrese de que el proceso subyacente está aislado y efímero. Si se usan ejecutores autohospedados, debe confirmar que el entorno del ejecutor está correctamente restringido de los recursos internos y no se reutiliza entre GitHub Actions ejecuciones. Para obtener más información, vea Referencia de uso seguro.
-
La compuerta se ejecuta después de la aprobación.
pull_request_targetlos flujos de trabajo pueden protegerse mediante unalabelobligatoria que solo los usuarios con permiso de escritura pueden añadir. Esto se detalla en la GitHub Security Labguía para prevenir solicitudes pwn. -
Aplique los GitHub Actions procedimientos recomendados de seguridad. Además de los riesgos específicos de las solicitudes pwn, pueden existir otras vulnerabilidades comunes, como la inyección de comandos, y afectar al código ejecutado en este evento con privilegios. Para obtener más información, consulte Mantener la seguridad de Acciones de GitHub y los flujos de trabajo: entrada no fiable de GitHub Security Lab. Para identificar y proteger proactivamente frente a vulnerabilidades comunes GitHub Actions , habilite CodeQL para GitHub Actions. Para obtener más información, vea Establecimiento de la configuración predeterminada para el examen del código.
Desactivar las protecciones integradas
Si ha revisado las preguntas anteriores y ha confirmado que su flujo de trabajo requiere pull_request_target y lo usa de forma segura, puede desactivar la protección de actions/checkout. Establecer allow-unsafe-pr-checkout: true como una entrada actions/checkout permite hacer checkout de las refs de HEAD de pull requests desde forks. Solo haga esto después de confirmar que el código extraído nunca se ejecuta. La entrada se denomina intencionadamente para ser fácil de detectar en la revisión de código y el análisis estático.
Esta protección solo cubre las referencias de las solicitudes de extracción de las bifurcaciones. Extraer otro código que no es de confianza, como un repositorio de terceros no relacionado, obtener código con git fetch o gh pr checkout, o ejecutar un artefacto descargado, no está cubierto por las comprobaciones de actions/checkout.
Restricción del uso de pull_request_target
Los administradores de repositorio, organización y empresa pueden usar protecciones de ejecución de flujo de trabajo para controlar qué eventos y actores pueden desencadenar flujos de trabajo. Si un repositorio no tiene ningún uso legítimo para pull_request_target, restringiendo elimina el riesgo independientemente de cómo se escriben los flujos de trabajo individuales.