Skip to content

About

A full-stack cyber threat intelligence platform for tracking dark web data breaches, mapping global cyber-attacks, and monitoring compromised assets using Flask, Angular, and MongoDB.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

BreachLens

Enterprise-Grade Cyber Threat Intelligence Platform - High-performance full-stack application for tracking data breaches, mapping cyber-attacks, and monitoring compromised assets.

Backend Tests Frontend Tests Coverage Backend CI Frontend CI Python Angular


Overview

BreachLens is a production-ready cyber threat intelligence platform designed to track and analyze data breaches globally. The platform provides:

  • Scalable Exposure Checks: High-speed email exposure detection using an in-memory Bloom Filter architecture.
  • Personal Defense Hub: A dedicated workspace for authenticated users featuring Risk Genome Breakdown (DNA deconstruction of leaks) and Tactical Defense Playbooks.
  • Privacy-First Security: k-Anonymity password checking via the Pwned Passwords API.
  • Geospatial Mapping: Visualize breach origins and affected regions globally.
  • Risk Analytics: Aggregated insights on industry risks, severity trends, and exposure metrics.
  • Enterprise Auth: Industry-standard Bearer Token (JWT) authentication with automated TTL-based revocation.

System Architecture

Detailed technical documentation on the system integration, data flow, and infrastructure components can be found in the ARCHITECTURE.md file.


Features

Production-Grade Infrastructure

  • Bloom Filter Architecture - High-speed scalable gate for millions of exposed email signatures (1.7MB footprint).
  • k-Anonymity Password Checker - Privacy-preserving exposure checks using SHA-1 range hashing.
  • Automated OSINT Sync - GitHub Action-powered daily synchronization with HaveIBeenPwned, XposedOrNot, and Ransomware.live repositories.
  • Dual-Tier CI/CD - Automated quality gates for both Backend and Frontend via GitHub Actions.
  • Cloud Rate Limiting - Production-grade brute-force protection using Upstash Redis.

Core Functionality

  • 65 REST API Endpoints - Complete CRUD operations for breaches, users, and analytics.
  • Defense Hub - Personal security posture center with Threat Magnitude (0-10) benchmarking.
  • Risk Genome - Categorization of exposed data into four functional vectors: Identity, Credentials, Financial, and Technical.
  • Tactical Playbook - Dynamic, priority-ranked remediation plans (Critical, High, Medium actions).
  • Geospatial Mapping - Leaflet-js tactical map with GeoJSON telemetry.
  • Interactive Alerts - Real-time "Open Alerts" overlay for monitoring unacknowledged security events.
  • Dark/Light Themes - System-aware theming with CSS custom properties.
  • Comprehensive Testing - 889 tests across backend (634) and frontend (255).

Technology Stack

Backend (Flask + MongoDB)

  • Database: MongoDB 7.0 (Atlas) with TTL indexes.
  • Caching/Rate-Limit: Upstash Redis (Production) / In-memory (Dev).
  • Security: Flask-Talisman (CSP/HSTS), Flask-Limiter, BCrypt (12 rounds).
  • Architecture: Layered Service Pattern with OSINT ETL Pipeline.

Frontend (Angular 17)

  • Framework: Angular 17.3 (Standalone components, Signals).
  • Mapping: Leaflet.js with Stadia Maps + OpenStreetMap tiles.
  • Charts: Chart.js 4.4 (Theme-reactive).

Quick Start

1. Setup Backend

cd backend
pip install -r requirements.txt
cp .env.example .env
# Build production assets (Bloom Filter + OSINT Sync)
bash build.sh
# Start API
python run.py

2. Setup Frontend

cd frontend
npm install
npm start

API & Authentication

Authentication

BreachLens uses standard Bearer Token authentication.

# Login to get JWT
POST /api/v1/auth/login
{
  "email": "<your-email>",
  "password": "<your-password>"
}

# Use token in headers
Authorization: Bearer <YOUR_TOKEN>

Full API Reference: docs/API_SPEC.md


Security & CI/CD

Continuous Integration

Our GitHub Actions pipeline ensures code quality on every push:

  • Linting: Style enforcement via flake8.
  • Security: Automated vulnerability scanning via Bandit.
  • Testing: Full PyTest suite with coverage tracking.

Cloud Deployment

  • Backend: Hosted on Render (Blue/Green deployment from main).
  • Frontend: Hosted on Vercel with SPA routing logic.
  • Data: MongoDB Atlas (Primary) + Upstash Redis (Rate Limiting).

Frontend Highlights

Angular 17 single-page application with 14 standalone components and full backend integration.

  • Interactive Breach Map: Leaflet.js with GeoJSON markers and severity coloring.
  • Analytics Dashboard: 6 Chart.js visualizations (bar, line, doughnut, etc.).
  • Advanced Search: Multi-criteria filtering and auto-suggestions.
  • Breach Management: Full CRUD with sub-document management.
  • Admin Panel: User management, role changes, and audit trail.
  • Theme-Aware: System preference detection (Dark/Light).

Testing

The project has comprehensive test coverage: 889 total tests.

# Backend tests
cd backend && pytest tests/ -v

# Frontend tests
cd frontend && npx ng test --watch=false --browsers=ChromeHeadless

Development & Local Testing

Security Warning

The following credentials are provided exclusively for local development and initial testing. They are automatically created by the seed/seed_data.py script. Do not use these in a production environment.

Role Default Email Password Permissions
Admin admin@breachlens.io Auto-generated Full system access
Analyst priya@breachlens.io Auto-generated Read + Write access
Guest marcus@example.com Auto-generated Limited read-only access

Note: All seeded accounts are initialized in an unlocked state (failed_login_attempts: 0). During initial seeding via seed_data.py or build.sh, secure random passwords will be generated and printed to your terminal. Please save these securely. You can override these defaults by setting ADMIN_PASSWORD, ANALYST_PASSWORD, and GUEST_PASSWORD in your .env file.


License

This project is licensed under the MIT License. See LICENSE for details.


Authors

Ritik Sah

Last Updated: May 2026 Version: v1.0.0 (Web Platform)


Roadmap

Current Version (v1.0.0)

  • Optimized for desktop and widescreen security terminals.
  • Full dashboard, map, and analytics capabilities.
  • Personal Defense Hub and OSINT synchronization.

Future Release (v2.0.0)

  • Mobile Responsive Interface: Refined UI for smartphones and tablets.
  • Push Notifications: Real-time breach alerts for mobile devices.
  • Advanced API Integrations: Expanded OSINT source peering.

About

A full-stack cyber threat intelligence platform for tracking dark web data breaches, mapping global cyber-attacks, and monitoring compromised assets using Flask, Angular, and MongoDB.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages