Metadata-Version: 2.4
Name: secret-scanner-cli
Version: 1.0.0
Summary: Scan codebases for leaked secrets, API keys, passwords, tokens & credentials with 40+ detection patterns
Project-URL: Homepage, https://github.com/SanjaySundarMurthy/secret-scanner
Project-URL: Repository, https://github.com/SanjaySundarMurthy/secret-scanner
Project-URL: Issues, https://github.com/SanjaySundarMurthy/secret-scanner/issues
Author-email: Sanjay S <sanjaysundarmurthy@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: api-keys,cli,credentials,devops,leak-detection,passwords,scanner,secrets,security,tokens
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Description-Content-Type: text/markdown

# 🔐 secret-scanner

[![PyPI version](https://badge.fury.io/py/secret-scanner-cli.svg)](https://pypi.org/project/secret-scanner-cli/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-passing-brightgreen.svg)]()

**Scan codebases for leaked secrets, API keys, passwords, tokens & credentials with 42 built-in detection patterns.**

Stop accidental secret leaks before they reach production. `secret-scanner` scans your code for hardcoded credentials — AWS keys, GitHub tokens, database URLs, private keys, and 35+ more secret types — with zero configuration needed.

---

## ✨ Features

| Feature | Description |
|---------|-------------|
| 🎯 **42 Detection Patterns** | AWS, Azure, GCP, GitHub, GitLab, Slack, Stripe, databases, private keys, JWTs, and more |
| 🚀 **Zero Config** | Works out of the box — just point at your code |
| 🔴 **Severity Levels** | Critical, High, Medium, Low, Info — prioritize what matters |
| 📊 **HTML Reports** | Beautiful dark-themed dashboards with severity cards and findings tables |
| 📋 **JSON Export** | Machine-readable output for CI/CD pipeline integration |
| 🛡️ **Baseline Support** | Track known secrets and ignore false positives |
| 🎨 **Rich Terminal Output** | Color-coded tables with redacted secret values |
| 🧪 **Demo Mode** | 5 sample files to see the scanner in action |
| ⚡ **Smart Filtering** | Skips binary files, node_modules, .git, and common non-code directories |
| 🔒 **Redaction** | Secrets are always partially redacted in output |

---

## 📦 Installation

```bash
pip install secret-scanner-cli
```

---

## 🚀 Quick Start

```bash
# Scan current directory
secret-scanner scan .

# Scan a specific file
secret-scanner scan config.py

# Scan with HTML report
secret-scanner scan src/ --html report.html

# Scan with JSON output
secret-scanner scan . -j results.json

# Run demo to see it in action
secret-scanner demo
```

---

## 📖 Commands

### `scan` — Scan files for secrets

```bash
secret-scanner scan <PATH> [OPTIONS]

Options:
  --html PATH            Export HTML dashboard report
  -j, --json-output PATH Export JSON report
  --include-comments     Also scan comments and placeholders
```

**Examples:**
```bash
# Scan entire project
secret-scanner scan .

# Scan with HTML dashboard
secret-scanner scan ./src --html security-report.html

# Include commented-out secrets
secret-scanner scan . --include-comments

# JSON for CI/CD pipelines
secret-scanner scan . -j scan-results.json
```

**Exit codes:**
- `0` — No critical or high severity secrets found
- `1` — Critical or high severity secrets detected

### `rules` — Show all detection patterns

```bash
secret-scanner rules
```

Displays all 42 detection rules with severity, type, and description.

### `demo` — Run demo with sample files

```bash
secret-scanner demo [OPTIONS]

Options:
  --type [all|python|env|yaml|javascript|private-key]
  --html PATH            Export HTML report
  -j, --json-output PATH Export JSON report
```

**Examples:**
```bash
# Run all demos
secret-scanner demo

# Just Python samples
secret-scanner demo --type python

# Generate demo HTML report
secret-scanner demo --html demo-report.html
```

### `baseline` — Create baseline for known secrets

```bash
secret-scanner baseline <PATH>
```

Creates `.secret-scanner-baseline.json` to track known/accepted secrets.

---

## 🎯 Detection Rules (42 Patterns)

### Cloud Provider Keys (Critical)

| Rule | Type | Description |
|------|------|-------------|
| SEC001 | AWS Key | AWS Access Key ID (`AKIA...`) |
| SEC002 | AWS Secret | AWS Secret Access Key |
| SEC003 | Azure Key | Azure Storage Account Key |
| SEC004 | GCP Key | Google Cloud API Key (`AIza...`) |

### Git & DevOps Tokens (Critical)

| Rule | Type | Description |
|------|------|-------------|
| SEC005 | GitHub Token | GitHub Personal Access Token (`ghp_...`) |
| SEC006 | GitHub Token | GitHub OAuth Access Token (`gho_...`) |
| SEC007 | GitHub Token | GitHub Fine-Grained PAT (`github_pat_...`) |
| SEC008 | GitLab Token | GitLab Personal/Project Access Token (`glpat-...`) |

### Communication Tokens (High)

| Rule | Type | Description |
|------|------|-------------|
| SEC009 | Slack Token | Slack Bot/User Token (`xoxb-...`) |
| SEC010 | Slack Token | Slack Webhook URL |
| SEC011 | Discord Token | Discord Bot Token |
| SEC012 | Telegram Token | Telegram Bot Token |

### Payment & SaaS (Critical/High/Medium)

| Rule | Type | Description |
|------|------|-------------|
| SEC013 | Stripe Key | Stripe Secret Key (`sk_live_...`) |
| SEC014 | Stripe Key | Stripe Publishable Key (`pk_live_...`) |
| SEC015 | SendGrid Key | SendGrid API Key (`SG....`) |
| SEC016 | Twilio Key | Twilio API Key (`SK...`) |
| SEC017 | Mailgun Key | Mailgun API Key (`key-...`) |

### Package Manager Tokens (Critical/High)

| Rule | Type | Description |
|------|------|-------------|
| SEC018 | NPM Token | NPM Access Token (`npm_...`) |
| SEC019 | PyPI Token | PyPI API Token (`pypi-...`) |
| SEC020 | Docker Token | Docker Hub Access Token (`dckr_pat_...`) |

### Cryptographic Material (Critical/High)

| Rule | Type | Description |
|------|------|-------------|
| SEC021 | Private Key | RSA/EC Private Key (PEM header) |
| SEC022 | SSH Key | SSH Private Key (OpenSSH format) |
| SEC023 | JWT Token | JSON Web Token (`eyJ...`) |

### Database Connections (Critical)

| Rule | Type | Description |
|------|------|-------------|
| SEC024 | Database URL | Connection string with embedded password |

### Generic Patterns (High)

| Rule | Type | Description |
|------|------|-------------|
| SEC025 | API Key | Generic API Key assignment |
| SEC026 | Generic Secret | Generic Secret assignment |
| SEC027 | Password | Hardcoded password |
| SEC028 | Token | Generic token assignment |
| SEC029 | Bearer Token | Bearer token in Authorization header |
| SEC030 | Basic Auth | Basic Auth credentials |

### Infrastructure & Monitoring (High/Medium/Critical)

| Rule | Type | Description |
|------|------|-------------|
| SEC031 | Heroku Key | Heroku API Key |
| SEC032 | Datadog Key | Datadog API/App Key |
| SEC033 | New Relic Key | New Relic License/API Key |
| SEC034 | Sentry DSN | Sentry Data Source Name |
| SEC035 | Vault Token | HashiCorp Vault Token (`hvs.`/`hvb.`/`hvr.`) |

### AI & Cloud Services (Critical/High)

| Rule | Type | Description |
|------|------|-------------|
| SEC036 | OpenAI Key | OpenAI API Key (legacy format) |
| SEC037 | OpenAI Key | OpenAI API Key (new `sk-proj-` format) |
| SEC038 | Firebase Key | Firebase Cloud Messaging Key |
| SEC039 | Cloudflare Key | Cloudflare API Key |
| SEC040 | DigitalOcean Token | DigitalOcean Access Token |

### Encryption & Credentials (High/Medium)

| Rule | Type | Description |
|------|------|-------------|
| SEC041 | Encryption Key | Hex-encoded encryption key (256-bit) |
| SEC042 | Credential | Connection string with embedded credentials |

---

## 📊 HTML Dashboard

Generate beautiful HTML reports with:

```bash
secret-scanner scan . --html report.html
```

The dark-themed dashboard includes:
- **Summary cards** — Total findings, files scanned, severity breakdown
- **Status banner** — CLEAN or SECRETS FOUND
- **Findings table** — Severity badges, rule IDs, redacted matches, fix suggestions

---

## 🔄 CI/CD Integration

### GitHub Actions

```yaml
- name: Secret Scan
  run: |
    pip install secret-scanner-cli
    secret-scanner scan . -j results.json
```

### GitLab CI

```yaml
secret_scan:
  script:
    - pip install secret-scanner-cli
    - secret-scanner scan . --html report.html
  artifacts:
    paths:
      - report.html
```

### Pre-commit Hook

```bash
#!/bin/sh
# .git/hooks/pre-commit
secret-scanner scan . 2>/dev/null
if [ $? -ne 0 ]; then
    echo "❌ Secrets detected! Commit blocked."
    exit 1
fi
```

---

## 🛡️ Baseline Workflow

Track known secrets that are intentional or false positives:

```bash
# Create baseline
secret-scanner baseline .

# The baseline file .secret-scanner-baseline.json captures current findings
# Future scans can reference this to skip known issues
```

---

## ⚡ Smart Filtering

The scanner automatically skips:

| Category | Skipped |
|----------|---------|
| **Directories** | `.git`, `node_modules`, `.venv`, `__pycache__`, `dist`, `build`, `vendor` |
| **Binary files** | `.png`, `.jpg`, `.exe`, `.dll`, `.pdf`, `.zip`, `.tar.gz` |
| **Lock files** | `*.lock` |
| **Large files** | Files > 1MB |
| **Placeholders** | `your_api_key_here`, `changeme`, `placeholder`, `example` |
| **Comments** | Lines starting with `#`, `//`, `/*` (unless `--include-comments`) |

---

## 🧪 Development

```bash
# Clone
git clone https://github.com/SanjaySundarMurthy/secret-scanner.git
cd secret-scanner

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Lint
ruff check .
```

---

## 📋 Requirements

- Python 3.10+
- click >= 8.0
- rich >= 13.0

---

## 📄 License

MIT License — see [LICENSE](LICENSE) for details.

---

## 👤 Author

**Sanjay S** — [GitHub](https://github.com/SanjaySundarMurthy) · [PyPI](https://pypi.org/user/sanjaysundarmurthy/)

---

## 🏆 Other Tools

| Tool | Description | PyPI |
|------|-------------|------|
| [docker-lens](https://github.com/SanjaySundarMurthy/docker-lens) | Dockerfile analyzer & optimizer | [docker-lens-cli](https://pypi.org/project/docker-lens-cli/) |
| [yaml-doctor](https://github.com/SanjaySundarMurthy/yaml-doctor) | YAML linter for K8s, Compose, GHA, GitLab CI | [yaml-doctor-cli](https://pypi.org/project/yaml-doctor-cli/) |
| [k8s-health-checker](https://github.com/SanjaySundarMurthy/k8s-health-checker) | Kubernetes manifest health checker | [k8s-health-checker](https://pypi.org/project/k8s-health-checker/) |
| [ats-resume-generator](https://github.com/SanjaySundarMurthy/ats-resume-generator) | ATS-optimized resume builder | [ats-resume-generator](https://pypi.org/project/ats-resume-generator/) |
