Como usar a API Submission

Neste documento, descrevemos como enviar URLs que você suspeita serem inseguros para o Navegação segura para análise e verificar de forma assíncrona os resultados desses envios. Todos os URLs confirmados para violar as Políticas de navegação segura são adicionados ao serviço Navegação segura.

Antes de começar

Entre em contato com a equipe de vendas ou com o engenheiro de clientes para ter acesso a esse recurso.

Práticas recomendadas

Leia as políticas de navegação segura.

A API Web Risk Submission valida se os URLs enviados renderizam conteúdo que viola as políticas da Navegação segura. Os desenvolvedores de API precisam garantir que os URLs enviados tenham evidências claras de violação dessas políticas. Os exemplos a seguir mostram evidências de violação das políticas:

  • Conteúdo de engenharia social que imita uma marca on-line legítima (nome da marca, logotipo, aparência), alertas do sistema, usa URLs enganosos ou pede que os usuários insiram credenciais sensíveis, como nome de usuário ou senha.
  • Um site que hospeda um executável de malware conhecido.

Não envie os seguintes tipos de URLs porque é improvável que eles sejam adicionados à lista de bloqueio da Navegação segura:

  • Pesquisas falsas, sites de compras ou outros golpes que não demonstram phishing (como golpes de criptomoedas).
  • Spam com jogos de azar, violência ou conteúdo adulto que não seja phishing ou malware.

Melhorar detecção

Recomendamos usar os campos ThreatInfo e ThreatDiscovery para fornecer mais informações sobre os envios. Isso pode ajudar a melhorar a detecção. Para mais informações, consulte Práticas recomendadas para usar a API Submission.

Taxonomia e segmentação por marca

Você pode fornecer denúncias de abuso mais precisas e detalhadas usando os seguintes componentes opcionais no objeto ThreatInfo: abuseSubtype e targetedBrand. Esses campos ajudam o Web Risk a analisar com mais precisão as entidades segmentadas e melhorar os modelos de detecção.

abuseSubtype

O campo abuseSubtype oferece uma classificação granular da ameaça. Verifique se esse campo está definido apenas quando o abuseType principal é SOCIAL_ENGINEERING. Caso contrário, um erro será retornado.

Os valores abuseSubtype compatíveis incluem:

  • BANK_PHISHING: phishing que se passa por um banco ou uma entidade financeira confiável.
  • CRYPTO_EXCHANGE_PHISHING: phishing que se passa por uma plataforma de negociação de criptomoedas.
  • SOCIAL_MEDIA_PLATFORM_PHISHING: phishing que se passa por uma rede social.
  • RETAIL_PHISHING: phishing se passando por uma plataforma de varejo estabelecida.
  • EMAIL_PROVIDER_PHISHING: phishing se passando por um serviço de e-mail.
  • ENTERTAINMENT_PHISHING: phishing se passando por um serviço de entretenimento.
  • GOVERNMENT_AGENCY_PHISHING: phishing se passando por um órgão governamental para obter informações de identificação pessoal (PII), como um número de CPF ou CNPJ.
  • PACKAGE_TRACKING_SCAM: imitar um serviço de frete para obter PII ou detalhes de pagamento.
  • FAKE_SUPPORT_SCAM: sites enganosos que alegam problemas falsos no dispositivo para enganar os usuários e fazer com que eles compartilhem informações de identificação pessoal ou entrem em contato com golpistas.
  • GOVERNMENT_FINE_SCAM: conteúdo enganoso afirmando que uma multa civil pendente precisa ser paga.
  • FAKE_PRIZE_SCAM: páginas enganosas que oferecem recompensas ou prêmios irreais.
  • OTHER_PHISHING / OTHER_SCAM: ataques de engenharia social que não pertencem às outras categorias mencionadas aqui.

targetedBrand

O objeto targetedBrand identifica a entidade visada por campanhas de phishing e engenharia social.

  • brandName: o nome reconhecível da marca ou empresa que está sendo representada (por exemplo, Altostrat).
  • domain: o domínio legítimo da marca que está sendo falsificada (por exemplo, altostrat.com).

Observações importantes para participantes da prévia

  • Consistência na taxonomia: o phishing continua categorizado no tipo de ameaça SOCIAL_ENGINEERING (em vez de um tipo principal PHISHING separado) para garantir a consistência em todo o conjunto de APIs Web Risk e Navegação Segura.
  • Categorias excluídas: as subcategorias de MALWARE e UNWANTED_SOFTWARE foram excluídas desta versão.
  • Como lidar com ameaças não listadas: se a sua denúncia não se encaixar em um subtipo específico, use OTHER_PHISHING ou OTHER_SCAM. Recomendamos usar o campo comments em ThreatJustification para descrever o ataque.
  • Opcional, mas recomendado: o preenchimento desses campos ajuda a Web Risk a priorizar e melhorar os modelos de inteligência contra ameaças associados.
  • Fase de prévia: os valores de enumeração e o comportamento desse recurso estão sujeitos a mudanças.

Enviar URLs

Para enviar um URL, envie uma solicitação HTTP POST ao método projects.uris.submit.

  • A API Submission é compatível com um URL por solicitação. Para verificar vários URLs, você precisa enviar uma solicitação separada para cada URL.

  • O URL precisa ser válido, mas não precisa ser canonizado. Para saber, consulte a RFC 46485 (em inglês).

  • A resposta HTTP POST retorna um long-running operation. Para mais informações sobre como recuperar o resultado do envio e verificar o status de um envio, consulte Operações de longa duração.

Exemplo

Método HTTP e URL:

POST https://webrisk.googleapis.com/v1/projects/project-id/uris:submit

Corpo JSON da solicitação:

{
  "submission": {
    "uri": "https://www.example.com/login.html"
  }
}

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://webrisk.googleapis.com/v1/projects/project-id/uris:submit"

PowerShell

Salve o corpo da solicitação em um arquivo com o nome request.json e execute o comando abaixo: 

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://webrisk.googleapis.com/v1/projects/project-id/uris:submit" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "name": "projects/project-number/operations/operation-id",
}

Verificar o status do envio

Use project-number e operation-id da resposta para verificar o status do envio. O status está localizado no campo metadata.state da operação retornada.

Os estados possíveis incluem RUNNING, SUCCEEDED e CLOSED. Para mais informações sobre esses estados, consulte Como entender o status da operação no guia de operações de longa duração.