Warning: This document has been automatically translated. Please send us a pull request if you find any errors.
- Understanding the UI
- How to install
- Try it!
- Going deeper
- How to contribute
- Known issues
- Understanding the code
We have amazing projects like Lightbeam, NoScript, ScriptSafe, uBlock Origin, HTTPS Everywhere and many others. All have the proposal to identify and/ or prevent the execution of questionable codes and requests.
- 6 requests influenced by HTTPS Everywhere
- 75 requests blocked by uBlock Origin
- 4 items blocked by ScriptSafe
Understanding the UI
How to install
Install the extension and go to our demo page to experience and better understand how it works:
See some screenshots here.
- Documentary: Do Not Track
- Book: 1984
- Book: Cypherpunks: Freedom and the Future of the Internet
- Book: The Filter Bubble: How the New Personalized Web Is Changing What We Read and How We Think
- Web page: Internet Health
- Web page: About Lightbeam
Guides are documents on many specific subjects where we can go deep into the details and easily find the information we are looking for. See all guides.
How to contribute
- Spread the word
- Report issues
- Get your hands dirty
Spread the word
Write some guide
Collaborate by writing some guide on subjects related to the project.
Tell your friends, family, and co-workers about how the extension was used to improve your web experience and teach them how to use it too!
Write and talk about it
Did you find a website invading your privacy? Did you block events you did’nt want? Did you make it easier for you to develop your code or debug errors? Record a video, prepare a talk, write an article or anything like that telling how it was done, explaining how the extension helped you and showing the possibilities.
Help with translations
.md files found inside the
doc/ directory and the
.json files into the
_locales/ directory for your language and help us reach more people!
Issues on specific websites
Had trouble accessing a site because of the extension? Was it slow? Caused errors? Has the site stopped working? Not all events were identified? Open an issue and tell us what happened.
Issues in some browser
Open an issue if something didn’t work as expected in a browser. We want everything to work fine for all possible browsers!
Get your hands dirty
Improve the UI
We don’t have the most beautiful and friendly interface in the world. Discussions and proposals on a new interface or improvements to the existing one (
html/interface-sample.html) will be very welcome! Do not underestimate the power of this kind of collaboration: better_errors#6 - better_errors#22
Example 1: The sooner we can inject code into websites and the less resources we use to process information, the more executions we’ll be able to identify and the better our experience will be by having an extension that does not slow navigation.
Look for example to our demo page (
This delay of 100 milliseconds exists because without it the code is executed too fast and we can not intercept it. How can we improve this so we do not need this delay or can we reduce it?
Example 2: We capture only one piece of the intercepted function, because it can be very large and let the reading of the information slow (
listener: ('' + listener).slice(0, 400)
How can we improve this? Is this the best way to deal with this problem?
Example 3: The way we found to pass messages from the context of the document to the context of the extension was by parsing the data in JSON reading an HTML element (
render_data( JSON.parse($(data_element).html()), tab_id );
Are there alternatives? Is parsing information constantly the best option?
Create new features
We start with a basic idea: identify and block events. We can expand this idea, some thoughts that have already arisen:
We intercept only calls to
handleEvent. Would not it be interesting to also intercept calls to
We are not intercepting inline defined events (
<a onclick="someAction()">), would not it be interesting to do so?
Today we can block events by domain: “Block the execution of mouseover in the domain somesite.com”. Would not it be interesting to have more elaborate rules and block an event only if its target is an element of type X or the code executed is matches with some regular expression?
Improve code quality
This is an experimental project that grew in an uncontrolled way, we do not have a defined standard of nomenclature, a strong organization based on some design pattern or automated tests. Discussions to improve the quality of the code will be very welcome!
We did not intercept inline codes (
A code can be executed before we can inject the interceptor. It’s rare, but possible.
Mozilla Firefox Service Workers
In Mozilla Firefox and derivatives, some websites that use Service Workers (like WhatsApp Web) can block the code interception because of a bug in the interception of headers with the Content-Security-Policy guidelines. The current workaround is to reload the Service Worker:
- Access the Service Workers screen at:
- Click on unregister in the Service Worker of the desired website:
- Reload the website.
Understanding the code
js/background/set_current_tab.js: Responsible for injecting the current tab ID into the document.
js/background/set_response_headers.js: Responsible for changing Content-Security-Policy header of requests.
js/background/update_badge.js: Responsible for updating the counter on the extension icon.
/content/injections/data.js: Responsible for injecting the HTML element that will store the data collected from the interceptions.
/content/injections/interceptor.js: Responsible for injecting the code that will actually execute the interceptions in the document.
/content/injections/options.js: Responsible for injecting the HTML element that will store user-defined options.
/content/readers/data.js: Responsible for reading the data in the HTML element of the document that stores the collected details of the interceptions and passes them to the extension.
/content/injections_controller.js: Responsible for making decisions about the code injections.
Responsible for rendering and handle interactions on the pop-up that is opened by clicking the extension icon:
Responsible for rendering and handle interactions on the settings pages:
js/utils/colors.js: Function used to determine the color displayed based on the value of the counter.
js/utils/number.js: Function used to format the number according to its size.
Third party libraries
vendor/bootstrap: Bootstrap front-end component library
vendor/tippyjs: A lightweight, vanilla JS tooltip library
This project is licensed under the GPLv3 license.
There is no kind of organization for receiving donations at the moment. See our guide on “how to contribute” to other ways of contributing. If you really want to make a donation, here are some incredible foundations that’s share some ideals of this project that you can help: