CONTRIBUTING.md

Contribution guidelines

General

Issues

If you have a feature or bug fix you would like to contribute please check if there are any open issues describing your proposed addition. If there are open issues, make a comment stating you are working on fixing or implementing said issue. If not, then please open an issue describing your addition. Make sure to link your PR to an issue.

Pull Requests

Fill out the template as best you can. Make sure your tests pass. If you see a PR that isn't one you opened and want it introduced in the next release, give it a 👍 on the PR description.

Adding new Gitleaks rules

If you want to add a new rule to the default Gitleaks configuration then follow these steps.

1. Create a cmd/generate/config/rules/{provider}.go file. This file is used to generate a new Gitleaks rule. Let's look at beamer.go for example. Comments have been added for context.

   func Beamer() *config.Rule {
       // Define Rule
       r := config.Rule{
           // Human readable description of the rule
           Description: "Beamer API token",
   
           // Unique ID for the rule
           RuleID:      "beamer-api-token",
   
           // Regex capture group for the actual secret
           SecretGroup: 1,
   
   
           // Regex used for detecting secrets. See regex section below for more details
           Regex: generateSemiGenericRegex([]string{"beamer"}, `b_[a-z0-9=_\-]{44}`, true)
   
           // Keywords used for string matching on fragments (think of this as a prefilter)
           Keywords: []string{"beamer"},
       }
   
       // validate
       tps := []string{
           generateSampleSecret("beamer", "b_"+secrets.NewSecret(alphaNumericExtended("44"))),
       }
       return validate(r, tps, nil)
   }

   Feel free to use this example as a template when writing new rules. This file should be fairly self-explanatory except for a few items; regex and secret generation. To help with maintence, most rules should be uniform. The functions, generateSemiGenericRegex and generateUniqueTokenRegex will generate rules that follow defined patterns.

   The function signatures look like this:

   func generateSemiGenericRegex(identifiers []string, secretRegex string, isCaseInsensitive bool) *regexp.Regexp
   
   func generateUniqueTokenRegex(secretRegex string, isCaseInsensitive bool) *regexp.Regexp

   generateSemiGenericRegex accepts a list of identifiers, a regex, and a boolean indicating whether the pattern should be case-insensitive. The list of identifiers should match the list of Keywords in the rule definition above. Both identifiers in the generateSemiGenericRegex function and Keywords act as filters for Gitleaks telling the program "at least one of these strings must be present to be considered a leak"

   generateUniqueToken just accepts a regex and a boolean indicating whether the pattern should be case-insensitive. If you are writing a rule for a token that is unique enough not to require an identifier then you can use this function. For example, Pulumi's API Token has the prefix pul- which is unique enough to use generateUniqueToken. But something like Beamer's API token that has a b_ prefix is not unique enough to use generateUniqueToken, so instead we use generateSemiGenericRegex and require a beamer identifier is part of the rule. If a token's prefix has more than 3 characters then you could probably get away with using generateUniqueToken.

   Last thing you'll want to hit before we move on from this file is the validation part. You can use generateSampleSecret to create a secret for the true positives (tps in the example above) used in validate.

2. Update cmd/generate/config/main.go. Add a line like configRules = append(configRules, rules.Beamer()) in main(). Try and keep this alphabetically pretty please.

3. Change directories into cmd/generate/config and run go run main.go

   cd cmd/generate/config && go run main.go
   

4. Check out your new rules in config/gitleaks.toml and see if everything looks good.

5. Open a PR