> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-u6tgua.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 威胁防护

> 通过由您的组织控制的策略，在所有端点上封禁对高风险 URL 的请求，并在服务端强制执行。

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

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

<Note>
  威胁防护是一项企业版功能，按组织开通。如需为您的账户启用此功能，请联系您的 Firecrawl 账户团队。
</Note>

<div id="modes">
  ## 模式
</div>

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

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

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

<div id="policy-controls">
  ## 策略控制
</div>

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

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

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

<div id="zscaler-mode">
  ## Zscaler 模式
</div>

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 列表中的精确条目则仅会精确匹配。

<div id="connecting-your-tenant">
  ### 连接您的租户
</div>

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

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

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

<div id="capacity-and-behavior">
  ### 容量和行为
</div>

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

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

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

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

<div id="configuring-the-policy">
  ## 配置策略
</div>

团队管理员可在 Dashboard 的 [Enterprise Controls → Threat Protection](https://www.firecrawl.dev/app/enterprise-controls?tab=threat-protection) 中配置威胁防护：

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

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

<div id="per-request-overrides">
  ## 单次请求覆盖
</div>

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

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

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

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

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

<div id="when-a-url-is-blocked">
  ## 当 URL 被封禁时
</div>

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

```json theme={null}
{
  "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 获取的所有内容；远程浏览器在页面内执行的导航不会被拦截。

<div id="billing">
  ## 计费
</div>

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

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

<div id="error-reference">
  ## 错误参考
</div>

| 状态    | 何时出现                                                         |
| ----- | ------------------------------------------------------------ |
| `403` | 请求的目标 URL 被策略封禁 (`code: unsafe_domain_blocked`)。             |
| `403` | 请求包含 `threatProtection` 覆盖，但该组织已禁用覆盖设置。                      |
| `403` | 团队强制启用威胁防护时，`threatProtection` 覆盖将 `mode: "off"`。            |
| `403` | 团队强制启用威胁防护时，组织策略被更新为 `mode: "off"`。                          |
| `403` | 在未启用该功能的团队中使用了威胁防护选项。                                        |
| `403` | 组织未配置 Zscaler 连接时，`threatProtection` 覆盖选择 `mode: "zscaler"`。 |
| `403` | 团队强制启用威胁防护时调用了已弃用的 v0 端点 (v0 不支持威胁防护) 。                      |

<div id="notes">
  ## 说明
</div>

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