Method: hashes.search

Pesquise hashes completos que correspondam aos prefixos especificados.

Esse é um método personalizado, conforme definido por https://google.aip.dev/136 (link em inglês). Esse método tem um nome personalizado na nomenclatura geral de desenvolvimento de API do Google, não se refere ao uso de um método HTTP personalizado.

Solicitação HTTP

GET https://safebrowsing.googleapis.com/v5/hashes:search

O URL usa a sintaxe de transcodificação gRPC.

Parâmetros de consulta

Parâmetros
hashPrefixes[]

string (bytes format)

Obrigatório. Os prefixos de hash a serem pesquisados. Os clientes NÃO PODEM enviar mais de 1.000 prefixos de hash. No entanto, seguindo o procedimento de processamento de URL, os clientes NÃO DEVEM enviar mais de 30 prefixos de hash.

Atualmente, cada prefixo de hash precisa ter exatamente 4 bytes. Isso PODE ser amenizado no futuro.

Uma string codificada em base64.

Corpo da solicitação

O corpo da solicitação precisa estar vazio.

Corpo da resposta

A resposta retornada após a pesquisa de hashes de ameaça.

Se nada for encontrado, o servidor retornará um status OK (código de status HTTP 200) com o campo fullHashes vazio, em vez de retornar um status NOT_FOUND (código de status HTTP 404).

Novidades na V5: há uma separação entre FullHash e FullHashDetail. No caso em que um hash representa um site que apresenta várias ameaças (por exemplo, MALWARE e SOCIAL_engineERING), o hash completo não precisa ser enviado duas vezes como na V4. Além disso, a duração do cache foi simplificada em um único campo cacheDuration.

Se bem-sucedido, o corpo da resposta incluirá dados com a estrutura a seguir:

Representação JSON 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
Campos
fullHashes[]

object (FullHash)

Lista não ordenada. A lista não ordenada de hashes completos foi encontrada.
cacheDuration

string (Duration format)

A duração do cache do lado do cliente. O cliente PRECISA adicionar essa duração ao horário atual para determinar o prazo de validade. O prazo de validade é aplicado a cada prefixo de hash consultado pelo cliente na solicitação, independentemente de quantos hashes completos forem retornados na resposta. Mesmo que o servidor não retorne hashes completos para um prefixo de hash específico, esse fato também PRECISA ser armazenado em cache pelo cliente.

Importante: o cliente NÃO PODE presumir que o servidor retornará a mesma duração de cache para todas as respostas. O servidor PODE escolher durações de cache diferentes para respostas distintas, dependendo da situação.

Uma duração em segundos com até nove dígitos fracionários, terminando em "s". Exemplo: "3.5s".

FullHash

O hash completo identificado com uma ou mais correspondências.

Representação JSON 
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
Campos
fullHash

string (bytes format)

O hash completo correspondente. Esse é o hash SHA256. O comprimento será de exatamente 32 bytes.

Uma string codificada em base64.
fullHashDetails[]

object (FullHashDetail)

Lista não ordenada. Um campo repetido que identifica os detalhes relevantes para esse hash completo.

FullHashDetail

Detalhes sobre um hash completo correspondente.

Uma observação importante sobre compatibilidade futura: novos tipos de ameaça e atributos de ameaça podem ser adicionados pelo servidor a qualquer momento; essas adições são consideradas pequenas alterações de versão. É política do Google não expor números de versão secundários nas APIs (consulte https://cloud.google.com/apis/design/versioning para a política de controle de versões). Por isso, os clientes PRECISAM estar preparados para receber mensagens FullHashDetail contendo valores de tipo enumerado ThreatType ou valores de tipo enumerado ThreatAttribute que são considerados inválidos pelo cliente. Portanto, é responsabilidade do cliente verificar a validade de todos os valores de tipo enumerado ThreatType e ThreatAttribute. Se algum valor for considerado inválido, o cliente PRECISA desconsiderar toda a mensagem FullHashDetail.

Representação JSON 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
Campos
threatType

enum (ThreatType)

O tipo de ameaça. Este campo nunca ficará vazio.
attributes[]

enum (ThreatAttribute)

Lista não ordenada. Atributos adicionais sobre esses hashes completos. Esse campo pode estar vazio.

ThreatType

Tipos de ameaças.

Enums
THREAT_TYPE_UNSPECIFIED Tipo de ameaça desconhecido. Se esse valor for retornado pelo servidor, o cliente precisará desconsiderar completamente o FullHashDetail.
MALWARE

Tipo de ameaça de malware. Malware é qualquer software ou aplicativo para dispositivos móveis projetado especificamente para causar danos a um computador, dispositivo móvel, bem como a usuários ou outro software. Além disso, o malware apresenta um comportamento malicioso que pode incluir a instalação de software sem o consentimento do usuário e a instalação de software nocivo, como vírus.

Saiba mais aqui.
SOCIAL_ENGINEERING

Tipo de ameaça de engenharia social. Páginas de engenharia social têm a intenção falsa de agir em nome de terceiros com a intenção de confundir os espectadores, fazendo-os realizar uma ação com a qual eles confiam somente em um agente desse terceiro. Phishing é um tipo de engenharia social que engana o espectador para que realize a ação específica de fornecer informações, como credenciais de login.

Saiba mais aqui.
UNWANTED_SOFTWARE Tipo de ameaça de software indesejado. Software indesejado é qualquer software que não esteja em conformidade com os Princípios de software do Google, mas não seja malware.
POTENTIALLY_HARMFUL_APPLICATION Tipo de ameaça de apps potencialmente nocivos usado pelo Google Play Protect na Play Store.

ThreatAttribute

Atributos das ameaças. Esses atributos podem conferir um significado adicional a uma ameaça específica, mas não afetam o tipo dela. Por exemplo, um atributo pode especificar uma confiança mais baixa, enquanto um atributo diferente pode especificar uma confiança mais alta. Mais atributos podem ser adicionados no futuro.

Enums
THREAT_ATTRIBUTE_UNSPECIFIED Atributo desconhecido. Se esse valor for retornado pelo servidor, o cliente precisará desconsiderar completamente o FullHashDetail.
CANARY Indica que o threatType não deve ser usado para aplicação.
FRAME_ONLY Indica que o threatType só deve ser usado para aplicação em frames.