API Safe Browsing Lookup (v4)

Visão geral

A API Lookup permite que seus aplicativos clientes enviem solicitações para a Navegação segura para verificar se os URLs estão incluídos em alguma das listas do Navegação segura. Se um URL for encontrado em uma ou mais listas, as informações correspondentes são retornadas.

Como verificar URLs

Para verificar se um URL está na lista do recurso Navegação segura, envie uma solicitação POST HTTP para o threatMatches.find :

• A solicitação HTTP POST pode incluir até 500 URLs. Os URLs precisam ser válidos Consulte RFC 2396 (em inglês). mas não precisam ser canonizados ou codificados.
• A resposta HTTP POST retorna os URLs correspondentes e a duração do cache.

Exemplo: ThreatMatches.find

Solicitação POST HTTP

No exemplo a seguir, duas listas de Navegação segura e três URLs são enviados ao servidor para determinar se há uma correspondência.

Cabeçalho da solicitação

O cabeçalho da solicitação inclui o URL e o tipo de conteúdo. Lembre-se de substituir a chave de API para API_KEY no URL.

  POST https://safebrowsing.googleapis.com/v4/threatMatches:find?key=API_KEY HTTP/1.1
  Content-Type: application/json
  

Corpo da solicitação

O corpo da solicitação inclui as informações do cliente (ID e versão) e as informações sobre a ameaça (os nomes das listas e os URLs). Para mais detalhes, consulte a Corpo da solicitaçãothreatMatches.find e as explicações que seguem o exemplo de código.

  {
    "client": {
      "clientId":      "yourcompanyname",
      "clientVersion": "1.5.2"
    },
    "threatInfo": {
      "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
      "platformTypes":    ["WINDOWS"],
      "threatEntryTypes": ["URL"],
      "threatEntries": [
        {"url": "http://www.urltocheck1.org/"},
        {"url": "http://www.urltocheck2.org/"},
        {"url": "http://www.urltocheck3.com/"}
      ]
    }
  }

Informações do cliente

Os campos clientID e clientVersion devem identificar exclusivamente uma implementação do cliente, não um para um usuário individual. (As informações do cliente são usadas para registro e contabilidade do lado do servidor. Você pode escolher qualquer nome para o ID do cliente, mas sugerimos que você escolha um nome que represente a verdadeira identidade do cliente, como o nome da sua empresa, apresentado como uma única palavra, em letras minúsculas.)

Listas do Navegação segura

Os campos threatType, platformType e threatEntryType são combinados para identificar (nomes) as listas de Navegação segura. No exemplo, duas listas são identificadas: MALWARE/WINDOWS/URL e SOCIAL_ENGINEERING/WINDOWS/URL. Antes de enviar uma solicitação, verifique se o tipo as combinações que você especificar são válidas. Consulte Listas de Navegação segura.

URLs de ameaças

No exemplo, a matriz threatEntries contém três URLs (urltocheck1.org, urltocheck2.org, e urltocheck3.org) que serão comparados às duas listas do Navegação segura.

Observação:a API Lookup e o método threatMatches sempre precisam usar o campo URL, nunca o campo hash (consulte ThreatEntry).

Resposta do POST HTTP

No exemplo a seguir, a resposta retorna uma correspondência. dois dos três URLs especificados solicitação forem encontradas em uma das duas listas da Navegação segura especificadas na solicitação.

Cabeçalho de resposta

O cabeçalho da resposta inclui o código de status HTTP. e o tipo de conteúdo.

HTTP/1.1 200 OK
Content-Type: application/json

Corpo da resposta

O corpo da resposta inclui as informações de correspondência (os nomes da lista e os URLs encontrados nos essas listas, os metadados, se disponíveis, e as durações do cache). Para mais detalhes, consulte a corpo da respostathreatMatches.find e as explicações que seguem o exemplo de código.

Observação:se não houver correspondências (ou seja, se nenhum dos URLs especificados for encontrada em qualquer uma das listas especificadas em uma solicitação), a resposta HTTP POST simplesmente retorna um objeto vazio no corpo da resposta.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck1.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key": "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck2.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key":   "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }]
}

Correspondências

O objeto matches lista os nomes das listas da Navegação segura e os URLs, se existe correspondência. No exemplo, dois URLs (urltocheck1.org e urltocheck2.org) foram encontrados em uma das listas de Navegação segura (MALWARE/WINDOWS/URL) para que as informações correspondentes sejam retornadas. O terceiro URL (urltocheck3.org) não foi encontrado em nenhuma das listas, por isso nenhuma informação é retornada para este URL.

Metadados

O campo threatEntryMetadata é opcional e fornece informações adicionais sobre a correspondência de ameaça. Atualmente, os metadados estão disponíveis para a lista de Navegação segura do MALWARE/WINDOWS/URL (consulte Metadados).

Durações de cache

O campo cacheDuration indica por quanto tempo o URL precisa ser considerado não seguro. (consulte Armazenamento em cache).