secchecker 0.2.1

A comprehensive CLI tool to detect secrets and sensitive information in repositories for maintaining security best practices.

secchecker

secchecker is a comprehensive Python package + CLI tool designed to detect hardcoded secrets, sensitive information, and security vulnerabilities in code repositories. It helps developers maintain security best practices and keep their projects audit-ready.

Features

Comprehensive Secret Detection

• 40+ Secret Patterns covering major security categories:
  • Database Connections: PostgreSQL, MySQL, MongoDB, Redis
  • Cloud Provider Keys: AWS, Google Cloud, Azure
  • Authentication Tokens: JWT, Bearer tokens, Basic Auth
  • Private Keys: RSA, EC, DSA, PGP, SSH keys
  • Version Control: GitHub, GitLab tokens
  • Communication: Slack, Discord, Telegram bot tokens
  • Cryptocurrency: Bitcoin, Ethereum private keys
  • Sensitive Data: Credit cards, Social Security numbers
  • URLs with Credentials: HTTP/FTP with embedded auth

Advanced Reporting

• Multiple Output Formats: JSON, Markdown, XML
• Severity Classification: CRITICAL, HIGH, MEDIUM, LOW levels
• Rich Metadata: Timestamps, statistics, tool version info
• Professional Formatting: Emojis, structured layout, detailed breakdowns

Performance & Accuracy

• Smart File Filtering: Automatically skips binary files and build directories
• False Positive Detection: Filters common test/example patterns
• Multiple Encoding Support: Handles international text files
• Memory Efficient: Optimized for large repositories

Developer-Friendly CLI

• Verbose Mode: Detailed scanning information
• Custom Output: Specify output file paths
• Environment Configuration: Set default formats via environment variables
• Comprehensive Help: Detailed usage examples and options

Installation

From PyPI (Recommended)

pip install secchecker

From Source

git clone https://github.com/vishnu-77/secchecker.git
cd secchecker
pip install -e .

Usage

Basic Scanning

# Scan current directory with markdown report
secchecker .

# Scan specific path
secchecker /path/to/project

# Generate JSON report
secchecker . --format json

# Generate XML report with custom output
secchecker . --format xml --output security_audit.xml

# Verbose mode for detailed information
secchecker . --format md --verbose

Environment Configuration

# Set default report format
export SECHECKER_REPORT_FORMAT=json
secchecker .  # Will use JSON format by default

Command Line Options

secchecker --help

Options:

• --format {json,md,xml}: Report format (default: md)
• --output, -o: Custom output file path
• --verbose, -v: Enable verbose output
• --help, -h: Show help message

Example Output

Note: Check the sample-reports/ folder for complete example outputs in all formats.

Markdown Report

# Secret Scan Report

**Generated:** 2025-11-12T18:05:17.494792  
**Tool:** secchecker v0.2.0  

## Summary
- **Files Scanned:** 25
- **Secret Types Found:** 12
- **Total Matches:** 18

### Severity Breakdown
- **CRITICAL:** 3
- **HIGH:** 8
- **MEDIUM:** 5
- **LOW:** 2

## Detailed Findings
### `config/database.py`
- **RSA Private Key** (CRITICAL): 1 match(es)
- **AWS Access Key** (HIGH): 1 match(es)

JSON Report Structure

{
  "metadata": {
    "timestamp": "2025-11-12T18:05:17.494792",
    "version": "0.2.0",
    "tool": "secchecker"
  },
  "summary": {
    "total_files": 25,
    "total_secrets": 12,
    "total_matches": 18,
    "severity_counts": {"CRITICAL": 3, "HIGH": 8, "MEDIUM": 5, "LOW": 2}
  },
  "findings": {
    "config/database.py": {
      "AWS Access Key": {
        "matches": ["AKIAIOSFODNN7EXAMPLE"],
        "severity": "HIGH",
        "count": 1
      }
    }
  }
}

API Usage

Basic Scanning

from secchecker import scan_directory, scan_file
from secchecker.reporter import generate_report

# Scan a directory
results = scan_directory("/path/to/project")

# Scan a single file
findings = scan_file("/path/to/file.py")

# Generate reports
json_report = generate_report(results, "json")
markdown_report = generate_report(results, "md")
xml_report = generate_report(results, "xml")

Advanced Usage

from secchecker.core import get_scan_stats
from secchecker.reporter import get_severity

# Get scan statistics
stats = get_scan_stats(results)
print(f"Found {stats['total_files']} files with secrets")

# Check severity of specific patterns
severity = get_severity("AWS Access Key")  # Returns "HIGH"

Security Categories

Category	Examples	Severity
Private Keys	RSA, EC, DSA, PGP keys	CRITICAL
Financial Data	Credit cards, SSN	CRITICAL
Cloud Keys	AWS, Google, Azure secrets	HIGH
Database URIs	PostgreSQL, MySQL connections	HIGH
API Tokens	GitHub, GitLab, service tokens	HIGH
Auth Tokens	JWT, Bearer tokens	MEDIUM
Config Passwords	Application passwords	MEDIUM
Contact Info	Email addresses	LOW

Performance

• Fast Scanning: Optimized regex patterns and smart file filtering
• Memory Efficient: Processes large repositories without memory issues
• Accurate Detection: Low false positive rate with pattern validation
• Cross-Platform: Works on Windows, macOS, and Linux

Testing

# Run the full test suite
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=secchecker --cov-report=html

Integration

CI/CD Pipeline Integration

# GitHub Actions example
- name: Security Scan
  run: |
    pip install secchecker
    secchecker . --format json --output security-report.json
    # Fail build if critical secrets found

Pre-commit Hook

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: secchecker
        name: Secret Checker
        entry: secchecker
        language: system
        args: ['.', '--format', 'md']

---

Disclaimer

secchecker is intended only for security auditing of repositories you own or have explicit permission to test.

• Misuse of this tool to access, scan, or extract information from systems you do not own is strictly prohibited and may violate the law.
• The author(s) assume no liability for misuse or damages caused by this software.
• Use responsibly for legitimate security auditing purposes only.

---

Terms & Conditions

By using secchecker, you agree to the following:

1. You will only use this tool on codebases you own or have explicit authorization to audit.
2. You will not use this software for malicious purposes, including but not limited to unauthorized access, exploitation, or data theft.
3. The software is provided "as is," without warranty of any kind, express or implied.
4. The author(s) are not responsible for any damages, losses, or legal consequences arising from the use or misuse of this software.
5. You accept full responsibility for ensuring that your use of this tool complies with applicable laws and regulations in your jurisdiction.

---

Contributing

Contributions are welcome! Here's how you can help:

🐛 Bug Reports & Feature Requests

• Open an issue on GitHub with detailed information
• Include sample code or files that demonstrate the issue
• Specify your environment (OS, Python version, etc.)

Development Setup

git clone https://github.com/vishnu-77/secchecker.git
cd secchecker
pip install -e ".[dev]"  # Install with development dependencies

🧪 Running Tests

pytest tests/ -v                    # Run tests
black secchecker/ tests/            # Format code
flake8 secchecker/ tests/           # Lint code
mypy secchecker/                    # Type checking

Adding New Patterns

1. Add patterns to secchecker/patterns.py
2. Add severity mapping in secchecker/reporter.py
3. Add tests in tests/test_patterns.py
4. Update documentation

Pull Request Process

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

🙏 Acknowledgments

• Inspired by security best practices from the DevSecOps community
• Thanks to all contributors and security researchers
• Built with dedication for the open-source community

📚 Resources

• OWASP Top 10
• GitHub Secret Scanning
• DevSecOps Best Practices