{"id":660,"date":"2026-03-06T18:09:45","date_gmt":"2026-03-06T17:09:45","guid":{"rendered":"https:\/\/secure-pipelines.com\/?p=660"},"modified":"2026-03-24T18:08:01","modified_gmt":"2026-03-24T17:08:01","slug":"lab-hardening-github-actions-workflows-permissions-pinning-secrets","status":"publish","type":"post","link":"https:\/\/secure-pipelines.com\/es\/ci-cd-security\/lab-hardening-github-actions-workflows-permissions-pinning-secrets\/","title":{"rendered":"Lab: Hardening de Workflows GitHub Actions \u2014 Permisos, Pinning y Secretos"},"content":{"rendered":"

Descripci\u00f3n General<\/h2>\n

GitHub Actions se ha convertido en la plataforma de CI\/CD m\u00e1s ampliamente adoptada tanto para software de c\u00f3digo abierto como comercial. Esa popularidad la convierte en la superficie de ataque n\u00famero uno en el panorama CI\/CD. Los workflows mal configurados filtran secretos de forma rutinaria, otorgan permisos excesivos e incorporan c\u00f3digo de terceros que puede ser manipulado silenciosamente.<\/p>\n

En este lab pr\u00e1ctico, endurecer\u00e1s un workflow de GitHub Actions deliberadamente inseguro utilizando las tres t\u00e9cnicas de mayor impacto disponibles actualmente:<\/p>\n

    \n
  1. Permisos m\u00ednimos<\/strong> \u2014 restringir el GITHUB_TOKEN<\/code> \u00fanicamente a los scopes que cada job realmente necesita.<\/li>\n
  2. SHA pinning<\/strong> \u2014 referenciar cada action de terceros por su SHA de commit inmutable en lugar de un tag mutable.<\/li>\n
  3. Protecci\u00f3n de secretos<\/strong> \u2014 delimitar los secretos a environments con puertas de aprobaci\u00f3n y prevenir fugas a trav\u00e9s de pull requests basados en forks.<\/li>\n<\/ol>\n

    Al finalizar el lab, tendr\u00e1s una plantilla de workflow de nivel producci\u00f3n que puedes incorporar en cualquier repositorio.<\/p>\n

    Requisitos Previos<\/h2>\n
      \n
    • Una cuenta de GitHub con permisos para crear repositorios.<\/li>\n
    • Familiaridad b\u00e1sica con la sintaxis YAML de GitHub Actions (triggers, jobs, steps).<\/li>\n
    • El CLI gh<\/code> instalado (opcional pero \u00fatil para consultar SHAs de actions).<\/li>\n<\/ul>\n

      Configuraci\u00f3n del Entorno<\/h2>\n

      Crear un Repositorio de Prueba<\/h3>\n

      Crea un nuevo repositorio p\u00fablico en GitHub llamado gha-hardening-lab<\/code>. Puedes hacerlo a trav\u00e9s de la interfaz o con el CLI:<\/p>\n

      gh repo create gha-hardening-lab --public --clone\ncd gha-hardening-lab<\/code><\/pre>\n
      Inicializa un proyecto Node.js m\u00ednimo para que el workflow tenga algo que construir:<\/p>\n
      npm init -y\ncat <<'EOF' > index.js\nconsole.log(\"Hello from the hardening lab\");\nEOF\ngit add -A && git commit -m \"Initial commit\" && git push<\/code><\/pre>\n
      El Workflow Inicial (Inseguro)<\/h3>\n
      Crea el archivo .github\/workflows\/build.yml<\/code> con el siguiente contenido. Este workflow es intencionalmente inseguro \u2014 no tiene bloque de permissions, usa tags mutables y expone secretos de forma demasiado amplia:<\/p>\n
      # .github\/workflows\/build.yml  \u2014 Punto de partida INSEGURO\nname: Build\n\non:\n  push:\n  pull_request_target:\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions\/checkout@v4\n      - uses: actions\/setup-node@v4\n        with:\n          node-version: 20\n      - run: npm install\n      - run: npm test\n        env:\n          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}\n      - uses: actions\/upload-artifact@v4\n        with:\n          name: build-output\n          path: .\n<\/code><\/pre>\n
      Haz commit y push de este archivo. Se ejecutar\u00e1 correctamente, pero tiene al menos cinco problemas de seguridad que corregir\u00e1s en los ejercicios siguientes.<\/p>\n
      Ejercicio 1: Permisos M\u00ednimos<\/h2>\n
      El Problema con los Permisos por Defecto<\/h3>\n
      Cuando un workflow no declara un bloque permissions<\/code>, el GITHUB_TOKEN<\/code> recibe los permisos por defecto del repositorio. Para la mayor\u00eda de los repositorios, esto significa acceso de lectura y escritura a cada scope<\/strong> \u2014 contents, packages, issues, pull requests, deployments y m\u00e1s. Si un atacante compromete cualquier step en ese workflow, hereda todos esos permisos.<\/p>\n
      El principio de m\u00ednimo privilegio exige que otorgues \u00fanicamente los permisos que cada job realmente requiere, y nada m\u00e1s.<\/p>\n
      Paso 1 \u2014 Establecer un Valor por Defecto Restrictivo a Nivel Superior<\/h3>\n
      A\u00f1ade una clave permissions<\/code> a nivel superior inmediatamente despu\u00e9s del bloque on:<\/code>. Esto establece el valor por defecto para cada job en el workflow:<\/p>\n
      permissions:\n  contents: read\n<\/code><\/pre>\n
      Si deseas comenzar con el valor por defecto m\u00e1s restrictivo posible y luego otorgar permisos por job, puedes usar un mapa vac\u00edo:<\/p>\n
      permissions: {}\n<\/code><\/pre>\n
      Paso 2 \u2014 A\u00f1adir Permisos por Job<\/h3>\n
      Cada job puede sobrescribir el valor por defecto a nivel de workflow. Otorga \u00fanicamente lo que el job necesita:<\/p>\n
      jobs:\n  build:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read       # check out code\n      actions: read        # read workflow metadata\n    steps:\n      - uses: actions\/checkout@v4\n      # ...\n<\/code><\/pre>\n
      Si un segundo job necesita subir un asset de release, le otorgar\u00edas contents: write<\/code> \u00fanicamente a ese job \u2014 nunca a nivel de workflow.<\/p>\n
      Antes y Despu\u00e9s<\/h3>\n
      Antes (inseguro):<\/strong><\/p>\n
      name: Build\non:\n  push:\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions\/checkout@v4\n      - run: npm install\n<\/code><\/pre>\n
      Despu\u00e9s (endurecido):<\/strong><\/p>\n
      name: Build\non:\n  push:\n    branches: [main]\n\npermissions:\n  contents: read\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n    permissions:\n      contents: read\n      actions: read\n    steps:\n      - uses: actions\/checkout@v4\n      - run: npm install\n<\/code><\/pre>\n
      Verificar los Permisos Efectivos<\/h3>\n
      Despu\u00e9s de que el workflow se ejecute, abre el job en la pesta\u00f1a Actions. Haz clic en el \u00edcono de engranaje en la parte superior derecha del log del job y selecciona \u201cSet up job\u201d<\/strong>. Expande esa secci\u00f3n para ver los permisos exactos del GITHUB_TOKEN<\/code> que fueron otorgados. Confirma que solo aparecen contents: read<\/code> y actions: read<\/code>.<\/p>\n
      Tambi\u00e9n puedes consultar los permisos program\u00e1ticamente dentro de un step:<\/p>\n
      - name: Print token permissions\n  run: |\n    curl -s -H \"Authorization: Bearer ${{ secrets.GITHUB_TOKEN }}\" \\\n      https:\/\/api.github.com\/repos\/${{ github.repository }} \\\n      | jq '.permissions'\n<\/code><\/pre>\n
      Ejercicio 2: Fijar Actions por SHA<\/h2>\n
      Por Qu\u00e9 los Tags Son Peligrosos<\/h3>\n
      Cuando escribes uses: actions\/checkout@v4<\/code>, est\u00e1s referenciando un tag de Git. Los tags son mutables \u2014 el mantenedor de la action (o un atacante que comprometa su cuenta) puede eliminar y recrear el tag apuntando a un c\u00f3digo completamente diferente. Tu workflow entonces ejecutar\u00eda silenciosamente el nuevo c\u00f3digo en su siguiente ejecuci\u00f3n. El SHA pinning elimina este riesgo porque un SHA de commit es inmutable.<\/p>\n
      Paso 1 \u2014 Encontrar el SHA de una Action<\/h3>\n
      Usa el CLI gh<\/code> para resolver un tag a su SHA de commit:<\/p>\n
      # Resolver actions\/checkout@v4 a un SHA de commit\ngh api repos\/actions\/checkout\/git\/ref\/tags\/v4 --jq '.object.sha'<\/code><\/pre>\n
      Si el tag es anotado (la mayor\u00eda lo son), el comando anterior devuelve el SHA del objeto tag. Necesitas desreferenciarlo al commit:<\/p>\n
      TAG_SHA=$(gh api repos\/actions\/checkout\/git\/ref\/tags\/v4 --jq '.object.sha')\ngh api repos\/actions\/checkout\/git\/tags\/$TAG_SHA --jq '.object.sha'<\/code><\/pre>\n
      Alternativamente, visita el repositorio de la action en GitHub, haz clic en el tag y copia el SHA de commit completo desde la URL o el encabezado del commit.<\/p>\n
      Paso 2 \u2014 Fijar las Actions Comunes<\/h3>\n
      Reemplaza cada tag mutable con el SHA completo de 40 caracteres. Siempre a\u00f1ade un comentario al final con la versi\u00f3n para facilitar la lectura:<\/p>\n
      steps:\n  - uses: actions\/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2\n  - uses: actions\/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0\n    with:\n      node-version: 20\n  - uses: actions\/cache@5a3ec84eff668545956fd18022155c47e93e2684 # v4.2.3\n    with:\n      path: ~\/.npm\n      key: ${{ runner.os }}-node-${{ hashFiles('**\/package-lock.json') }}\n  - uses: actions\/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2\n    with:\n      name: build-output\n      path: dist\/\n<\/code><\/pre>\n
      Paso 3 \u2014 Automatizar las Actualizaciones de SHA con Dependabot<\/h3>\n
      Fijar por SHA significa que ya no recibir\u00e1s actualizaciones autom\u00e1ticas basadas en tags. Dependabot resuelve esto abriendo pull requests cada vez que una action fijada publica una nueva versi\u00f3n.<\/p>\n
      Crea el archivo .github\/dependabot.yml<\/code>:<\/p>\n
      version: 2\nupdates:\n  - package-ecosystem: \"github-actions\"\n    directory: \"\/\"\n    schedule:\n      interval: \"weekly\"\n    commit-message:\n      prefix: \"ci\"\n<\/code><\/pre>\n
      Despu\u00e9s de hacer push de este archivo, Dependabot escanear\u00e1 tus workflows semanalmente y abrir\u00e1 PRs para actualizar los SHAs fijados. Cada PR muestra el diff del c\u00f3digo de la action, d\u00e1ndote la oportunidad de revisar antes de hacer merge.<\/p>\n
      Si prefieres Renovate en lugar de Dependabot, a\u00f1ade un archivo renovate.json<\/code> en la ra\u00edz del repositorio:<\/p>\n
      {\n  \"$schema\": \"https:\/\/docs.renovatebot.com\/renovate-schema.json\",\n  \"extends\": [\"config:recommended\"],\n  \"github-actions\": {\n    \"enabled\": true\n  }\n}\n<\/code><\/pre>\n
      Ejercicio 3: Protecci\u00f3n de Secretos<\/h2>\n
      Repository Secrets vs. Environment Secrets<\/h3>\n
      GitHub ofrece dos niveles de almacenamiento de secretos:<\/p>\n
        \n
      • Repository secrets<\/strong> \u2014 disponibles para cada workflow y cada job en el repositorio. Convenientes pero excesivamente amplios.<\/li>\n
      • Environment secrets<\/strong> \u2014 disponibles \u00fanicamente para jobs que declaren expl\u00edcitamente environment: <nombre><\/code>. Este es el enfoque recomendado para credenciales sensibles.<\/li>\n<\/ul>\n
        Paso 1 \u2014 Crear un Environment con Reglas de Protecci\u00f3n<\/h3>\n
        En tu repositorio, navega a Settings \u2192 Environments<\/strong> y crea un environment llamado production<\/code>. Habilita las siguientes reglas de protecci\u00f3n:<\/p>\n
          \n
        1. Required reviewers<\/strong> \u2014 a\u00f1ade al menos un miembro del equipo que debe aprobar los deployments.<\/li>\n
        2. Wait timer<\/strong> \u2014 opcionalmente a\u00f1ade un retraso (por ejemplo, 5 minutos) para dar tiempo a los revisores.<\/li>\n
        3. Deployment branches<\/strong> \u2014 restringe \u00fanicamente a main<\/code>.<\/li>\n<\/ol>\n
          Ahora a\u00f1ade tu DEPLOY_TOKEN<\/code> como secreto dentro de este environment, no a nivel de repositorio.<\/p>\n
          Paso 2 \u2014 Referenciar el Environment en Tu Workflow<\/h3>\n
          jobs:\n  deploy:\n    runs-on: ubuntu-latest\n    environment: production\n    permissions:\n      contents: read\n    steps:\n      - uses: actions\/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2\n      - name: Deploy\n        run: .\/deploy.sh\n        env:\n          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}\n<\/code><\/pre>\n
          La declaraci\u00f3n environment: production<\/code> significa que este job se pausar\u00e1 y esperar\u00e1 a que un revisor lo apruebe antes de que cualquier step se ejecute. El secreto DEPLOY_TOKEN<\/code> solo est\u00e1 disponible dentro de este environment \u2014 no puede ser accedido por otros jobs o workflows que no declaren este environment.<\/p>\n
          Paso 3 \u2014 Entender el Comportamiento con Forks<\/h3>\n
          Los secretos no<\/strong> est\u00e1n disponibles para workflows disparados por eventos pull_request<\/code> desde forks. Esta es una frontera de seguridad cr\u00edtica. Si creas un workflow que depende de secretos durante las verificaciones de PR, fallar\u00e1 para contribuidores externos:<\/p>\n
          # Este step fallar\u00e1 para PRs basados en forks porque DEPLOY_TOKEN est\u00e1 vac\u00edo\n- name: Authenticated API call\n  run: |\n    curl -H \"Authorization: Bearer $DEPLOY_TOKEN\" https:\/\/api.example.com\/health\n  env:\n    DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}\n<\/code><\/pre>\n
          Esto es por dise\u00f1o<\/strong> \u2014 evita que forks maliciosos exfiltren tus secretos.<\/p>\n
          Paso 4 \u2014 El Peligro de pull_request_target<\/h3>\n
          El trigger pull_request_target<\/code> se ejecuta en el contexto del repositorio base<\/strong>, lo que significa que s\u00ed<\/em> tiene acceso a los secretos. Esto es extremadamente peligroso si tambi\u00e9n haces checkout del c\u00f3digo head del PR:<\/p>\n
          # PELIGROSO \u2014 NO HAGAS ESTO\non:\n  pull_request_target:\n\njobs:\n  build:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions\/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2\n        with:\n          ref: ${{ github.event.pull_request.head.sha }}  # Checks out UNTRUSTED code\n      - run: npm install  # Executes attacker-controlled code with access to secrets\n        env:\n          DEPLOY_TOKEN: ${{ secrets.DEPLOY_TOKEN }}\n<\/code><\/pre>\n
          Un atacante puede modificar package.json<\/code> para incluir un script postinstall<\/code> que exfiltre DEPLOY_TOKEN<\/code>. Nunca combines pull_request_target<\/code> con un checkout del head del PR a menos que hayas validado y aislado expl\u00edcitamente el c\u00f3digo.<\/p>\n
          Alternativa segura:<\/strong> Usa el trigger est\u00e1ndar pull_request<\/code> para workflows de build y test. Reserva pull_request_target<\/code> \u00fanicamente para workflows de etiquetado o comentarios que nunca ejecuten c\u00f3digo del PR.<\/p>\n
          Resumen de Mejores Pr\u00e1cticas<\/h3>\n