> ## 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.
# 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 três 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.**
* **Zscaler** — as URLs são verificadas no tenant do [Zscaler Internet Access](https://www.zscaler.com/products-and-solutions/zscaler-internet-access) (ZIA) da sua organização: as categorias de URL definidas pela Zscaler que você optar por bloquear, além das suas categorias de URL e listas de URLs personalizadas. Consulte o [modo Zscaler](#zscaler-mode) abaixo. **Sem taxas de verificação** — a classificação é feita no seu próprio tenant.
As verificações foram projetadas para proteger seus dados. No modo Normal, a grande maioria das requisições é 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. No modo Zscaler, a classificação de URLs ocorre no seu próprio tenant ZIA — o mesmo sistema que já aplica a política web da sua organização. Em todos os modos, 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`. Aplica-se ao modo Normal; o modo Zscaler bloqueia por categoria.
* **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.
## Modo Zscaler
O modo Zscaler permite que organizações que já mantêm políticas de URL no ZIA as apliquem ao tráfego do Firecrawl, sem precisar manter uma taxonomia paralela. Dois mecanismos trabalham em conjunto:
* **Classificação em linha** — as URLs são classificadas pela API URL Lookup do seu tenant em categorias definidas pela Zscaler, e URLs em categorias que você bloqueou são bloqueadas.
* **Regras personalizadas sincronizadas** — suas categorias de URL personalizadas (listas de URLs e palavras-chave) e suas adições a categorias definidas pela Zscaler são sincronizadas do tenant de acordo com um agendamento e avaliadas diretamente pelo Firecrawl, pois a API de consulta do ZIA não retorna classificações personalizadas. Entradas removidas no ZIA desaparecem na próxima sincronização; a opção manual **Sincronizar agora** está disponível no painel.
A proposta é **suas listas personalizadas mais as categorias Zscaler selecionadas** — não "idêntico à sua política do ZIA". As regras do ZIA também podem depender de usuários, grupos, locais, horário e contexto da solicitação, que o Firecrawl não reproduz. As regras de palavras-chave em categorias personalizadas são avaliadas da melhor forma possível (correspondência sem diferenciação entre maiúsculas e minúsculas com a URL); entradas exatas em listas de URLs têm correspondência exata.
### Conecte seu tenant
Administradores da equipe conectam o tenant pelo painel (veja abaixo) usando um [cliente OAuth do Zidentity](https://help.zscaler.com/oneapi/understanding-oneapi): ID do cliente, segredo do cliente e seu domínio personalizado do Zidentity. Use uma função de API com privilégios mínimos restrita a Categorias de URL. O botão **Testar conexão** verifica separadamente três itens — as credenciais, o acesso à taxonomia e o acesso à Consulta de URL — para identificar, durante a configuração, uma função que pode ler categorias, mas não classificar URLs, em vez de apenas no primeiro scraping. O segredo do cliente é somente para gravação e é criptografado em repouso; o suporte da Zscaler a dois segredos ativos permite rotacioná-los sem tempo de inatividade.
Após conectar, escolha na taxonomia do próprio tenant as categorias a bloquear — categorias definidas pela Zscaler e categorias personalizadas aparecem no seletor.
O tráfego de classificação para o tenant é originado de um IP estático dedicado para inclusão na allowlist; solicite o endereço à equipe responsável pela sua conta.
### Capacidade e comportamento
A API URL Lookup do ZIA permite 1 solicitação por segundo e 400 solicitações por hora por tenant. O Firecrawl agrupa as consultas em lotes (de até 100 URLs por solicitação) e aplica esses limites a todo o tenant, proporcionando uma capacidade sustentada de classificação de cerca de 11 URLs por segundo. O throughput do seu scraping nunca é limitado: quando a demanda excede o orçamento ou o orçamento por hora se esgota, as solicitações afetadas são resolvidas imediatamente de acordo com sua política de falha, em vez de ficarem na fila indefinidamente.
Duas diferenças em relação ao modo Normal no nível do endpoint:
* **Os resultados de Map são avaliados apenas com base em regras locais** (suas listas e regras personalizadas sincronizadas), em vez de serem classificados em linha — um map pode retornar milhares de URLs, e classificá-las consumiria o orçamento por hora com links que talvez nunca sejam buscados. Cada URL ainda passa pela verificação completa quando seu scraping é iniciado.
* **Os resultados de busca são classificados em linha**, e os resultados bloqueados são removidos, como no modo Normal; cada resultado único consome o orçamento de consultas por hora.
Os vereditos nunca são armazenados em cache nem salvos (como em todos os modos), portanto, uma mudança de classificação no Zscaler é aplicada já na próxima solicitação, e mudanças em listas personalizadas são aplicadas na próxima sincronização.
## 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. Para o modo Zscaler: insira a conexão do tenant, execute o teste de conexão, escolha as categorias a bloquear e defina o intervalo de sincronização.
4. Escolha se deseja permitir substituições por requisição e defina a política de falha.
5. 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.
Uma substituição poderá selecionar `"mode": "zscaler"` somente quando a organização tiver uma conexão Zscaler configurada; a própria conexão e a seleção de categorias negadas são definidas no nível da organização e não podem ser configuradas por requisição.
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
No modo Normal, uma verificação custa **+2 créditos por URL verificada**, além do custo base da requisição. **O modo Zscaler não tem taxas de verificação**: a classificação é executada no seu próprio tenant ZIA, com suas credenciais e sua cota de API, portanto, os detalhes sobre taxas de verificação abaixo se aplicam apenas ao modo Normal. 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 verificação.
* Uma requisição bloqueada ainda é cobrada pela verificação que gerou o veredito.
* As verificações são deduplicadas dentro de um único scraping: uma reverificação de redirecionamento que resolve para a mesma URL compartilha a verificação original, enquanto um redirecionamento que chega a uma URL diferente é uma segunda verificação.
* **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 verificação 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 verificação 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` | Uma substituição de `threatProtection` seleciona `mode: "zscaler"` enquanto a organização não tem uma conexão Zscaler configurada. |
| `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.
* Com o [SIEM Audit Logging](/pt-BR/features/siem) configurado, cada decisão fica visível na sua trilha de auditoria: os eventos incluem a regra que determinou a decisão, o classificador consultado, as categorias de ameaça e — para URLs classificadas pelo Zscaler — uma sinalização `security_alert` quando a URL recebeu uma classificação de alerta de segurança.