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, 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 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:

{
  "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:

{
  "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.