How mav01-code/dark-web-breach-monitor works
What this project is (type + purpose)
This is a monolithic web application that provides a Dark Web / breach monitoring dashboard:
• Web UI: server-rendered HTML templates (login/register/dashboard/etc.)
• Backend/API: Flask app serving routes like /register, /login, /dashboard, and breach-check logic
• Data store: a single relational DB (schema hinted by DB.sql)
• External integration: Have I Been Pwned (HIBP) API for credential breach checks (k-anonymity using first 5 SHA1 hex chars)
• Real-time/recurring monitoring: Azure Functions timer/cron that periodically scans stored credentials and writes monitoring logs, which are plotted as a line chart in the dashboard
What the file tree tells you to include (map files → architecture)
Top-level artifacts imply these components:
Flask application (core runtime)
• app.py
Likely the main Flask server: routes, session handling, DB access, rendering templates, calling HIBP.
• templates/
Server-rendered UI pages:
• login.html, register.html → auth UI
• dashboard.html → main view that includes credential check + monitoring plot + remediation
• credential-storage.html, remediation.html → sub-views or dedicated pages
Azure Functions (scheduled monitor)
• function_app.py
• host.json
• AzuriteConfig
Database
• DB.sql
• register (users)
• credential (hashed credentials)
• monitoring logs table (name unknown—derive from DB.sql; if absent, show “monitoring_logs (inferred)”)
Configuration / dependencies
• requirements.txt → Flask + DB driver + requests, etc.
Given the small repo, L2 + one L3 are usually the “most value.”
Use these as the canonical nodes:
Client / UI
• User Browser
• Renders HTML/CSS from Flask templates
• Sends HTTP requests for register/login/credential check
Backend (monolith)
• Flask Web Server (app.py)
• Auth: /register, /login
• Dashboard: /dashboard
• Credential check service (internal module/function)
• Remediation scoring service (internal module/function)
• DB access layer (inline in app or separate helpers—represent it anyway)
Data
• Relational Database (“monitor DB”)
• Tables: register, credential, monitoring_logs (confirm actual names from DB.sql)
External services
• Have I Been Pwned API
• Called by Flask during credential check
• Possibly also called by Azure Function during periodic checks
Scheduled monitoring
• Azure Functions App (function_app.py)
• Timer Trigger (every 5 minutes)
• Reads credential table
• Calls HIBP (or re-checks)
• Writes monitoring logs (DB and/or storage)
Optional but worth including (if supported by code/config)
• Azure Storage (Blob/Table/Queue)
• If AzuriteConfig is used for local emulation, show the production equivalent as the backing service.
Flask (Credential Check)
• SHA1 hash password
• Take first 5 hex chars
Flask
• compare remaining suffix
• decide breached/safe (+ breach count)
Flask → DB
• if email not in credential table: store hashed password
• store breach results / last_checked / etc. (whatever exists in schema)
Browser → Flask → DB: dashboard loads monitoring logs
6. Flask → Browser: line plot data (either embedded server-side or delivered to front-end JS)
Flask (Remediation Engine)
• Inputs: breach count, password age, MFA flag
• Outputs: risk score + risk level (low/medium/high)
Architectural patterns/design principles to highlight (explicit callouts)
• Monolithic server: Flask handles UI rendering + API endpoints + business logic.
• Single DB: central source of truth for users, credentials, and monitoring logs.
• K-anonymity credential checking: only first 5 SHA1 chars sent to HIBP (privacy-preserving).
• Event/time-driven background processing: Azure Function timer acts as a cron-like scheduler.
• Separation of concerns inside monolith (even if not separated into modules in code): show “Auth”, “Credential Check”, “Monitoring Log Retrieval”, “Remediation Scoring” as internal components.
External: HIBP API
• Browser ↔ Flask (HTTP)
• Flask ↔ DB (SQL)
• Flask → HIBP (HTTPS)
• Azure Function ↔ DB (SQL)
• Azure Function → HIBP (HTTPS)
• “/register”, “/login”, “/dashboard”
• “SHA1 prefix query (first 5 hex chars)”
• “Timer: every 5 min”
• Auth Controller: register/login/session
• Dashboard Controller: renders dashboard.html
• Credential Check Service: hashing + HIBP parsing + store credential
• Remediation Scoring Service: rule-based scoring
• DB Access Layer: queries/inserts (even if direct)
• Template Renderer: templates/*.html
Connect:
• Controllers call services
• Services use DB layer
• Credential check uses HIBP client
Inside “Azure Functions”:
• Timer Trigger
• Credential Scanner (reads credential table)
• HIBP Client
• Monitoring Log Writer (writes DB logs)
Consistently:
• Clear labels: use file-based references where possible: “Flask (app.py)”, “Azure Function (function_app.py)”
• HTTP/HTTPS
• SQL
• Rectangles: compute (Flask, Azure Function)
• Cloud: external services (HIBP)
• Trust boundaries:
• Public Internet boundary between Browser and backend
• External service boundary around HIBP
• Data classification notes:
• “Store hashed password (SHA1)” in DB
• “Never send full hash/password to HIBP; only 5-char prefix”