detect-secrets (Bridgecrew Fork)

1.5.47 · active · verified Thu Apr 09

detect-secrets (Bridgecrew fork) is a Python tool designed for detecting secrets within a codebase. It focuses on enterprise use cases by providing a systematic way to prevent new secrets, detect explicit bypasses, and offer a checklist for secret migration. Unlike tools that solely find secrets, it emphasizes baseline management to allow for gradual remediation of existing secrets while blocking new ones. The current version is 1.5.47, and it is actively maintained on GitHub.

Warnings

breaking Older versions (primarily Yelp's original detect-secrets before version 1.0) changed CLI flag syntax. `--audit` and `--scan` became subcommands `audit` and `scan`. `scan --import <baseline>` became `scan --update <baseline>`. While the `bc-detect-secrets` fork aims for backwards compatibility, awareness of these changes is important if migrating from very old setups or consulting legacy documentation.
Fix: Update CLI commands to use subcommands (e.g., `detect-secrets scan` instead of `detect-secrets --scan`) and the `--update` flag for baseline management. Consult the latest documentation for correct syntax.
gotcha By default, `detect-secrets scan` only operates on files tracked by Git. Untracked files or scanning outside a Git repository will require the `--all-files` flag to be included in the scan command.
Fix: When scanning repositories with untracked files or when the repository is not a Git repo, append `--all-files` to your `detect-secrets scan` command.
gotcha Creating 'slim' baselines using the `--slim` flag will make them incompatible with the `audit` functionality. If you intend to audit your baseline, avoid using the `--slim` option.
Fix: Do not use the `--slim` flag when generating baselines that you intend to audit. If a slim baseline has already been created, it will need to be regenerated without the `--slim` flag to enable auditing.
gotcha When working on Windows, the `.secrets.baseline` file might encounter encoding issues. It is recommended to save this file with UTF-8 with BOM (Byte Order Mark) encoding.
Fix: Ensure your editor saves `.secrets.baseline` files using UTF-8 with BOM encoding to prevent parsing issues.
gotcha This library (`bc-detect-secrets`) is a fork maintained by Bridgecrew of the original `detect-secrets` by Yelp. While aiming for compatibility, users should be aware of this distinction and ensure they are installing the correct package (`bc-detect-secrets`) and referring to the Bridgecrew repository and documentation for the most accurate information.
Fix: Verify that you have installed `bc-detect-secrets` via pip and are consulting the GitHub repository at `github.com/bridgecrewio/detect-secrets` for documentation and issue tracking.

Install

pip install bc-detect-secrets Basic Installation
pip install bc-detect-secrets[word_list] With Word List Support

Imports

SecretsCollection
```
from detect_secrets import SecretsCollection
```
Used for programmatic collection and management of detected secrets.
transient_settings
```
from detect_secrets.settings import transient_settings
```
Context manager for temporarily modifying detect-secrets settings, such as plugin configurations.
plugins
```
from detect_secrets.core import plugins
```
Access point for initializing and interacting with detection plugins programmatically.

Quickstart

The primary quickstart involves using the command-line interface to create a baseline file. This file (`.secrets.baseline`) tracks existing 'secrets' in your repository, allowing the tool to focus on preventing *new* leaks. The baseline can then be used with pre-commit hooks or CI/CD pipelines.

# 1. Navigate to your repository root.
# 2. Run the scan command to create an initial baseline file.
#    This file records all currently detected 'secrets' to be ignored in future scans.
detect-secrets scan > .secrets.baseline

# 3. (Optional) Add to .pre-commit-config.yaml for Git hook integration:
#    - repo: https://github.com/bridgecrewio/detect-secrets
#      rev: 1.5.47 # Use the current version
#      hooks:
#        - id: detect-secrets
#          args: ['--baseline', '.secrets.baseline']

# 4. To update the baseline with new secrets or remove old ones:
detect-secrets scan --update .secrets.baseline

view raw JSON →