chromium/components/safe_browsing/content/resources/real_time_url_checks_allowlist/README.md

# Behavior of Real Time URL Allowlist Checks in Chrome on Android

This describes how a dev can create a new allowlist component version with an updated
version of the allowlist from Safe Browsing and push it to GCS. Once the newly generated
component is in GCS, the component updater will provide Chrome with this new version of the
allowlist.

## Procedure for updating the allowlist by creating a new component
* **Edit** `real_time_url_allowlist.asciipb` file.
  * The version_id should be the current pb's version_id incremented by 1.
  * The scheme_id should not be changed, unless there are backwards-incompatible changes made
  such that the previous version of the code is no longer compatible with the latest version
  of the component. This will block clients that are using older versions of the code from
  upgrading to the latest component version until they update to the latest version of the
  code. This should be used carefully, since while it ensures backwards compatibility, it
  also makes it so that we can no longer update the component for clients with older code.
  Therefore, the new scheme_id should be incremented by 1 only if such changes are made to
  the code.
  * Do not change the url_hashes, since they will be fetched and stored in the next step.
* **Run** `python3 store_real_time_url_allowlist_prefixes.py -p ~/chromium/src/out/{Android}`,
  where {Android} is the name of your Android build directory. Run this from the
  `components/safe_browsing/content/resources/real_time_url_checks_allowlist/` directory.
  This script will use the Safe Browsing API to fetch the URL hash prefixes, validate
  them, and if they're valid, store them in the real_time_url_allowlist.asciipb file.
    * To double check that the new allowlist contents are valid, **run**
    `~/chromium/src/out/{Android}/components_unittests --gtest_filter="RealTimeUrlChecksAllowlistResourceFileTest.*"`
    before proceeding
* **Submit** a chromium CL with the new `real_time_url_allowlist.asciipb` version.
    * When chrome builds, it will automatically run the make_real_time_url_allowlist_protobuf
      target. This target builds the new version of the local real_time_url_allowlist.pb file.
    * Wait 1 week for this to run on Canary. Then, verify there have been no crashes and that
      there are no regressions on UMA for the metrics listed below for Android. (If either of
      these issues happen, follow the rollback procedure described in the next section.)
        * Allowlist match rate
          (SafeBrowsing.RT.LocalMatch.Result)
        * Number of times SB is the navigation bottleneck
          (SafeBrowsing.BrowserThrottle.IsCheckCompletedOnProcessResponse)
        * Time to contentful paint
          (PageLoad.PaintTiming.NavigationToFirstContentfulPaint)
* **Push** the new version of the component to GCS to roll it out to users.
    * In a synced checkout, run the following to generate the proto and push it to GCS. Run this
      from the `/chromium/src/` directory. Replace the arg with your build directory:
        * % `components/safe_browsing/content/resources/real_time_url_checks_allowlist/push_real_time_url_allowlist_proto.py -d out-gn/Android`
    * It will ask you to double check its actions before proceeding.  It will fail if you're not
      a member of `[email protected]`, since that's required for access to
      the GCS bucket.
    * The Component Updater system will notice those files and gradually push them to users
      over a 3 day period. If not, contact the Omaha support team.

## Procedure for rollback
While Omaha allows rollback through the release manager, the Chrome client will
reject updates with lower version numbers. (This is important for running new
versions on Canary/Dev channel). Rolling back a bad version is best achieved by:
  * **Reverting** the changes on the Chromium source tree.
  * **Submitting** a new CL incrementing the version number.
  * **Push** the newest version, as above.