{"id":25510239,"url":"https://github.com/pesader/gnome-shell-extension-blocker","last_synced_at":"2025-04-10T15:36:30.277Z","repository":{"id":222564328,"uuid":"756678810","full_name":"pesader/gnome-shell-extension-blocker","owner":"pesader","description":"A content blocker for your entire computer.","archived":false,"fork":false,"pushed_at":"2025-02-24T20:32:04.000Z","size":1743,"stargazers_count":29,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-24T13:21:22.326Z","etag":null,"topics":["adblocker","dns","gnome"],"latest_commit_sha":null,"homepage":"https://pesader.dev/gnome-shell-extension-blocker/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pesader.png","metadata":{"files":{"readme":"README.jsdoc.md","changelog":"CHANGELOG.md","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}},"created_at":"2024-02-13T04:54:43.000Z","updated_at":"2025-03-16T16:55:30.000Z","dependencies_parsed_at":"2025-02-19T09:49:11.484Z","dependency_job_id":null,"html_url":"https://github.com/pesader/gnome-shell-extension-blocker","commit_stats":null,"previous_names":["pesader/gnome-shell-extension-hblock-toggle","pesader/gnome-shell-extension-blocker"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pesader%2Fgnome-shell-extension-blocker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pesader%2Fgnome-shell-extension-blocker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pesader%2Fgnome-shell-extension-blocker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pesader%2Fgnome-shell-extension-blocker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pesader","download_url":"https://codeload.github.com/pesader/gnome-shell-extension-blocker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248243474,"owners_count":21071054,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["adblocker","dns","gnome"],"created_at":"2025-02-19T09:38:21.328Z","updated_at":"2025-04-10T15:36:30.266Z","avatar_url":"https://github.com/pesader.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Blocker banner](./assets/banner-jsdoc.png)\n\nBlocker is a GNOME Shell Extension that allows users to easily toggle system-wide content blocking. It uses a program named [hBlock](https://hblock.molinero.dev/) to change your computer's DNS settings, so it does not to connect to domains that are known for serving adverts, trackers, and malware. This strategy of content blocking has its limitations, and you can read more about them in the FAQ.\n\n## Getting started\n\n### Installation\n\nFirst, you need to install [hBlock](https://hblock.molinero.dev/). Follow the instructions [here](https://github.com/pesader/gnome-shell-extension-blocker/wiki/Installing-hBlock) to install it.\n\n\u003cdiv style=\"border-left: 4px solid #8250df; padding: 10px; border-radius: 5px;\"\u003e\n  \u003cdiv style=\"color: #8250df; font-weight: bold; margin-bottom: 5px;\"\u003e\u0026#128712; Important\u003c/div\u003e\n  \u003cdiv\u003eBlocker depends on \u003ca href=\"https://github.com/hectorm/hblock/\" target=\"_blank\"\u003ehBlock\u003c/a\u003e and won't work if you haven't installed it on your computer.\u003c/div\u003e\n\u003c/div\u003e\n\nAfter installing hBlock, you can install Blocker itself through the GNOME Extensions website.\n\n\u003ca href=\"https://extensions.gnome.org/extension/7831/blocker/\"\u003e\n  \u003cimg height=\"80\" src=\"assets/ego.png\"\u003e\n\u003c/a\u003e\n\n### Usage\n\n\u003cbr\u003e\n\u003cdiv style=\"border-left: 4px solid #d32f2f; padding: 10px; border-radius: 5px;\"\u003e\n  \u003cdiv style=\"color: #d32f2f; font-weight: bold; margin-bottom: 5px;\"\u003e\u0026#9888; Caution\u003c/div\u003e\n  \u003cdiv\u003eBlocker replaces your system's \u003ccode\u003e/etc/hosts\u003c/code\u003e file. Consider making a backup of it!\u003c/div\u003e\n\u003c/div\u003e\n\nClick the Quick Settings toggle and input your user's password to activate Blocker (it will take a while to download all its denylists). Once Blocker is active, it will display a system indicator of a shield. To turn it off, simply click the toggle and input your password again.\n\n## FAQ\n\n### How does it work?\n\nThis GNOME Shell extension is just a convenient frontend for [hBlock](https://github.com/hectorm/hblock/), which does all the heavy lifting. Here's what happens when you toggle Blocker:\n\nFirst, Blocker uses pkexec (the program that prompts you for your password) to gain super user privilege, which is required to run hBlock. Then, if you enabled Blocker, it enables hBlock by running `hblock`. If you disabled Blocker, it disables hBlock by running `hblock -S none -D none`. I couldn't resist a flowchart...\n\n\u003cimg src=\"assets/flowchart.png\"\u003e\n\n### What are its limitations?\n\nBlocker is powered by hBlock, so its limitations are Blocker's limitations.\n\nThe content blocking strategy used by hBlock is [DNS blocking](https://en.wikipedia.org/wiki/DNS_blocking). That means that any connections that do not depend on name resolution cannot be blocked using this approach, such as accessing an IP address directly. Additionally, certain applications may set their own DNS settings (e.g. Firefox, when it uses DNS over HTTPS) instead of adhering to the system's configuration. Finally, your DNS settings may be affected if you are using a VPN, which tipically route your DNS queries to its own resolvers.\n\n### How do I know it's working?\n\nVisit https://hblock.molinero.dev, it tells you whether hBlock is active or not. This is does that by checking if connections to https://hblock-check.molinero.dev are blocked, which is the case for hBlock's default configuration.\n\n### Can I customize the denylist?\n\nBlocker does not provide, nor plans to provide, that kind of customization. However, you can do that if you use hBlock directly in the terminal, using `-A`, `-D`, and `-S` flags. Run `hblock --help` for more details.\n\n### Where should I report problems?\n\nFor false positives (i.e. a legimate site is being mistakenly blocked), report in [hBlock's issue tracker](https://github.com/hectorm/hblock/issues). For everything else, report in [Blocker's issue tracker](https://github.com/pesader/gnome-shell-extension-blocker/issues).\n\n## Contributing\n\n### Translating\n\nBlocker can be translated using [Weblate](https://hosted.weblate.org/projects/gnome-shell-extension-blocker/extension/). Here's our progress so far:\n\n[![Translation status](https://hosted.weblate.org/widgets/gnome-shell-extension-blocker/-/multi-auto.svg)](https://hosted.weblate.org/engage/gnome-shell-extension-blocker/)\n\n### Programming\n\n#### Understanding the codebase\n\nBlocker's code is documented using JSDoc. You can read the documentation directly in the source code, or head to the [Developer Documentation](https://pesader.dev/gnome-shell-extension-blocker/) page.\n\n#### Building and installing from source\n\nIf you wish to make changes to the Blocker codebase, you will likely want to build it and install it from source. Blocker's source code on hosted on [GitHub](https://github.com/pesader/gnome-shell-extension-blocker). Your first step is cloning Blocker's repository with:\n\n```bash\ngit clone https://github.com/pesader/gnome-shell-extension-blocker.git\n```\n\nYou can then build and install the extension with:\n\n```bash\ncd gnome-shell-extension-blocker\nmake build \u0026\u0026 make install\n```\n\nYou can run a nested session of GNOME Shell to test the extension out with:\n\n```bash\nmake run\n```\n\nBefore submitting a pull request, make sure you install and run the linter with:\n\n```bash\nmake lint-install # install the linter\nmake lint         # run the linter\n```\n\nYou can also have the linter attempt to fix the errors it found with:\n\n```bash\nmake lint-fix\n```\n\n## Attribution\n\n### Code\n\n- Assign a custom icon to a Quick Settings toggle: based on the codebase from [Caffeine](https://github.com/eonpatapon/gnome-shell-extension-caffeine).\n- Run shell commands asynchronously: heavily inspired by the [GJS docs](https://gjs.guide/guides/gio/subprocesses.html) and [GSConnect](https://github.com/GSConnect/gnome-shell-extension-gsconnect/blob/main/src/service/plugins/runcommand.js).\n- Send customized notifications: reused from [Gravatar](https://github.com/dsheeler/gnome-shell-extensions-gravatar) and [Picture of the day](https://github.com/swsnr/gnome-shell-extension-picture-of-the-day) extensions.\n\n### Assets\n\n- Blocker's logo: derived from the [`shield-safe-symbolic`](https://gitlab.gnome.org/World/design/icon-library/-/blob/master/data/resources/icon-dev-kit/shield-safe-symbolic.svg?ref_type=heads) icon, by the GNOME Project.\n- Blocker's banner: inspired by the banners at [Flathub's home page](https://flathub.org/)\n- Extension logo in banner: is the symbolic icon from Matthew Jakeman's [Extension Manager](https://github.com/mjakeman/extension-manager/blob/master/data/icons/com.mattjakeman.ExtensionManager-symbolic.svg)\n- EGO banner: modified from [Just Perfection's work](https://gitlab.gnome.org/jrahmatzadeh/just-perfection/-/blob/main/data/imgs/ego.svg?ref_type=heads).\n\n### Build system\n\n- Makefile: inspired by the Makefile of [Caffeine](https://github.com/eonpatapon/gnome-shell-extension-caffeine/blob/master/Makefile)\n- GitHub Actions workflow for linting: again, inspired [Caffeine](https://github.com/eonpatapon/gnome-shell-extension-caffeine/tree/master/.github/workflows)\n\n### Documentation\n\n- How to install hBlock: copied and pasted staright from hBlock's [README](https://github.com/hectorm/hblock/?tab=readme-ov-file#installation) and [docs](https://github.com/hectorm/hblock/blob/master/PACKAGES.md)\n\n## Gratitude\n\nThis project would not exist if it weren't for hBlock, so I thank its maintainer and all its contributors. I'm also grateful to everyone in the GNOME Extensions matrix room, who kindly answered the many questions that came up while I was writing this program.\n\n## License\n\nThis project is licensed under the terms of the [GPLv3](https://www.gnu.org/licenses/gpl-3.0.txt).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpesader%2Fgnome-shell-extension-blocker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpesader%2Fgnome-shell-extension-blocker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpesader%2Fgnome-shell-extension-blocker/lists"}