Skip to content

README.md

Latest commit

 

History

History
265 lines (203 loc) · 7.8 KB

README.md

File metadata and controls

265 lines (203 loc) · 7.8 KB

System Website Blocker for macOS

A comprehensive system-level website blocking solution for macOS that blocks websites at the network level, making them inaccessible through any browser or application.

🚀 Features

Basic Version

  • Hosts File Blocking: Redirects blocked websites to localhost
  • Simple GUI: Easy-to-use interface for managing blocked sites
  • Real-time Status: Check if websites are actually blocked
  • Automatic Backups: Creates backups before making changes
  • DNS Cache Flushing: Automatically flushes DNS cache after changes

Advanced Version

  • Multiple Blocking Methods:
    • Hosts file blocking
    • Packet filter (pfctl) blocking
    • Combined blocking for maximum effectiveness
  • Scheduled Blocking: Set up time-based blocking schedules
  • Network Monitoring: Real-time network statistics and monitoring
  • Web Interface: Manage blocks through a web browser
  • Advanced Settings: Custom pfctl rules, DNS configuration
  • Comprehensive Logging: Track blocked attempts and network activity

🛡️ How It Works

System-Level Blocking

Unlike browser extensions, this application blocks websites at the system level by:

  1. Hosts File Modification: Adds entries to /etc/hosts that redirect blocked domains to 127.0.0.1
  2. Packet Filter Rules: Uses macOS's built-in pfctl to block network packets
  3. DNS Cache Management: Flushes DNS cache to ensure immediate effect

Why It's More Effective

  • Universal Blocking: Works across all browsers, applications, and network tools
  • Bypass-Proof: Cannot be circumvented by using different browsers or incognito mode
  • System Integration: Integrates with macOS networking stack
  • Persistent: Survives browser restarts and system reboots

📋 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 and dependency installation

🚀 Installation

Quick Install

  1. Download or clone this repository
  2. Open Terminal and navigate to the project directory
  3. Run the installation script: 
    chmod +x install.sh
./install.sh

Manual Installation

  1. Install Python dependencies:

    pip3 install -r requirements.txt

  2. Make scripts executable:

    chmod +x *.py

  3. Run the launcher:

    python3 launcher.py

🎯 Usage

Starting the Application

  1. Desktop Shortcut: Double-click the "WebsiteBlocker" icon on your desktop
  2. Applications Folder: Run /Applications/WebsiteBlocker/WebsiteBlocker.command
  3. Terminal: Navigate to the installation directory and run python3 launcher.py

Basic Usage

  1. Launch: Choose between Basic or Advanced version
  2. Add Websites: Enter URLs to block (e.g., facebook.com, youtube.com)
  3. Apply Blocks: Click "Apply Blocks" to activate blocking
  4. Verify: Use "Refresh Status" to verify websites are blocked
  5. Remove: Use "Remove All Blocks" or "Remove Selected" to unblock

Advanced Features

Scheduled Blocking

  • Set specific times and days for blocking
  • Configure duration for temporary blocks
  • Automatic activation and deactivation

Network Monitoring

  • Real-time connection monitoring
  • Blocked attempt tracking
  • Network statistics export

Web Interface

  • Access via http://localhost:8080
  • Remote management capabilities
  • Mobile-friendly interface

⚙️ Configuration

Blocking Methods

  • Hosts File: Fast and reliable, works immediately
  • Packet Filter: More comprehensive, blocks at network level
  • Both: Maximum effectiveness with redundancy

Custom Settings

  • pfctl Rules: Add custom packet filter rules
  • DNS Servers: Configure custom DNS servers
  • Backup Settings: Automatic backup configuration

🔧 Troubleshooting

Common Issues

"Permission Denied" Error

  • Solution: Run with administrator privileges
  • Command: sudo python3 launcher.py

Websites Still Accessible

  1. Check if blocking is actually applied
  2. Clear browser cache and cookies
  3. Flush DNS cache manually: 
    sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

Application Won't Start

  1. Check Python installation: python3 --version
  2. Install dependencies: pip3 install -r requirements.txt
  3. Check system requirements

Advanced Troubleshooting

Check Hosts File

sudo cat /etc/hosts | grep -i "website blocker"

Verify DNS Resolution

nslookup blocked-website.com

Check pfctl Status

sudo pfctl -s rules

🛠️ Development

Project Structure

Blocker/
├── website_blocker.py      # Basic version
├── advanced_blocker.py     # Advanced version
├── launcher.py            # Application launcher
├── requirements.txt       # Python dependencies
├── install.sh            # Installation script
├── uninstall.sh          # Uninstallation script
└── README.md             # This file

Adding New Features

  1. Fork the repository
  2. Create a feature branch
  3. Implement your changes
  4. Test thoroughly
  5. Submit a pull request

🔒 Security Considerations

System Access

  • This application requires administrator privileges
  • It modifies system files (/etc/hosts, /etc/pf.conf)
  • Always backup your system before installation

Data Privacy

  • No data is sent to external servers
  • All configuration is stored locally
  • Network monitoring data stays on your machine

Best Practices

  • Use automatic backups
  • Test blocking on non-critical websites first
  • Keep the application updated
  • Monitor system logs for issues

📚 Technical Details

Hosts File Blocking

  • Adds entries like 127.0.0.1 facebook.com to /etc/hosts
  • Redirects DNS resolution to localhost
  • Immediate effect after DNS cache flush

Packet Filter Blocking

  • Uses macOS's built-in packet filter (pfctl)
  • Blocks network packets at the kernel level
  • More comprehensive but requires system restart

DNS Management

  • Automatically flushes DNS cache after changes
  • Uses dscacheutil and mDNSResponder
  • Ensures immediate effect of blocking

🤝 Contributing

We welcome contributions! Please see our contributing guidelines:

  1. Bug Reports: Use GitHub issues with detailed information
  2. Feature Requests: Describe the feature and its use case
  3. Code Contributions: Follow the existing code style
  4. Documentation: Help improve this README and other docs

📄 License

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

⚠️ Disclaimer

This software is provided "as is" without warranty. Use at your own risk. The authors are not responsible for any damage to your system or data. Always backup your system before making changes.

🆘 Support

Getting Help

  1. Check this README for common solutions
  2. Search GitHub Issues for similar problems
  3. Create a new issue with detailed information
  4. Include system information (macOS version, Python version, error messages)

System Information

When reporting issues, please include:

  • macOS version
  • Python version
  • Error messages
  • Steps to reproduce
  • System logs (if relevant)

🔄 Updates

Checking for Updates

  • Monitor the GitHub repository for new releases
  • Check the application's built-in update checker
  • Subscribe to release notifications

Updating

  1. Download the latest version
  2. Run the uninstall script: ./uninstall.sh
  3. Run the install script: ./install.sh
  4. Your configuration will be preserved

👨‍💻 Author

Suraj Van Verma

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