{"id":50912581,"url":"https://github.com/dan-j-d/kblocker","last_synced_at":"2026-06-20T15:00:44.773Z","repository":{"id":364795109,"uuid":"1269182428","full_name":"Dan-J-D/kblocker","owner":"Dan-J-D","description":"Linux Kernel-level internet blocker with PGP-encrypted keys. Block distracting sites, then remove your own ability to disable it by encrypting the unblock key to trusted recipients and erasing it from kernel memory. Uses netfilter SNI inspection, /etc/hosts null-routing, and chattr +i file hardening.","archived":false,"fork":false,"pushed_at":"2026-06-18T11:54:02.000Z","size":101,"stargazers_count":6,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-18T13:28:03.774Z","etag":null,"topics":["distraction-free","focus","kernel-module","linux-kernel","netfilter","pgp","productivity","self-discipline","sni-inspection","sysfs","website-blocker","willpower"],"latest_commit_sha":null,"homepage":"https://github.com/Dan-J-D/kblocker","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Dan-J-D.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-14T12:01:17.000Z","updated_at":"2026-06-18T11:54:05.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Dan-J-D/kblocker","commit_stats":null,"previous_names":["dan-j-d/kblocker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Dan-J-D/kblocker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dan-J-D%2Fkblocker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dan-J-D%2Fkblocker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dan-J-D%2Fkblocker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dan-J-D%2Fkblocker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Dan-J-D","download_url":"https://codeload.github.com/Dan-J-D/kblocker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Dan-J-D%2Fkblocker/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34534278,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-19T02:00:06.005Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["distraction-free","focus","kernel-module","linux-kernel","netfilter","pgp","productivity","self-discipline","sni-inspection","sysfs","website-blocker","willpower"],"created_at":"2026-06-16T11:30:36.845Z","updated_at":"2026-06-19T14:01:11.516Z","avatar_url":"https://github.com/Dan-J-D.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# kblocker\n\nA kernel-level internet blocker designed to remove your ability to break your own focus. Once enabled, it blocks access to configured domains by dropping matching TCP connections via netfilter and null-routing them via `/etc/hosts`. The key needed to disable or unload the module can be encrypted to trusted recipients and erased from kernel memory, making the decision to unblock a deliberate, collaborative act rather than an impulse.\n\n## Use case\n\nYou want to block distracting sites and make it *genuinely hard* to disable the blocker even for yourself. The goal isn't just to block, but to remove your own agency to undo it in a moment of weakness.\n\n- The kernel module hooks `NF_INET_LOCAL_OUT` and `NF_INET_FORWARD`, inspects TLS SNI, and drops matching connections\n- Disabling or unloading requires a 128-bit key, validated against a SHA-256 hash stored in the kernel\n- With PGP mode, the key is encrypted to your trusted recipients' GPG public keys and then **erased from kernel memory**. The only way to retrieve it is to have someone else PGP-decrypt it. You've outsourced your willpower.\n- The module file, auto-load config, hosts file, and domains config are protected with `chattr +i` (immutable) and `inode_operations` overrides, re-applied every second\n\n## Quick start\n\n```sh\n# build and install\nsudo make install\n\n# register a PGP key (do this first)\nsudo kblockerctl add-pgp alice.pub\n\n# block YouTube for 60 minutes\nsudo kblockerctl enable 60\n\n# check status\nsudo kblockerctl status\n\n# disable blocking (module stays loaded)\nsudo kblockerctl unblock\n\n# remove module entirely\nsudo kblockerctl unload\n```\n\n## PGP mode\n\nWithout PGP, the unload key is readable from `/sys/kernel/kblocker/key`. Anyone with root can retrieve it and disable the blocker. PGP mode encrypts the key to trusted recipients so that:\n\n1. On `enable`, kblockerctl reads the key from sysfs, GPG-encrypts it for all registered public keys, and signals the kernel to zero the key from memory\n2. The `key` sysfs attribute returns `\"encrypted\"` instead of the raw hex\n3. `unblock` and `unload` require the decrypted key (PGP-decrypt the ciphertext, write the plain hex to the kernel)\n\n```sh\n# register a PGP public key\nsudo kblockerctl add-pgp alice.pub\n\n# enable with PGP protection\nsudo kblockerctl enable 60\n\n# disable (needs PGP private key to decrypt)\nsudo kblockerctl unblock\n\n# unload (needs the key too)\nsudo kblockerctl unload\n```\n\n### Web UI: Browser-based PGP key management\n\nGenerate PGP keys entirely in your browser (using OpenPGP.js). The private key never touches the server:\n\n```sh\n# start web UI for key generation\nsudo kblockerctl add-pgp-web\n# Opens on http://127.0.0.1:\u003crandom-port\u003e\n```\n\nThe unblock-web UI lets you decrypt the PGP ciphertext client-side in the browser and submit the key:\n\n```sh\nsudo kblockerctl unblock-web\n# Opens on http://127.0.0.1:\u003crandom-port\u003e\n```\n\n### Insecure mode\n\nWithout any key registered, `--insecure` mode prints the key to stdout instead:\n\n```sh\nsudo kblockerctl enable 60 --insecure\n```\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `enable \u003cminutes\u003e [--insecure]` | Enable blocking. Requires PGP unless `--insecure` |\n| `disable` / `unblock [--key \u003chex\u003e]` | Disable blocking. Needs PGP key when PGP mode is active |\n| `unload [--key \u003chex\u003e]` | Permanently remove the module. Needs the unblock key |\n| `status` | Show blocking state, remaining time, protected files |\n| `block \u003cdomain\u003e...` | Write domains to kernel and config file (does not enable) |\n| `add \u003cdomain\u003e` | Add a domain to the persistent config |\n| `remove \u003cdomain\u003e` | Remove a domain |\n| `reload` | Re-write domains to kernel, refresh PGP ciphertexts, restore persisted state |\n| `block-ip \u003cip\u003e...` | Set blocked IPs directly (replaces existing list) |\n| `list` | Show blocked IPs and configured domains |\n| `key` | Show the current unload key and PGP key fingerprints |\n| `add-pgp \u003cpubkey.asc\u003e [name]` | Register a PGP public key |\n| `remove-pgp \u003cfingerprint\u003e` | Remove a registered PGP key |\n| `list-pgp` | List registered PGP keys |\n| `pgp-cipher \u003cfingerprint\u003e` | Print the PGP-encrypted unload key for a recipient |\n| `add-pgp-web [--port \u003cport\u003e] [--bind \u003cip\u003e]` | Start web UI for browser-based PGP key generation |\n| `unblock-web [--port \u003cport\u003e] [--bind \u003cip\u003e]` | Start web UI to decrypt and submit unblock key via browser |\n| `crash` | Force-remove module (triggers kernel panic) |\n\n## Architecture\n\n```\n┌──────────────────────────────────────────────────────────┐\n│                    Userspace                             │\n│                                                          │\n│  kblockerctl                                             │\n│      │ writes                                            │\n│      ▼                                                   │\n│  /sys/kernel/kblocker/{enabled,blocked_ips,              │\n│                        blocked_domains,unblock,          │\n│                        disable,pgp_active,...}            │\n│                                                          │\n│  PGP keys: /etc/kblocker/keys/                           │\n│  Ciphertexts: /var/lib/kblocker/unlock-pgp/              │\n│  Persisted state: /var/lib/kblocker/state                │\n│  Domain config: /etc/kblocker/domains.conf               │\n│                                                          │\n│  Web UIs: add-pgp-web (key gen)                          │\n│           unblock-web (browser PGP decrypt)              │\n└──────────────────────┬───────────────────────────────────┘\n                       │ sysfs\n┌──────────────────────▼───────────────────────────────────┐\n│                    Kernel                                │\n│                                                          │\n│  netfilter hooks (LOCAL_OUT, FORWARD)                    │\n│    ├─ IPv4/IPv6 IP blacklist check                       │\n│    ├─ TLS SNI inspection (domain blacklist)              │\n│    └─ TLS ECH (0xFE0A) drop to force SNI fallback        │\n│                                                          │\n│  File protection (inode_operations override + immut)     │\n│    ├─ kblocker.ko                                        │\n│    ├─ /etc/modules-load.d/kblocker.conf                  │\n│    └─ /etc/hosts                                         │\n│                                                          │\n│  Key management                                          │\n│    ├─ 128-bit random key at module init                  │\n│    ├─ SHA-256 hash stored for verification               │\n│    ├─ PGP mode: key zeroed on pgp_active=1               │\n│    └─ disable: regenerates key + clears pgp_active       │\n│                                                          │\n│  Timer: auto-disable on expiry (checks every 1s)         │\n│  Workqueue: file protection re-check (every 1s)          │\n└──────────────────────────────────────────────────────────┘\n```\n\n## Build\n\n```sh\nmake\n```\n\nRequires kernel headers (`linux-headers-$(uname -r)`) and Go 1.21+.\n\n## Install / Uninstall\n\n```sh\n# install\nsudo ./install\n\n# uninstall\nsudo ./uninstall\n```\n\nOr via the deb package: `./build-deb.sh` produces a `.deb` in `build/`.\n\n## Testing\n\n```sh\nsudo ./test.sh\n```\n\nRuns integration tests against the live kernel module via sysfs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdan-j-d%2Fkblocker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdan-j-d%2Fkblocker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdan-j-d%2Fkblocker/lists"}