Defining custom patterns for secret scanning

About custom patterns for secret scanning

You can define custom patterns to identify secrets that are not detected by the default patterns supported by secret scanning. For example, you might have a secret pattern that is internal to your organization. For details of the supported secrets and service providers, see Patrones de examen de secretos admitidos.

You can define custom patterns for your enterprise, organization, or repository. Secret scanning supports up to 500 custom patterns for each organization or enterprise account, and up to 100 custom patterns per repository.

You can also enable push protection for custom patterns. For more information about push protection, see Acerca de la protección de inserción.

About using regular expressions for custom patterns

You can specify custom patterns for secret scanning as one or more regular expressions.

Secret scanning uses the Hyperscan library and only supports Hyperscan regex constructs, which are a subset of PCRE syntax. Hyperscan option modifiers are not supported. For more information on Hyperscan pattern constructs, see Pattern support in the Hyperscan documentation.

Regular expressions can be entered manually or generated using Digitalización secreta de Copilot's generador de expresiones regulares.

Regular expression syntax for manually defining custom patterns

The More options section in the UI helps you write regular expressions manually.

• Secret format: an expression that describes the format of the secret itself.
• Before secret: an expression that describes the characters that come before the secret. By default, this is set to \A|[^0-9A-Za-z] which means that the secret must be at the start of a line or be preceded by a non-alphanumeric character.
• After secret: an expression that describes the characters that come after the secret. By default, this is set to \z|[^0-9A-Za-z] which means that the secret must be followed by a new line or a non-alphanumeric character.
• Additional match requirements: one or more optional expressions that the secret itself must or must not match.

For simple tokens you will usually only need to specify a secret format. The other fields provide flexibility so that you can specify more complex secrets without creating complex regular expressions. For an example of a custom pattern, see Example of a custom pattern specified using additional requirements below.

Using Digitalización secreta de Copilot's generador de expresiones regulares

generador de expresiones regulares de Digitalización secreta de Copilot usa un modelo de IA generativa donde se introduce una descripción textual del tipo de patrón que deseas detectar, incluidas las cadenas de ejemplo opcionales que se deben detectar. El modelo devuelve hasta tres expresiones regulares para revisar. For more information, see Responsible generation of regular expressions with Copilot secret scanning and Generating regular expressions for custom patterns with Copilot secret scanning.

Defining a custom pattern for a repository

Before defining a custom pattern, you must ensure that Secret Protection is enabled on your repository. For more information, see Enabling secret scanning for your repository.

1. En GitHub, navegue hasta la página principal del repositorio.

2. Debajo del nombre del repositorio, haz clic en Settings. Si no puedes ver la pestaña "Configuración", selecciona el menú desplegable y, a continuación, haz clic en Configuración.

   

3. En la sección "Security" de la barra lateral, haz clic en Advanced Security.

4. Under "Secret Protection", to the right of "Custom patterns", click New pattern.

5. Escribe los detalles del nuevo patrón personalizado. Debes proporcionar por lo menos el nombre de tu patrón y una expresión regular para el formato de tu patrón secreto.

   1. En el campo "Nombre de patrón", escribe un nombre para el patrón.
   2. En el campo "Formato secreto", escriba una expresión regular para el formato del patrón secreto.
   3. Puedes hacer clic en More options para proporcionar otro tipo de contenido circundante o requisitos de coincidencia adicionales para el formato del secreto.
   4. Proporciona una secuencia de pruebas de muestra para asegurarte de que tu configuración empate con los patrones que esperas.
   

6. When you're ready to test your new custom pattern, to identify matches in the repository without creating alerts, click Save and dry run.

7. Cuando termine el simulacro verás un ejemplo de los resultados (hasta 1000). Revisa los resultados e identifica cualquier falso positivo.

   

8. Edita el nuevo patrón personalizado para corregir cualquier problema con los resultados y, después, haz clic en Guardar y realizar simulacro para probar los cambios.

9. Cuando el nuevo patrón personalizado sea satisfactorio, haz clic en Publicar patrón.

10. Optionally, to enable push protection for your custom pattern, click Enable.

    Nota:

    The "Enable" button isn't available until after the dry run succeeds and you publish the pattern.

    For more information about push protection, see Acerca de la protección de inserción.

After your pattern is created, El secret scanning escanea cualquier secreto en el total de tu historial de Git en todas las ramas presentes de tu repositorio de GitHub. For more information on viewing alertas de examen de secretos, see Administración de alertas del examen de secretos.

Example of a custom pattern specified using additional requirements

A company has an internal token with five characteristics. They use the different fields to specify how to identify tokens as follows:

Characteristic	Field and regular expression
Length between 5 and 10 characters	Secret format: [$#%@AA-Za-z0-9]{5,10}
Does not end in a .	After secret: [^\.]
Contains numbers and uppercase letters	Additional requirements: secret must match [A-Z] and [0-9]
Does not include more than one lowercase letter in a row	Additional requirements: secret must not match [a-z]{2,}
Contains one of $%@!	Additional requirements: secret must match [$%@!]

These tokens would match the custom pattern described above:

a9@AAfT!         # Secret string match: a9@AAfT
ee95GG@ZA942@aa  # Secret string match: @ZA942@a
a9@AA!ee9        # Secret string match: a9@AA

These strings would not match the custom pattern described above:

a9@AA.!
a@AAAAA
aa9@AA!ee9
aAAAe9

Defining a custom pattern for an organization

Before defining a custom pattern, you must ensure that you enable secret scanning for the repositories that you want to scan in your organization. You can use security configurations to enable secret scanning on all repositories in your organization. For more information, see Habilitación de características de seguridad a gran escala.

1. En la esquina superior derecha de GitHub, haz clic en la foto del perfil y luego en Your organizations.

2. Junto a la organización, haga clic en Settings.

3. In the "Security" section of the sidebar, select the Advanced Security dropdown menu, then click Global settings.

4. En «Patrones personalizados», haz clic en Nuevo patrón.

5. Escribe los detalles del nuevo patrón personalizado. Debes proporcionar por lo menos el nombre de tu patrón y una expresión regular para el formato de tu patrón secreto.

   1. En el campo "Nombre de patrón", escribe un nombre para el patrón.
   2. En el campo "Formato secreto", escriba una expresión regular para el formato del patrón secreto.
   3. Puedes hacer clic en More options para proporcionar otro tipo de contenido circundante o requisitos de coincidencia adicionales para el formato del secreto.
   4. Proporciona una secuencia de pruebas de muestra para asegurarte de que tu configuración empate con los patrones que esperas.
   

6. When you're ready to test your new custom pattern, to identify matches in select repositories without creating alerts, click Save and dry run.

7. Seleccione los repositorios en los que desea realizar el simulacro.

   • Para realizar la ejecución en seco en toda la organización, seleccione Todos los repositorios de la organización.
   • Para especificar los repositorios en los que desea realizar el simulacro, seleccione Repositorios seleccionados, busque y seleccione hasta 10 repositorios.

8. Cuando tenga todo listo para probar el nuevo patrón personalizado, haga clic en Ejecutar.

9. Cuando termine el simulacro verás un ejemplo de los resultados (hasta 1000). Revisa los resultados e identifica cualquier falso positivo.

   

10. Edita el nuevo patrón personalizado para corregir cualquier problema con los resultados y, después, haz clic en Guardar y realizar simulacro para probar los cambios.

11. Cuando el nuevo patrón personalizado sea satisfactorio, haz clic en Publicar patrón.

12. Optionally, to enable push protection for your custom pattern, click Enable. For more information, see Acerca de la protección de inserción.

    Nota:

    • La opción para habilitar la protección de inserción solo es visible para los patrones publicados.
    • La protección de inserción para patrones personalizados solo se aplicará a los repositorios de tu organización que tengan secret scanning como protección de inserción habilitada. Para más información, consulta Acerca de la protección de inserción.
    • La habilitación de la protección de inserción para patrones personalizados que se encuentran habitualmente puede ser perjudicial para los colaboradores.

After your pattern is created, secret scanning scans for any secrets in repositories in your organization, including their entire Git history on all branches. Organization owners and repository administrators will be alerted to any secrets found and can review the alert in the repository where the secret is found. For more information on viewing alertas de examen de secretos, see Administración de alertas del examen de secretos.

Defining a custom pattern for an enterprise account

1. En la parte superior de la página, haz clic en Policies.

2. En "Directivas", haz clic en Advanced Security.

3. Under "Advanced Security", click Security features.

4. Under "Secret scanning custom patterns", click New pattern.

5. Escribe los detalles del nuevo patrón personalizado. Debes proporcionar por lo menos el nombre de tu patrón y una expresión regular para el formato de tu patrón secreto.

   1. En el campo "Nombre de patrón", escribe un nombre para el patrón.
   2. En el campo "Formato secreto", escriba una expresión regular para el formato del patrón secreto.
   3. Puedes hacer clic en More options para proporcionar otro tipo de contenido circundante o requisitos de coincidencia adicionales para el formato del secreto.
   4. Proporciona una secuencia de pruebas de muestra para asegurarte de que tu configuración empate con los patrones que esperas.
   

6. When you're ready to test your new custom pattern, to identify matches in the enterprise without creating alerts, click Save and dry run.

7. Busca y selecciona hasta 10 repositorios en los que quieras realizar el simulacro.

8. Cuando tenga todo listo para probar el nuevo patrón personalizado, haga clic en Ejecutar.

9. Cuando termine el simulacro verás un ejemplo de los resultados (hasta 1000). Revisa los resultados e identifica cualquier falso positivo.

   

10. Edita el nuevo patrón personalizado para corregir cualquier problema con los resultados y, después, haz clic en Guardar y realizar simulacro para probar los cambios.

11. Cuando el nuevo patrón personalizado sea satisfactorio, haz clic en Publicar patrón.

12. Optionally, to enable push protection for your custom pattern, click Enable. For more information, see Acerca de la protección de inserción.

    Nota:

    • Para habilitar la protección de inserción para patrones personalizados, secret scanning porque la protección de inserción debe habilitarse en el nivel empresarial. Para más información, consulta Acerca de la protección de inserción.
    • La habilitación de la protección de inserción para patrones personalizados que se encuentran habitualmente puede ser perjudicial para los colaboradores.

After your pattern is created, secret scanning scans for any secrets in repositories within your organizations with GitHub Secret Protection enabled, including their entire Git history on all branches. Organization owners and repository administrators will be alerted to any secrets found, and can review the alert in the repository where the secret is found. For more information on viewing alertas de examen de secretos, see Administración de alertas del examen de secretos.

Further reading

• Managing custom patterns
• Métricas para patrones personalizados