secrettrack 1.0.2

A professional tool for detecting exposed secrets in code and configuration files

🔍 SecretTrack

👨‍💻 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)

pip install secrettrack

Installation from source

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

Quick Verification

# 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

# 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)

{
  "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

# 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:

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)

# .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)

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

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

# 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
• 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
• LinkedIn: Juphin Mbaya
• 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