macblock 0.2.1__tar.gz

macblock-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 macblock contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

macblock-0.2.1/PKG-INFO

@@ -0,0 +1,195 @@
+Metadata-Version: 2.4
+Name: macblock
+Version: 0.2.1
+Summary: Local DNS sinkhole for macOS using dnsmasq
+Author: macbblock contributiers
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/SpyicyDev/macblock
+Project-URL: Repository, https://github.com/SpyicyDev/macblock
+Project-URL: Issues, https://github.com/SpyicyDev/macblock/issues
+Project-URL: Changelog, https://github.com/SpyicyDev/macblock/blob/main/CHANGELOG.md
+Keywords: dns,ad-blocker,dnsmasq,macos
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet :: Name Service (DNS)
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: ruff>=0.8.0; extra == "dev"
+Requires-Dist: pyright>=1.1.390; extra == "dev"
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Dynamic: license-file
+
+# macblock
+
+[![CI](https://github.com/SpyicyDev/macblock/actions/workflows/ci.yml/badge.svg)](https://github.com/SpyicyDev/macblock/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Local DNS sinkhole for macOS using `dnsmasq` on `127.0.0.1:53`, with automatic system DNS configuration and split-DNS preservation.
+
+## Vibe-coding disclaimer
+
+Most of this project was vibe-coded with careful code review and analysis of what the daemon touches. Every effort was made to ensure that the services here are using root as little as possible. If you find any holes I missed, please open an issue or a PR!
+
+## Features
+
+- Blocks ads, trackers, and malware at the DNS level
+- Automatically configures DNS for managed network services
+- Preserves VPN/corporate split-DNS routing
+- Pause/resume with automatic timers
+- Whitelist/blacklist management
+- Multiple blocklist sources (StevenBlack, HaGeZi, OISD) or a custom URL
+
+## Install
+
+### Via Homebrew (recommended)
+
+```bash
+brew install SpyicyDev/formulae/macblock
+```
+
+Or, if you prefer adding the tap explicitly:
+
+```bash
+brew tap SpyicyDev/formulae
+brew install macblock
+```
+
+### Quick start
+
+`macblock` performs privileged operations (launchd + system DNS changes). You can run root-required commands with `sudo`, or omit it and let `macblock` auto-elevate.
+
+```bash
+sudo macblock install
+sudo macblock enable
+macblock status
+```
+
+## Usage
+
+```text
+macblock <command> [flags]
+```
+
+### Global flags
+
+- `-h`, `--help`: show help for a command
+- `-V`, `--version`: show version
+
+### Commands
+
+Status & diagnostics:
+
+- `macblock status`: show current status
+- `macblock doctor`: run diagnostics and health checks
+- `macblock logs [--component daemon|dnsmasq] [--lines N] [--follow] [--stderr]`: view logs
+- `macblock test <domain>`: test resolution against the local resolver
+
+Control:
+
+- `sudo macblock enable`: enable DNS blocking
+- `sudo macblock disable`: disable DNS blocking
+- `sudo macblock pause <duration>`: temporarily disable (e.g. `10m`, `2h`, `1d`)
+- `sudo macblock resume`: resume blocking
+
+Installation & updates:
+
+- `sudo macblock install [--force] [--skip-update]`: install system integration
+- `sudo macblock uninstall [--force]`: remove system integration
+- `sudo macblock update [--source <name|url>] [--sha256 <hash>]`: download + compile blocklist and reload dnsmasq
+
+Configuration:
+
+- `macblock sources list`: list available blocklist sources
+- `sudo macblock sources set <source>`: set blocklist source
+- `macblock allow list`: list whitelisted domains
+- `sudo macblock allow add|remove <domain>`: manage whitelist
+- `macblock deny list`: list blacklisted domains
+- `sudo macblock deny add|remove <domain>`: manage blacklist
+
+Tip: `macblock <command> --help` shows per-command usage.
+
+## How it works
+
+1. `dnsmasq` listens on `127.0.0.1:53` and serves DNS.
+2. The macblock daemon watches for network changes and reconciles state.
+3. When enabled, macblock sets DNS to `127.0.0.1` for a set of managed macOS network services (it intentionally skips VPN-ish services/devices).
+4. macblock generates dnsmasq upstream routing from `scutil --dns` so domain-specific resolvers (VPN/corporate split-DNS) keep working.
+5. Blocked domains are answered as `NXDOMAIN` via dnsmasq rules.
+
+Note: Encrypted DNS (DoH/DoT) can bypass macblock; `macblock doctor` warns if detected.
+
+## `macblock test` behavior
+
+`macblock test <domain>` runs `dig` against `127.0.0.1:53` and uses the compiled block rules to interpret `NXDOMAIN`:
+
+- If the domain matches a block rule, `NXDOMAIN` is reported as **BLOCKED**.
+- If the domain does not match a block rule, `NXDOMAIN` is reported as **does not exist**.
+
+If you don't have `dig`, install it with:
+
+```bash
+brew install bind
+```
+
+## Uninstall
+
+See `docs/UNINSTALL.md`.
+
+Quick version:
+
+```bash
+sudo macblock uninstall
+brew uninstall macblock dnsmasq
+```
+
+## Troubleshooting
+
+- Run `macblock doctor` first.
+- View logs: `macblock logs --component daemon` or `macblock logs --component dnsmasq --stderr`.
+- Verify DNS state: `scutil --dns` (macblock uses this to preserve split DNS).
+- Port conflict on `:53`: `sudo lsof -i :53 -P -n`.
+
+## Attribution
+
+macblock can download third-party blocklists from:
+
+- StevenBlack hosts: https://github.com/StevenBlack/hosts
+- HaGeZi DNS blocklists: https://github.com/hagezi/dns-blocklists
+- OISD: https://oisd.nl/
+
+Please review each upstream project's license/terms. macblock does not vendor or redistribute these lists in this repository.
+
+## Security
+
+See `SECURITY.md` for the threat model and privileged footprint.
+
+## Development
+
+Tooling:
+
+```bash
+brew install just direnv
+```
+
+Then:
+
+```bash
+direnv allow
+just sync
+just ci
+```
+
+## License
+
+MIT

macblock-0.2.1/README.md

@@ -0,0 +1,163 @@
+# macblock
+
+[![CI](https://github.com/SpyicyDev/macblock/actions/workflows/ci.yml/badge.svg)](https://github.com/SpyicyDev/macblock/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+Local DNS sinkhole for macOS using `dnsmasq` on `127.0.0.1:53`, with automatic system DNS configuration and split-DNS preservation.
+
+## Vibe-coding disclaimer
+
+Most of this project was vibe-coded with careful code review and analysis of what the daemon touches. Every effort was made to ensure that the services here are using root as little as possible. If you find any holes I missed, please open an issue or a PR!
+
+## Features
+
+- Blocks ads, trackers, and malware at the DNS level
+- Automatically configures DNS for managed network services
+- Preserves VPN/corporate split-DNS routing
+- Pause/resume with automatic timers
+- Whitelist/blacklist management
+- Multiple blocklist sources (StevenBlack, HaGeZi, OISD) or a custom URL
+
+## Install
+
+### Via Homebrew (recommended)
+
+```bash
+brew install SpyicyDev/formulae/macblock
+```
+
+Or, if you prefer adding the tap explicitly:
+
+```bash
+brew tap SpyicyDev/formulae
+brew install macblock
+```
+
+### Quick start
+
+`macblock` performs privileged operations (launchd + system DNS changes). You can run root-required commands with `sudo`, or omit it and let `macblock` auto-elevate.
+
+```bash
+sudo macblock install
+sudo macblock enable
+macblock status
+```
+
+## Usage
+
+```text
+macblock <command> [flags]
+```
+
+### Global flags
+
+- `-h`, `--help`: show help for a command
+- `-V`, `--version`: show version
+
+### Commands
+
+Status & diagnostics:
+
+- `macblock status`: show current status
+- `macblock doctor`: run diagnostics and health checks
+- `macblock logs [--component daemon|dnsmasq] [--lines N] [--follow] [--stderr]`: view logs
+- `macblock test <domain>`: test resolution against the local resolver
+
+Control:
+
+- `sudo macblock enable`: enable DNS blocking
+- `sudo macblock disable`: disable DNS blocking
+- `sudo macblock pause <duration>`: temporarily disable (e.g. `10m`, `2h`, `1d`)
+- `sudo macblock resume`: resume blocking
+
+Installation & updates:
+
+- `sudo macblock install [--force] [--skip-update]`: install system integration
+- `sudo macblock uninstall [--force]`: remove system integration
+- `sudo macblock update [--source <name|url>] [--sha256 <hash>]`: download + compile blocklist and reload dnsmasq
+
+Configuration:
+
+- `macblock sources list`: list available blocklist sources
+- `sudo macblock sources set <source>`: set blocklist source
+- `macblock allow list`: list whitelisted domains
+- `sudo macblock allow add|remove <domain>`: manage whitelist
+- `macblock deny list`: list blacklisted domains
+- `sudo macblock deny add|remove <domain>`: manage blacklist
+
+Tip: `macblock <command> --help` shows per-command usage.
+
+## How it works
+
+1. `dnsmasq` listens on `127.0.0.1:53` and serves DNS.
+2. The macblock daemon watches for network changes and reconciles state.
+3. When enabled, macblock sets DNS to `127.0.0.1` for a set of managed macOS network services (it intentionally skips VPN-ish services/devices).
+4. macblock generates dnsmasq upstream routing from `scutil --dns` so domain-specific resolvers (VPN/corporate split-DNS) keep working.
+5. Blocked domains are answered as `NXDOMAIN` via dnsmasq rules.
+
+Note: Encrypted DNS (DoH/DoT) can bypass macblock; `macblock doctor` warns if detected.
+
+## `macblock test` behavior
+
+`macblock test <domain>` runs `dig` against `127.0.0.1:53` and uses the compiled block rules to interpret `NXDOMAIN`:
+
+- If the domain matches a block rule, `NXDOMAIN` is reported as **BLOCKED**.
+- If the domain does not match a block rule, `NXDOMAIN` is reported as **does not exist**.
+
+If you don't have `dig`, install it with:
+
+```bash
+brew install bind
+```
+
+## Uninstall
+
+See `docs/UNINSTALL.md`.
+
+Quick version:
+
+```bash
+sudo macblock uninstall
+brew uninstall macblock dnsmasq
+```
+
+## Troubleshooting
+
+- Run `macblock doctor` first.
+- View logs: `macblock logs --component daemon` or `macblock logs --component dnsmasq --stderr`.
+- Verify DNS state: `scutil --dns` (macblock uses this to preserve split DNS).
+- Port conflict on `:53`: `sudo lsof -i :53 -P -n`.
+
+## Attribution
+
+macblock can download third-party blocklists from:
+
+- StevenBlack hosts: https://github.com/StevenBlack/hosts
+- HaGeZi DNS blocklists: https://github.com/hagezi/dns-blocklists
+- OISD: https://oisd.nl/
+
+Please review each upstream project's license/terms. macblock does not vendor or redistribute these lists in this repository.
+
+## Security
+
+See `SECURITY.md` for the threat model and privileged footprint.
+
+## Development
+
+Tooling:
+
+```bash
+brew install just direnv
+```
+
+Then:
+
+```bash
+direnv allow
+just sync
+just ci
+```
+
+## License
+
+MIT

macblock-0.2.1/pyproject.toml

@@ -0,0 +1,68 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "macblock"
+version = "0.2.1"
+description = "Local DNS sinkhole for macOS using dnsmasq"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "macbblock contributiers" }]
+keywords = ["dns", "ad-blocker", "dnsmasq", "macos"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: End Users/Desktop",
+  "Operating System :: MacOS :: MacOS X",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Internet :: Name Service (DNS)",
+  "Topic :: Security",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/SpyicyDev/macblock"
+Repository = "https://github.com/SpyicyDev/macblock"
+Issues = "https://github.com/SpyicyDev/macblock/issues"
+Changelog = "https://github.com/SpyicyDev/macblock/blob/main/CHANGELOG.md"
+
+[project.optional-dependencies]
+dev = [
+  "ruff>=0.8.0",
+  "pyright>=1.1.390",
+  "pytest>=8.0.0",
+  "pytest-cov>=5.0.0",
+]
+
+[dependency-groups]
+dev = [
+  "ruff>=0.8.0",
+  "pyright>=1.1.390",
+  "pytest>=8.0.0",
+  "pytest-cov>=5.0.0",
+]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-v --tb=short"
+
+[project.scripts]
+macblock = "macblock.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pyright]
+extraPaths = ["src"]

macblock-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

macblock-0.2.1/src/macblock/__init__.py

@@ -0,0 +1,8 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("macblock")
+except PackageNotFoundError:
+    __version__ = "0.0.0"
+
+__all__ = ["__version__"]

macblock-0.2.1/src/macblock/__main__.py

@@ -0,0 +1,4 @@
+from macblock.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())