1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
|
# 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 :thumbsup: on the PR description.
## Adding new Gitleaks rules
If you want to add a new rule to the [default Gitleaks configuration](https://github.com/zricethezav/gitleaks/blob/master/config/gitleaks.toml) 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.
```golang
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
// 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"))),
}
fps := []string{
`R21A-A-V010SP13RC181024R16900-CN-B_250K-Release-OTA-97B6C6C59241976086FABDC41472150C.bfu`,
}
return validate(r, tps, fps)
}
```
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`](https://github.com/zricethezav/gitleaks/blob/master/cmd/generate/config/rules/rule.go#L31) and [`GenerateUniqueTokenRegex`](https://github.com/zricethezav/gitleaks/blob/master/cmd/generate/config/rules/rule.go#L44) will generate rules
that follow defined patterns.
The function signatures look like this:
```golang
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_"
`GenerateUniqueTokenRegex` 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 `GenerateUniqueTokenRegex`. But something like Beamer's API
token that has a `b_` prefix is not unique enough to use `GenerateUniqueTokenRegex`,
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 `GenerateUniqueTokenRegex`.
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`.
1. Update `cmd/generate/config/main.go`. Extend `configRules` slice with
the `rules.Beamer(),` in `main()`. Try and keep
this alphabetically pretty please.
1. Run `go generate ./...`
1. Check out your new rules in `config/gitleaks.toml` and see if everything looks good.
1. Open a PR
|
