Skip to main content

Protecting pushes with secret scanning

You can use secret scanning to prevent supported secrets from being pushed into your enterprise, organization, or repository by enabling push protection.

Secret scanning for advanced security is available for organization-owned repositories in GitHub Enterprise Cloud if your enterprise has a license for GitHub Advanced Security. Para más información, consulte "Acerca de GitHub Advanced Security".

Nota: Secret scanning como inserción de protección se encuentra actualmente en versión beta y está sujeta a cambios. Para solicitar acceso a la versión beta, póngase en contacto con el equipo de administración de la cuenta.

About push protection for secrets

Up to now, secret scanning for advanced security checks for secrets after a push and alerts users to exposed secrets. Al habilitar la protección de inserción, secret scanning también comprueba si hay secretos de alta confianza (los identificados con una tasa de falsos positivos baja). Secret scanning enumera los secretos que detecta para que el creador pueda revisarlos y quitarlos, o si es necesario, permitir que se inserten.

If a contributor bypasses a push protection block for a secret, GitHub:

  • creates an alert in the "Security" tab of the repository in the state described in the table below.
  • adds the bypass event to the audit log.
  • sends an email alert to organization owners, security managers, and repository administrators who are watching the repository, with a link to the secret and the reason why it was allowed.

En esta tabla se muestra el comportamiento de las alertas para cada forma en que un usuario puede omitir un bloque de protección de inserción.

Razón de la omisiónComportamiento de alerta
Se usa en pruebasGitHub crea una alerta cerrada, resuelta como "se usa en pruebas"
Es un falso positivoGitHub crea una alerta cerrada, resuelta como "falso positivo"
Lo arreglaré más tardeGitHub crea una alerta abierta

For information on the secrets and service providers supported for push protection, see "Secret scanning patterns."

Enabling secret scanning as a push protection

For you to use secret scanning as a push protection, the enterprise, organization, or repository needs to have both GitHub Advanced Security and secret scanning enabled. For more information, see "Managing security and analysis settings for your enterprise," "Managing security and analysis settings for your organization," "Managing security and analysis settings for your repository," and "About GitHub Advanced Security."

Organization owners, security managers, and repository administrators can enable push protection for secret scanning via the UI and API. For more information, see "Repositories" and expand the "Properties of the security_and_analysis object" section in the REST API documentation.

Enabling secret scanning as a push protection for your enterprise

  1. En la esquina superior derecha de GitHub.com, haga clic en la imagen de perfil y después en Your enterprises. "Your enterprises" en el menú desplegable de la imagen de perfil en GitHub Enterprise Cloud

  2. En la lista de empresas, da clic en aquella que quieras ver. Nombre de una empresa en la lista de sus empresas

  3. En la barra lateral de la cuenta de empresa, haga clic en Configuración. Pestaña Configuración en la barra lateral de la cuenta de empresa

  4. In the left sidebar, click Code security and analysis.

  5. Under "Secret scanning", under "Push protection", click Enable all.

    Screenshot showing how to enable push protection for secret scanning for an enterprise

  6. Optionally, click "Automatically enable for repositories added to secret scanning."

  7. Optionally, to include a custom link in the message that members will see when they attempt to push a secret, click Add a resource link in the CLI and web UI when a commit is blocked, then type a URL, and click Save link.

    Screenshot showing checkbox and text field for enabling a custom link

Enabling secret scanning as a push protection for an organization

  1. On GitHub.com, navigate to the main page of the organization.

  2. Debajo del nombre de la organización, haga clic en Settings. Botón de configuración de la organización

  3. In the "Security" section of the sidebar, click Code security and analysis.

  4. Debajo de "Seguridad y análisis de código", encuentra "GitHub Advanced Security".

  5. Under "Secret scanning", under "Push protection", click Enable all. Screenshot showing how to enable push protection for secret scanning for an organization

  6. Optionally, click "Automatically enable for repositories added to secret scanning."

  7. Optionally, to include a custom link in the message that members will see when they attempt to push a secret, select Add a resource link in the CLI and web UI when a commit is blocked, then type a URL, and click Save link.

    Screenshot showing checkbox and text field for enabling a custom link

Enabling secret scanning as a push protection for a repository

  1. On GitHub.com, navigate to the main page of the repository.

  2. Debajo del nombre del repositorio, haz clic en Configuración. Botón de configuración del repositorio

  3. In the "Security" section of the sidebar, click Code security and analysis.

  4. Debajo de "Seguridad y análisis de código", encuentra "GitHub Advanced Security".

  5. En "Secret scanning", en "Push protection" (Protección de inserciones), haga clic en Enable (Habilitar). Captura de pantalla en la que se muestra cómo habilitar la protección de inserciones para secret scanning para un repositorio

Using secret scanning as a push protection from the command line

Al intentar insertar un secreto admitido en un repositorio u organización con secret scanning como protección de inserción habilitada, GitHub bloqueará la inserción. Puedes quitar el secreto de la rama o seguir una dirección URL proporcionada para permitir la inserción.

Up to five detected secrets will be displayed at a time on the command line. If a particular secret has already been detected in the repository and an alert already exists, GitHub will not block that secret.

Organization admins can provide a custom link that will be displayed when a push is blocked. This custom link can contain organization-specific resources and advice, such as directions on using a recommended secrets vault or who to contact for questions relating to the blocked secret.

Screenshot showing that a push is blocked when a user attempts to push a secret to a repository

Si confirmas que un secreto es real, debes quitar el secreto de la rama, de todas las confirmaciones en las que aparece, antes de volver a insertar. For more information about remediating blocked secrets, see "Pushing a branch blocked by push protection."

If you confirm a secret is real and that you intend to fix it later, you should aim to remediate the secret as soon as possible. For example, you might revoke the secret and remove the secret from the repository's commit history. Real secrets that have been exposed must be revoked to avoid unauthorized access. You might consider first rotating the secret before revoking it. For more information, see "Removing sensitive data from a repository."

Notas:

  • Si la configuración de Git admite inserciones en varias ramas y no solo en la actual, es posible que se bloquee la inserción debido a que se insertan referencias adicionales y no deseadas. Para obtener más información, consulta las opciones push.default en la documentación de Git.
  • Si se agota el tiempo de espera de secret scanning tras una inserción, GitHub todavía examinará las confirmaciones en busca de secretos después de la inserción.

Allowing a blocked secret to be pushed

If GitHub blocks a secret that you believe is safe to push, you can allow the secret and specify the reason why it should be allowed.

Cuando permites la inserción de un secreto, se crea una alerta en la pestaña "Seguridad". GitHub cierra la alerta y no envía una notificación si especificas que el secreto es un falso positivo o que solo se usa en las pruebas. Si especificas que el secreto es real y lo corregirás más adelante, GitHub mantiene abierta la alerta de seguridad y envía notificaciones al creador de la confirmación, así como a los administradores del repositorio. Para más información, vea "Administración de alertas del análisis de secretos".

Cuando un colaborador omite un bloque de protección de inserción para un secreto, GitHub también envía una alerta por correo electrónico a los propietarios de la organización, los administradores de seguridad y los administradores de repositorios que han optado por recibir notificaciones por correo electrónico.

  1. Visit the URL returned by GitHub when your push was blocked. Screenshot showing form with options for unblocking the push of a secret
  2. Elija la opción que mejor describa por qué debería poder insertar el secreto.
    • Si el secreto solo se usa en pruebas y no supone ninguna amenaza, haga clic en Se usa en las pruebas.
    • Si la cadena detectada no es un secreto, haga clic en Es un falso positivo.
    • Si el secreto es real, pero piensa corregirlo más adelante, haga clic en Lo corregiré más adelante.
  3. Click Allow me to push this secret.
  4. Reattempt the push on the command line within three hours. If you have not pushed within three hours, you will need to repeat this process.

Using secret scanning as a push protection from the web UI

Cuando se usa la interfaz de usuario web para intentar confirmar un secreto admitido en un repositorio u organización con el examen de secretos como protección de inserción habilitada, GitHub bloqueará la confirmación.

Verás un banner en la parte superior de la página con información sobre la ubicación del secreto, y el secreto también estará subrayado en el archivo para que puedas encontrarlo fácilmente.

Captura de pantalla que muestra la confirmación en la interfaz de usuario web bloqueada debido a la protección de inserción de análisis de secretos

GitHub will only display one detected secret at a time in the web UI. If a particular secret has already been detected in the repository and an alert already exists, GitHub will not block that secret.

Organization admins can provide a custom link that will be displayed when a push is blocked. This custom link can contain resources and advice specific to your organization. For example, the custom link can point to a README file with information about the organization's secret vault, which teams and individuals to escalate questions to, or the organization's approved policy for working with secrets and rewriting commit history.

You can remove the secret from the file using the web UI. Once you remove the secret, the banner at the top of the page will change and tell you that you can now commit your changes.

Screenshot showing commit in web ui allowed after secret fixed

Bypassing push protection for a secret

Si confirmas que un secreto es real, debes quitar el secreto de la rama, de todas las confirmaciones en las que aparece, antes de volver a insertar. For more information about remediating blocked secrets, see "Pushing a branch blocked by push protection."

If you confirm a secret is real and that you intend to fix it later, you should aim to remediate the secret as soon as possible. For more information, see "Removing sensitive data from a repository."

If GitHub blocks a secret that you believe is safe to push, you can allow the secret and specify the reason why it should be allowed.

Cuando permites la inserción de un secreto, se crea una alerta en la pestaña "Seguridad". GitHub cierra la alerta y no envía una notificación si especificas que el secreto es un falso positivo o que solo se usa en las pruebas. Si especificas que el secreto es real y lo corregirás más adelante, GitHub mantiene abierta la alerta de seguridad y envía notificaciones al creador de la confirmación, así como a los administradores del repositorio. Para más información, vea "Administración de alertas del análisis de secretos".

Cuando un colaborador omite un bloque de protección de inserción para un secreto, GitHub también envía una alerta por correo electrónico a los propietarios de la organización, los administradores de seguridad y los administradores de repositorios que han optado por recibir notificaciones por correo electrónico.

If you confirm a secret is real and that you intend to fix it later, you should aim to remediate the secret as soon as possible.

  1. In the banner that appeared at the top of the page when GitHub blocked your commit, click Bypass protection.

  2. Elija la opción que mejor describa por qué debería poder insertar el secreto.

    • Si el secreto solo se usa en pruebas y no supone ninguna amenaza, haga clic en Se usa en las pruebas.
    • Si la cadena detectada no es un secreto, haga clic en Es un falso positivo.
    • Si el secreto es real, pero piensa corregirlo más adelante, haga clic en Lo corregiré más adelante.

    Screenshot showing form with options for unblocking the push of a secret

  3. Click Allow secret.