This page describes how to write rulesets for HTTPS Everywhere, a browser extension that switches sites over from HTTP to HTTPS automatically. HTTPS Everywhere comes with thousands of rulesets that tell HTTPS Everywhere which sites it should switch to HTTPS and how. If there is a site that offers HTTPS and is not handled by the extension, this guide will explain how to add that site.
<ruleset name="RabbitMQ"> <target host="rabbitmq.com" /> <target host="www.rabbitmq.com" /> <rule from="^http:" to="https:" /> </ruleset>
target tag specifies which web sites the ruleset applies to. The
rule tag specifies how URLs on those web sites should be rewritten. This rule says that any URLs on
www.rabbitmq.com should be modified by replacing "http:" with "https:".
When the browser loads a URL, HTTPS Everywhere takes the host name (e.g. www.rabbitmq.com) and searches its ruleset database for rulesets that match that host name.
HTTPS Everywhere then tries each rule in those rulesets against the full URL. If the Regular Expression, or regexp, in one of those rules matches, HTTPS Everywhere rewrites the URL according the
to attribute of the rule.
To cover all of a domain's subdomains, you may want to specify a wildcard target like
*.twitter.com. Specifying this type of left-side wildcard matches any host name with
.twitter.com as a suffix, e.g.
urls.api.twitter.com. You can also specify a right-side wildcard like
www.google.*. Right-side wildcards, unlike left-side wildcards, apply only one level deep. So if you want to cover all countries you'll generally need to specify
www.google.com.* to cover domains like
www.google.com.au. You should use wildcard targets only when you have rules that apply to the entire wildcard space. If your rules only apply to specific hosts, you should list each host as a separate target.
Avoid regexes with long strings of subdomains, e.g.
<rule from="^http://(foo|bar|baz|bananas).example.com" />. These are hard to read and maintain, and are usually better expressed with a longer list of target hosts, plus a plain rewrite from
In general, avoid using open-ended regex in rules. In certain cases, open-ended regex may be the most elegant solution. But carefully consider if there are other options.
- Rulesets with a lot of domains that we can catch with a simple regex that would be tedious and error-prone to list individually, like
- CDNs with an arbitrarily large number of subdomains, like https://github.com/EFForg/https-everywhere/pull/7484#issuecomment-262852427 .
An exclusion specifies a pattern, using a regular expression, for URLs where the rule should not be applied. The Stack Exchange rule contains an exclusion for the OpenID login path, which breaks logins if it is rewritten:
<exclusion pattern="^http://(?:\w+\.)?stack(?:exchange|overflow)\.com/users/authenticate/" />
Exclusions are always evaluated before rules in a given ruleset. Matching any exclusion means that a URL won't match any rules within the same ruleset. However, if other rulesets match the same target hosts, the rules in those rulesets will still be tried.
There are many different ways you can write a ruleset, or regular expression within the ruleset. It's easier for everyone to understand the rulesets if they follow similar practices. You should read and follow the Ruleset style guide. Some of the guidelines in that document are intended to make Ruleset testing less cumbersome.
Many HTTPS websites fail to correctly set the secure flag on authentication and/or tracking cookies. HTTPS Everywhere provides a facility for turning this flag on. For instance:
<securecookie host="^market\.android\.com$" name=".+" />
We use an automated checker to run some basic tests on all rulesets. This is described in more detail in our Ruleset Testing document, but in short there are two parts: Your ruleset must have enough test URLs to cover all the various types of URL covered by your rules. And each of those test URLs must load, both before rewriting and after rewriting. Every target host tag generates an implicit test URL unless it contains a wildcard. You can add additional test URLs manually using the
You can test rulesets in the browser using a hidden debugging page, but please be aware that this approach should only be used for debugging purposes and should not be used for setting up personal custom rules. You can access the hidden debugging page this way:
about:addons> HTTPS Everywhere preferences > click under
General Settings> press Ctrl-Z
chrome://extensions/> HTTPS Everywhere options > click under
General Settings> press Ctrl-Z
You might need to disable popup blocking for the page to appear. Once you have loaded the page, you might find it convenient to bookmark it for later use.
If you've tested your rule and are sure it would be of use to the world at large, submit it as a pull request on our GitHub repository or send it to the rulesets mailing list at
https-everywhere-rules AT eff.org. Please be aware that this is a public and publicly-archived mailing list.
As an alternative to writing rules by hand, there are scripts you can run from a Unix command line to automate the process of creating a simple rule for a specified domain. These scripts are not included with HTTPS Everywhere releases but are available in our development repository and are described in our development documentation.
Sometimes rulesets are useful or interesting, but cause problems that make them unsuitable for being enabled by default in everyone's browsers. Typically when a ruleset has problems we will disable it by default until someone has time to fix it. You can do this by adding a
default_off attribute to the ruleset element, with a value explaining why the rule is off.
<ruleset name="Amazon (buggy)" default_off="breaks site"> <target host="www.amazon.*" /> <target host="amazon.*" /> </ruleset>
You can add more details, like a link to a bug report, in the comments for the file.
Some rulesets may trigger active mixed content (i.e. scripts loaded over HTTP instead of HTTPS). This type of mixed content is blocked in both Chrome and Firefox, before HTTPS Everywhere has a chance to rewrite the URLs to an HTTPS version. This generally breaks the site. However, the Tor Browser doesn't block mixed content, in order to allow HTTPS Everywhere to try and rewrite the URLs to an HTTPS version.
To enable a rule only on platforms that allow mixed content (currently only the Tor Browser), you can add a
platform="mixedcontent" attribute to the ruleset element.