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`)

Base Ad Shield: Network-level blocking for major ad exchanges, programmatic bidding, and banner injection.
Privacy Engine: Web beacons, browser fingerprinting, and analytics telemetry neutralizer.
Smart TV & IoT Shield: Automatic Content Recognition (ACR) telemetry and ad blocker for Roku, Samsung Tizen, LG webOS, Fire TV, and smart appliances.
Web Annoyances & Cookie Banners: Eliminates GDPR cookie consent popups, CMP modals (OneTrust, Cookiebot), and overlay nags.
Social Tracker Neutralizer: Disables cross-site tracking beacons and pixels (Meta, TikTok, X, LinkedIn).
Threat & Malicious Domain Defense: Blocks drive-by payloads, phishing gateways, cryptominers, and known malware C2 nodes.
URL Tracking Stripper: Strips privacy-invasive tracking parameters (fbclid, gclid, utm_*, twclid).
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:

Ensure all new features include unit test coverage in the corresponding __tests__ directory.
Verify that npm run lint passes with 0 errors and 0 warnings.
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.}

Name		Name	Last commit message	Last commit date
.forgejo/workflows		.forgejo/workflows
.github		.github
assets		assets
custom_components/blockingmachine		custom_components/blockingmachine
docs		docs
packages		packages
scripts		scripts
.env.example		.env.example
.gitignore		.gitignore
AUDIT.md		AUDIT.md
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
eslint.config.mjs		eslint.config.mjs
hacs.json		hacs.json
package-lock.json		package-lock.json
package.json		package.json
repository.yaml		repository.yaml

Latest commit

History

Folders and files

Repository files navigation

Blockingmachine

Overview

Monorepo Workspaces

📦 Downloads & Installation

Desktop Application (macOS Apple Silicon)

Checksum Verification

NPM Packages

From npmjs.com (Public)

From GitHub Packages

From Forgejo Package Registry (git.greighstudios.com)

Key Features

🔍 Unified Rule & AI Inspector (⌘5)

📡 AI Defense Radar Hub (⌘9)

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

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

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

🏠 Home Assistant Integration & HACS Hub

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

🚀 Deploy & Sync Hub (⌘8)

Keyboard Shortcuts Matrix

Monorepo Architecture

Supported Export Formats

Prerequisites

Installation & Build Guide

1. Clone the Repository

2. Install Dependencies

3. Build All Workspaces

4. Launch Desktop Application

5. Package for Distribution

CLI Usage Guide

Quality Assurance & Testing

Security Policy

Remotes & CI/CD Pipelines

Contributing

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

From Forgejo Package Registry (`git.greighstudios.com`)

🔍 Unified Rule & AI Inspector (`⌘5`)

📡 AI Defense Radar Hub (`⌘9`)

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

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

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

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

🚀 Deploy & Sync Hub (`⌘8`)