Esta página foi traduzida pela API Cloud Translation.
Switch to English

Como usar a API Update

Visão geral

A API Update permite que seus aplicativos cliente façam o download de versões com hash das listas da Web Risk para armazenamento em um banco de dados local ou na memória. Os URLs podem ser verificados localmente. Quando a correspondência é encontrada no banco de dados local, o cliente envia uma solicitação aos servidores da Web Risk para verificar se o URL está incluído nas listas da Web Risk.

Como atualizar o banco de dados local

Para se manter atualizado, os clientes precisam atualizar periodicamente as listas da Web Risk 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 Web Risk, os clientes farão o download do prefixo 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 de download de uma única entrada de lista é 4 bytes antes da compactação.

Para atualizar as listas da Web Risk no banco de dados local, envie uma solicitação HTTP GET para o método threatLists.computeDiff:

  • A solicitação HTTP GET inclui o nome da lista a ser atualizada junto com as restrições do cliente para considerar as limitações de memória e largura de banda.
  • A resposta HTTP GET retorna uma atualização completa ou parcial. A resposta também pode retornar um tempo de espera recomendado até a próxima operação de diferença de computação.

Exemplo: threatLists.computeDiff

Solicitação GET HTTP

No exemplo a seguir, as diferenças da lista da Web Risk do MALWARE são solicitadas. Para mais detalhes, consulte os parâmetros de consulta threatLists.computeDiff e as explicações que seguem o exemplo de código.

Método HTTP e URL:

GET "https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW"

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

curl

Execute o comando a seguir:

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
"https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW"

PowerShell

Execute o comando a seguir:

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

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri ""https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW"" | Select-Object -Expand Content

Você receberá uma resposta JSON semelhante a esta:

{
  "recommendedNextDiff": "2020-01-08T19:41:45.436722194Z",
  "responseType": "RESET",
  "additions": {
    "rawHashes": [
      {
        "prefixSize": 4,
        "rawHashes": "AArQMQAMoUgAPn8lAE..."
      }
    ]
  },
  "newVersionToken": "ChAIARAGGAEiAzAwMSiAEDABEPDyBhoCGAlTcIVL",
  "checksum": {
    "sha256": "wy6jh0+MAg/V/+VdErFhZIpOW+L8ulrVwhlV61XkROI="
  }
}

Listas da Web Risk

O campo threatType identifica a lista da Web Risk. No exemplo, as diferenças para a lista da Web Risk do MALWARE são solicitadas.

Token de versão

O campo versionToken contém o estado atual do cliente da lista da Web Risk. Os tokens de versão são retornados no campo newVersionToken da resposta threatLists.computeDiff. Para atualizações iniciais, deixe o campo versionToken vazio.

Restrições de tamanho

O campo maxDiffEntries 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, 4096). Os clientes devem definir restrições de tamanho somente se tiverem limitações de memória ou largura de banda. 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 Web Risk é compatível com outros tipos de compactação. Para mais informações, consulte Compactação.

Resposta HTTP GET

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

Corpo da resposta

O corpo da resposta inclui as informações de diferenças (o tipo de resposta, as adições e remoções a serem aplicadas ao banco de dados local, o novo token de versão e uma soma de verificação).

No exemplo, a resposta também inclui um próximo horário de diferença recomendado. Para mais detalhes, consulte o corpo da resposta threatLists.computeDiff e as explicações que seguem o exemplo de código.

{
  "responseType" :   "DIFF",
  "recommendedNextDiff": "2019-12-31T23:59:59.000000000Z",
  "additions": {
    "compressionType": "RAW",
    "rawHashes": [{
      "prefixSize": 4,
      "rawHashes":  "rnGLoQ=="
    }]
  },
  "removals": {
    "rawIndices": {
      "indices": [0, 2, 4]
    }
  },
  "newVersionToken": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
  "checksum": {
    "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
  },
  "recommendedNextDiff": "2019-07-17T15:01:23.045123456Z"
}

Diferenças de banco de dados

O campo responseType indicará uma atualização parcial (DIFF) ou completa (RESET). No exemplo, as diferenças parciais são retornadas. Portanto, a resposta inclui adições e remoções. Pode haver vários conjuntos de adições, mas apenas um conjunto de remoções. Para mais informações, consulte Diferenças de banco de dados.

Novo token de versão

O campo newVersionToken contém o novo token de versão da lista da Web Risk recém-atualizada. Os clientes precisam salvar o novo estado do cliente para solicitações de atualização subsequentes (o campo versionToken na solicitação threatLists.computeDiff.

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 a soma de verificação não corresponder, o cliente precisará limpar o banco de dados e reemitir uma atualização com um campo versionToken vazio. No entanto, os clientes nessa situação ainda precisam seguir os intervalos de tempo para atualizações. Para mais informações, consulte Frequência de solicitação.

O campo recommendedNextDiff indica um carimbo de data / hora até quando o cliente deve aguardar antes de enviar outra solicitação de atualização. O período de espera recomendado pode ou não ser incluído na resposta. Para mais detalhes, consulte Frequência de solicitação.

Como verificar URLs

Para verificar se um URL está em uma lista da Web Risk, primeiro o cliente precisa calcular o hash e o prefixo de hash do URL. Para detalhes, 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 (ou seja, não nas listas da Web Risk).

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 Web Risk para verificação. Os servidores retornarão todos os hashes SHA 256 completos que contêm o prefixo de hash fornecido. 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 os prefixos de hash não fornecem muitas informações sobre os URLs reais.

Para verificar se um URL está em uma lista da Web Risk, envie uma solicitação HTTP GET para o método hashes.search:

  • A solicitação HTTP GET inclui o prefixo de hash do URL a ser verificado.
  • A resposta HTTP GET retorna os hashes de comprimento total correspondentes, juntamente com os tempos de expiração positivos e negativos.

Exemplo: hashes.search

Solicitação GET HTTP

No exemplo a seguir, os nomes de duas listas da Web Risk e um prefixo de hash são enviados para comparação e verificação. Para mais detalhes, consulte os parâmetros de consulta hashes.search e as explicações que seguem o exemplo de código.

curl \
  -H "Content-Type: application/json" \
  "https://webrisk.googleapis.com/v1/hashes:search?key=YOUR_API_KEY&threatTypes=MALWARE&threatTypes=SOCIAL_ENGINEERING&hashPrefix=WwuJdQ%3D%3D"

Listas da Web Risk

O campo threatTypes identifica as listas da Web Risk. No exemplo, duas listas são identificadas: MALWARE e SOCIAL_ENGINEERING.

Prefixos de hash de ameaças

O campo hashPrefix contém o prefixo de hash do URL que você quer verificar. Esse campo precisa conter o prefixo de hash exato que está presente no banco de dados local. Por exemplo, se o prefixo de hash local tiver 4 bytes, o campo hashPrefix precisará ter 4 bytes. Se o prefixo de hash local tiver sido aumentado para 7 bytes, o campo hashPrefix precisará ter 7 bytes.

Resposta HTTP GET

No exemplo a seguir, a resposta retorna as ameaças correspondentes, contendo as listas da Web Risk correspondentes e os tempos de expiração.

Corpo da resposta

O corpo da resposta inclui as informações de correspondência (os nomes da lista e os hashes de comprimento total e as durações do cache). Para mais detalhes, consulte o corpo da resposta hashes.search e as explicações que seguem o exemplo de código.

{
  "threats": [{
      "threatTypes": ["MALWARE"],
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
      "expireTime": "2019-07-17T15:01:23.045123456Z"
    }, {
      "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"],
      "hash": "WwuJdQxaCSH453-uytERC456gf45rFExcE23F7-hnfD="
      "expireTime": "2019-07-17T15:01:23.045123456Z"
    },
  }],
  "negativeExpireTime": "2019-07-17T15:01:23.045123456Z"
}

Correspondências

O campo threats retorna um hash completo correspondente ao prefixo de hash. Os URLs correspondentes a esses hashes são considerados não seguros. Se nenhuma correspondência for encontrada para um prefixo de hash, nada será retornado. o URL correspondente a esse prefixo de hash é considerado seguro.

Tempo de expiração

Os campos expireTime e negativeExpireTime indicam até quando os hashes precisam ser considerados não seguros ou seguros, respectivamente. Para mais detalhes, consulte Armazenamento em cache.