Add-ons

Testing Staged Add-ons Blocklist

Prerequisites

To test the full functionality of blocklist v3 against the staging server, you need to set up a Firefox profile with the following preferences:

1. extensions.blocklist.useMLBF.stashes = true
2. extensions.blocklist.useMLBF = true
3. services.settings.server = https://settings.stage.mozaws.net/v1
4. xpinstall.signatures.dev-root = true
5. extensions.webapi.testing = true (new pref to be created to be able to interact with the install button on stage)
   

Note 1: During testing, the behavior should be identical regardless of whether stashes=true or stashes=false. This preference enables an optimization to save bandwidth.
Note 2: The preferences referenced in entries 1 and 2 should be enabled by default in the latest version of Firefox and will not require manually setting them.

Creating a block entry

Blocks in v3 are managed via the admin tool on AMO, and are automatically on a schedule used to create a new bloomfilter.
To set up a block entry, follow these steps:

1. Identify an add-on on AMO stage https://addons.allizom.org/ that should be blocked and download the .XPI
   Note: The add-on needs to be a webextension and approved (signed). Or upload an add-on and download the .XPI once approved and signed.
2. Install the add-on in Firefox.
   Note: You will need to enable the preference to install add-ons from AMO stage (xpinstall.signatures.dev-root = true, see Prerequisite #4). Make sure that the add-on appears installed in addons manager (about:addons)
3. Retrieve the add-on’s guid
   Note: If the guid is not specified in the manifest.json of the .XPI you can retrieve it from about:debugging#/runtime/this-firefox.
4. Login at https://addons-internal.stage.mozaws.net/en-US/admin/models/.
   Note: You will need to connect via Mozilla’s VPN. You will also need to be added to an admin user group on AMO if not already a member. You’ll aslo need the ‘Blocklist:Create’ permission.
5. Make sure the waffle switch blocklist_mlbf_submit is enabled in https://addons-internal.stage.mozaws.net/en-US/admin/models/waffle/switch/
6. Create a new add-on block record for the add-on guid from Step 1 via https://addons-internal.stage.mozaws.net/en-US/admin/models/blocklist/block/add/
   Note: If you chose to block multiple guids at a time, the version range can be manually entered (i.e. there is no predefined select field with versions available to choose from). Make sure that at least one version of the guids you work with is covered by your chosen that range, otherwise the you ,might not find the add-on in the new generated blocklist.
7. If you are blocking an add-on that has a large number of active daily users (over 100k, which is unlikely for AMO stage), or an add-on that has 0 users (which is guaranteed if you created a new add-on in Step 1) then a sign-off is required from a different AMO/FxA user (who will also need to login via the VPN and be in an admin user group on AMO).
8. Take note of the contents of https://kinto.stage.mozaws.net/v1/buckets/blocklists/collections/addons-bloomfilters/records
   Important Note: The new blocklist starts being generated on AMO every 6 hours (06:35 UTC), so it should be available between 06:45 – 07:00 UTC (and every 6 hours thereafter)
9. Check the contents of https://kinto.stage.mozaws.net/v1/buckets/blocklists/collections/addons-bloomfilters/records have changed since Step 8
   Note: How to verify the new stash: the stash will contain two sections - blocked: [] and unblocked: []; There will be one entry for each combination or "guid:version string” covered by the block range set up in AMO admin. If a block is deleted, all the add-on versions should be located in the stash - unblocked section. Also, keep in mind that if you edit an existing block by expanding the blocked version range (i.e. you include additional add-on versions in the blocked range), you should see the new covered versions in the stash - blocked. Similarly, if you exclude some previous blocked versions from the block range, the excluded versions should be visible in stash - unblocked.
   

Connecting to the stage server and triggering a new blocklist

You need to force an update of the blocklist in Firefox and verify that the add-on added in the previous step are indeed blocked. And similarly, marking an add-on as unblocked in the AMO admin tools, forcing an update and verifying that the add-on is unblocked again.
To point Firefox to the stage server, follow these steps:

1. set services.settings.server = https://settings.stage.mozaws.net/v1 (Prerequisites #3)
2. on Beta and Release, start Firefox via the command line as follows:
   ▪ [Windows]: Open cmd and run:
   1. set XPCSHELL_TEST_PROFILE_DIR=1
   2. firefox.exe --no-remote -p
   ▪ [Linux and macOS]: Open the terminal and run:
   1. export XPCSHELL_TEST_PROFILE_DIR=1
   2. firefox --no-remote -p
   Note: In both cases `-p` opens the profile manager. You can also use --profile to specify an explicit location of the profile directory. (“firefox”/”firefox.exe” must be replaced with the actual path to the Firefox binary if needed).
   Optional: to verify that the switch to the staging server has been successful, open the DevTools console and run
   ChromeUtils.import("resource://services-settings/Utils.jsm").Utils.SERVER_URL => this should return https://settings.stage.mozaws.net/v1
3. Go to about:addons, open the DevTools console and force an update of the blocklist by running:
   ChromeUtils.import('resource://gre/modules/Blocklist.jsm').Blocklist.ExtensionBlocklist._client.sync()
   The installed add-on should now reflect the blocked status. If the status is not automatically updated, refresh the page.

Logging States

Enable logging to help debug via the browser console:

• open a new tab and type about:config into the URL
• change the extensions.logging.enabled preference from false to true
• open the browser console using the steps from Forcing a Blocklist Ping and force a ping

You'll receive similar output via the browser console:

Blocklist state for firefox-devedition@mozilla.org@personas.mozilla.org changed from 0 to 0
Blocklist state for Shockwave Flash changed from 0 to 4

The definitions of each state can be found in the following source file

Plugins

Flash (Downloading/Uninstalling)

• Uninstalling Flash on Windows
• Uninstalling Flash on OSX

Graphics

Testing Graphics Blocklist entries

(Note: this only applies to Windows.)

1. If the blocklist entry is on staging, see above for testing a staged blocklist first.
2. Ensure you're currently hardware accelerated by opening about:support and looking at the Graphics section. Check that you have:
   1. Direct2D true (if on Windows 7 or Vista with the platform update)
   2. Hardware accelerated windows 1/1 Direct3D 9 (or 10)
3. Force a blocklist ping, as above.
4. Wait 5 seconds.
5. Restart your browser.
6. Open about:support and look at the Graphics section again. Ensure that:
   1. Direct2D is false
   2. Hardware accelerated windows 0/1

Quickly Checking Features

In addition to the above section, features can also be checked for disabled/enabled status by the following:

• NOTE: Direct3D 10 and Direct3D 10.1 are impossible to distinguish visually.

Spoofing Hardware Details for Blocklist Testing

Sometimes you don't have hardware or software available to test a given blocklist entry. On Windows, you can spoof your hardware and software details to the graphics blacklist using environment variables.