> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Proteção contra ameaças
> Bloqueie requests para URLs arriscadas em todos os endpoints usando uma política controlada pela sua organização. Aplicado no servidor.
A Proteção contra ameaças permite que sua organização impeça o Firecrawl de acessar URLs arriscadas. Quando ela está habilitada, toda URL que uma request tentaria buscar por meio da API — um alvo `scrape`, um resultado de busca, um link descoberto durante um rastreamento, a URL inicial de um agente — é verificada de acordo com a política da sua organização, e URLs que não estiverem em conformidade com a política são bloqueadas. As verificações ocorrem no nível da URL: uma única página maliciosa pode ser bloqueada enquanto o restante do site continua acessível, e um site sinalizado é bloqueado em todas as páginas.
A política é definida uma única vez no nível da organização e se aplica automaticamente a todos os endpoints. Você também pode permitir ajustes por request ou bloquear a política para que nenhuma request possa enfraquecê-la.
A Proteção contra ameaças é um recurso enterprise e é disponibilizada por organização. Entre em contato com a equipe da sua conta Firecrawl para habilitá-la na sua conta.
## Modos
A Proteção contra ameaças tem dois modos, definidos no nível da organização:
* **Desativado** (padrão) — nenhuma verificação é realizada.
* **Normal** — as URLs são verificadas com base no [Google Web Risk](https://cloud.google.com/web-risk), que sinaliza páginas e sites associados a malware, engenharia social (phishing) e software indesejado. **+2 créditos por URL verificada.**
As verificações foram projetadas para proteger seus dados: na grande maioria das requisições, a verificação é resolvida localmente com base em uma lista de ameaças sincronizada regularmente, então as URLs coletadas por scraping nunca são enviadas ao classificador, e nenhum veredito sobre o seu tráfego é armazenado pelo Firecrawl.
## Controles da política
Além do classificador, uma política pode incluir:
* **Lista de bloqueio personalizada** — domínios exatos ou globs (por exemplo, `*.example.com`) que são sempre bloqueados, sem chamar o classificador.
* **Lista de permissões personalizada** — domínios exatos ou globs que são sempre permitidos. A lista de permissões prevalece sobre todas as outras regras, então um domínio em que você confia nunca é bloqueado.
* **TLDs bloqueados** — domínios de nível superior bloqueados diretamente (por exemplo, `zip`), com correspondência nos limites dos rótulos.
* **Limite de pontuação de risco** — a pontuação normalizada (0–100) a partir da qual um veredito do classificador é tratado como bloqueio. Quanto menor, mais rigoroso. O padrão é `75`.
* **Política de falha** — o que fazer quando o classificador não puder ser acessado: **bloquear** (`closed`, o padrão e recomendado para um controle de segurança) ou **permitir** (`open`).
As regras de lista de bloqueio personalizada, lista de permissões e TLDs bloqueados são de nível de domínio — elas correspondem ao host da URL verificada; apenas o classificador opera em URLs completas. Os domínios personalizados que você adiciona à lista de bloqueio ou à lista de permissões são comparados usando a mesma normalização canônica de host do classificador, portanto codificações alternativas de um endereço (por exemplo, um IP em formato inteiro) não podem ser usadas para contornar uma entrada da lista.
## Configurando a política
Os administradores da equipe configuram a Proteção contra Ameaças em [Controles empresariais → Proteção contra Ameaças](https://www.firecrawl.dev/app/enterprise-controls?tab=threat-protection) no painel:
1. Abra **Controles empresariais → Proteção contra Ameaças**.
2. Escolha um modo, defina o limite de pontuação de risco e adicione entradas à lista de bloqueio, à lista de permissões ou TLDs bloqueados.
3. Escolha se deseja permitir substituições por requisição e defina a política em caso de falha.
4. Salve. As mudanças entram em vigor imediatamente — a próxima requisição será avaliada de acordo com a nova política.
Somente os administradores da equipe podem ver ou alterar a política. Todos os demais veem uma visualização somente leitura.
## Substituições por requisição
Todo endpoint que aceita URLs também aceita um objeto `threatProtection` opcional, para que uma requisição específica possa reforçar (ou, se sua organização permitir, ajustar) a política dessa chamada:
```json theme={null}
{
"url": "https://example.com",
"threatProtection": {
"mode": "normal",
"riskScoreThreshold": 50,
"blacklist": ["*.risky.example"]
}
}
```
As substituições são mescladas à política da organização, campo por campo. Se a sua organização tiver **desativado as substituições por requisição**, qualquer requisição que inclua um objeto `threatProtection` será rejeitada com `403` — isso permite que um administrador garanta que a política da organização seja o nível mínimo para todas as requisições.
Se a Proteção contra ameaças for **obrigatória** para a sua equipe, uma substituição ainda poderá reforçar a política, mas não poderá incluir `"mode": "off"` — uma requisição que tente fazer isso será rejeitada com `403`.
## Quando uma URL é bloqueada
Uma requisição bloqueada retorna `403` e um código de erro estável:
```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)."
}
```
O comportamento varia ligeiramente conforme o endpoint, de acordo com o que for mais útil:
* **Scraping, extração em lote, extração, agente** — um alvo bloqueado retorna o erro `unsafe_domain_blocked` para essa URL.
* **Rastreamento** — uma URL inicial bloqueada faz a solicitação falhar; links bloqueados descobertos durante o rastreamento são ignorados, e o rastreamento continua.
* **Busca, mapeamento** — URLs bloqueadas são removidas dos resultados retornados, em vez de serem exibidas e recusadas.
Se uma solicitação for redirecionada para uma URL diferente — incluindo um redirecionamento no mesmo site para uma página diferente — o destino será verificado novamente, e o conteúdo de um destino bloqueado nunca é retornado. Para **agente**, a política cobre as URLs iniciais e tudo o que o agente busca por meio da API do Firecrawl; navegações que o navegador remoto realiza dentro de uma página não são interceptadas.
## Cobrança
Uma varredura custa **+2 créditos por URL verificada** no modo Normal, além do custo base da requisição. Alguns detalhes:
* Decisões tomadas inteiramente com base na sua própria política (correspondências com lista de bloqueio, lista de permissões ou TLDs bloqueados) não acionam o classificador e **não** geram cobrança de taxa de varredura.
* Uma requisição bloqueada ainda é cobrada pela varredura que gerou o veredito.
* As varreduras são deduplicadas dentro de um único scraping: uma reverificação de redirecionamento que resolve para a mesma URL compartilha a varredura original, enquanto um redirecionamento que chega a uma URL diferente é uma segunda varredura.
* **Rastreamentos e extrações em lote verificam cada página de forma independente.** Os vereditos nunca são reutilizados entre páginas — nada sobre o seu tráfego é armazenado (veja acima) — portanto, no modo Normal, espere **+2 créditos por página extraída**. Um link descoberto durante o rastreamento e bloqueado tem a varredura cobrada uma vez por rastreamento, não importa quantas páginas apontem para ele.
* **Busca e mapeamento** verificam cada URL única no conjunto de resultados uma vez por requisição, então as taxas de varredura aumentam conforme o número de resultados verificados — o que pode exceder ligeiramente o número retornado quando os resultados são limitados ao seu `limit`.
## Referência de erros
| Status | Quando |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `403` | Uma requisição visa uma URL bloqueada pela política (`code: unsafe_domain_blocked`). |
| `403` | Uma requisição inclui uma substituição de `threatProtection` enquanto as substituições estão desabilitadas para a organização. |
| `403` | Uma substituição de `threatProtection` define `mode: "off"` enquanto a Proteção contra ameaças é obrigatória para a equipe. |
| `403` | A política da organização é atualizada com `mode: "off"` enquanto a Proteção contra ameaças é obrigatória para a equipe. |
| `403` | As opções de Proteção contra ameaças são usadas em uma equipe sem o recurso habilitado. |
| `403` | Um endpoint v0 descontinuado é chamado enquanto a Proteção contra ameaças é obrigatória para a equipe (v0 não oferece suporte à Proteção contra ameaças). |
## Observações
* A política vale para toda a organização: ela se aplica automaticamente a cada chave de API e a cada endpoint.
* A lista de permissões sempre prevalece, então uma URL em um domínio explicitamente confiável nunca é bloqueada pelo classificador nem por uma regra de TLD.
* O código de erro `unsafe_domain_blocked` é mantido estável por compatibilidade, embora as verificações ocorram no nível da URL.
* Com a política de falha definida como `closed` (o padrão), uma indisponibilidade do classificador faz com que as solicitações afetadas sejam bloqueadas, em vez de serem permitidas silenciosamente.