Blockingmachine

A modern network defense suite and filter list compiler for AdGuard, uBlock Origin & EasyList. Features an Electron desktop app, MV3 extension, loopback DNS daemon, Home Assistant hub, and embedded Mini-AI classification with intelligent rule deduplication, multi-format exports, and 100% local processing.

---

Overview

Blockingmachine is a unified, privacy-first network defense ecosystem engineered to compile high-speed adblock and DNS filter lists, synchronize homelab sinkholes, detect zero-day ad trackers with on-device machine intelligence, and enforce system-wide and in-browser blocking with sub-microsecond latency.

Designed for network engineers, homelab operators, and privacy advocates, Blockingmachine processes millions of filter rules in milliseconds, eliminates redundant subdomains via hierarchical suffix trees, runs procedural anti-circumvention scriptlets, and integrates natively with Home Assistant.

Monorepo Workspaces

• Desktop Application (@blockingmachine/electron-app): Native macOS/Linux/Windows Electron suite featuring the Unified Rule & AI Inspector, AI Defense Radar, Deploy & Sync Hub, Curated Defense Modules, and Compiled Rule Browser.
• Browser Extension (@blockingmachine/browser-extension): High-performance Manifest V3 extension featuring dynamic declarativeNetRequest (DNR) compilation, procedural anti-adblock scriptlet defusers (Admiral, Google Funding Choices), in-page visual ElementPicker, and live AI Radar inspection.
• System DNS Daemon (@blockingmachine/system-daemon): High-throughput loopback UDP/TCP DNS proxy on port 53/5353, powered by an in-memory reversed-label suffix trie for sub-microsecond O(k) rule lookups, $important precedence resolution, upstream DNS-over-HTTPS (Quad9 default), and a local HTTP control API (127.0.0.1:9292).
• Core Engine (@blockingmachine/core): Zero-dependency rule parsing engine, hierarchy-aware subdomain deduplicator, multi-format export compiler, Shannon entropy analyzer, CNAME uncloaking resolver, and embedded Mini-AI classification neural model.
• Command Line Interface (@blockingmachine/cli): Autonomous CLI binary (blockingmachine) for CI/CD pipelines, automated homelab cron tasks, local feed serving, diffing, and DNS diagnostics.
• Home Assistant Hub (@blockingmachine/homeassistant-addon & integration): HACS-compliant Home Assistant integration and local Add-on container providing a bidirectional telemetry mesh (sensor.blockingmachine_browser_*), live rule distribution via Server-Sent Events (/v1/events), and remote cosmetic shield toggles.
• Audit & Database Layer (blockingmachine-database): Offline JSONL and MongoDB audit logging and rule snapshot rollback engine.

---

📦 Downloads & Installation

Desktop Application (macOS Apple Silicon)

The latest pre-release desktop application is cryptographically signed with an Apple Developer ID (Greigh Studios LLC (365KR8NF53)):

Package / Installer	Architecture	Download
Apple Silicon Disk Image (.dmg)	macOS arm64 (M1/M2/M3/M4)	Download .dmg
Standalone Application Bundle (.zip)	macOS arm64 (M1/M2/M3/M4)	Download .zip
SHA-256 Checksums	All Platforms	Download SHA256SUMS.txt

Checksum Verification

shasum -a 256 -c SHA256SUMS.txt

---

NPM Packages

Blockingmachine distributes its core parsing engine and command-line interface as standalone packages on npmjs.com, GitHub Packages, and Forgejo Packages:

From npmjs.com (Public)

# Core Library
npm install @blockingmachine/core

# CLI Tool
npm install -g @blockingmachine/cli

From GitHub Packages

# Core Library
npm install @greigh/blockingmachine-core@1.0.0-rc.5 --registry=https://npm.pkg.github.com

# CLI Tool
npm install -g @greigh/blockingmachine-cli@1.0.0-rc.5 --registry=https://npm.pkg.github.com

From Forgejo Package Registry (git.greighstudios.com)

# Core Library
npm install @blockingmachine/core@1.0.0-rc.5 --registry=https://git.greighstudios.com/api/packages/greighstudios/npm/

# CLI Tool
npm install -g @blockingmachine/cli@1.0.0-rc.5 --registry=https://git.greighstudios.com/api/packages/greighstudios/npm/

Direct tarballs are also attached to Release v1.0.0-rc.5:

• blockingmachine-core-1.0.0-rc.5.tgz
• blockingmachine-cli-1.0.0-rc.5.tgz

---

Key Features

🔍 Unified Rule & AI Inspector (⌘5)

• Simultaneous Static & AI Evaluation: Instantly assesses any domain or URL against your active compiled filter lists while simultaneously running live AI threat heuristics.
• Heuristic Threat Profiling: Measures lexical Shannon entropy (H(X)), detects algorithmic Domain Generation Algorithms (DGA), resolves multi-hop CNAME cloaking aliases, and breaks down mathematical feature weights.
• Multi-Format Rule Synthesizer: Generates syntax-perfect blocking rules in Universal (||domain^), AdGuard (||domain^$important), Pi-hole regex, uBlock Origin, Unbound, or Hosts format.
• $badfilter Neutralization: Automatically generates $badfilter exception syntax to neutralize upstream false positives and erroneous filter rules without altering third-party feeds.
• 1-Click Actions: One-click Add to Custom Rules, Whitelist (@@), rule clipboard copying, and Mini-AI feedback tuning (Confirm Threat / Mark Safe).

📡 AI Defense Radar Hub (⌘9)

• Sinkhole Query Scout: Connects directly to AdGuard Home or Pi-hole to inspect recent DNS query logs for anomalous, uncategorized ad beacons and tracking telemetry.
• Subdomain Compaction Engine: Collapses swarms of ephemeral subdomains into clean parent zone wildcard rules to prevent list bloat.
• Web Canary Crawler: Proactively crawls target URLs to audit and extract third-party trackers, beacons, and programmatic ad auctions before you visit them.
• Threat Quarantine Ledger: Centralized persistent ledger tracking intercepted threats with category filtering, batch exports (ABP, Hosts, JSON), and one-click firewall blocking.

🧠 Centralized AI Engine & Sentinel Watchdog (Preferences ⌘,)

• Built-in Mini-AI Classifier (Default & Recommended): Embedded 25-feature mathematical neural classifier executing on-device in <0.05ms with zero daemons, zero cloud telemetry, and zero network overhead.
• Calibrated Entropy Engine: Multi-tiered Shannon entropy scoring with base64 anomaly detection, segment decomposition, and bigram transition scoring.
• Flexible Provider Support:
  • Local Heuristics: Pure offline Shannon entropy, token decomposition, and CNAME uncloaking.
  • Ollama Local LLM: Air-gapped on-device neural models (llama3.2, mistral, qwen2.5, deepseek-r1).
  • Google Gemini Flash: Deep pattern reasoning via Gemini 2.0 Flash.
  • OpenAI / Custom Server: Full compatibility with OpenAI, Groq, LM Studio, OpenRouter, and custom endpoints.
• Sentinel Watchdog Automation: Automated background threat hunting that periodically sweeps homelab DNS logs at customizable intervals (15m to 24h) and populates the Quarantine Ledger.
• Active Feedback Memory: Tracks user corrections to refine heuristic weights over time, with one-click memory reset.

🌐 Manifest V3 Browser Extension (@blockingmachine/browser-extension)

• DeclarativeNetRequest Rulesets: Translates network blocking rules into native browser DNR rulesets for zero-latency network interception.
• Procedural Scriptlet Defusers: Defuses hostile anti-adblock detection walls (e.g. Admiral, Google Funding Choices CMP) without breaking legitimate page layouts.
• Interactive Element Picker: Visual element isolation tool allowing users to click and eliminate cosmetic annoyances directly in the browser DOM.
• Real-Time SSE Sync: Connects to the local Blockingmachine Hub via Server-Sent Events (/v1/events) to instantly hot-reload rules upon compilation without browser restarts.

⚙️ System Loopback DNS Proxy (@blockingmachine/system-daemon)

• In-Memory Reversed-Label Trie: Ultra-fast O(k) suffix lookup trie matching DNS queries in nanoseconds regardless of list size (100k+ rules).
• Service Configuration Generators: One-click generation and installation of macOS launchd plist daemons and Linux systemd services with CAP_NET_BIND_SERVICE.
• Precedence & Wildcards: Full resolution of $important flags, whitelist exceptions (@@), and multi-level subdomain wildcards (*.telemetry.example.com).

🏠 Home Assistant Integration & HACS Hub

• HACS Compliant Integration: Native Home Assistant integration with standard configuration flow and automatic hub discovery.
• Telemetry Mesh Sensors: Publishes real-time browser and network protection metrics:
  • sensor.blockingmachine_browser_blocked_today
  • sensor.blockingmachine_browser_cosmetic_hidden
  • sensor.blockingmachine_browser_active_defusers
  • binary_sensor.blockingmachine_browser_connected
• Remote Cosmetic Shield Toggles: Enable or disable cosmetic hiding and scriptlet defusers directly from Home Assistant automations or Lovelace dashboards.

🛡️ First-Party Curated Defense Modules (⌘3)

1. Base Ad Shield: Network-level blocking for major ad exchanges, programmatic bidding, and banner injection.
2. Privacy Engine: Web beacons, browser fingerprinting, and analytics telemetry neutralizer.
3. Smart TV & IoT Shield: Automatic Content Recognition (ACR) telemetry and ad blocker for Roku, Samsung Tizen, LG webOS, Fire TV, and smart appliances.
4. Web Annoyances & Cookie Banners: Eliminates GDPR cookie consent popups, CMP modals (OneTrust, Cookiebot), and overlay nags.
5. Social Tracker Neutralizer: Disables cross-site tracking beacons and pixels (Meta, TikTok, X, LinkedIn).
6. Threat & Malicious Domain Defense: Blocks drive-by payloads, phishing gateways, cryptominers, and known malware C2 nodes.
7. URL Tracking Stripper: Strips privacy-invasive tracking parameters (fbclid, gclid, utm_*, twclid).
8. Unbreak & Safe Exceptions: Hand-crafted allowlist rules (@@) preventing breakage for banking, SSO identity providers, and DRM streaming.

🚀 Deploy & Sync Hub (⌘8)

• Pi-hole Integration: Syncs compiled blocklists directly into Pi-hole gravity databases via API with instant connection testing.
• AdGuard Home Integration: Native integration supporting Direct (Port 3000), Home Assistant API (Port 8123), HA Webhooks, and Nabu Casa Cloud tunnels.
• Custom Automation Webhooks: Emits HTTP POST event payloads to Technitium DNS, pfSense, OPNsense, Blocky, or Node-RED upon every compilation.
• Built-in Local Feed Server: Serves compiled blocklists on your local network (e.g. http://localhost:9191/rules.txt, /dns.txt, /browser.txt) for automatic appliance polling.

---

Keyboard Shortcuts Matrix

Shortcut	View	Purpose
⌘1	Process & Stats	Dashboard, compile metrics, feed status, and instant compilation trigger
⌘2	Sources	Manage remote filter list subscriptions, feed toggles, and health checks
⌘3	Defense Modules	First-party curated shields (Smart TV, Telemetry, Annoyances, Privacy)
⌘4	Custom Rules	Custom domain blocks, whitelist exceptions (@@), and syntax validation
⌘5	Rule & AI Inspector	Simultaneous filter rule matching and live AI heuristic threat analysis
⌘6	Rule Browser	Search, filter, and paginate through tens of thousands of active compiled rules
⌘7	Bulk Import	Add multiple feed URLs simultaneously or import text files via drag-and-drop
⌘8	Deploy & Sync	Push compiled lists to Pi-hole, AdGuard Home, and homelab webhooks
⌘9	AI Radar Hub	Homelab Sinkhole Scout, Web Canary Crawler, and Threat Quarantine Ledger
⌘,	Preferences	Output formats, directory paths, AI engines, Watchdog, and accent colors
⌘R	Compile Now	Global trigger to compile and deduplicate all active filter lists

---

Monorepo Architecture

Blockingmachine/
├── packages/
│   ├── core/                    # @blockingmachine/core (Compiler, deduplicator, parsers, Mini-AI engine)
│   ├── cli/                     # @blockingmachine/cli (CLI binary, local feed server, diffing, doctor)
│   ├── electron-app/            # @blockingmachine/electron-app (Desktop suite, Deploy Hub, AI Radar)
│   ├── browser-extension/       # @blockingmachine/browser-extension (Manifest V3 WebExtension)
│   ├── system-daemon/           # @blockingmachine/system-daemon (Loopback DNS filtering proxy)
│   ├── homeassistant-addon/     # @blockingmachine/homeassistant-addon (Home Assistant Supervisor Add-on)
│   ├── homeassistant-integration/# HACS-compliant Home Assistant integration & Python tests
│   └── database/                # Snapshot rollback engine and audit logging schemas
├── custom_components/           # Root HACS custom component distribution directory
├── .github/workflows/           # GitHub Actions CI, CodeQL Analysis, and HACS Validation
├── .forgejo/workflows/          # Forgejo Actions CI and Forgejo Packages publishing
├── hacs.json                    # HACS repository metadata and compliance definition
├── SECURITY.md                  # Comprehensive vulnerability disclosure and security policy
├── package.json                 # Root npm workspaces configuration (Node.js >= 24.0.0)
└── README.md

---

Supported Export Formats

Format	Syntax Example	Target Platform / Resolver
AdGuard Home	`
AdBlock Plus	`
Standard Hosts	0.0.0.0 example.com	System /etc/hosts, Pi-hole, standard DNS
dnsmasq	address=/example.com/0.0.0.0	OpenWrt, DD-WRT, pfSense, dnsmasq
Unbound	local-zone: "example.com" static	OPNsense, pfSense, Unbound DNS resolvers
Plain Domains	example.com	Minimalist domain blocklists, Pi-hole domain lists

---

Prerequisites

• Node.js: v24.0.0 or higher
• npm: v10.0.0 or higher
• Python: v3.10 or higher (for Home Assistant integration testing)
• Git: Installed and available in your system PATH
• Build Tools:
  • macOS: Xcode Command Line Tools (xcode-select --install)
  • Linux (Ubuntu/Debian): sudo apt-get install build-essential python3
  • Windows: Visual Studio C++ Build Tools

---

Installation & Build Guide

1. Clone the Repository

git clone https://github.com/greigh/Blockingmachine.git
cd Blockingmachine

2. Install Dependencies

Install all workspace dependencies from the root directory:

npm ci

3. Build All Workspaces

Compile the core TypeScript engine, CLI binaries, browser extension, and Electron bundles:

npm run build

4. Launch Desktop Application

Run the Electron desktop suite in development mode:

npm start

5. Package for Distribution

Build native macOS, Linux, or Windows binaries:

npm run package --workspace=@blockingmachine/electron-app

---

CLI Usage Guide

The @blockingmachine/cli binary provides full command-line access for headless homelab environments and CI/CD automation:

# Run CLI directly via npm workspace
npx --workspace=@blockingmachine/cli blockingmachine --help

# Or install globally from GitHub Packages
npm install -g @greigh/blockingmachine-cli --registry=https://npm.pkg.github.com

# Scan a suspect domain using the built-in Mini-AI classifier
blockingmachine ai-scan doubleclick.net

# Scan a domain using a local Ollama LLM
blockingmachine ai-scan tracking-bidder.biz --provider ollama --model llama3.2

# Crawl a webpage for third-party ad beacons and trackers
blockingmachine ai-crawl https://example-news-site.com

# Verify whether a domain is blocked by your compiled filter list
blockingmachine test malware-c2-domain.com

# Compare rule differences between two compiled blocklist snapshots
blockingmachine diff baseline-rules.txt updated-rules.txt

# Launch local HTTP subscription feed server for network clients
blockingmachine serve --port 9191

# Run system diagnostic health check
blockingmachine doctor

---

Quality Assurance & Testing

Blockingmachine maintains a strict 100% test pass rate with 0 ESLint errors and 0 warnings across all monorepo packages:

# Run all 398 automated tests across 31 suites in the monorepo
npm test

# Run tests with open handle leak detection
npm test --workspace=@blockingmachine/core -- --detectOpenHandles

# Run linter across all workspaces
npm run lint

# Validate TypeScript typing across all packages
npm run type-check

# Verify Manifest V3 Chrome Web Store compliance
npm run verify:mv3

---

Security Policy

We treat security as a first-class feature across all network proxies and extensions. For vulnerability disclosure procedures, supported versions, and architectural isolation guarantees, see our SECURITY.md.

---

Remotes & CI/CD Pipelines

Blockingmachine is concurrently mirrored and continuously tested across:

• GitHub Repository: github.com/Greigh/Blockingmachine
• Forgejo Repository: git.greighstudios.com/greighstudios/Blockingmachine
• GitHub Actions: .github/workflows/ci.yml, .github/workflows/codeql.yml, .github/workflows/hacs-validation.yml
• Forgejo Actions: .forgejo/workflows/ci.yml and .forgejo/workflows/publish.yml

---

Contributing

We welcome community contributions! Please adhere to the following guidelines:

1. Ensure all new features include unit test coverage in the corresponding __tests__ directory.
2. Verify that npm run lint passes with 0 errors and 0 warnings.
3. Ensure npm test passes with 100% success across all workspaces.

---

License

This project is licensed under the BSD-3-Clause License. See the LICENSE file for details.

_{Designed and engineered by Greigh Studios LLC.}