CredGuard

A Streamlit-based security monitoring application that helps detect if credentials (emails, domains) have been exposed in data breaches or leaked in public code repositories.

Features

• Breach Detection: Check emails against HaveIBeenPwned database
• Code Leak Search: Scan GitHub for exposed credentials in public repositories
• ML Risk Scoring: IsolationForest-based anomaly detection for risk assessment
• Visual Dashboard: Interactive charts showing breach timeline and risk gauge
• PDF Reports: Downloadable security reports for documentation
• Usage Quotas: Redis-based rate limiting (50 scans/month free tier)
• Premium Upgrade: Stripe integration for subscription billing

Architecture

cred/
├── app.py                    # Main Streamlit application
├── requirements.txt          # Python dependencies
├── .env.example              # Environment variables template
├── SECURITY_AUDIT.md         # Security audit documentation
├── tests/                    # Unit tests (94 tests)
│   ├── test_billing.py
│   ├── test_db.py
│   ├── test_github_client.py
│   ├── test_hibp_client.py
│   ├── test_ml_score.py
│   ├── test_report_generator.py
│   ├── test_risk_levels.py
│   ├── test_validation.py
│   └── test_visuals.py
└── utils/
    ├── billing.py            # Stripe checkout integration
    ├── db.py                 # Supabase + Redis connections
    ├── github_client.py      # GitHub API for secret scanning
    ├── hibp_client.py        # HaveIBeenPwned API client
    ├── ml_score.py           # IsolationForest risk scoring
    ├── report_generator.py   # PDF report generation
    ├── risk_levels.py        # Risk classification utilities
    ├── validation.py         # Input validation & sanitization
    └── visuals.py            # Plotly visualizations

Prerequisites

• Python 3.10+
• Supabase account (PostgreSQL database)
• Upstash Redis account
• HaveIBeenPwned API key (optional, uses stub data without it)
• GitHub token (optional, for higher API rate limits)
• Stripe account (for billing features)

Installation

1. Clone the repository

   git clone <repository-url>
   cd cred

2. Create virtual environment

   python -m venv .venv
   source .venv/bin/activate  # Linux/Mac
   # or
   .venv\Scripts\activate     # Windows

3. Install dependencies

   pip install -r requirements.txt

4. Configure environment variables

   cp .env.example .env
   # Edit .env with your credentials

5. Set up Supabase database

   Create a users table with the following schema:

   CREATE TABLE users (
       id UUID DEFAULT uuid_generate_v4() PRIMARY KEY,
       email TEXT UNIQUE NOT NULL,
       password_hash TEXT NOT NULL,
       created_at TIMESTAMP DEFAULT NOW()
   );

Environment Variables

Variable	Description	Required
SUPABASE_URL	Supabase project URL	Yes
SUPABASE_KEY	Supabase service role key	Yes
UPSTASH_REDIS_URL	Redis connection URL	Yes
COOKIE_KEY	Secret key for session cookies	Yes
HIBP_API_KEY	HaveIBeenPwned API key	No (uses stub data)
GITHUB_TOKEN	GitHub personal access token	No
STRIPE_API_KEY	Stripe secret key	No
STRIPE_PRICE_ID	Stripe subscription price ID	No
SENTRY_DSN	Sentry error tracking DSN	No

Usage

1. Start the application

   streamlit run app.py

2. Access the app

   Open http://localhost:8501 in your browser

3. Create an account or log in

4. Run a scan

   • Enter an email address (e.g., user@example.com) or domain (e.g., example.com)
   • Click "Run Scan"
   • View results in the dashboard
   • Download PDF report if needed

Running Tests

# Install test dependencies
pip install pytest pytest-mock

# Run all tests
pytest tests/ -v

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

API Integrations

HaveIBeenPwned

• Checks if an email appears in known data breaches
• Rate limited to 1 request per 1.5 seconds
• Requires paid API key for production use

GitHub Code Search

• Searches public repositories for exposed credentials
• Looks for domain + "password" in .env files
• Works without authentication (lower rate limits)

Risk Scoring

The ML risk score (0-100) is calculated using:

Factor	Weight
Number of breaches	High
Age of oldest breach	Medium
Critical data exposed (passwords, banking)	Critical override (min 70)

Risk Levels:

• LOW (0-30): No significant exposure detected
• MEDIUM (31-70): Some exposure, review recommended
• CRITICAL (71-100): Immediate action required

Security Features

• Password hashing with bcrypt
• Input validation for emails and domains
• Filename sanitization for PDF downloads
• Fail-safe quota system (denies on error)
• No verbose error messages to users

See SECURITY_AUDIT.md for detailed security documentation.

Development

Code Style

# Check linting
flake8 app.py utils/ --max-line-length=120

# Format code (optional)
black app.py utils/

Adding New Features

1. Create utility module in utils/
2. Add corresponding tests in tests/
3. Import and use in app.py
4. Update this README

Limitations (MVP)

• All users loaded into memory at startup (not scalable)
• Synchronous API calls (no background processing)
• Single-page PDF reports (no pagination)
• No email notifications
• No scheduled monitoring

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Run linting and tests
5. Submit a pull request