dotenv-secrets-scanner 1.0.0

Production-ready secrets scanner for Git repositories. Detects API keys, passwords, tokens, and credentials accidentally committed to source code.

🔐 Dotenv Secrets Scanner

An open-source security tool that detects accidentally committed secrets before they reach production.

Installation • Usage • What Does It Find? • How It Works • Configuration

---

🎯 Problem

Developers accidentally commit API keys, database passwords, and tokens to source code. This leads to data leaks, financial losses, and security breaches.

⚠️ Over 6 million secrets were exposed on public GitHub repositories in 2023.

Dotenv Secrets Scanner solves this problem: it scans your code, detects secrets, and warns you — before you commit.

🔍 Why Not Other Tools?

Feature	This Tool	Gitleaks	TruffleHog
Regional payment providers support	✅	❌	❌
Entropy + Regex	✅	✅	✅
Baseline support	✅	Limited	❌

Includes pattern support for region-specific services (e.g., Iyzico, PayTR) in addition to global ones.

✨ What Does It Do?

$ python -m scanner scan .

  🔍 Scanning: ./config/production.py

  🚨 CRITICAL  AWS Access Key
     Line 12: AWS_KEY = "AKIA████████████████"
     Confidence: 95%

  ⚠️  HIGH  GitHub Personal Access Token
     Line 28: TOKEN = "ghp_████████████████████████████████████"
     Confidence: 90%

  📊 Scan Results
  ┌────────────────┬───────┐
  │ Files scanned  │    47 │
  │ Total findings │     3 │
  │   CRITICAL     │     1 │
  │   HIGH         │     2 │
  └────────────────┴───────┘

  🚨 Action required: Critical secrets must be rotated!

---

📦 Installation

# Install from PyPI
pip install dotenv-secrets-scanner

# or from source
git clone https://github.com/Quarrezz/dotenv-secrets-scanner.git
cd dotenv-secrets-scanner
pip install -e .

🚀 Usage

Basic Scan

# Scan the current directory
python -m scanner scan .

# Scan a specific file
python -m scanner scan config/settings.py

# Scan a specific folder
python -m scanner scan src/

Output Formats

# Colored output in Terminal (default)
python -m scanner scan .

# JSON format (for CI/CD integration)
python -m scanner scan . --output json

# Plain text
python -m scanner scan . --output text

# HTML report
python -m scanner scan . --output html

# Save results to a file
python -m scanner scan . --output json --output-file report.json

Filtering by Severity

# Show only critical findings
python -m scanner scan . --severity CRITICAL

# High and critical
python -m scanner scan . --severity HIGH

# Break CI if HIGH or above is found
secrets-scan scan . --fail-on-severity HIGH

Performance and Output Control

# Show fewer context lines
secrets-scan scan . --context-lines 1

# Speed up scanning on multi-core machines
secrets-scan scan . --workers 8

Suppressing Old Findings with Baseline

In real projects, there might be secrets committed in the past that you can't clean up immediately. With Baseline, you can save the findings from the first scan and focus only on new secrets thereafter.

# Write current findings to baseline file in the first scan
python -m scanner scan . --write-baseline baseline.json

# Show only findings not in baseline (new) in subsequent scans
python -m scanner scan . --baseline baseline.json

# In CI: break job only if there are new and HIGH/CRITICAL findings
secrets-scan scan . --baseline baseline.json --fail-on-severity HIGH

Git Integration

# Install pre-commit hook (automatic scan before every commit)
python -m scanner install-hook

# Uninstall hook
python -m scanner uninstall-hook

# Create .secretsignore file
python -m scanner init

---

🔍 What Does It Find?

🔴 Critical (CRITICAL)

Type	Example Format
AWS Access Key	20-character key starting with AKIA
AWS Secret Key	aws_secret_access_key = "..."
GitHub Token	Tokens starting with ghp_, gho_, ghs_
Stripe Secret Key	Key starting with sk_live_
SSH Private Key	-----BEGIN RSA PRIVATE KEY----- format
PostgreSQL/MySQL URL	postgres://user:pass@host format
Iyzico API Key	Iyzico/iyzipay payment keys
PayTR Merchant Key	PayTR payment keys

🟠 High (HIGH)

Type	Example Format
OpenAI API Key	Key starting with sk-
Google API Key	Key starting with AIza
Slack Bot Token	Token starting with xoxb-
Slack Webhook	https://hooks.slack.com/...
JWT Token	Token in eyJ... format
SendGrid API Key	Key starting with SG.
NPM / PyPI Token	Tokens starting with npm_, pypi-

🟡 Medium (MEDIUM)

Type	Example Format
Azure Storage Key	AccountKey = "..."
Generic API Key	api_key = "...", api_secret = "..."
Generic Password	password = "...", passwd = "..."
Docker Auth	Docker registry tokens

🔵 Low (LOW)

Type	Example Format
.env Secret	In SECRET_KEY=value format
High Entropy Hex	Long hex strings (potentially secret)

📌 Total 30+ different secret types are detected. Includes regional provider support (e.g., Iyzico, PayTR, Türk Telekom Cloud, e-Devlet) in addition to global services.

---

🧠 How It Works

Scanner uses a 3-layer detection system:

  Source Code
      │
      ▼
┌─────────────────┐
│  1. Regex Match   │  ← Searches for known secret formats with 30+ patterns
└────────┬────────┘
         │ match found
         ▼
┌─────────────────┐
│ 2. Entropy Analysis│  ← Checks randomness with Shannon entropy
└────────┬────────┘    (low entropy = not password, high = likely password)
         │
         ▼
┌─────────────────┐
│ 3. FP Filtering   │  ← Filters out placeholders, templates, and
└────────┬────────┘    example values
         │
         ▼
    ✅ True Finding
    (With Confidence score)

Thanks to this 3-layer system:

• ❌ API_KEY = "YOUR_API_KEY_HERE" → Placeholder, skipped
• ❌ API_KEY = "changeme" → Known test value, skipped
• ❌ API_KEY = "${ENV_VAR}" → Template syntax, skipped
• ❌ # API_KEY = "sk_live_..." → Comment line, low confidence score
• ✅ API_KEY = "sk_live_4eC39Hq████████████" → Real secret found!

---

⚙️ Configuration

.secretsignore File

Create a .secretsignore file in the project root to exclude specific files or directories from scanning:

# Create automatically
python -m scanner init

# .secretsignore example

# Skip test files
tests/
test_*.py
test_*.py

# Skip specific files
config/example.env
docs/api-guide.md

# Skip folders
fixtures/
examples/

YAML Configuration

You can make detailed configuration by creating .secretscan.yml in the project root:

# .secretscan.yml
excluded_dirs:
  - node_modules
  - .git
  - vendor
  - dist

excluded_extensions:
  - .png
  - .jpg
  - .lock

min_severity: MEDIUM
scan_hidden: false
follow_symlinks: false
max_file_size: 1048576  # 1 MB

---

📚 Listing All Patterns

To see which secret types the Scanner detects, you can list patterns via CLI:

# List all patterns
python -m scanner patterns

# List only HIGH and CRITICAL patterns
python -m scanner patterns --severity HIGH

This command shows pattern ID, name, severity level, and short description in a table.

---

🔗 Pre-commit Integration

Direct Installation (Recommended)

python -m scanner install-hook

This command automatically adds the scanner hook to .git/hooks/pre-commit. Automatic scan is performed before every git commit.

With pre-commit Framework

Add to your .pre-commit-config.yaml file:

repos:
  - repo: https://github.com/Quarrezz/dotenv-secrets-scanner
    rev: v1.0.0
    hooks:
      - id: secrets-scan

---

📊 CI/CD Integration

GitHub Actions

# .github/workflows/secrets-check.yml
name: Secrets Check
on: [push, pull_request]
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install dotenv-secrets-scanner
      - run: secrets-scan scan . --severity HIGH --output json

---

🏗️ Project Structure

src/scanner/
├── __init__.py       # Package initialization
├── __main__.py       # python -m scanner support
├── models.py         # Data models (Finding, ScanResult, ScanConfig)
├── patterns.py       # 30+ regex pattern definitions
├── entropy.py        # Shannon entropy analysis
├── validators.py     # False positive filtering
├── core.py           # Main scanning engine
├── reports.py        # Report generators (JSON, Text, HTML)
├── cli/
│   └── main.py       # CLI commands (Click)
├── hooks/
│   └── pre_commit.py # Git pre-commit hook
└── utils/
    ├── config.py     # Configuration management
    └── git.py        # Git integration

---

🚀 Roadmap

• GitHub App version
• Official Docker image
• VSCode Extension
• SARIF output support

---

📝 License

MIT License — See LICENSE file for details.

---

_{🇹🇷 By Turkish developers, for all developers.}