# secrets

> Checks environment files and examples, scans staged changes and pushed commits for secrets, and requires reasons for allowed values.

Checks environment files and examples, scans staged changes and pushed commits for secrets, and requires reasons for allowed values. The [Security and secrets guide](/checks/security/) explains the setup.

## Checks

| Check                                                                       | Stage    | Level         | What it does                                                                                                                                                                                       |
| --------------------------------------------------------------------------- | -------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`secrets/gitleaks-staged`](/reference/checks/secrets/gitleaks-staged/)     | `commit` | `recommended` | Scans the staged change for keys, tokens, and passwords before the commit exists.                                                                                                                  |
| [`secrets/gitleaks-pushed`](/reference/checks/secrets/gitleaks-pushed/)     | `push`   | `recommended` | Scans every commit about to be pushed for keys, tokens, and passwords.                                                                                                                             |
| [`secrets/trufflehog-pushed`](/reference/checks/secrets/trufflehog-pushed/) | `push`   | `recommended` | Verifies candidate secrets in the pushed commits against the service that issued them.                                                                                                             |
| [`secrets/dotenv-linter`](/reference/checks/secrets/dotenv-linter/)         | `commit` | `recommended` | Checks every tracked environment file: key format, duplicates, quoting, ordering, and trailing spaces.                                                                                             |
| [`secrets/env-examples`](/reference/checks/secrets/env-examples/)           | `push`   | `recommended` | Checks that an existing env example lists each static uppercase key that code reads through process.env, import.meta.env, Bun.env, Deno.env.get, the Python os module, or an environment function. |

## Settings

| Setting                                                                                 | What it sets                                                                                                                   |
| --------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| [`secrets.env_examples`](/reference/gspot-toml/#secrets.env_examples)                   | The env example filenames to search for environment keys; a key may appear in any one of them.                                 |
| [`secrets.environment_functions`](/reference/gspot-toml/#secrets.environment_functions) | Functions of this project that read environment variables, such as read\_env. The env-examples check reads the keys they take. |

## Selected when

Always selected.

## Rules for coding agents

| Rule file                                                | Installed when |
| -------------------------------------------------------- | -------------- |
| `.gspot/configurations/general/secrets/rules/SECRETS.md` | Always         |

## Tools and versions

| Tool          | Version  |
| ------------- | -------- |
| gitleaks      | `8.30.1` |
| trufflehog    | `3.97.5` |
| dotenv-linter | `4.0.0`  |

## Files gspot writes

gspot writes `.gspot/configurations/general/secrets/gitleaks.toml`.