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

Informações gerais

Com a API Update, os aplicativos clientes podem fazer o download de versões em hash das listas da Navegação segura para armazenamento 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 da Navegação segura.

Antes de usar a API Update, você precisa configurar um banco de dados local. O Navegação segura oferece um 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 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 do 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, os prefixos de hash têm 4 bytes, o que significa que o custo médio da largura de banda para fazer o download de uma única entrada da lista é de 4 bytes antes da compactação.

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

• A solicitação HTTP POST inclui os nomes das listas a serem atualizadas, além de várias restrições de 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 também pode retornar uma duração mínima de espera.

Exemplo: threatListUpdates.fetch

Solicitação HTTP POST

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

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/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 de atualização (o nome, o estado 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 precisam identificar exclusivamente uma implementação do cliente, não um usuário individual. As informações do cliente são usadas na geração de registros do servidor. É possível 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 da Navegação segura

Os campos threatType, platformType e threatEntryType são combinados para identificar (nomear) as listas do Navegação segura. No exemplo, uma lista é identificada: MALWARE/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.

Estado do cliente

O campo state contém o estado atual do cliente da lista do recurso 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 banco de dados local pode gerenciar (no exemplo, 4.096). Os clientes precisam definir restrições de tamanho para proteger as limitações de memória e largura de banda e contra o crescimento da lista. Para mais informações, consulte Restrições de atualização.

Compactação compatível

O campo supportedCompressions lista os tipos de compactação com suporte do cliente. No exemplo, o cliente aceita apenas dados brutos e descompactados. No entanto, o recurso Navegação segura é compatível com outros tipos de compactação. Consulte Compactação.

Resposta HTTP POST

Neste exemplo, a resposta retorna uma atualização parcial para a 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 (em inglês) 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 é retornada, de modo que a resposta inclui adições e remoções. Pode haver vários conjuntos de adições, mas apenas um conjunto de remoções (consulte Atualizações de banco de dados).

Estado do novo cliente

O campo newClientState contém o novo estado de cliente para a lista da Navegação segura recém-atualizada. Os clientes precisam salvar o novo estado do cliente para as próximas solicitações de atualização (o campo state na solicitação threatListUpdates.fetch ou 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 sofreu nenhuma corrupção. Se a soma de verificação não for correspondente, o cliente precisará limpar o banco de dados e emitir novamente uma atualização com um campo state vazio. No entanto, os clientes nessa situação ainda precisam seguir os intervalos de tempo para as atualizações. Consulte Frequência da solicitação.

Duração mínima da espera

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 na resposta. Consulte Frequência da 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 nas listas da Navegação segura).

Se o prefixo de hash estiver presente no banco de dados local (uma colisão de prefixos de hash), o cliente precisará enviar esse prefixo 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 os prefixos de hash dos URLs, mas eles não fornecem muitas informações sobre os URLs reais.

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

• A solicitação HTTP POST pode incluir até 500 entradas de ameaça.
• A solicitação HTTP POST inclui os prefixos de hash dos URLs a serem verificados. Os clientes são incentivados a agrupar várias entradas de ameaça em uma única solicitação para reduzir o uso da largura de banda.
• A resposta HTTP POST retorna os hashes completos correspondentes com as durações positivas e negativas do cache. A resposta também pode retornar uma duração mínima de espera.

Exemplo: fullHashes.find

Solicitação HTTP POST

No exemplo a seguir, os nomes de duas listas do 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 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/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 sobre ameaças (os nomes da lista e os prefixos de hash). Para solicitações JSON, os prefixos de hash precisam ser enviados no formato codificado em base64. Para mais detalhes, consulte o 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 precisam identificar exclusivamente uma implementação do cliente, não um usuário individual. As informações do cliente são usadas na geração de registros 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 da 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 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.

Prefixos de hash de ameaças

A matriz threatEntries contém os prefixos de hash dos URLs que você quer verificar. O campo hash precisa conter o prefixo de hash exato presente no banco de dados local. Por exemplo, se o prefixo de hash local tem 4 bytes, a entrada da ameaça precisa ter 4 bytes. Se o prefixo de hash local for aumentado para 7 bytes, a entrada da ameaça vai precisar ter 7 bytes.

No exemplo, a solicitação inclui três prefixos de hash. Todos os três prefixos serão comparados a cada uma das listas da Navegação segura para determinar se há um hash completo correspondente.

Observação:a API Update e o método fullHashes.find devem sempre usar o campo hash, nunca o campo URL. Consulte ThreatEntry.

Resposta HTTP POST

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

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 esperar. 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 correspondência (os nomes da lista e os hashes completos, os metadados, se disponíveis, e a duração do cache). No exemplo, o corpo da resposta também inclui uma duração de espera mínima. 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 completo correspondente para dois dos prefixos de hash. Os URLs correspondentes 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 esse exemplo corresponde um hash completo a um prefixo de hash. No entanto, pode haver vários hashes completos que mapeiam o mesmo prefixo de hash.

Metadados

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

Durações do cache

Os campos cacheDuration e negativeCacheDuration indicam por quanto tempo os hashes precisam ser considerados inseguros ou seguros. Consulte Armazenamento em cache.

Duração mínima da espera

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