> ## Documentation Index > Fetch the complete documentation index at: https://docs.hapara.fail/llms.txt > Use this file to discover all available pages before exploring further. # Blocklist > Technical specifications and integration for the hapara.fail blocklist ## Specification The blocklist is a text file containing domain rules formatted for compatibility with standard ad-blocking engines. [Adblock Plus (ABP)](https://adblockplus.org/filter-cheatsheet) Continuous — community-maintained [hapara-fail/blocklist](https://github.com/hapara-fail/blocklist) on GitHub Served via jsDelivr for high availability ### CDN Endpoint For integration, use the jsDelivr CDN endpoint: ``` https://cdn.jsdelivr.net/gh/hapara-fail/blocklist@main/blocklist.txt ``` *** ## Blocking Standards Our blocklist targets services that surveil, restrict, or compromise the autonomy and privacy of users — particularly students and minors subject to invasive monitoring tools. ### What We Block This includes software deployed in educational institutions that goes beyond reasonable network management and crosses into surveillance. Products like **Hapara, GoGuardian, Securly, Lightspeed, and Bark** that track browsing history, capture screenshots, read emails, or monitor keystrokes on student devices. Mobile device management solutions that impose persistent content restrictions or reporting even **outside of school hours or networks** — monitoring students on their personal time. Services that aggregate behavioral data about students and transmit it to third-party servers, often without meaningful transparency or consent. We also target commercial parental control services that are commonly bundled with ISPs, devices, or operating systems and function in ways that undermine user autonomy. Services that silently monitor or log browsing and app usage and report it to a third-party cloud — without the user's knowledge or consent. Products that enforce network-level restrictions without a clear and accessible override mechanism for the device owner. Tools that market themselves as "safety" software but collect and monetize behavioral data as a core part of their business model. Not everything adjacent to surveillance is a valid block target. We maintain clear exclusions to protect legitimate services. We do **not** block services that: * Perform standard, transparent network management (e.g., firewall rules, bandwidth throttling). * Provide parental controls that are limited to on-device filtering **without** external reporting. * Are general-purpose platforms only incidentally used by surveillance vendors (e.g., cloud infrastructure, CDNs). *** ## No-Overblocking Philosophy We deliberately prioritize precision over breadth. **We would rather miss a block than break something legitimate.** This blocklist is designed to be **set it and forget it**. That means: We do not add a domain unless we are confident it is exclusively or primarily associated with a surveillance or invasive service. Uncertainty is a reason to wait, not to block. We do not block entire TLDs, IP ranges, or CDNs shared with legitimate services. If a surveillance vendor uses a shared CDN, we only target their specific subdomains. We do not speculatively block domains that *might* be used by a monitored service but serve no confirmed surveillance function. Rules must be backed by evidence. Even if a rule would block a bad actor, we won't add it if it risks catching unrelated traffic. The collateral damage is not worth it. The result is a blocklist that is safe to deploy network-wide — on a home router, Pi-hole, or recursive resolver — without fear of breaking legitimate services. If you notice a false positive, please [report it](#reporting-issues). *** ## Whitelist Rules Some monitored vendors host domains that serve dual purposes — authentication portals, student-facing apps, or status endpoints that are needed for a degraded-but-functional experience even when the surveillance service itself is blocked. In these cases, we maintain **explicit allowlist exceptions** using ABP exception syntax: ``` @@||hello.example.com^ ``` The `@@` prefix instructs compatible engines to **allow** matching traffic, overriding any block rule that would otherwise apply. Allowlist entries are placed **above** their associated block rules in `blocklist.txt`. ### Example Allowlist Entries **Securly Pass** is a digital hall pass system used by schools. Blocking it breaks hall pass functionality without meaningfully reducing surveillance exposure. **Status page only** — no behavioral data collection occurs through this endpoint. Safe to allow with no privacy trade-off. ### Whitelist Standards A domain is added to the allowlist only if it meets **all three** of the following criteria: Blocking it causes breakage for the user beyond just defeating the surveillance tool — for example, it breaks authentication, connectivity, or a student-facing service that is not itself a surveillance endpoint. The endpoint in question does not transmit behavioral, usage, or personally identifying data to the vendor. We verify this before adding the exception. We require a real-world report or demonstrated evidence that blocking the domain causes a specific, reproducible problem. Theoretical breakage is not sufficient. *** ## Patched Services Some vendors have implemented what we call **"patched" behavior** — a failsafe specifically designed to defeat DNS-level blocking by holding internet access hostage. ### How Patching Works Rather than gracefully degrading when their domains are unreachable, patched services **intentionally sever internet connectivity** when they cannot reach their command-and-control (C2) servers. The vendor's agent — a browser extension, system service, or MDM profile — periodically sends a heartbeat to its C2 servers to confirm the monitoring stack is reachable. If the domain is blocked by DNS, the heartbeat fails. Instead of treating this as a routine network error, the agent interprets it as a **policy violation**. The agent responds by cutting internet access on the device — redirecting all traffic to a captive block page or dropping connectivity entirely. This affects **all devices regardless of operating system** and persists until the C2 servers are reachable again. This behavior is intentional and adversarial. It is designed to coerce users (or network administrators) into unblocking the vendor's infrastructure under the threat of lost connectivity. ### Known Patched Vendors Adding blocks for patched services will cut off internet access on affected devices. **Do not deploy these rules on networks with devices enrolled in these services without a mitigation plan.** Patched vendors are tagged in the blocklist source using the following comment format: ``` ! GoGuardian [PATCHED] ||goguardian.com^ ``` The Lightspeed Relay agent periodically checks in with its relay infrastructure. If those domains are blocked, it **cuts internet access on all affected devices** until connectivity to Lightspeed's servers is restored. Securly documents an [Enhanced DNS Bypass Protection mode](https://support.securly.com/hc/en-us/articles/38847438046103-Filter-Enabling-Enhanced-DNS-Bypass-Protection-for-Chromebooks) for Chromebooks. When enabled, affected devices can lose internet access if they cannot reach Securly's filtering infrastructure. Extension-based. When its policy servers are unreachable, the GoGuardian extension **cuts internet access on all devices** rather than failing open. ### Reporting a Patched Service If you discover a service that severs internet connectivity when its domains are blocked, please [report it](https://github.com/hapara-fail/blocklist/issues/new?template=patched.yml) so we can flag it appropriately and warn other users before they deploy the block. *** ## Compatibility The list is designed for engines that support **Adblock Plus (ABP)** syntax for DNS or network-level blocking. ## Integration 1. Navigate to **Group Management > Adlists**. 2. Add the [CDN URL](#cdn-endpoint) as a new list. 3. Update Gravity (`pihole -g`). 1. Navigate to **Filters > DNS blocklists**. 2. Click **Add blocklist > Add a custom list**. 3. Enter `hapara.fail` as the name and the [CDN URL](#cdn-endpoint). 4. Click **Save**. 1. Open **Settings > Filter lists**. 2. Scroll to **Custom** and click **Import**. 3. Paste the [CDN URL](#cdn-endpoint) and click **Apply changes**. *** # Contributing We accept community contributions to keep the blocklist accurate and effective. ## Reporting Issues Suggest a new service or domain to be added to the blocklist. Report a service that cuts internet access when its domains are blocked. Report a legitimate site that was broken by our blocklist. ## Submitting Changes Fork the repository and create a new branch for your changes. Follow these conventions when editing the file: * Use **Adblock Plus syntax**: `||domain.com^` * One domain per line, placed under the correct vendor header. * Mark patched vendors with a `! VendorName [PATCHED]` comment directly above their block rules. * Place allowlist exceptions (`@@||...^`) above their associated block rules with an explanatory comment. Check for trailing spaces, accidental deletions, or rules that could cause false positives before submitting. Submit a PR with a clear description of what was added, removed, or changed and why. For full details, see our [Contributing Guidelines](https://github.com/hapara-fail/blocklist/blob/main/CONTRIBUTING.md) and [Code of Conduct](https://github.com/hapara-fail/blocklist/blob/main/CODE_OF_CONDUCT.md).