威胁防护

威胁防护可让您的组织阻止 Firecrawl 访问高风险 URL。启用后，请求通过 API 将要获取的每个 URL——无论是抓取目标、搜索结果、爬取过程中发现的链接，还是代理的起始 URL——都会根据您组织的策略进行检查，未通过策略的 URL 会被拒绝访问。检查在 URL 级别进行：单个恶意页面可被封禁，而其所在站点的其余部分仍可访问；被标记的站点则会在所有页面上被封禁。

该策略只需在组织级别定义一次，便会自动应用到所有端点。您也可以允许按请求进行调整，或锁定该策略，使任何请求都无法削弱它。

威胁防护 提供三种模式，可在组织级别设置：

• 关闭 (默认值) — 不进行任何检查。
• 正常 — URL 会与 Google Web Risk 进行比对；该服务会标记与恶意软件、社会工程攻击 (网络钓鱼) 和有害软件相关的页面和网站。每扫描一个 URL 需消耗 +2 额度。
• Zscaler — URL 会与你组织自己的 Zscaler Internet Access (ZIA) 租户进行比对：包括你选择封禁的由 Zscaler 定义的 URL 类别，以及你的自定义 URL 类别和自定义 URL 列表。请参见下方的 Zscaler 模式。无需扫描费用 — 分类会在你自己的租户中进行。

这些检查旨在保护你的数据。在正常模式下，绝大多数请求都会基于定期同步的威胁列表在本地完成，因此你抓取的 URL 绝不会发送给分类器。在 Zscaler 模式下，URL 分类会在你自己的 ZIA 租户中进行 — 即已知晓你组织网页策略的同一系统。无论采用哪种模式，Firecrawl 都不会存储关于你流量的任何判定结果。

除了分类器外，策略还可以包含：

• 自定义黑名单 —— 始终封禁的精确域名或 glob (例如 *.example.com) ，无需调用分类器。
• 自定义白名单 —— 始终允许的精确域名或 glob。白名单优先于所有其他规则，因此你信任的域名绝不会被封禁。
• 封禁的 TLD —— 直接封禁的顶级域名 (例如 zip) ，按标签边界匹配。
• 风险评分阈值 —— 归一化分数 (0–100) ；达到或高于该分数时，分类器的判定会被视为封禁。数值越低，策略越严格。默认值为 75。适用于正常模式；Zscaler 模式则按类别封禁。
• 失败策略 —— 当无法访问分类器时的处理方式：封禁 (closed，默认值，也是安全控制场景下的推荐设置) 或 允许 (open) 。

自定义黑名单、白名单以及 blocked-TLD 规则都属于域名级别 —— 它们匹配的是被检查 URL 的主机；只有分类器会基于完整 URL 运行。你加入黑名单或白名单的自定义域名，会使用与分类器相同的主机规范化方式进行匹配，因此无法通过地址的其他编码形式 (例如整数形式的 IP) 绕过列表规则。

Zscaler 模式允许已在 ZIA 中维护 URL 策略的组织将这些策略应用于 Firecrawl 流量，无需维护一套平行的分类体系。两个层面协同工作：

• 内联分类 — 系统会通过您租户的 URL Lookup API 将 URL 归类到 Zscaler 定义的类别中；如果某个类别已被您拒绝，该类别中的 URL 将被封禁。
• 同步自定义规则 — 您的自定义 URL 类别 (URL 列表和关键字) 以及您添加到 Zscaler 定义类别中的内容，会按计划从租户同步，并由 Firecrawl 直接评估，因为 ZIA Lookup API 不会返回自定义分类结果。在 ZIA 中移除的条目会在下次同步时消失；您也可以在 Dashboard 中手动点击 立即同步。

这里承诺的是您的自定义列表加上您所选的 Zscaler 类别，而非“与您的 ZIA 策略完全一致”。ZIA 规则还可能依赖用户、组、位置、一天中的时间和请求上下文，而 Firecrawl 不会重现这些条件。自定义类别中的关键字规则会尽力匹配 (以不区分大小写的方式匹配 URL) ；URL 列表中的精确条目则仅会精确匹配。

团队管理员可在 Dashboard (见下文) 中使用 Zidentity OAuth 客户端连接租户：客户端 ID、客户端密钥以及您的 Zidentity 自定义域名。请使用权限范围限定为 URL Categories 的最小权限 API 角色。测试连接按钮会分别验证三项内容——凭据、分类体系访问权限和 URL Lookup 访问权限——因此，能够读取类别但无法对 URL 进行分类的角色会在设置时发现问题，而不会等到首次抓取时才暴露。客户端密钥为只写且静态加密；Zscaler 支持同时启用两个密钥，因此您可以无停机轮换密钥。

连接后，从租户自身的分类体系中选择要封禁的类别——选择器中会同时显示 Zscaler 定义的类别和自定义类别。

发往您租户的分类流量来自专用静态 IP，可将其加入允许列表；请向您的客户团队索取该地址。

ZIA 的 URL Lookup API 对每个租户限制为每秒 1 个请求、每小时 400 个请求。Firecrawl 会将查询请求批量处理 (每个请求最多包含 100 个 URL) ，并在整个租户范围内执行这些限制，因此持续分类吞吐量上限约为每秒 11 个 URL。抓取吞吐量绝不会被限流：当需求超过预算或每小时预算耗尽时，受影响的请求会立即按你的失败策略处理，而不会无限期排队。

与正常模式相比，端点层面有两项差异：

• Map 结果仅依据本地规则进行评估 (你的列表及已同步的自定义规则) ，不会内联分类——一次 map 可能返回数千个 URL，若逐一分类，会消耗每小时预算，而其中的链接可能永远不会被抓取。每个 URL 在开始抓取时仍会接受完整检查。
• Search 结果会内联分类，并移除被封禁的结果，与正常模式相同；每个唯一结果都会占用每小时查询预算。

裁决结果绝不会被缓存或存储 (所有模式均如此) ，因此 Zscaler 中的分类变更会在下一次请求时生效，自定义列表的变更则会在下次同步时生效。

团队管理员可在 Dashboard 的 Enterprise Controls → Threat Protection 中配置威胁防护：

1. 打开 Enterprise Controls → Threat Protection。
2. 选择一种模式，设置风险评分阈值，并添加黑名单、白名单或封禁的 TLD 条目。
3. 对于 Zscaler 模式：输入租户连接信息，运行连接测试，选择要封禁的类别，并设置同步间隔。
4. 选择是否允许单次请求覆盖，并设置失败策略。
5. 保存。更改会立即生效——下一个请求将按新策略进行评估。

只有团队管理员可以查看或修改此策略。其他人只能看到只读视图。

所有接受 URL 的端点也都支持可选的 threatProtection 对象，因此你可以针对单次请求收紧该次调用的策略 (或者，如果你的组织允许，也可以进行调整) ：

{
  "url": "https://example.com",
  "threatProtection": {
    "mode": "normal",
    "riskScoreThreshold": 50,
    "blacklist": ["*.risky.example"]
  }
}

覆盖项会按字段逐一合并到组织策略中。如果你的组织已禁用请求覆盖，任何包含 threatProtection 对象的请求都会被拒绝，并返回 403——这样管理员就能确保组织策略是每个请求都必须遵守的最低基线。

仅当组织已配置 Zscaler 连接时，覆盖项才能选择 "mode": "zscaler"；连接本身和拒绝类别的选择均属于组织级别，无法按请求设置。

如果你的团队已强制执行威胁防护，覆盖项仍然可以收紧策略，但不能包含 "mode": "off"——任何试图这样做的请求都会被拒绝，并返回 403。

被封禁的请求会以 403 失败，并返回一个固定的错误代码：

{
  "success": false,
  "code": "unsafe_domain_blocked",
  "error": "This URL (https://risky.example/landing) is blocked by your organization's threat protection policy (rule: blacklist). If you believe this is a mistake, contact your organization administrator to adjust the policy (e.g. whitelist the domain)."
}

不同端点的行为略有差异，会采用最实用的处理方式：

• Scrape, batch scrape, extract, 代理 — 被封禁的目标会针对该 URL 返回 unsafe_domain_blocked 错误。
• Crawl — 被封禁的种子 URL 会导致请求失败；在爬取过程中发现的被封禁链接会被跳过，爬取会继续。
• Search, map — 被封禁的 URL 会从返回结果中移除，而不是返回后再拒绝。

如果请求被重定向到其他 URL——包括站点内重定向到其他页面——系统会再次检查目标地址，并且绝不会返回来自被封禁目标地址的内容。对于 代理，该策略适用于起始 URL 以及代理通过 Firecrawl API 获取的所有内容；远程浏览器在页面内执行的导航不会被拦截。

在 正常 模式下，URL 扫描会在请求的基础成本之外，按每个扫描 URL 额外收取 +2 额度。Zscaler 模式不收取扫描费用：分类将在你自己的 ZIA 租户中运行，使用你的凭据和 API 配额，因此以下扫描费用说明仅适用于 正常 模式。补充说明如下：

• 如果判定完全基于你自己的策略 (黑名单、白名单或 blocked-TLD 匹配) ，则不会调用分类器，因此不会收取扫描费用。
• 即使请求被封禁，生成该判定结果的扫描仍会照常收费。
• 在单次抓取中，扫描会去重：如果重定向复检最终解析到同一个 URL，则会复用原始扫描；而落到不同 URL 的重定向则算作第二次扫描。
• 爬取和批量抓取会独立检查每个页面。判定结果绝不会在页面之间复用——不会存储任何与你的流量有关的信息 (见上文) ——因此在 正常 模式下，预计会按每个抓取页面额外 +2 额度收费。在抓取过程中发现并被封禁的链接，无论有多少页面链接到它，每次抓取都只会对其扫描收费一次。
• Search 和 map会在每次请求中对结果集里的每个唯一 URL 扫描一次，因此它们的扫描费用会随扫描结果数量增加——当结果因你的 limit 被截断时，这个数量可能会略高于最终返回的结果数。

• 该策略在整个组织范围内生效：会自动应用于每个 API 密钥和每个端点。
• 白名单始终优先生效，因此位于被明确设为受信任域名上的 URL 绝不会被分类器或 TLD 规则封禁。
• 错误代码 unsafe_domain_blocked 会保持稳定以确保兼容性，尽管检查是在 URL 级别进行的。
• 当失败策略设为 closed (默认值) 时，如果分类器发生故障，受影响的请求会被封禁，而不会被默认放行。
• 配置 SIEM Audit Logging 后，每项决策都会显示在您的审计跟踪中：事件会包含作出决策的规则、所查询的分类器、威胁类别，以及——对于由 Zscaler 分类的 URL——当该 URL 被归类为安全告警时的 security_alert 标志。