# Gitleaks configuration utilities

[Gitleaks](https://github.com/zricethezav/gitleaks)  is a SAST tool for detecting and preventing hardcoded secrets like passwords, api keys, and tokens in git repos.

`gitleaks-py` provides a python library and CLI to manage Gitleaks rule configurations:

* Compare configurations using sort and diff
* Verify rules against fixture files containing secrets
* Merge rules from multiple files into a single file

## Sort

Sort Gitleaks config file by case-insensitive rule ID.

```bash
python -m gitleaks_py.cli sort [OPTIONS] CONFIG_FILE
```

* `CONFIG_FILE`
  File or URL to sort

* `-d`, `--dst`
  Output destination file. Writes to `std-out` if omitted

## Diff

Diff two config files.

```bash
python -m gitleaks_py.cli diff [OPTIONS] CONFIG_FILE [DEFAULT_CONFIG_FILE]
```

* `CONFIG_FILE`
  File or URL to diff

* `DEFAULT_CONFIG_FILE`
  File or URL to diff against.
  Defaults to [gitleaks default config file](https://raw.githubusercontent.com/zricethezav/gitleaks/master/config/gitleaks.toml)

* `-d`, `--dst`
  Output destination file. Writes to `std-out` if omitted

* `-o`, `--omissions`
  Display omissions (rules from default config, not found in config)

* `-a`, `--additions`
  Display additions (rule from config, not found in default config)

## Verify

Verify config file against secrets held in sample files.

```bash
python -m gitleaks_py.cli verify [OPTIONS] CONFIG_FILE
```

* `CONFIG_FILE`
  File or URL to verify

* `-d`, `--dst`
  Output destination file. Writes to `std-out` if omitted

* `-s`, `--secrets`
  Folder with secrets to test rules. Defaults to `./secrets`

  Files should be in [YAML](https://yaml.org/) named as the rule id.
  e.g. `uk-gov-notify.yml`

  The yaml should be structured as key-value pairs under two groupings, `secrets` and `allowed`.
  The key is an identifier for failures, and the value contains the secret or allowed value to be tested.
  e.g.

```yaml
secrets:
  api-key: "gitleakstest-af3bb117-d149-4b23-ab1d-8d19ab184094-68a09f80-1f89-4d98-bd9e-ec431e970940"
  api-key-upper: "GITLEAKSTEST-AF3BB117-D149-4B23-AB1D-8D19AB184094-68A09F80-1F89-4D98-BD9E-EC431E970940"
  api-key-no-delim: "gitleakstest-af3bb117d1494b23ab1d8d19ab18409468a09f801f894d98bd9eec431e970940"
allowed:
  test-api-key: "gitleakstest-aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa-aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa"
```

  When allowing patterns for test data, choose something that is obviously not a real secret, such as all letter 'a'.
  The chances of this being generated in production should be low.

## Merge

Merge multiple config files into one

```bash
python -m gitleaks_py.cli merge [OPTIONS] [CONFIG_FILES]...
```

* `CONFIG_FILES`
  A space separated list of files to merge. Glob patterns may be used. e.g. `toml/*.toml`

* `-t`, `--title`
  Output config title. Joins titles from files if omitted

* `-d`, `--dst`
  Output destination file. Writes to `std-out` if omitted
