Detect Secrets

1.5.0 · active · verified Fri Apr 10

Detect-secrets is a tool designed to identify and prevent sensitive information, such as API keys, passwords, and other credentials, from being committed into source code repositories. It leverages various detectors, including regex, keyword, and optional machine learning-based algorithms. The current version is 1.5.0, with minor releases typically occurring every few months.

Warnings

breaking Support for Python 3.6 and 3.7 was dropped in v1.5.0. Python 3.8 support will also be removed in a future release (likely after its EOL in October 2024).
Fix: Upgrade your Python environment to 3.9 or higher to maintain compatibility and receive updates.
gotcha The ML-based `gibberish-detector` (introduced in v1.1.0) is not included in the default installation. It requires an 'extra' package.
Fix: Install `detect-secrets` with the `[ml]` extra: `pip install 'detect-secrets[ml]'`.
gotcha For effective use, especially with `pre-commit` hooks, `detect-secrets` heavily relies on configuration files (`.detect-secrets.yaml`) and a baseline file (`.secrets.baseline`). Skipping these can lead to excessive false positives or missed secrets.
Fix: Initialize your repository with `detect-secrets init` to create a default config, and generate a baseline with `detect-secrets scan --baseline .secrets.baseline` to ignore existing secrets.

Install

pip install detect-secrets Basic Installation
pip install 'detect-secrets[ml]' Installation with ML-based Gibberish Detector

Imports

run_as_library
```
from detect_secrets.core.usage import run_as_library
```
Primary function for programmatic scanning of files or directories.
TransientSettings
```
from detect_secrets.settings import TransientSettings
```
Used to configure scanning parameters programmatically.
Baseline
```
from detect_secrets.core.baseline import Baseline
```
For programmatic interaction with baseline files, e.g., creating or updating.

Quickstart

This quickstart demonstrates how to programmatically scan a temporary directory containing a file with simulated secrets using `detect-secrets`. It initializes a temporary directory, creates a file with some fake credentials, and then uses `run_as_library` to perform the scan and print the detected secret types.

import os
import tempfile
from pathlib import Path
from detect_secrets.core.usage import run_as_library

def run_detect_secrets_scan():
    with tempfile.TemporaryDirectory() as tmpdir:
        repo_path = Path(tmpdir)
        
        # Create a dummy file with a fake secret
        (repo_path / "my_project").mkdir()
        (repo_path / "my_project" / "config.py").write_text(
            "API_KEY = 'AKIAIOSFODNN7EXAMPLE' # This is a fake AWS key, DO NOT USE
            DB_PASSWORD = 'supersecretpassword123'
            SECRET_PHRASE = 'NotARealSecret'
            ")
        
        print(f"Scanning directory: {repo_path}")
        
        # Run the scan
        # 'plugins_used': None lets detect-secrets use its default plugin set.
        # 'secret_type_mapping': None uses default mappings.
        # 'mount_paths': Specify the path to scan.
        scan_results = run_as_library(
            plugins_used=None,
            secret_type_mapping=None,
            mount_paths=[str(repo_path)]
        )
        
        # Process results
        if scan_results.data:
            print("\n--- Detected Secrets ---")
            for filepath, secrets in scan_results.data.items():
                print(f"File: {filepath}")
                for secret in secrets:
                    print(f"  - Type: {secret.type}, Hashed Secret: {secret.hashed_secret}")
        else:
            print("\nNo secrets detected.")

if __name__ == '__main__':
    run_detect_secrets_scan()

view raw JSON →