PyBlock is a production-grade Manifest V3 Chrome Extension and Python rule compilation engine built for real-time network request blocking, tracker classification, domain analytics, and cosmetic element cleanup.
PyBlock is designed with a dual architecture philosophy:
- Standalone Chrome Extension: Operates 100% inside Google Chrome using native
declarativeNetRequest(DNR) APIs with zero reliance on local databases, proxy servers, or background Python processes during browsing. - Optional Python Processing Engine: An offline/local microservice for fetching, parsing, optimizing, deduplicating, validating, and compiling standard filter lists (ABP, uBlock Origin, Hosts files) into Chrome MV3 compliant JSON rulesets.
- 🛡️ Declarative Network Request (DNR) Blocking: Intercepts ad servers, telemetry endpoints, tracking pixels, and malicious redirects at the browser network layer with minimal memory and CPU overhead.
- 🎯 Domain & Tracker Classification: Categorizes request patterns into Advertising, Analytics, Fingerprinting, Social Tracking, Telemetry, and Annoyances.
- 🧹 Cosmetic Cleanup & Anti-Adblock Mitigation: Hides blank ad slots and suppresses soft anti-adblock overlay backdrops without breaking page layout or script execution.
- ⚡ Dynamic Rule Whitelisting: Per-site instant protection pause/resume that dynamically updates MV3 allow rules in real time.
- 📊 Cybersecurity Dashboard & Popup UI: Modern dark theme glassmorphism interfaces displaying block statistics, category breakdowns, recent request logs, and whitelist managers.
- 🔧 Python Optimization Pipeline: Rule parser, deduplicator, ID conflict resolver, schema validator, and rule generator adhering to Chrome MV3 quotas.
PyBlock/
├── extension/
│ ├── manifest.json # Manifest V3 setup with DNR, storage, scriptings permissions
│ ├── background/
│ │ └── service-worker.js # DNR rule state, badge counters, popup messaging, whitelist sync
│ ├── content/
│ │ ├── content.js # Cosmetic filtering (hiding empty ad containers), anti-adblock mitigation
│ │ └── content.css # Base cosmetic hide rules
│ ├── popup/
│ │ ├── popup.html # Compact extension popup UI (Stats, Toggle, Refresh, Quick Links)
│ │ ├── popup.css # Dark/Light cybersecurity theme styling
│ │ └── popup.js # Popup logic, communication with service-worker
│ ├── dashboard/
│ │ ├── dashboard.html # Full-page analytics & statistics dashboard
│ │ ├── dashboard.css # Glassmorphism/Dark modern UI theme
│ │ └── dashboard.js # Statistics display, request logs, domain breakdowns
│ ├── settings/
│ │ ├── settings.html # Settings manager (Protection modes, Whitelist, Custom Rules, Python API link)
│ │ ├── settings.css # Settings visual styles
│ │ └── settings.js # Settings persistence using chrome.storage.local
│ ├── rules/
│ │ └── generated-rules.json # Pre-compiled MV3 declarativeNetRequest rule file
│ └── icons/ # 16px, 48px, 128px PyBlock branding icons
│
├── python/
│ ├── main.py # CLI & optional FastAPI/Flask local service runner
│ ├── rule_parser.py # ABP / uBlock filter list line parser (domains, options, types)
│ ├── rule_generator.py # Rule compiler (maps parsed rules to MV3 DNR JSON format)
│ ├── domain_classifier.py # Category classifier (Ads, Analytics, Social, Cryptomining, Telemetry)
│ ├── tracker_classifier.py # Advanced domain fingerprinting & tracker category analyzer
│ ├── validator.py # DNR schema validator, ID collision check, Chrome limits verification
│ └── updater.py # HTTP filter list retriever with fallback caching
│
├── rules/ # Raw & intermediate configuration files
│ ├── ads.json # Raw ad domains & URL patterns
│ ├── trackers.json # Raw tracking endpoints
│ ├── privacy.json # Privacy & telemetry patterns
│ ├── annoyances.json # Popup overlays & cosmetic block targets
│ ├── custom.json # User-defined custom rules
│ └── whitelist.json # Domain/URL whitelisting rules
│
├── config/
│ └── settings.json # Default extension configuration & filter source URLs
│
├── tests/
│ ├── test_parser.py # Pytest suite for filter list syntax parsing
│ ├── test_matcher.py # Python matcher verification tests
│ └── test_rules.py # Rule validation, schema conformity, deduplication tests
│
├── requirements.txt # Python dependencies (requests, pydantic, fastapi, pytest, etc.)
├── README.md # Comprehensive technical documentation
└── LICENSE # MIT License
- Open Google Chrome and navigate to
chrome://extensions. - Enable Developer mode in the top right corner.
- Click Load unpacked.
- Select the
PyBlock/extensiondirectory. - Click the PyBlock shield icon in your Chrome toolbar!
To fetch external lists, parse customized rules, or run the local FastAPI microservice:
Install dependencies:
pip install -r requirements.txt
Compile and optimize raw rules into extension rules:
python python/main.py --build
Validate compiled rule schema:
python python/main.py --validate
Run automated unit test suite:
pytest tests/
(Optional) Run local API microservice:
python python/main.py --serve
Microservice exposes
GET /status,POST /rules/update,POST /rules/validate,GET /classify?domain=...onhttp://127.0.0.1:8765.
- No Remote Code Execution: Full compliance with Manifest V3 policies. No
eval(), no remote script injection, no untrusted HTML string innerHTML manipulation. - Privacy-First: No database required. Lightweight local storage (
chrome.storage.local) holds user preferences and session statistics. - Fail-Safe Operation: If external filter sources or the local Python server are unreachable, PyBlock continues executing with its built-in generated ruleset.
- Ad-Block Detection: No ad blocker can guarantee 100% bypass of complex server-side anti-adblock paywalls. PyBlock uses safe, non-intrusive cosmetic hiding.
- Manifest V3 Ruleset Limits: Chrome restricts static rules to 30,000 rules per ruleset. PyBlock's Python engine automatically prunes and deduplicates rules to adhere to Chrome limits.
Distributed under the MIT License.