# Uso seguro de pull_request_target

Obtenga información sobre los riesgos de seguridad del pull_request_target evento.

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 explican las protecciones que GitHub se aplican a estos riesgos de forma predeterminada y cómo rechazar esas protecciones si es necesario.

## Riesgos de `pull_request_target`

Los flujos de trabajo activados por `pull_request_target` se ejecutan con un nivel de confianza elevado: el trabajo recibe el `GITHUB_TOKEN` del repositorio base y acceso a los secretos del repositorio y de la organización. 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`](/es/enterprise-server@3.23/actions/reference/workflows-and-actions/events-that-trigger-workflows#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. 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:

```yaml
# 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](https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/) 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, con `git fetch`, `gh pr checkout` o descargando un artefacto de la ejecución de `pull_request` de 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_request` en su lugar?**
  `pull_request` se activa con los mismos eventos que `pull_request_target` y ejecuta el código del flujo de trabajo desde la rama de combinación `pull_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, use `pull_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, vea [Impedir solicitudes pwn](https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/#preventing-pwn-requests) de 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/checkout` extrayendo 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 entrada `path`, `actions/checkout` escribe 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, como `npm install` y `npm 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 evento `pull_request_target`**.

## Refuerzo de un flujo de trabajo `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_TOKEN` tienen 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](/es/enterprise-server@3.23/actions/tutorials/authenticate-with-github_token#modifying-the-permissions-for-the-github_token).

* **Comprenda el impacto en el almacenamiento en caché.** Para reducir el riesgo de intoxicación de caché, los flujos de trabajo desencadenados por `pull_request_target` tienen acceso de solo lectura a la memoria caché en el ámbito de la rama predeterminada. Estos flujos de trabajo pueden restaurar entradas de caché existentes, pero no pueden crearlas ni sobrescribirlas, por lo que no pueden afectar a la ejecución de otros flujos de trabajo, no relacionados, a través de la caché compartida. Si este flujo de trabajo intenta guardar una memoria caché, se produce un error en el guardado, pero el paso y el trabajo continúan, y el error se notifica como una advertencia en el registro de flujo de trabajo. Si su flujo de trabajo necesita poblar la caché, guárdela desde un flujo de trabajo que se ejecute con un activador de confianza, como `push`. Para obtener más información, vea [Referencia de almacenamiento en caché de dependencias](/es/enterprise-server@3.23/actions/reference/workflows-and-actions/dependency-caching#cache-access-for-low-trust-workflow-triggers).

* **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](/es/enterprise-server@3.23/actions/reference/security/secure-use#hardening-for-self-hosted-runners).

* **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](https://securitylab.github.com/resources/github-actions-untrusted-input/) 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](/es/enterprise-server@3.23/code-security/how-tos/find-and-fix-code-vulnerabilities/configure-code-scanning/configure-code-scanning).

## 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 excluirse de la directiva predeterminada de eventos .

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`.