Preamble: The core of uMatrix is the sum of all your rules -- i.e. your ruleset. All rules are of the form:
source destination type action
sourceis the scope in which the rule must be enforced.- The scope is derived from the hostname of the URL address of the current web page.
- The special scope
*represents the global scope, meaning a rule in that scope will apply everywhere, unless overridden by a higher precedence rule.
destinationis the remote server for which the rule applies.- The special destination
*means "all destinations", meaning a rule that will be enforced for all destinations, unless overridden by a higher precedence rule.
- The special destination
typeis the type of resource for which the rule applies.- The special type
*means "all types", meaning a rule that will be enforced for all types of resources, unless overridden by a higher precedence rule.
- The special type
actionis whether the resource must be blocked or allowed.
The matrix UI in the popup panel is a direct and accurate view of your ruleset for the current scope.
The matrix UI will show you at once all the connections for the current page (including the blocked ones), and how your ruleset affected the outcome. The matrix UI is fully interactive, you can point-and-click to add/remove rules to/from your ruleset.
Scope selector
The scope currently selected in the picture above is sciencemag.org.
The scope selector allows you to pick the scope to visualize which rules are part of, or propagate to that scope, and also from which scope rules will be added/removed when you click on a cell in the matrix.
Using the picture above as example, one can use the scope selector to visualize or add/remove rules specific to the www.sciencemag.org, sciencemag.org, org, and even the global scope, *:
Just click the proper hostname label to select various scopes.
As per uMatrix rule-propagation logic, remember that rules from a broader scope propagate to narrower scopes, unless of course there is an explicit rule on the way.
Given a rule source destination type action, the scope selector controls the source part of that rule.
The matrix cells
The matrix is made of cells.
All cells in the matrix map to a source destination type action rule internally. For any given cell, an associated rule may or may not exist. This mapping allows you to easily visualize your ruleset for the currently selected scope, and to easily add/remove rules to/from your ruleset through easy point-and-click.
The color of a cell tells whether the underlying resource will result in a block or allow action:
- Dark red: the cell is affected by a block rule.
- Pale red: the cell inherit a block rule by virtue of uMatrix's rule-propagation logic.
- Dark green: the cell is affected by an allow rule.
- Pale green: the cell inherit an allow rule by virtue of uMatrix's rule-propagation logic.
The matrix is a view on the current state of the temporary ruleset. The temporary ruleset is always what uMatrix uses to decide whether a resource must be blocked or allowed.
The matrix will however also show you the permanent rule assigned to a cell, if any: the little triangle in the top left corner of a cell when present represent a permanent rule that exists for that cell.
If a cell has a permanent rule assigned to it and you change the state of the cell, you will see that the permanent state and the temporary state become different as a result. The discrepancy will disappear when you persist the temporary rules in the current scope by clicking the padlock icon:
The above picture shows that the cell has a temporary allow rule assigned to it, and a permanent block rule, meaning that if you revert all temporary rules, the cell will go back to its saved block state.
There are four distinct sections in the matrix, from top to bottom:
- Top section is for 1st-party domain and subdomains.
- Second section is for whitelisted domains.
- Third section is for graylisted domains, i.e. domains which are neither whitelisted or blacklisted.
- Fourth section is for blacklisted domains.
The fourth section is fully collapsible, as its content can be considered "noise", as it is unlikely you will need to modify rules in that section (though it may happen you will need to do so).
The "all" cell
The all cell allows you to set the default rule which will affect all other cells in the matrix for the current scope, and related narrower scopes as per rule-propagation logic.
As per uMatrix rule-propagation logic, all cells for which there is no explicit rules will inherit the state of the all cell.
Given a rule source destination type action, the all cell means that source, destination, and type are all *.
The "type" cells
Given a rule source destination type action, a type cell controls the type part of that rule while the destination part is * (meaning all destinations).
Currently, the type cells translate into these network request types internally:
| matrix header | rule type | browser resources |
|---|---|---|
| (invisible) | doc |
root document |
| cookie | cookie |
cookies, local storages (as browser API allows) |
| css | css |
stylesheets, fonts |
| image | image |
images (<img>, <picture>) |
| media | media |
audio (<audio>),video ( <video>),plugins ( <object>, <embed>)it is expected that users of uMatrix will have their click-to-play setting enabled in their browser |
| script | script |
scripts |
| XHR | xhr |
XMLHttpRequest, Fetch, WebSockets |
| frame | frame |
embedded documents (<iframe>, <frame>) |
| other | other |
everything which does not fit in previous types: beacons, CSP reports, ping, Web App Manifest, XBL, DTD, XSLT, and other unspecified types |
The "destination" cells
The destination cells allow to easily set allow/block rules to allow/block all types of resources from a specific destination.
When a network request is made to a specific destination, uMatrix will report the hostname at which the network request was made, and all the intermediate subdomains (if any) up to the base domain.
Rules on a base domain or subdomains propagate to all descendant subdomains. Generally, if you trust a base domain, it is convenient to set an allow rule to it, so that all subdomains are also allowed as per rule-propagation logic.
Again, keep in mind that rules from broader scopes propagate to narrower scopes, so for some it might be convenient to set an allow rule in the global scope for a base domain they completely trust, for example this is convenient for content delivery networks ("CDN") which use is widespread: * jquery.com * allow (but really this is a matter of opinion, many will argue that it is not good to wholly allow even such popular CDN: in the end, it's your choice).
The 1st-party cell and associated cell types is a special row used to assign default rules to whatever is 1st-party to the current site (what is reported in the scope selector). Typically the rules for 1st-party are set in the global scope -- it's a bit weird to set a 1st-party rule in a narrower scope, but it is possible after all.
All hostnames which are explicitly blocked are sent at the bottom of the matrix, so as to reduce visual noise for destinations which are of little interest since they have already been blacklisted. You can collapse/expand that section of the matrix. Typically all the blocked rules created as a result of loading hosts files are reported in that section. Keep in mind you can override these built-in block rules as you wish with either a noop rule or an allow rule (you can click the cell to add/remove rules just as with any other cell).
Given a rule source destination type action, the destination cell controls the destination part of that rule, and the type is set to * -- meaning "all resources" from that destination will be affected by the rule.
The "destination & type" cells
These cells serve to visualize what resource for what destination are allowed/blocked in the current scope. They can also be used to add/remove rules for specific destination and type of resources.
The count reported in these cells represent the number of distinct URLs which were used to connect (or attempted connection) to the remote server.
Typically, it is inconvenient to strictly work at such granularity, one will usually assign rules to whole domains or whole types, but the destination & type are very useful in case one needs to override an inherited rule from a lower scope or lower precedence cell.
For example, with uMatrix's default ruleset, there is a global allow rule assigned to the 1st-party/frame cell, to override the global block rule for frame.
But as usual, it's up to you to make use of this ability to go more granular when you craft your ruleset.
Given a rule source destination type action, a destination & type cell controls the destination and type part of that rule.