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 Modèles de détection de secrets pris en charge.

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 À propos de la protection push.

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 Analyse des secrets Copilot's générateur d’expressions régulières.

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 Analyse des secrets Copilot's générateur d’expressions régulières

Analyse des secrets Copilot's utilise un modèle IA génératif où vous entrez une description textuelle du type de modèle que vous souhaitez détecter, y compris des exemples facultatifs de chaînes qui doivent être détectées. Le modèle retourne jusqu’à trois expressions régulières pour vous permettre de les vérifier et de faire votre choix. 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.

Sur GitHub, accédez à la page principale du référentiel.
Sous le nom de votre référentiel, cliquez sur Paramètres. Si vous ne voyez pas l’onglet « Paramètres », sélectionnez le menu déroulant , puis cliquez sur Paramètres.
Dans la section « Sécurité » de la barre latérale, cliquez sur Advanced Security.
Under "Secret Protection", to the right of "Custom patterns", click New pattern.
Entrez les détails de votre nouveau modèle personnalisé. Vous devez au moins fournir le nom de votre modèle, ainsi qu’une expression régulière pour le format de votre modèle de secret.
1. Dans le champ Nom du modèle, saisissez un nom pour votre modèle.
2. Dans le champ Format secret, saisissez une expression régulière pour le format de votre modèle secret. Vous pouvez également utiliser le générateur pour générer une expression régulière pour vous. Pour plus d’informations, consultez Generating regular expressions for custom patterns with Copilot secret scanning.
3. Vous pouvez cliquer sur Plus d'options pour fournir d'autres contenus environnants ou des exigences supplémentaires en matière de correspondance pour le format secret.
4. Fournissez un exemple de chaîne de test pour vérifier que votre configuration correspond aux modèles que vous attendez.
When you're ready to test your new custom pattern, to identify matches in the repository without creating alerts, click Save and dry run.
Une fois le test à blanc terminé, vous voyez un échantillon de résultats (jusqu’à 1000). Passez en revue les résultats et identifiez les faux résultats positifs.
Modifiez le nouveau modèle personnalisé pour résoudre les problèmes liés aux résultats, puis cliquez sur Enregistrer et effectuer un test à blanc pour tester vos modifications.
Quand vous êtes satisfait de votre nouveau modèle personnalisé, cliquez sur Publier le modèle.
Optionally, to enable push protection for your custom pattern, click Enable.

Remarque

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

For more information about push protection, see À propos de la protection push.

After your pattern is created, secret scanning recherche les secrets dans l’historique Git de toutes les branches présentes dans votre référentiel GitHub. For more information on viewing Alertes d’analyse de secrets, see Gestion des alertes à partir de l’analyse des secrets.

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 À propos de l'activation des fonctionnalités de sécurité à grande échelle.

Dans le coin supérieur droit de GitHub, cliquez sur votre photo de profil, puis sur Vos organisations.
En regard de l’organisation, cliquez sur Paramètres.
In the "Security" section of the sidebar, select the Advanced Security dropdown menu, then click Global settings.
Sous « Modèles personnalisés », cliquez sur Nouveau modèle.
Entrez les détails de votre nouveau modèle personnalisé. Vous devez au moins fournir le nom de votre modèle, ainsi qu’une expression régulière pour le format de votre modèle de secret.
1. Dans le champ Nom du modèle, saisissez un nom pour votre modèle.
2. Dans le champ Format secret, saisissez une expression régulière pour le format de votre modèle secret. Vous pouvez également utiliser le générateur pour générer une expression régulière pour vous. Pour plus d’informations, consultez Generating regular expressions for custom patterns with Copilot secret scanning.
3. Vous pouvez cliquer sur Plus d'options pour fournir d'autres contenus environnants ou des exigences supplémentaires en matière de correspondance pour le format secret.
4. Fournissez un exemple de chaîne de test pour vérifier que votre configuration correspond aux modèles que vous attendez.
When you're ready to test your new custom pattern, to identify matches in select repositories without creating alerts, click Save and dry run.
Sélectionnez les référentiels dans lesquels vous souhaitez effectuer le test.
- Pour effectuer l’exécution sèche dans l’ensemble de l’organisation, sélectionnez Tous les référentiels de l’organisation.
- Pour spécifier les référentiels dans lesquels vous souhaitez effectuer le test, sélectionnez Référentiels sélectionnés, puis recherchez et sélectionnez jusqu’à 10 référentiels.
Lorsque vous êtes prêt à tester votre nouveau modèle personnalisé, cliquez sur Exécuter.
Une fois le test à blanc terminé, vous voyez un échantillon de résultats (jusqu’à 1000). Passez en revue les résultats et identifiez les faux résultats positifs.
Modifiez le nouveau modèle personnalisé pour résoudre les problèmes liés aux résultats, puis cliquez sur Enregistrer et effectuer un test à blanc pour tester vos modifications.
Quand vous êtes satisfait de votre nouveau modèle personnalisé, cliquez sur Publier le modèle.
Optionally, to enable push protection for your custom pattern, click Enable. For more information, see À propos de la protection push.
Remarque
- L'option permettant d'activer la protection push n'est visible que pour les modèles publiés.
- La protection des envois (push) pour les modèles personnalisés s’applique uniquement aux référentiels de l’organisation sur lesquels l’secret scanning est activée comme protection des envois (push). Pour plus d’informations, consultez « À propos de la protection push ».
- L’activation de la protection des envois (push) pour les modèles personnalisés courants peut entraîner des perturbations pour les contributeurs.

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 Alertes d’analyse de secrets, see Gestion des alertes à partir de l’analyse des secrets.

Defining a custom pattern for an enterprise account

Remarque

At the enterprise level, only the creator of a custom pattern can edit the pattern, and use it in a dry run.
Vous pouvez uniquement effectuer un essai à blanc sur les dépôts auxquels vous bénéficiez d’un accès administrateur. Si un propriétaire d’entreprise souhaite pouvoir effectuer des essais à blanc sur n’importe quel dépôt d’une organisation, le rôle propriétaire d’organisation doit lui être attribué. Pour plus d’informations, consultez « Gestion de votre rôle dans une organisation appartenant à votre entreprise ».

En haut de la page, cliquez sur Stratégies.
Sous » Politiques », cliquez sur Advanced Security.
Under "Advanced Security", click Security features.
Under "Secret scanning custom patterns", click New pattern.
Entrez les détails de votre nouveau modèle personnalisé. Vous devez au moins fournir le nom de votre modèle, ainsi qu’une expression régulière pour le format de votre modèle de secret.
1. Dans le champ Nom du modèle, saisissez un nom pour votre modèle.
2. Dans le champ Format secret, saisissez une expression régulière pour le format de votre modèle secret. Vous pouvez également utiliser le générateur pour générer une expression régulière pour vous. Pour plus d’informations, consultez Generating regular expressions for custom patterns with Copilot secret scanning.
3. Vous pouvez cliquer sur Plus d'options pour fournir d'autres contenus environnants ou des exigences supplémentaires en matière de correspondance pour le format secret.
4. Fournissez un exemple de chaîne de test pour vérifier que votre configuration correspond aux modèles que vous attendez.
When you're ready to test your new custom pattern, to identify matches in the enterprise without creating alerts, click Save and dry run.
Recherchez et sélectionnez jusqu’à 10 référentiels dans lesquels vous souhaitez effectuer le test.
Lorsque vous êtes prêt à tester votre nouveau modèle personnalisé, cliquez sur Exécuter.
Une fois le test à blanc terminé, vous voyez un échantillon de résultats (jusqu’à 1000). Passez en revue les résultats et identifiez les faux résultats positifs.
Modifiez le nouveau modèle personnalisé pour résoudre les problèmes liés aux résultats, puis cliquez sur Enregistrer et effectuer un test à blanc pour tester vos modifications.
Quand vous êtes satisfait de votre nouveau modèle personnalisé, cliquez sur Publier le modèle.
Optionally, to enable push protection for your custom pattern, click Enable. For more information, see À propos de la protection push.
Remarque
- Pour rendre possible la protection des envois (push) dans le cadre des modèles personnalisés, l’secret scanning doit être activée comme protection des envois (push) au niveau de l’entreprise. Pour plus d’informations, consultez « À propos de la protection push ».
- L’activation de la protection des envois (push) pour les modèles personnalisés courants peut entraîner des perturbations pour les contributeurs.

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 Alertes d’analyse de secrets, see Gestion des alertes à partir de l’analyse des secrets.

Qui peut utiliser cette fonctionnalité ?

Dans cet article