Method: hashes.search

Pesquisa hashes completos que correspondem aos prefixos especificados.

Esse é um método personalizado, conforme definido por https://google.aip.dev/136. O método personalizado se refere a ter um nome personalizado dentro da nomenclatura geral de desenvolvimento de APIs do Google, e não ao uso de um método HTTP personalizado.

Solicitação HTTP

GET https://safebrowsing.googleapis.com/v5alpha1/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 hash a serem consultados. Os clientes NÃO PODEM enviar mais de 1.000 prefixos de hash. No entanto, seguindo o procedimento de processamento do 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 relaxado no futuro.

Uma string codificada em base64.
filter

string

Opcional. Se o cliente estiver interessado em filtrar, como na recuperação de tipos específicos de ameaças, isso pode ser especificado. Se omitido, todas as ameaças correspondentes são retornadas. É altamente recomendável omitir isso para ter a proteção mais completa que a Navegação segura pode oferecer.

O filtro é especificado usando a Common Expression Language do Google, que pode ser encontrada em https://github.com/google/cel-spec (em inglês) com exemplos gerais. Aqui estão alguns exemplos específicos que podem ser usados aqui:

O filtro "threatType == ThreatType.SOCIAL_ENGINEERING" exige que o tipo de ameaça em FullHashDetail seja SOCIAL_ENGINEERING. O identificador "threatType" se refere ao tipo de ameaça atual. O identificador "ThreatType" se refere à coleção de todos os tipos de ameaça possíveis.

O filtro "threatType in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" exige que o tipo de ameaça seja UNWANTED_SOFTWARE ou MALWARE.

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ças.

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 tem 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 encontrados.
cacheDuration

string (Duration format)

A duração do cache do lado do cliente. O cliente PRECISA adicionar essa duração à hora 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 são retornados na resposta. Mesmo que o servidor não retorne hashes completos para um determinado prefixo de hash, esse fato também PRECISA ser armazenado em cache pelo cliente.

Somente se o campo fullHashes estiver vazio, o cliente PODE aumentar o cacheDuration para determinar uma nova expiração posterior à especificada pelo servidor. De qualquer forma, a duração do cache aumentada não deve ser superior a 24 horas.

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 diferentes dependendo da situação.

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. Este é 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 com versões futuras: novos tipos e atributos de ameaças podem ser adicionados pelo servidor a qualquer momento; essas adições são consideradas pequenas alterações da versão. Faz parte da política do Google não expor números de versões secundárias nas APIs (consulte https://cloud.google.com/apis/design/versioning para ver a política de controle de versões). Por isso, os clientes PRECISAM receber mensagens FullHashDetail com valores de tipo enumerado ThreatType ou de tipo enumerado ThreatAttribute 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. Esse campo nunca estará vazio.
attributes[]

enum (ThreatAttribute)

Lista não ordenada. Outros atributos sobre esses hashes completos. Pode estar vazio.

ThreatAttribute

Atributos das ameaças. Esses atributos podem conferir significado adicional a uma ameaça específica, mas não afetarão o tipo de ameaça. Por exemplo, um atributo pode especificar um nível de confiança menor, enquanto outro atributo pode especificar um nível de confiança maior. Mais atributos podem ser adicionados no futuro.

Enums
THREAT_ATTRIBUTE_UNSPECIFIED Atributo desconhecido. Se ele for retornado pelo servidor, o cliente desconsidera 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.