BlockMaster - System Level Website Blocker for macOS

BlockMaster is a powerful system-level website blocking solution for macOS that provides unbreakable website blocking at the network level, making blocked sites inaccessible through any browser or application.

🚀 Quick Start

🚀 One-Click Installation

Option 1: DMG Installer (Recommended)

# Download the .dmg file
curl -O https://github.com/bythebug/Block-Master-System-Level-Website-Blocker/releases/latest/download/BlockMaster-2.0.0.dmg

# Double-click to mount and drag to Applications
open BlockMaster-2.0.0.dmg

Option 2: Script Installer

# Download the installer
curl -O https://raw.githubusercontent.com/bythebug/Block-Master-System-Level-Website-Blocker/main/install.sh

# Make it executable and run
chmod +x install.sh
./install.sh

Or install manually:

# Clone the repository
git clone https://github.com/bythebug/Block-Master-System-Level-Website-Blocker.git
cd Block-Master-System-Level-Website-Blocker

# Install dependencies
pip3 install -r requirements.txt

# Run BlockMaster
python3 src/launcher.py

Usage

1. DMG Installer: Download and double-click BlockMaster-2.0.0.dmg
2. BlockMaster GUI: python3 src/launcher.py
3. Console Version: python3 src/console_blocker.py
4. Script Installer: ./install.sh

🛡️ Features

• Dual-Layer Blocking: Hosts file + pfctl packet filtering for unbreakable blocking
• Browser-Proof: Works even with DNS-over-HTTPS and incognito mode
• Multiple Interfaces: GUI (tkinter), Advanced (web), and Console versions
• Real-Time Status: Live system status monitoring
• Automatic Backups: Safe system file protection
• Permission Handling: Seamless sudo integration with GUI password prompts
• System Safety: Comprehensive error handling and rollback capabilities
• Smart URL Processing: Handles complex URLs with subdomains, paths, and ports
• Enhanced DNS Cache Flushing: Clears system and browser DNS caches for immediate effect
• Professional GUI: Clean, modern interface with author branding
• Production Ready: Thoroughly tested and bug-free

🆕 Recent Updates (v2.0.0)

🐛 Critical Bug Fixes

• Fixed Website Removal Issue: Websites now unblock immediately after removal
• Enhanced Hosts File Cleaning: Proper removal of both markers and block entries
• Improved pfctl Rules Management: Safer firewall rule handling
• Smart URL Processing: Better handling of complex URLs with subdomains and paths

🚀 New Features

• Professional DMG Installer: Single-file download and installation
• Enhanced DNS Cache Flushing: Clears system and browser caches
• Simplified Launcher: Clean, single-button interface
• Production Ready: Comprehensive testing and validation

🔧 Technical Improvements

• Better Error Handling: More robust error management
• Improved Safety: Enhanced backup and rollback capabilities
• Performance Optimizations: Faster and more reliable operations

📁 Project Structure

blockmaster/
├── src/                    # Source code
│   ├── website_blocker.py      # Main GUI version (tkinter)
│   ├── advanced_blocker.py     # Advanced version with web interface
│   ├── console_blocker.py      # Console version
│   ├── launcher.py            # Application launcher
│   ├── safety_manager.py      # System safety and backup management
│   ├── tkinter_sudo_helper.py # Sudo integration for GUI
│   └── gui_permission_helper.py # Permission management GUI
├── scripts/                # Installation and utility scripts
│   ├── install.sh             # Installation script
│   ├── uninstall.sh           # Uninstallation script
│   └── test_blocker.py        # Testing script
├── docs/                   # Documentation
│   ├── README.md              # Detailed documentation
│   ├── QUICK_START.md         # Quick start guide
│   └── CONTRIBUTING.md        # Contributing guidelines
├── requirements.txt        # Python dependencies
├── LICENSE                 # MIT License
└── .gitignore             # Git ignore rules

🔧 System Requirements

• macOS: 10.12 (Sierra) or later
• Python: 3.6 or later
• Administrator Privileges: Required for system file modification
• Internet Connection: For initial setup

📚 Documentation

• Detailed README - Complete documentation
• Quick Start Guide - Get started quickly
• Contributing Guidelines - How to contribute

🚀 How It Works

This blocker uses dual-layer protection for unbreakable blocking:

Layer 1: Hosts File Blocking

• Modifies /etc/hosts - Redirects blocked domains to localhost (127.0.0.1)
• DNS-level blocking - Prevents domain resolution

Layer 2: Packet Filter (pfctl)

• Network-level blocking - Blocks packets at the kernel level
• IP address blocking - Blocks actual IP addresses of blocked domains
• Unbreakable protection - Cannot be bypassed by any method

Additional Features

• Automatic DNS cache flush - Ensures immediate effect
• Real-time status monitoring - Shows blocking status
• Safe backup system - Protects system files

Unlike browser extensions, this solution:

• ✅ Works across ALL browsers (Chrome, Firefox, Safari, Brave, etc.)
• ✅ Cannot be bypassed by incognito mode, DNS-over-HTTPS, or VPNs
• ✅ Survives system reboots - Permanent blocking
• ✅ Integrates with macOS networking stack
• ✅ Network-level protection - Blocks at the kernel level

⚠️ Important Notes

• Administrator Privileges Required: This application modifies system files
• Automatic Backups: Creates backups before making changes
• Local Only: No data is sent to external servers
• Open Source: Full transparency and community contributions

🛠️ Development

Running Tests

python3 scripts/test_blocker.py

Contributing

See CONTRIBUTING.md for detailed guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

👨‍💻 Author

Suraj Van Verma

• LinkedIn: https://www.linkedin.com/in/bythebug

🤝 Contributing

Contributions are welcome! Please read our Contributing Guidelines for details.

⭐ Support

If you find this project helpful, please give it a star on GitHub!

---

Made with ❤️ for macOS users who want true system-level website blocking