Security
🛡️ Security Features
Learn how the built-in security features protect against malicious filter lists, tampering, and network attacks.
Why Security Matters
When using ad-blocking or DNS filtering, filter lists are trusted to protect the network. But what if those lists themselves become compromised? The mandatory validation system ensures that every filter list is authentic, unmodified, and safe.
🔒 Automatic Protection
Security validation runs automatically every time you compile rules. No configuration needed - it just works.
⚡ Lightning Fast
Adds less than 100ms to compilation time. Get enterprise-grade security without the wait.
🎯 Zero False Sense of Security
Unlike optional features that users forget to enable, this validation is mandatory by design.
What is Hash Verification?
A hash is like a unique fingerprint for a file. Even changing a single character creates a completely different fingerprint. We use SHA-384, a cryptographic hash algorithm that creates 96-character fingerprints.
How It Works: A Simple Example
Original file content:
||example.com^
SHA-384 Hash:
abc123def456789abc123def456789abc123def456789abc123def456789abc123def456789abc123def456789abc123
If someone changes just ONE character (l → 1):
||examp1e.com^
New SHA-384 Hash (completely different!):
xyz789uvw321abc789uvw321xyz789uvw321abc789uvw321xyz789uvw321abc789uvw321xyz789uvw321xyz789
❌ Hash mismatch detected! Compilation stopped.
5 Real-World Threats Mitigated
🚨 1. Man-in-the-Middle Attacks
The Threat: An attacker intercepts downloads of filter lists and replaces them with malicious versions that redirect banking sites or unblock malware.
The Protection: Every downloaded list must match a known fingerprint. If even 1 character changes, validation fails immediately.
🚨 2. Compromised List Providers
The Threat: A popular filter list website gets hacked, and attackers replace legitimate lists with ones that block security warnings or allow phishing domains.
The Protection: Fingerprints of known-good versions are stored. If a list changes unexpectedly, users are alerted and can review the changes before accepting them.
🚨 3. Local File Tampering
The Threat: Malware on a computer modifies local filter lists to remove its own domains from blocklists or add legitimate security tools to the blocklist.
The Protection: Before each compilation, files are verified to ensure they haven't changed. If tampering is detected, compilation stops immediately.
🚨 4. Typosquatting & Fake Lists
The Threat: Attackers create fake lists with names similar to trusted lists (e.g., easy1ist.to instead of easylist.to).
The Protection: HTTPS-only URLs are enforced, domains are verified via DNS, and content is scanned to ensure it's actually a filter list.
🚨 5. Supply Chain Attacks
The Threat: Attackers compromise the build pipeline of a trusted filter list provider, injecting malicious rules into otherwise legitimate updates.
The Protection: Cryptographic signatures and audit trails ensure that validation actually occurred and can't be forged.
5 Layers of Protection
🛡️ Layer 1: HTTPS-Only
Only allows secure downloads. HTTP connections can be intercepted and modified - we simply don't allow them.
🛡️ Layer 2: Domain Validation
Verifies domains are legitimate via DNS lookups, preventing typosquatting attacks and catching typos in URLs.
🛡️ Layer 3: Content Validation
Scans downloads to ensure they're actually filter lists, not malware or fake pages.
🛡️ Layer 4: Cryptographic Hashing
SHA-384 fingerprinting provides mathematical certainty. Tampering is impossible to hide.
🛡️ Layer 5: Audit Trail
Complete transparency with records of what was validated, when, and by which version.
🛡️ Bonus: Runtime Enforcement
Cryptographic proof that validation actually ran, preventing bypasses and ensuring compliance.
Performance Impact
Security shouldn't slow you down. Our validation system is designed for speed:
| Operation | Time |
|---|---|
| SHA-384 hash computation per file | ~0.5ms |
| URL validation (DNS lookup) | ~10ms |
| Syntax validation per file | ~5ms |
| Total overhead (typical) | <100ms |
Compare this to downloading remote lists (500-5000ms) and compilation (1000-10000ms). The security overhead is negligible!
Frequently Asked Questions
Can I disable validation if I trust my sources?
No, and that's by design for safety. Validation is mandatory. Even trusted sources can be compromised. However, "warning mode" is available for development which logs issues without failing compilation. For production, "strict mode" is strongly recommended, which fails on any anomaly.
What if a legitimate list updates and validation fails?
This is a feature, not a bug! When validation detects a change, it alerts users to review what was modified. If the change is legitimate, simply update the hash database and compilation proceeds. This provides visibility and control over what enters the network.
How do I know validation is actually running?
Every compilation includes validation metadata with timestamps, file counts, and a cryptographic signature. Our CI/CD workflows fail if validation is bypassed, and you can use verification functions to programmatically confirm validation occurred.
Why SHA-384 instead of SHA-256?
SHA-384 provides enhanced security with ~2^192 operations required to find a collision (vs 2^128 for SHA-256), while still being fast enough for real-time validation (<1ms per file). It's FIPS 180-4 compliant and approved by NIST for cryptographic use.
Is this overkill for personal use?
No. Attacks don't discriminate by network size. The same techniques work against home users and enterprises alike. The best security is security you don't have to think about - validation handles the complexity automatically.
✅ The Bottom Line
- Automatic: Works silently in the background - no configuration needed
- Fast: Adds less than 100ms to compilation time
- Comprehensive: Stops 5+ types of attacks automatically
- Proven: Uses NIST-approved SHA-384 cryptographic hashing
- Transparent: Complete audit trails and verification
- Universal: Protects everyone from home users to enterprises
Remember: The best security is security that doesn't require thinking about. The validation system handles the complexity automatically.
Learn More
Why Validation Matters
Complete technical and non-technical guide to the validation system, including threat models and attack scenarios.
Hash Verification
Technical documentation on the hash verification callback system and implementation across all compilers.
Runtime Enforcement
How cryptographic validation ensures security measures are actually executed and can't be bypassed.
Validation Enforcement
CI/CD enforcement mechanisms and how validation is ensured to never be skipped in production.
Getting Started
Start using the toolkit with built-in security validation in under 5 minutes.
Security Policy
The project's commitment to security, vulnerability reporting, and responsible disclosure.