secrettrack 1.0.2
A professional tool for detecting exposed secrets in code and configuration files
License: MIT
Requires Python: >=3.9
Keywords: security, secrets, detection, devsecops, appsec

# 🔍 SecretTrack

[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)](https://python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyPI Version](https://img.shields.io/pypi/v/secrettrack)](https://pypi.org/project/secrettrack/)
[![Downloads](https://static.pepy.tech/badge/secrettrack)](https://pepy.tech/project/secrettrack)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

## 👨‍💻 About the Creator
**SecretTrack** is the brainchild of **Juphin Mbaya**, a passionate Cybersecurity Engineer and Application Security Specialist with extensive experience in DevSecOps, threat detection, and secure software development. Drawing from real-world security challenges faced in enterprise environments, Juphin developed SecretTrack to address the critical need for proactive secret detection in modern development workflows.

> "Having witnessed firsthand the devastating impact of exposed credentials, I built SecretTrack to empower developers and security teams with a tool that's both powerful and practical. This isn't just another security scanner—it's born from hands-on experience in securing complex applications at scale."  
> **— Juphin Mbaya, Cybersecurity Engineer**

## 🚀 Why SecretTrack?

Secret leaks (API keys, tokens, credentials) are among the leading causes of security breaches in modern applications. Born from practical security engineering experience, SecretTrack helps you:

- **Prevent catastrophic leaks** before they reach production environments
- **Discover hidden secrets** in existing codebases and historical commits
- **Bridge the gap** between security teams and developers with actionable findings
- **Integrate seamlessly** into modern CI/CD pipelines and development workflows
- **Reduce false positives** with intelligent context-aware analysis

## ✨ Key Features Built for Real-World Security

| Feature | Description | Why It Matters |
|---------|-------------|----------------|
| 🔍 **Multi-platform Detection** | AWS, GitHub, Stripe, Firebase, generic secrets | Comprehensive coverage for today's diverse tech stacks |
| 🧠 **Intelligent Context Analysis** | Dev/staging/prod detection with confidence scoring | Reduces false positives by understanding environment context |
| 📊 **Dual Output Formats** | Human-readable console & JSON for CI/CD | Adapts to both developer workflows and automated pipelines |
| ⚡ **Performance-Optimized** | Smart file filtering and parallel processing | Scans large codebases quickly without compromising accuracy |
| 🛡️ **Security by Design** | 100% local execution, no data exfiltration | Your secrets never leave your environment—built with privacy first |
| 🔧 **Professional Architecture** | Modular, extensible design with clean separation of concerns | Easy to extend with custom detectors and integrations |

## 🎯 Who Benefits from SecretTrack?

- **Developers** - Catch secrets before they're committed, preventing embarrassing and dangerous leaks
- **DevSecOps Engineers** - Integrate automated scanning into CI/CD pipelines with actionable results
- **Application Security Teams** - Conduct thorough security audits with context-aware detection
- **Security Consultants** - Quickly assess codebases for exposed credentials during engagements
- **Open Source Maintainers** - Ensure your projects don't accidentally expose sensitive information

## 📦 Installation

### Installation via pip (recommended)

```bash
pip install secrettrack
```

### Installation from source

```bash
git clone https://github.com/juphinmbaya/secrettrack.git
cd secrettrack
pip install -e .
```

### Quick Verification

```bash
# Verify installation
secrettrack --version

# Test the scanner on a sample directory
secrettrack scan . --exclude "venv,node_modules,.git"
```

## 🚀 Quick Start: Get Scanning in 60 Seconds

```bash
# 1. Install SecretTrack
pip install secrettrack

# 2. Scan your project
secrettrack scan /path/to/your/project

# 3. For CI/CD integration, use JSON output
secrettrack scan . --json --severity critical,high

# 4. Customize exclusions for your workflow
secrettrack scan . --exclude "node_modules,.env.local,dist,build"

# 5. Save detailed reports for documentation
secrettrack scan . --output security-scan-$(date +%Y%m%d).json
```

## 📋 Supported Secrets Detection

SecretTrack detects a comprehensive range of secrets using intelligent pattern matching developed from analyzing real-world security incidents:

| Category | Specific Secrets Detected | Real-World Impact |
|----------|--------------------------|-------------------|
| **Cloud Providers** | AWS Access Keys, Secret Keys, Session Tokens | Full cloud account compromise, resource creation, data exfiltration |
| **Developer Platforms** | GitHub Personal Access Tokens, OAuth Tokens, SSH Keys | Repository takeover, code injection, organization compromise |
| **Payment Processors** | Stripe Live/Test Keys, Webhook Secrets | Unauthorized payments, customer data exposure, refund fraud |
| **Database & Services** | Firebase API Keys, Connection Strings, Private Keys | Data breach, service impersonation, authentication bypass |
| **Generic Credentials** | API Keys, JWT Tokens, Passwords, Bearer Tokens | Various depending on service, often critical |

### Smart Detection Features:
- **Context-aware matching**: Distinguishes between production and test keys
- **Confidence scoring**: Each finding includes a 0.0-1.0 confidence score
- **False positive reduction**: Intelligent pattern analysis minimizes noise
- **Environment detection**: Auto-detects dev/staging/prod contexts

## 🎪 Real-World Example Output

### Console Output (Human Readable)

```
🔐 SecretTrack Security Audit
============================================================
🔍 Scanner: Juphin Mbaya's SecretTrack v1.0.0
📅 Scan Date: 2024-01-29
📁 Target: /projects/ecommerce-platform

📊 Executive Summary:
  Total findings: 3
  🔥 Critical: 1 (Immediate action required)
  ⚠️ High: 1 (Review within 24 hours)
  🔸 Medium: 1 (Address in next sprint)
  ℹ️ Low: 0

🔥 CRITICAL FINDING - IMMEDIATE ACTION REQUIRED
--------------------------------------------------------
🆔 Detection ID: ST-CRIT-001
🔍 Type: Stripe Live Secret Key
📁 Location: config/production/.env:3
🔐 Secret: sk_live_***xyz789 (full detection masked)
🎯 Environment: Production
📈 Confidence: 95%
💥 Risk Impact: Full payment system compromise
   • Process unauthorized charges
   • Access customer payment information
   • Issue fraudulent refunds

✅ Recommended Action:
   1. IMMEDIATELY rotate key in Stripe Dashboard
   2. Review recent transactions for anomalies
   3. Remove key from git history: `git filter-branch`
   4. Implement Stripe webhook signature verification

⚠️ HIGH SEVERITY FINDING
--------------------------------------------------------
🆔 Detection ID: ST-HIGH-002
🔍 Type: AWS Production Access Key
📁 Location: src/infrastructure/aws_config.py:42
🔐 Secret: AKIA***XYZ789
🎯 Environment: Production
📈 Confidence: 88%
💥 Risk Impact: AWS account takeover

✅ Recommended Action:
   1. Rotate compromised key via AWS IAM
   2. Review CloudTrail logs for suspicious activity
   3. Implement AWS Secrets Manager for credential management

🛡️ SECURITY RECOMMENDATIONS
--------------------------------------------------------
Based on my experience securing enterprise applications:

🔧 Immediate Actions:
   • Rotate all compromised credentials NOW
   • Audit access logs for unauthorized activity
   • Implement secret scanning in pre-commit hooks

🏗️ Strategic Improvements:
   • Migrate to environment variables or secret managers
   • Implement just-in-time access for production credentials
   • Regular security training for development teams

📈 Proactive Measures:
   • Schedule quarterly credential rotation
   • Implement multi-factor authentication everywhere
   • Regular security audits using SecretTrack
```

### JSON Output (CI/CD Integration)

```json
{
  "metadata": {
    "tool": "secrettrack",
    "version": "1.0.0",
    "creator": "Juphin Mbaya",
    "scan_timestamp": "2024-01-29T10:30:00Z",
    "context": "Professional security audit by Application Security Engineer"
  },
  "summary": {
    "total_findings": 3,
    "by_severity": {
      "critical": 1,
      "high": 1,
      "medium": 1,
      "low": 0
    },
    "by_environment": {
      "production": 2,
      "staging": 1,
      "development": 0
    }
  },
  "findings": [
    {
      "id": "ST-CRIT-001",
      "type": "stripe",
      "subtype": "stripe_live_secret_key",
      "severity": "critical",
      "file": "config/.env",
      "line": 3,
      "environment": "production",
      "confidence": 0.95,
      "risk": "Full payment system takeover, unauthorized charges",
      "recommendation": "Rotate key immediately via Stripe Dashboard → Developers → API keys",
      "hash": "abc123def456",
      "context_preview": "STRIPE_SECRET_KEY=sk_live_abc123xyz789",
      "secret_preview": "sk_**789",
      "remediation_steps": [
        "Rotate compromised key immediately",
        "Review Stripe logs for unauthorized activity",
        "Update all integrations with new key",
        "Remove old key from version control history"
      ]
    }
  ]
}
```

## 🖥️ Command Line Interface

### Complete Usage Guide

```bash
# Show comprehensive help
secrettrack --help

# Show version with creator information
secrettrack --version

# Basic scan (recommended for first-time users)
secrettrack scan .

# Advanced scan with all options
secrettrack scan /path/to/project \
  --json \
  --severity critical,high \
  --exclude "node_modules,.git,__pycache__,*.log,dist,build" \
  --output scan-results-$(date +%Y%m%d-%H%M%S).json \
  --max-size 20
```

### CLI Options Reference

| Option | Description | Default | Expert Tip |
|--------|-------------|---------|------------|
| `--json` | JSON output for CI/CD | `False` | Use with `--output` for audit trails |
| `--severity` | Severity filter | `low,medium,high,critical` | Start with `critical,high` for quick audits |
| `--exclude` | Exclusion patterns | Common dev patterns | Add project-specific exclusions |
| `--output, -o` | Output file | `stdout` | Use timestamps in filename for tracking |
| `--max-size` | Max file size (MB) | `10` | Increase for scanning large config files |

### Exit Codes for Automation

| Code | Meaning | Automation Response |
|------|---------|-------------------|
| `0` | Success, no secrets found | Continue pipeline |
| `1` | Secrets found (non-critical) | Warning, continue with caution |
| `2` | Critical secrets found | **STOP pipeline**, require manual review |
| `3` | Error in scanning | Investigate scanner configuration |

## 🛡️ Security Principles & Architecture

### Built with Security First Philosophy

As a cybersecurity professional, I've embedded security at every layer:

#### 🔒 Privacy & Confidentiality
- **Zero Data Exfiltration**: No external calls, no telemetry, no analytics
- **Local-First Execution**: Works completely offline—no internet required
- **Secret Masking**: Automatic masking in outputs to prevent accidental re-exposure

#### 🛡️ Accuracy & Reliability
- **Context-Aware Detection**: Understands dev/staging/prod contexts
- **Confidence Scoring**: Transparent scoring (0.0-1.0) for each finding
- **Reduced False Positives**: Intelligent pattern matching reduces noise

#### 🔐 Professional Architecture

```
secrettrack/                          # Enterprise-grade structure
├── scanner/                          # Scanning engines
│   ├── filesystem.py                 # Optimized filesystem traversal
│   └── git_history.py                # Historical commit analysis (optional)
├── detectors/                        # Detection modules (extensible)
│   ├── base.py                       # Abstract base class
│   ├── aws.py                        # AWS credential detection
│   ├── github.py                     # GitHub token detection
│   ├── stripe.py                     # Stripe key detection
│   ├── firebase.py                   # Firebase credential detection
│   └── generic.py                    # Generic pattern detection
├── analyzer/                         # Intelligent analysis
│   ├── context.py                    # Environment detection
│   └── confidence.py                 # Confidence scoring engine
└── report/                           # Professional reporting
    ├── human.py                      # Human-readable output
    └── json.py                       # Machine-readable output
```

### Adding Custom Detectors

Extend SecretTrack with domain-specific detectors:

```python
from secrettrack.detectors.base import BaseDetector
import re

class InternalAPIDetector(BaseDetector):
    """Custom detector for internal API keys based on organizational patterns."""
    
    def _get_patterns(self):
        return [
            {
                "name": "internal_api_v2",
                "pattern": re.compile(r'(?i)internal_api_v2_key[\s:=]+[\'"](int_[0-9a-zA-Z]{32})[\'"]'),
            }
        ]
    
    def get_secret_type(self):
        return "internal_api"
    
    def _get_risk_description(self):
        return "Internal API compromise leading to data exposure"
    
    def _get_recommendation(self):
        return "Rotate internal API key and review access logs"
```

## 🔧 Enterprise Integration Guide

### Pre-commit Hook (Prevent Leaks Before Commit)

```yaml
# .pre-commit-config.yaml
repos:
  - repo: https://github.com/juphinmbaya/secrettrack
    rev: v1.0.0
    hooks:
      - id: secrettrack
        name: SecretTrack Security Scan
        description: "Pre-commit security scanning by Juphin Mbaya"
        entry: secrettrack
        args: [scan, .]
        language: python
        pass_filenames: false
        always_run: true
```

### GitHub Actions (Automated CI/CD Scanning)

```yaml
name: Security Scanning with SecretTrack
on: [push, pull_request]

jobs:
  secret-scan:
    runs-on: ubuntu-latest
    name: SecretTrack Security Audit
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
        with:
          fetch-depth: 0  # Full history for comprehensive scanning
      
      - name: Install SecretTrack
        run: pip install secrettrack
      
      - name: Run SecretTrack Security Scan
        run: |
          secrettrack scan . \
            --json \
            --severity critical,high \
            --output secret-scan-results.json
        continue-on-error: true
      
      - name: Upload Security Report
        uses: actions/upload-artifact@v3
        with:
          name: secret-track-report
          path: secret-scan-results.json
      
      - name: Check for Critical Findings
        run: |
          if grep -q '"severity": "critical"' secret-scan-results.json; then
            echo "❌ CRITICAL SECRETS FOUND - Blocking merge"
            exit 1
          else
            echo "✅ No critical secrets found"
          fi
```

### GitLab CI/CD Integration

```yaml
stages:
  - security

secret_track_scan:
  stage: security
  image: python:3.9
  before_script:
    - pip install secrettrack
  script:
    - |
      secrettrack scan . \
        --json \
        --severity critical,high \
        --output gl-secret-scan.json
  artifacts:
    paths:
      - gl-secret-scan.json
    when: always
    expire_in: 1 week
  allow_failure: false  # Block pipeline on critical findings
```

## 📊 Performance & Scalability

SecretTrack is engineered for performance in real-world scenarios:

### Optimization Techniques
- **Intelligent File Filtering**: Automatically skips binaries, media, archives
- **Memory-Efficient Processing**: Line-by-line scanning, not whole-file loading
- **Parallel Processing Architecture**: Optimized for multi-core systems
- **Smart Caching**: Minimizes redundant operations

### Performance Benchmarks

| Scenario | Files | Time | Memory | Notes |
|----------|-------|------|--------|-------|
| **Small Project** (Startup) | ~1,000 | 2-3s | < 50MB | Typical web application |
| **Medium Project** (Enterprise) | ~10,000 | 15-20s | < 100MB | Monorepo with microservices |
| **Large Project** (Platform) | ~100,000 | 2-3min | < 200MB | Large codebase with history |
| **Historical Scan** (Git) | All commits | Varies | < 250MB | Full git history analysis |

## 🚀 Roadmap & Future Development

### Near-Term Enhancements (Q1 2024)
- [ ] **Git History Deep Dive**: Complete commit history scanning
- [ ] **Enhanced Pattern Library**: More service providers and patterns
- [ ] **Performance Optimizations**: Parallel scanning improvements
- [ ] **IDE Plugins**: VS Code and JetBrains integrations

### Medium-Term Vision (2024)
- [ ] **Machine Learning Detection**: AI-powered pattern recognition
- [ ] **Remediation Automation**: Auto-rotation for certain key types
- [ ] **Team Collaboration**: Shared findings and collaborative review
- [ ] **Compliance Reporting**: SOC2, ISO27001, GDPR-ready reports

### Long-Term Goals
- [ ] **Enterprise Edition**: Advanced features for large organizations
- [ ] **Threat Intelligence Integration**: Real-time pattern updates
- [ ] **Custom Rule Engine**: No-code rule creation for teams
- [ ] **API-First Design**: REST API for integration with other tools

## 🤝 Contributing & Community

As an open-source project built by a security professional, contributions are welcome! Here's how you can help improve SecretTrack:

### Ways to Contribute
1. **Report Issues**: Found a bug or have a feature request? Open an issue
2. **Submit Detectors**: Add detection for new services or improve existing ones
3. **Improve Documentation**: Help make SecretTrack more accessible
4. **Share Experiences**: Tell us how you're using SecretTrack in your workflow

### Development Setup
```bash
# 1. Clone and setup
git clone https://github.com/juphinmbaya/secrettrack.git
cd secrettrack

# 2. Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

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

# 4. Run tests
pytest tests/

# 5. Make your changes and test
# Your contribution here!
```

### Contributor Guidelines
- Follow Python best practices (PEP 8)
- Include comprehensive tests for new features
- Update documentation with changes
- Maintain backward compatibility where possible
- Security-focused code review for all changes

## 📄 License & Legal

### MIT License
```
MIT License

Copyright (c) 2024 Juphin Mbaya

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
```

### Security & Ethical Usage Disclaimer

**Important**: SecretTrack is designed exclusively for defensive security purposes:

#### ✅ Approved Uses
- Auditing your own codebases and repositories
- Security education and training exercises
- CI/CD security scanning with proper authorization
- Internal security assessments within your organization
- Open-source project security reviews

#### ❌ Strictly Prohibited
- Scanning systems without explicit written permission
- Attempting to discover secrets in third-party code
- Any malicious or unauthorized security testing
- Bypassing security controls or terms of service

**Always obtain proper authorization before scanning any systems. The creator assumes no liability for misuse.**

## 📞 Support & Contact

### Getting Help
- **GitHub Issues**: [Report bugs or request features](https://github.com/juphinmbaya/secrettrack/issues)
- **Documentation**: Comprehensive usage guides and examples
- **Security Questions**: For security-related inquiries, use GitHub Security Advisories

### About the Creator
**Juphin Mbaya** is a Cybersecurity Engineer specializing in Application Security, DevSecOps, and threat mitigation. With experience securing enterprise applications and infrastructure, Juphin builds tools that bridge the gap between security requirements and developer workflows.

### Connect & Collaborate
- **GitHub**: [@juphinmbaya](https://github.com/juphinmbaya)
- **LinkedIn**: [Juphin Mbaya](https://www.linkedin.com/in/juphin-mbaya-5a955a198)
- **Email**: For serious security inquiries only

### Enterprise Support
For organizations needing custom integrations, enterprise features, or dedicated support, contact for consultation on implementing SecretTrack at scale within your security program.

---

**SecretTrack** – Professional secret detection built by a security engineer, for security-conscious teams. 🔒

*"In cybersecurity, prevention isn't just better than cure—it's often the only cure."*  
**— Juphin Mbaya, Creator of SecretTrack**