API de atualização da Navegação segura (v4)

Visão geral

A API Update permite que seus aplicativos clientes façam o download de versões em hash das listas da Navegação segura para em um banco de dados local. Os URLs podem ser verificados localmente. Somente se uma correspondência for encontrada no banco de dados local, o cliente precisará enviar uma solicitação aos servidores da Navegação segura para verificar se o URL está incluído nas listas de navegação segura.

Antes de usar a API Update, você precisa configurar um banco de dados local. A Navegação segura oferece uma o pacote Go que você pode usar para começar. Para mais detalhes, consulte a seção Configuração do banco de dados em Bancos de dados locais.

Como atualizar o banco de dados local

Para se manterem atualizados, os clientes precisam atualizar periodicamente as listas da Navegação segura nos próprios no banco de dados local. Para economizar largura de banda, os clientes fazem o download dos prefixos de hash dos URLs em vez dos URLs brutos. Por exemplo, se "www.badurl.com/" estiver em uma lista da Navegação segura, os clientes farão o download do prefixo de hash SHA256 desse URL em vez do próprio URL. Na maioria dos casos, o hash os prefixos têm 4 bytes, o que significa que o custo médio de largura de banda para fazer o download de uma única lista da entrada é de 4 bytes antes da compactação.

Para atualizar as listas da Navegação segura no banco de dados local, envie uma solicitação POST HTTP para o threatListUpdates.fetch :

• A solicitação HTTP POST inclui os nomes das listas a serem atualizadas junto com várias restrições do cliente para considerar as limitações de memória e largura de banda.
• A resposta HTTP POST retorna uma atualização completa ou parcial. A resposta pode também retornar um tempo de espera mínimo.

Exemplo: ThreatListUpdates.fetch

Solicitação POST HTTP

No exemplo a seguir, são solicitadas as atualizações de uma única lista do recurso Navegação segura.

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 API chave para API_KEY no URL.

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?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 de atualização (o nome da lista, o estado da lista e as restrições do cliente). Para mais detalhes, consulte o corpo da solicitação threatListUpdates.fetch e as explicações que seguem o exemplo de código.

{
  "client": {
    "clientId":       "yourcompanyname",
    "clientVersion":  "1.5.2"
  },
  "listUpdateRequests": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "state":           "Gg4IBBADIgYQgBAiAQEoAQ==",
    "constraints": {
      "maxUpdateEntries":      2048,
      "maxDatabaseEntries":    4096,
      "region":                "US",
      "supportedCompressions": ["RAW"]
    }
  }]
}

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 na geração de registros 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 (nomear) as listas de Navegação segura. No exemplo, uma lista é identificada: MALWARE/WINDOWS/URL. Antes de enviar uma solicitação, verifique se as combinações de tipos especificadas são válidas (consulte Listas do Navegação segura).

Estado do cliente

O campo state contém o estado atual do cliente da lista da Navegação segura. Os estados do cliente são retornados no campo newClientState da resposta threatListUpdates.fetch. Para atualizações iniciais, deixe o campo state vazio.

Restrições de tamanho

O campo maxUpdateEntries especifica o número total de atualizações que o cliente pode gerenciar (no exemplo, 2048). O campo maxDatabaseEntries especifica o número total de entradas que o local pode gerenciar (no exemplo, 4096). Os clientes precisam definir restrições de tamanho para proteger as limitações de memória e largura de banda e evitar o crescimento da lista. Para mais informações, consulte Atualizar restrições.

Compactação compatível

O campo supportedCompressions lista os tipos de compactação compatíveis com o cliente. No exemplo, o cliente suporta apenas dados brutos e não compactados. No entanto, a Navegação segura tem suporte tipos de compactação. Consulte Compactação.

Resposta HTTP POST

Neste exemplo, a resposta retorna uma atualização parcial da lista da Navegação segura usando o tipo de compactação solicitado.

Cabeçalho de resposta

O cabeçalho de resposta inclui o código de status HTTP e o tipo de conteúdo. Os clientes que recebem um código de status diferente de HTTP/200 precisam entrar no modo de espera Consulte Frequência da solicitação.

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

Corpo da resposta

O corpo da resposta inclui as informações de atualização (o nome da lista, o tipo de resposta, as adições e remoções a serem aplicadas ao banco de dados local, o novo estado do cliente e uma soma de verificação). No exemplo, a resposta também inclui uma duração mínima de espera. Para mais detalhes, consulte o corpo da resposta threatListUpdates.fetch e as explicações que seguem o exemplo de código.

{
  "listUpdateResponses": [{
    "threatType":      "MALWARE",
    "threatEntryType": "URL",
    "platformType":    "WINDOWS",
    "responseType" :   "PARTIAL_UPDATE",
    "additions": [{
      "compressionType": "RAW",
      "rawHashes": {
        "prefixSize": 4,
        "rawHashes":  "rnGLoQ=="
      }
    }],
    "removals": [{
      "compressionType": "RAW",
      "rawIndices": {
        "indices": [0, 2, 4]
      }
    }],
    "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
    "checksum": {
      "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
    }
  }],
  "minimumWaitDuration": "593.440s"
}

Atualizações do banco de dados

O campo responseType indica uma atualização parcial ou completa. No exemplo, uma atualização parcial é retornado, então a resposta inclui as adições e as remoções. Pode haver vários conjuntos de adições, mas apenas um conjunto de remoções (consulte Atualizações do banco de dados).

Novo estado do cliente

O campo newClientState contém o novo estado do cliente para a lista recém-atualizada da Navegação segura. Os clientes devem salvar o novo estado do cliente para solicitações de atualização subsequentes (o campo state na solicitaçãothreatListUpdates.fetch (em inglês) ou o campo clientStates na solicitação fullHashes.find).

Somas de verificação

A soma de verificação permite que os clientes verifiquem se o banco de dados local não foi corrompido. Se o a soma de verificação não corresponder, o cliente deverá limpar o banco de dados e emitir novamente uma atualização com uma state. No entanto, os clientes nessa situação ainda precisam seguir os intervalos de tempo para as atualizações. Consulte Frequência da solicitação.

Tempos de espera mínimos

O campo minimumWaitDuration indica que o cliente precisa aguardar 593,44 segundos (9,89 minutos) antes de enviar outra solicitação de atualização. Um período de espera pode ou não ser incluído no resposta (consulte Frequência de solicitação).

Como verificar URLs

Para verificar se um URL está em uma lista da Navegação segura, primeiro o cliente precisa calcular o hash e o prefixo de hash do URL. Consulte URLs e hash. Em seguida, o cliente consulta o banco de dados local para determinar se há uma correspondência. Se o prefixo de hash não estiver presente no banco de dados local, o URL será considerado seguro (não estará nas listas do recurso Navegação segura).

Se o prefixo de hash estiver presente no banco de dados local (uma colisão de prefixo de hash), o cliente precisará enviar o prefixo de hash aos servidores da Navegação segura para verificação. Os servidores retornam todos os hashes SHA 256 completos que contêm o prefixo de hash especificado. Se um desses hashes completos corresponder ao hash completo do URL em questão, o URL será considerado não seguro. Se nenhum dos hashes completos corresponder ao hash completo do URL em questão, esse URL será considerado seguro.

Em nenhum momento o Google aprende sobre os URLs que você está examinando. o Google aprende o hash prefixos de URLs, mas os prefixos hash não fornecem muitas informações sobre os URLs reais.

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

• A solicitação HTTP POST pode incluir até 500 entradas de ameaças.
• A solicitação HTTP POST inclui os prefixos hash dos URLs a serem verificados. Recomendamos que os clientes agrupem várias entradas de ameaças em uma única solicitação para reduzir o uso da largura de banda.
• A resposta HTTP POST retorna os hashes de comprimento total correspondentes, juntamente com as durações de cache positivas e negativas. A resposta também pode retornar um tempo de espera mínimo.

Exemplo: fullHashes.find

Solicitação POST HTTP

No exemplo a seguir, os nomes de duas listas da Navegação segura e três prefixos de hash são enviados para comparação e verificação.

Cabeçalho da solicitação

O cabeçalho da solicitação inclui o URL da solicitação 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/fullHashes: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), os estados do cliente e as informações da ameaça (os nomes da lista e os prefixos hash). Para solicitações JSON, os prefixos de hash precisam ser enviada em formato codificado em base64. Para mais detalhes, consulte a Corpo da solicitação fullHashes.find e as explicações que seguem o exemplo de código.

{
  "client": {
    "clientId":      "yourcompanyname",
    "clientVersion": "1.5.2"
  },
  "clientStates": [
    "ChAIARABGAEiAzAwMSiAEDABEAE=",
    "ChAIAhABGAEiAzAwMSiAEDABEOgH"
  ],
  "threatInfo": {
    "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes":    ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"hash": "WwuJdQ=="},
      {"hash": "771MOg=="},
      {"hash": "5eOrwQ=="}
    ]
  }
}

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 na geração de registros do lado do servidor. Você pode escolher qualquer nome para o ID do cliente, mas sugerimos que 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.

Todos os estados do cliente

O campo clientStates contém os estados do cliente para todas as listas do recurso Navegação segura no banco de dados local do cliente. Os estados do cliente são retornados no campo newClientState da resposta threatListUpdates.fetch.

Listas da Navegação segura

Os campos threatTypes, platformTypes e threatEntryTypes se combinam para identificar (nomear) 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 as combinações de tipo especificar são válidos (consulte Listas do Navegação segura).

Prefixos de hash de ameaças

A matriz ThreatEntries contém os prefixos hash dos URLs que você deseja verificar. O campo hash precisa conter o prefixo de hash exato que está presente no banco de dados local. Para exemplo, se o prefixo hash local tiver 4 bytes, a entrada da ameaça deverá ter 4 bytes. Se o prefixo de hash local tiver sido aumentado para 7 bytes, a entrada de ameaça precisará ter 7 bytes.

No exemplo, a solicitação inclui três prefixos de hash. Os três prefixos serão comparados em cada lista da Navegação segura para determinar se há um hash completo correspondente.

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

Resposta do POST HTTP

No exemplo abaixo, a resposta retorna os dados correspondentes, organizados por lista da Navegação segura, com as durações de cache e espera.

Cabeçalho de resposta

O cabeçalho da resposta inclui o código de status HTTP. e o tipo de conteúdo. Os clientes que recebem um código de status diferente de HTTP/200 precisam se afastar (consulte Frequência de solicitações).

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 hashes completos, os metadados, se disponíveis, e as durações do cache). No exemplo, o corpo da resposta também inclui uma duração mínima de espera. Para mais detalhes, consulte o corpo da resposta fullHashes.find e as explicações que seguem o exemplo de código.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
    },
    "threatEntryMetadata": {
      "entries": [{
        "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==",  // base64-encoded "malware_threat_type"
        "value": "TEFORElORw=="  // base64-encoded "LANDING"
       }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "SOCIAL_ENGINEERING",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
    },
    "threatEntryMetadata": {
      "entries": []
    },
    "cacheDuration": "300.000s"
  }],
  "minimumWaitDuration": "300.000s",
  "negativeCacheDuration": "300.000s"
}

Correspondências

O objeto Matches retorna um hash de comprimento total correspondente para dois dos prefixos de hash. Os URLs que correspondem a esses hashes são considerados não seguros. Nenhuma correspondência foi encontrada para o terceiro prefixo de hash, então nada é retornado. O URL correspondente a esse prefixo de hash é considerado seguro.

Observe que este exemplo corresponde um hash completo a um prefixo de hash. é possível, no entanto, vários hashes completos que são mapeados para o mesmo prefixo de hash.

Metadados

O campo threatEntryMetadata é opcional e fornece mais informações sobre a correspondência de ameaças. No momento, os metadados estão disponíveis para a lista MALWARE/WINDOWS/URL Safe Browsing. Consulte Metadados.

Durações de cache

Os campos cacheDuration e negativeCacheDuration indicam o tempo de validade dos hashes, que pode ser considerado seguro ou não seguro (consulte Armazenamento em cache).

Tempos de espera mínimos

O campo minimumWaitDuration indica que o cliente precisa aguardar 300 segundos (5 minutos) antes enviando outra solicitação fullHashes. Um período de espera pode ou não ser incluído na resposta. Consulte Frequência da solicitação.