API Safe Browsing Lookup (v4)

Informações gerais

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

Como verificar URLs

Para verificar se um URL está em uma lista da Navegação segura, envie uma solicitação HTTP POST para o método threatMatches.find:

• A solicitação HTTP POST pode incluir até 500 URLs. Os URLs precisam ser válidos (consulte a RFC 2396), mas não precisam ser canonizados ou codificados.
• A resposta HTTP POST retorna os URLs correspondentes junto com a duração do cache.

Exemplo: threatMatches.find

Solicitação HTTP POST

No exemplo a seguir, duas listas do 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 sua chave de API por 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 da ameaça (os nomes da lista e os URLs). Para mais detalhes, consulte o corpo da solicitação threatMatches.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 precisam identificar exclusivamente uma implementação do cliente, não um usuário individual. As informações do cliente são usadas para geração de registros e contabilidade do lado do servidor. É possível escolher qualquer nome para o ID do cliente, mas sugerimos que você escolha um que represente a verdadeira identidade do cliente, como o nome da sua empresa, apresentado como uma única palavra, em letras minúsculas.

Listas da Navegação segura

Os campos threatType, platformType e threatEntryType são combinados para identificar (nomear) as listas do 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 as combinações de tipo especificadas são válidas. Consulte Listas do Navegação segura.

URLs da ameaça

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

Observação:a API Lookup e o método threatMatches sempre precisam usar o campo URL, e não o campo hash. Consulte ThreatEntry.

Resposta HTTP POST

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

Cabeçalho de resposta

O cabeçalho de 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 das listas e os URLs encontrados nessas listas, os metadados, se disponíveis, e as durações do cache. Para mais detalhes, consulte o corpo da resposta threatMatches.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 na solicitação for encontrado em qualquer uma das listas especificadas em uma solicitação, a resposta HTTP POST retornará 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 do Navegação segura e os URLs, se houver correspondência. No exemplo, dois URLs (urltocheck1.org e urltocheck2.org) foram encontrados em uma das listas da Navegação segura (MALWARE/WINDOWS/URL), então as informações correspondentes são retornadas. O terceiro URL (urltocheck3.org) não foi encontrado em nenhuma das listas. Portanto, nenhuma informação é retornada para esse URL.

Metadados

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

Durações do cache

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