Shavar 列表文档

Shavar - 简要概述

Shavar 是一款基于 Python 的服务，它为 Firefox 客户端提供跟踪保护列表。每 6 小时，Firefox 客户端都会向该服务发送一个 POST 请求以获取更新的列表，如果存在更新，Shavar 会返回客户端可以从中下载最新列表的 CloudFront URL。请注意，用户可以使用 about:url-classifier 手动触发更新。

更新列表流程

shavar-list-creation 从 shavar-prod-lists 获取 blocklist .json 并生成兼容 Safe Browsing 的摘要列表文件。

Disconnect 每隔一段时间就会向 Mozilla 提供更新的 blocklist，并向 https://github.com/mozilla-services/shavar-prod-lists 存储库提交一个拉取请求，负责的工程师需要手动合并该 PR 以触发 shavar 服务器上的自动更新。

列表

以下列表保存在 shavar-prod-lists 存储库中。

列表 用途
disconnect-blacklist.json 此 blocklist 是 Firefox 中跟踪保护的核心。Firefox 按如下方式使用该列表：

跟踪：广告、分析、社交、内容或 Disconnect 类别中的任何内容。Firefox 提供了跟踪列表的两个版本：“级别 1”列表，它不包含“内容”类别，以及“级别 2”列表，它包含“内容”类别。

加密货币挖矿：加密货币挖矿类别中的任何内容。

指纹识别：FingerprintingInvasive 类别中的任何内容。默认情况下，ETP 的指纹识别阻止功能仅阻止跟踪指纹识别器，即同时出现在 FingerprintingInvasive 类别和其中一个跟踪类别中的域。Firefox 目前不使用 FingerprintingGeneral 类别。
disconnect-entitylist.json Disconnect 的实体列表的版本控制副本。当资源出现在 blocklist 上并作为第三方加载时，ETP 会将其分类为跟踪资源。实体列表用于允许完全由访问者正在访问的顶级网站所属的公司拥有的第三方子资源。

更新过程

跟踪保护列表更新每两到三个月进行一次。Disconnect 人员在最近的时间范围内汇总更改，并创建一个 PR 以将列表更新提交到 shavar-prod-lists 存储库。然后，我们采取以下步骤来审查和合并对我们生产列表的更改。

  • 自动化脚本首先验证更新列表的完整性。

  • Shavar 审阅者手动检查 PR 中的提交。通常，我们接受更改集，并且不会要求 Disconnect 做出进一步的修改。但是，我们可以要求他们合并或拆分提交，以便轻松地将更改提升到不同的版本。

  • Shavar 审阅者将 PR 合并到 master 分支。

  • 检查是否需要将某些提交提升到以前的版本。这偶尔需要执行，以部署 ETP Webcompat 问题的修复程序。

  • 为 Firefox 版本创建分支。请注意，创建分支有一条特殊规则；如果 Nightly 通道是偶数版本，则必须首先创建奇数版本。否则，需要先创建偶数版本。然后，需要等待 30 分钟，然后为其他版本创建分支。

为了确保 Firefox 客户端收到其 ETP 列表的适当更新，我们利用分支策略。这意味着我们为不同的 Firefox 版本维护单独的分支。当运行 Firefox 80 (fx80) 的客户端请求 ETP 列表更新时，它会被定向到 Github 上 shavar-prod-lists 存储库中名为 80.0 的分支。

Shavar 基础设施

alt_text

基础设施包括一个 Jenkins Pipeline，它构建实际的跟踪保护列表并将它们上传到 S3 存储桶。列表由 Shavar 服务提供给 Firefox 客户端，Shavar 服务运行在一个位于 Cloudfront 分发后面、自动扩展的 EC2 实例组上。

.ini 文件结构

shavar_list_creation.ini 文件用于配置 Mozilla Shavar 服务中跟踪保护和阻止列表的创建和管理。它包含多个部分，每个部分指定列表创建和上传过程的不同方面。

示例 .ini 文件：sample_shavar_list_creation.ini

[main] 部分

[main] 部分包含上传过程的常规配置设置。关键变量包括：

  • s3_upload：指示是否将输出上传到 S3 的布尔值。

  • remote_settings_upload：指示是否上传到远程设置的布尔值。

  • default_disconnect_url：默认 Disconnect 黑名单 JSON 的 URL。

其他部分的格式

shavar_list_creation.ini 文件中的其他部分配置特定的列表及其设置。这些部分通常遵循常见的格式，包括类别、输出文件名和版本控制要求的设置。

以下是如何构建这些部分的常规示例：

[section-name]
categories=Category1|Category2|Category3
output=output-filename
versioning_needed=true

  • categories：指定要包含的类别，用 | 分隔。

  • output：生成的数据文件的名称。

  • versioning_needed：指示是否需要版本控制的布尔值。

远程设置

远程设置 (RS) 用于管理 Firefox 中的常青数据，可以使用 API 访问这些数据，以便在客户端和服务器之间同步数据。您可以在此处找到更多相关信息：远程设置 — Firefox 源码文档

我们打算迁移 ETP 列表管理以利用 RS。好处包括：

  • 减少维护：RS 是一项现有的服务，拥有完善的工具和基础设施，从而减少了对专门的 Shavar 维护团队的需求。

  • GCP 集成：由于 RS 已经与 GCP 集成，因此无需额外的设置或团队即可进行云存储，并且无需从 aws 迁移到 gcp。

  • Shavar 弃用：转向 RS 允许完全弃用 Shavar，从而简化整体架构。

如何为远程设置运行 shavar-lists-creation 脚本

远程设置上传逻辑包含在 shavar-list-creation 存储库中。需要设置某些环境变量才能在本地运行这些脚本。

  1. 使用 export KEY=value 在您的终端或 bash/zshrc 文件中直接设置您的环境变量。

# The server locations are as follows
# dev: https://remote-settings-dev.allizom.org/v1
# stage: https://remote-settings.allizom.org/v1
# prod: https://remote-settings.mozilla.org/v1
export SERVER="server_location"

# For testing purposes, we use auth tokens, but the server uses userpass. To run locally, set the auth method to tokens
export REMOTE_SETTINGS_AUTH_METHOD="token"

# Get your auth token by logging into the server using single sign on, it will be of the format "Bearer token_string"
export AUTHORIZATION="Bearer your_token"

# Since this script is used for both shavar and remote settings, we need to set an execution environment. JENKINS is used for the shavar server, and GKE is used for remote settings. Since we are concerned with remote settings here, set it to GKE
export EXECUTION_ENVIRONMENT="GKE"

# Lastly, we want to set which server we are uploading to, make sure you set this based on the AUTHORIZATION and SERVER you have set
export ENVIRONMENT="dev"

  1. 设置这些环境变量后，我们可以直接运行脚本以上传到服务器。settings.py 代码将根据您要上传到的位置使用 rs_dev.ini、rs_stage.ini 或 rs_prod.ini 之一。这些 ini 文件已经启用了 rs 上传并禁用了 s3 上传。

python3 lists2safebrowsing.py

远程设置执行环境

这些脚本每天在 Google Cloud 服务器 (GKE) 上为每个环境（开发、测试和生产）运行。这些脚本会比较来自 shavar-prod-lists 的列表和已使用 chunknum 值上传的列表，并且仅在有新的更改时才会触发更新。

开发更改会在远程设置中自动更新，无需审阅者。测试和生产更改需要审阅者合并更改。当有新的更改时会发送电子邮件。

从 Shavar 迁移到远程设置

截至 2024 年 8 月，我们已进入从 Shavar 完全过渡到远程设置以向 Firefox 提供版本化列表的最后阶段。

但是，为了支持旧版本的 Firefox，需要在较长一段时间内支持 Shavar。

远程设置中的版本控制

远程设置通过在列表上使用 filter_expression 标记来实现版本控制。这些标记指示每个列表支持哪个版本的 Firefox。

工作原理

  1. 触发更新时，Firefox 客户端会收到所有远程设置列表。

  2. 获取后，每个客户端都会检索与其 filter_expression 匹配的特定列表。

这种方法确保每个 Firefox 版本都收到适合其功能和要求的适当列表。

维护 Nightly 版本

重要说明

shavar-prod-lists 存储库中的 master 分支提供了 Nightly 版本的列表。为了保持一致性并防止出现问题：

  • **不要**在更新 lists2safebrowsing.py 脚本之前为 Nightly 版本创建新分支。添加新分支可能会导致错误，因为该脚本使用 master 分支作为最新列表，这是 Nightly 版本使用的列表。

  • 确保 Nightly 列表的所有更改都正确反映在脚本中，以避免出现差异。

Shavar 的已知痛点

  • 频繁的构建错误：我们在构建过程中经常遇到错误，这在 shavar-ci 通道中得到了证明。调查和解决这些错误应成为优先事项，以确保发布工作流程顺利进行。

  • 版本控制规则不一致： 目前针对不同版本的代码分支遵循一套未记录的规则。这些规则需要被审查、标准化并记录下来，以消除混淆和潜在的错误。彻底的审查可以识别和解决系统诞生以来遗留的任何错误。

  • 版本控制系统不可验证： 当前系统缺乏验证版本控制过程完整性和准确性的机制。