How tontonjo/calmweb works
Project Type and Purpose
• Calm Web is a Windows-based, system-wide HTTP/HTTPS proxy and web-filter tool written in Python.
• Its goal is to protect non-technical users by blocking ads, scams, remote-control tools, and unwanted domains via configurable blocklists and whitelists.
• It installs as a local proxy service, configures firewall rules and scheduled tasks, and periodically updates filter lists from remote sources.
Core Components
a. Installer Component
• calmweb_installer.py (packaged as calmweb_proxy.exe)
• Actions: copy files to C:\Program Files\CalmWeb, set up Windows Firewall rule, create Windows Scheduled Task, launch proxy service
b. Proxy Service / Filter Engine
• Python service that intercepts all HTTP/HTTPS traffic on localhost
• Loads blocklists/whitelists from local “filters” folder and remote URLs
• Applies domain-based and port-based filtering logic
• Logs blocked/allowed requests
c. Configuration & Data Storage
• Local filter files: filters/blocklist.txt, whitelist.txt, usefull_domains.txt, remote_desktop.txt
• Custom cfg under %appdata%\calmweb\custom.cfg for user-added rules
• ressources/readme.txt (documentation)
d. Scheduler & Updater
• Windows Scheduled Task triggers on startup (and periodic intervals)
• Updater module fetches and merges remote blocklists (StevenBlack, EasyList, DNS blocklists, URLHaus, etc.)
e. OS Integration Layer
• Windows Firewall API (enforce proxy port blocking)
• Windows Task Scheduler API
• System proxy settings (Windows registry or winhttp proxy)
f. Client Applications
• Any user browser or network-enabled program
• All outbound traffic is routed to the local proxy on port (e.g., 8080)
Relationships and Data Flow
1) User launches calmweb_proxy.exe → Installer sets up environment
2) Installer starts Proxy Service → registers service with OS
3) OS routes all HTTP/HTTPS traffic from Client Apps to Proxy Service
4) Proxy Service reads Configuration & Data Storage → builds in-memory filter rules
5) For each HTTP(S) request:
• Check domain/IP against Whitelist → allow immediately
• Else check against Blocklists or non-standard ports → block or drop
• Log outcome
• Forward allowed requests to destination server
6) Scheduler invokes Updater → fetches remote lists → updates local filter files → triggers Proxy Service reload of rules
Architectural Patterns & Design Principles
• Modular separation: installer, proxy engine, updater, storage, OS integration
• Single Responsibility: each module does one job (installation, filtering, updating)
• Plugin-style filter lists: easily add/remove blocklists or custom rules
• Resilience: scheduled updates, automatic startup, firewall enforcement