Method: hashes.search

Busca hashes completos que coincidan con los prefijos especificados.

Este es un método personalizado según se define en https://google.aip.dev/136 (el método personalizado se refiere a que este método tiene un nombre personalizado dentro de la nomenclatura general de desarrollo de APIs de Google; no se refiere al uso de un método HTTP personalizado).

Solicitud HTTP

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

La URL usa la sintaxis de la transcodificación gRPC.

Parámetros de consulta

Parámetros
hashPrefixes[]

string (bytes format)

Obligatorio. Son los prefijos hash que se buscarán. Los clientes NO DEBEN enviar más de 1,000 prefijos hash. Sin embargo, según el procedimiento de procesamiento de URLs, los clientes NO DEBERÍAN necesitar enviar más de 30 prefijos hash.

Actualmente, cada prefijo de hash debe tener exactamente 4 bytes de longitud. Esta restricción SE PUEDE relajar en el futuro.

String codificada en base64.
filter

string

Opcional. Si el cliente está interesado en filtrar, por ejemplo, para recuperar solo tipos específicos de amenazas, esto se puede especificar. Si se omite, se devuelven todas las amenazas que coinciden. Se recomienda omitir esta opción para obtener la protección más completa que puede ofrecer la Navegación segura.

El filtro se especifica con el lenguaje de expresiones comunes de Google, que se puede encontrar en https://github.com/google/cel-spec junto con ejemplos generales. Estos son algunos ejemplos específicos que se pueden usar aquí:

El filtro "threatType == ThreatType.SOCIAL_ENGINEERING" requiere que el tipo de amenaza dentro de FullHashDetail sea SOCIAL_ENGINEERING. El identificador "threatType" hace referencia al tipo de amenaza actual. El identificador "ThreatType" hace referencia a la colección de todos los tipos de amenazas posibles.

El filtro "threatType in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" requiere que el tipo de amenaza sea UNWANTED_SOFTWARE o MALWARE.

Cuerpo de la solicitud

El cuerpo de la solicitud debe estar vacío.

Cuerpo de la respuesta

Es la respuesta que se devuelve después de buscar hashes de amenazas.

Si no se encuentra nada, el servidor devolverá un estado OK (código de estado HTTP 200) con el campo fullHashes vacío, en lugar de devolver un estado NOT_FOUND (código de estado HTTP 404).

Novedades de la versión 5: Se separaron FullHash y FullHashDetail. En el caso de que un hash represente un sitio con varias amenazas (p.ej., MALWARE y SOCIAL_ENGINEERING), no es necesario enviar el hash completo dos veces como en la versión 4. Además, la duración de la caché se simplificó en un solo campo cacheDuration.

Si se ejecuta correctamente, el cuerpo de la respuesta contendrá datos con la siguiente estructura:

Representación JSON 
{
  "fullHashes": [
    {
      object (FullHash)
    }
  ],
  "cacheDuration": string
}
Campos
fullHashes[]

object (FullHash)

Lista sin ordenar. Es la lista no ordenada de los hashes completos encontrados.
cacheDuration

string (Duration format)

Es la duración de la caché del cliente. El cliente DEBE agregar esta duración a la hora actual para determinar la hora de vencimiento. Luego, la hora de vencimiento se aplica a cada prefijo de hash que consulta el cliente en la solicitud, independientemente de la cantidad de hashes completos que se devuelven en la respuesta. Incluso si el servidor no devuelve hashes completos para un prefijo de hash en particular, el cliente TAMBIÉN DEBE almacenar en caché este hecho.

Si y solo si el campo fullHashes está vacío, el cliente PUEDE aumentar el valor de cacheDuration para determinar una nueva fecha de vencimiento posterior a la especificada por el servidor. En cualquier caso, la duración de la caché aumentada no debe ser superior a 24 horas.

Importante: El cliente NO DEBE suponer que el servidor devolverá la misma duración de caché para todas las respuestas. El servidor PUEDE elegir diferentes duraciones de caché para diferentes respuestas según la situación.

Una duración en segundos con hasta nueve dígitos decimales, que terminan en “s”. Ejemplo: "3.5s".

FullHash

Es el hash completo identificado con una o más coincidencias.

Representación JSON 
{
  "fullHash": string,
  "fullHashDetails": [
    {
      object (FullHashDetail)
    }
  ]
}
Campos
fullHash

string (bytes format)

Es el hash completo coincidente. Este es el hash SHA256. La longitud será exactamente de 32 bytes.

String codificada en base64.
fullHashDetails[]

object (FullHashDetail)

Lista sin ordenar. Es un campo repetido que identifica los detalles pertinentes para este hash completo.

FullHashDetail

Son los detalles de un hash completo coincidente.

Nota importante sobre la compatibilidad con versiones posteriores: El servidor puede agregar nuevos tipos y atributos de amenazas en cualquier momento. Estas adiciones se consideran cambios de versión secundaria. La política de Google es no exponer los números de versión secundaria en las APIs (consulta https://cloud.google.com/apis/design/versioning para conocer la política de control de versiones), por lo que los clientes DEBEN estar preparados para recibir mensajes FullHashDetail que contengan valores de enumeración ThreatType o valores de enumeración ThreatAttribute que el cliente considere no válidos. Por lo tanto, es responsabilidad del cliente verificar la validez de todos los valores de enumeración ThreatType y ThreatAttribute. Si algún valor se considera no válido, el cliente DEBE ignorar todo el mensaje FullHashDetail.

Representación JSON 
{
  "threatType": enum (ThreatType),
  "attributes": [
    enum (ThreatAttribute)
  ]
}
Campos
threatType

enum (ThreatType)

Es el tipo de amenaza. Este campo nunca estará vacío.
attributes[]

enum (ThreatAttribute)

Lista sin ordenar. Son atributos adicionales sobre esos hashes completos. Puede estar vacío.

ThreatAttribute

Son los atributos de las amenazas. Estos atributos pueden agregar significado adicional a una amenaza en particular, pero no afectarán el tipo de amenaza. Por ejemplo, un atributo puede especificar una confianza más baja, mientras que otro puede especificar una confianza más alta. Es posible que se agreguen más atributos en el futuro.

Enums
THREAT_ATTRIBUTE_UNSPECIFIED Atributo desconocido. Si el servidor devuelve este valor, el cliente debe ignorar el objeto FullHashDetail que lo contiene.
CANARY Indica que el valor de threatType no se debe usar para la aplicación de políticas.
FRAME_ONLY Indica que el parámetro threatType solo se debe usar para la aplicación de políticas en fotogramas.