Package google.security.safebrowsing.v5alpha1

Índice

SafeBrowsing

Las APIs de Navegación segura permiten a los clientes verificar los recursos web (por lo general, URLs) con respecto a las listas de Google de recursos web no seguros que se actualizan constantemente.

BatchGetHashLists

rpc BatchGetHashLists(BatchGetHashListsRequest) returns (BatchGetHashListsResponse)

Obtén varias listas de hash a la vez.

Es muy común que un cliente necesite varias listas de hash. Es preferible usar este método en lugar del método Get normal varias veces.

Este es un método Get por lotes estándar, según se define en https://google.aip.dev/231, y el método HTTP también es GET.

GetHashList

rpc GetHashList(GetHashListRequest) returns (HashList)

Obtener el contenido más reciente de una lista de hash Una lista de hash puede ser mediante una lista de amenazas o una lista no relacionada con amenazas, como la Caché global.

Este es un método Get estándar, como se define en https://google.aip.dev/131, y el método HTTP también es GET.

ListHashLists

rpc ListHashLists(ListHashListsRequest) returns (ListHashListsResponse)

Enumera listas de hash.

En la API V5, Google nunca quitará una lista de hash que haya devuelto este método. Esto permite a los clientes omitir el uso de este método y simplemente codificar todas las listas de hash que necesitan.

Este es un método List estándar, como se define en https://google.aip.dev/132, y el método HTTP es GET.

SearchHashes

rpc SearchHashes(SearchHashesRequest) returns (SearchHashesResponse)

Busca hashes completos que coincidan con los prefijos especificados.

Este es un método personalizado, como lo define https://google.aip.dev/136 (el método personalizado hace referencia a que este método tiene un nombre personalizado dentro de la nomenclatura de desarrollo general de la API de Google; no hace referencia al uso de un método HTTP personalizado).

BatchGetHashListsRequest

La solicitud para obtener varias listas de hash al mismo tiempo.

Campos
names[]

string

Obligatorio. Los nombres de las listas de hash en particular La lista PUEDE ser una lista de amenazas o puede ser la Caché Global. Los nombres NO DEBEN contener duplicados. Si lo hicieron, el cliente recibirá un error.

version[]

bytes

Las versiones de la lista de hash que ya tiene el cliente. Si es la primera vez que el cliente recupera las listas de hash, el campo debe dejarse vacío. De lo contrario, el cliente debe proporcionar las versiones que recibió previamente del servidor. El cliente NO DEBE manipular esos bytes.

No es necesario que el cliente envíe las versiones en el mismo orden que los nombres de lista correspondientes. Es posible que el cliente envíe menos o más versiones que nombres en una solicitud. Sin embargo, el cliente NO DEBE enviar múltiples versiones que correspondan al mismo nombre; si lo hizo, recibirá un error.

Nota histórica: En la V4 de la API, se llamaba states. Ahora, se cambió el nombre por version para mayor claridad.

desired_hash_length

HashLength

La longitud deseada del prefijo de hash de los hashes que se muestran, expresada en bytes. Luego, el servidor mostrará todos los prefijos de hash de esta longitud especificada.

Las diferentes listas de hash tienen diferentes requisitos en los valores aceptables del campo desired_hash_length. Puedes encontrarlo en el campo supported_hash_lengths de HashListMetadata. Si desired_hash_length no especifica un valor en supported_hash_lengths, se mostrará un error a los clientes.

En el caso de BatchGetHashListsRequest en particular, los clientes no pueden especificar un desired_hash_length diferente para listas distintas. Si es necesario, el cliente debe dividirse en varios BatchGetHashListsRequest.

size_constraints

SizeConstraints

Las restricciones de tamaño de cada lista. Si se omite, no hay restricciones. Tenga en cuenta que los tamaños que figuran aquí son por lista, no en todas las listas.

BatchGetHashListsResponse

La respuesta que contiene varias listas de hash.

Campos
hash_lists[]

HashList

Las listas de hash en el mismo orden dado en la solicitud.

FullHash

El hash completo identificado con una o más coincidencias.

Campos
full_hash

bytes

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

full_hash_details[]

FullHashDetail

Lista sin ordenar. Un campo repetido que identifica los detalles relevantes para este hash completo.

FullHashDetail

Detalles sobre un hash completo coincidente.

Nota importante sobre la compatibilidad con versiones futuras: el servidor puede agregar nuevos tipos de amenazas y atributos de amenazas en cualquier momento; esas incorporaciones se consideran cambios de versión menores. La política de Google es no exponer los números de versión secundarios 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 enum ThreatType o valores enum ThreatAttribute que el cliente considere no válidos. Por lo tanto, es responsabilidad del cliente verificar la validez de todos los valores enum ThreatType y ThreatAttribute. Si algún valor se considera no válido, el cliente DEBE ignorar todo el mensaje FullHashDetail.

Campos
threat_type

ThreatType

El tipo de amenaza. Este campo nunca estará vacío.

attributes[]

ThreatAttribute

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

GetHashListRequest

Es una solicitud para obtener una lista de hash, que puede ser una lista de amenazas o una lista sin amenazas, como la caché global.

Novedades de la versión 5: Lo que antes se llamaba states en la versión 4 se cambió por version para brindar mayor claridad. Ahora las listas tienen un nombre, y se quitaron los tipos de plataformas y de entrada de amenazas. Ahora es posible que varias listas tengan el mismo tipo de amenaza, o una sola lista preocupada por varios tipos de amenazas. Los clientes tienen la nueva capacidad de especificar la longitud de hash deseada. Esta es parte de la respuesta a los prefijos de hash de longitud variable de V4, que causaron problemas en muchas implementaciones de clientes: todos los hashes de una lista ahora tienen una sola longitud, lo que permite implementaciones de clientes mucho más eficientes. Se simplificaron las restricciones y se quitó el tipo de compresión (la compresión siempre se aplica).

Campos
name

string

Obligatorio. Es el nombre de esta lista de hash en particular. Puede ser una lista de amenazas o la caché global.

version

bytes

La versión de la lista de hash que ya tiene el cliente. Si es la primera vez que el cliente recupera la lista de hash, este campo DEBE dejarse vacío. De lo contrario, el cliente DEBE proporcionar la versión previamente recibida del servidor. El cliente NO DEBE manipular esos bytes.

Novedades de V5: En la versión 4 de la API, se llamaba states; ahora, se cambió su nombre por version para mayor claridad.

desired_hash_length

HashLength

La longitud deseada del prefijo de hash de los hashes que se muestran, expresada en bytes. Luego, el servidor mostrará todos los prefijos de hash de esta longitud especificada.

Las diferentes listas de hash tienen diferentes requisitos en los valores aceptables del campo desired_hash_length. Puedes encontrarlo en el campo supported_hash_lengths de HashListMetadata. Si desired_hash_length no especifica un valor en supported_hash_lengths, se mostrará un error.

size_constraints

SizeConstraints

Las restricciones de tamaño de la lista. Si se omite, no hay restricciones. Se recomiendan las restricciones en todos los dispositivos con capacidad de procesamiento, ancho de banda o almacenamiento limitados.

HashList

Una lista de hashes identificados por su nombre.

Campos
name

string

Es el nombre de la lista de hash. Ten en cuenta que la caché global también es solo una lista de hash y que se puede hacer referencia a ella aquí.

version

bytes

Es la versión de la lista de hash. El cliente NO DEBE manipular esos bytes.

partial_update

bool

Cuando es verdadero, esta es una diferencia parcial que contiene adiciones y eliminaciones basadas en lo que el cliente ya tiene. Cuando es falso, esta es la lista de hash completa.

Cuando es falso, el cliente DEBE borrar cualquier versión almacenada localmente para esta lista de hash. Esto significa que la versión que posee el cliente está muy desactualizada o que los datos del cliente se cree que están dañados. El campo compressed_removals estará vacío.

Cuando es verdadero, el cliente DEBE aplicar una actualización incremental aplicando eliminaciones y luego adiciones.

compressed_removals

RiceDeltaEncoded32Bit

Es la versión codificada Rice-delta de los índices de eliminación. Dado que cada lista de hash definitivamente tiene menos de 2^32 entradas, los índices se tratan como números enteros de 32 bits y se codifican.

minimum_wait_duration

Duration

Los clientes deben esperar al menos este tiempo para volver a obtener la lista de hash. Si se omite o si se omite, los clientes DEBEN recuperarse de inmediato porque indica que el servidor tiene una actualización adicional que se enviará al cliente, pero no podría hacerlo debido a las restricciones que especifica el cliente.

metadata

HashListMetadata

Metadatos sobre la lista de hashes No se propaga con el método GetHashList, sino con el método ListHashLists.

Campo de unión compressed_additions. La versión codificada de Rice-delta de las adiciones. Las longitudes del prefijo de hash de las adiciones son uniformes en todas las adiciones de la lista. Es el desired_hash_length que envía el cliente o un valor que elige el servidor si el cliente omitió ese campo. compressed_additions puede ser solo uno de los siguientes:
additions_four_bytes

RiceDeltaEncoded32Bit

Las incorporaciones de 4 bytes.

additions_eight_bytes

RiceDeltaEncoded64Bit

Las adiciones de 8 bytes.

additions_sixteen_bytes

RiceDeltaEncoded128Bit

Las adiciones de 16 bytes.

additions_thirty_two_bytes

RiceDeltaEncoded256Bit

Las adiciones de 32 bytes.

Campo de unión checksum. Esta es la suma de verificación para la lista ordenada de todos los hashes presentes en la base de datos después de aplicar la actualización proporcionada. Este es un campo "uno de" que permite varios algoritmos de hash. También es posible que el servidor omita este campo (en el caso de que no se hayan proporcionado actualizaciones) para indicar que el cliente debe usar la suma de verificación existente. Las direcciones (checksum) solo pueden ser una de las siguientes opciones:
sha256_checksum

bytes

Es la lista ordenada de todos los hashes, con la codificación hash de nuevo con SHA256.

HashListMetadata

Metadatos sobre una lista de hash en particular

Campos
threat_types[]

ThreatType

Lista sin ordenar. Si no está vacío, especifica que la lista de hash es un tipo de lista de amenazas y enumera el tipo de amenazas asociadas con los hash o sus prefijos en esta lista. Puede estar vacía si la entrada no representa una amenaza, es decir, en el caso de que represente un tipo probablemente seguro.

likely_safe_types[]

LikelySafeType

Lista sin ordenar. Si no está vacío, especifica que la lista de hash representa una lista de hashes probablemente seguros y enumera las formas en que se consideran probables. Este campo es mutuamente excluyente con el campo Threat_types.

mobile_optimized

bool

Si esta lista está optimizada para dispositivos móviles (iOS y Android).

description

string

Es una descripción legible sobre esta lista. Escrita en inglés.

supported_hash_lengths[]

HashLength

Las longitudes de hash admitidas para esta lista de hashes. Cada lista de hash admitiría al menos una longitud. Por lo tanto, este campo no estará vacío.

HashLength

Es la longitud de los hashes en una lista de hash.

Enumeradores
HASH_LENGTH_UNSPECIFIED Longitud no especificada. El servidor no mostrará este valor en respuestas al cliente (en el campo supported_hash_lengths), pero el cliente puede enviar este valor al servidor (en el campo desired_hash_length), en cuyo caso el servidor elegirá un valor automáticamente. Los clientes DEBEN dejar que el servidor elija un valor.
FOUR_BYTES Cada hash es un prefijo de cuatro bytes.
EIGHT_BYTES Cada hash es un prefijo de ocho bytes.
SIXTEEN_BYTES Cada hash es un prefijo de dieciséis bytes.
THIRTY_TWO_BYTES Cada hash es un hash completo de treinta y dos bytes.

LikelySafeType

Tipos de sitios probablemente seguros.

Ten en cuenta que SearchHashesResponse no contiene LikelySafeType de forma intencional.

Enumeradores
LIKELY_SAFE_TYPE_UNSPECIFIED Desconocido.
GENERAL_BROWSING Es probable que este sitio sea lo suficientemente seguro para la navegación general. Esto también se conoce como caché global.
CSD Es probable que este sitio sea lo suficientemente seguro como para que no sea necesario ejecutar modelos de detección del cliente ni verificaciones de protección de contraseñas.
DOWNLOAD Es probable que este sitio sea lo suficientemente seguro como para que no sea necesario revisar las descargas.

ListHashListsRequest

Es la solicitud para enumerar las listas de hash disponibles.

Campos
page_size

int32

La cantidad máxima de listas de hash que se mostrarán. El servicio puede mostrar menos que este valor. Si no se especifica, el servidor elegirá un tamaño de página, que puede ser superior al número de listas de hash, de modo que la paginación no sea necesaria.

page_token

string

Un token de página, recibido desde una llamada ListHashLists anterior. Proporciona esto para recuperar la página siguiente.

ListHashListsResponse

La respuesta que contiene metadatos sobre las listas de hash.

Campos
hash_lists[]

HashList

Las listas de hash en un orden arbitrario. Solo se incluirán los metadatos sobre las listas de hash, no el contenido.

next_page_token

string

Un token, que se puede enviar como page_token para recuperar la página siguiente. Si se omite este campo, no habrá páginas siguientes.

RiceDeltaEncoded128Bit

Es igual que RiceDeltaEncoded32Bit, excepto que este codifica números de 128 bits.

Campos
first_value_hi

uint64

Los 64 bits superiores de la primera entrada en los datos codificados (hashes). Si el campo está vacío, los 64 bits superiores son todos cero.

first_value_lo

fixed64

Los 64 bits inferiores de la primera entrada en los datos codificados (hashes). Si el campo está vacío, los 64 bits inferiores son iguales a cero.

rice_parameter

int32

El parámetro Golomb-Rice. Se garantiza que este parámetro estará entre 99 y 126, inclusive.

entries_count

int32

El número de entradas que están codificadas delta en los datos codificados. Si solo se codificó un número entero, este será cero y el valor único se almacenará en first_value.

encoded_data

bytes

Los deltas codificados que se codifican con el codificador Golomb-Rice.

RiceDeltaEncoded256Bit

Igual que RiceDeltaEncoded32Bit, excepto que esto codifica números de 256 bits.

Campos
first_value_first_part

uint64

Los primeros 64 bits de la primera entrada en los datos codificados (hashes). Si el campo está vacío, los primeros 64 bits son iguales a cero.

first_value_second_part

fixed64

Los bits 65 a 128 de la primera entrada en los datos codificados (hashes). Si el campo está vacío, los bits 65 a 128 son todos cero.

first_value_third_part

fixed64

Los bits 129 a 192 de la primera entrada en los datos codificados (hashes). Si el campo está vacío, los bits 129 a 192 son todos cero.

first_value_fourth_part

fixed64

Los últimos 64 bits de la primera entrada en los datos codificados (hashes). Si el campo está vacío, los últimos 64 bits son todos cero.

rice_parameter

int32

El parámetro Golomb-Rice. Se garantiza que este parámetro estará entre 227 y 254, inclusive.

entries_count

int32

El número de entradas que están codificadas delta en los datos codificados. Si solo se codificó un número entero, este será cero y el valor único se almacenará en first_value.

encoded_data

bytes

Los deltas codificados que se codifican con el codificador Golomb-Rice.

RiceDeltaEncoded32Bit

Los datos codificados en Rice-Golomb. Se usa para los hashes o los índices de eliminación. Se garantiza que cada hash o índice tiene la misma longitud, y que esta longitud es exactamente de 32 bits.

En términos generales, si ordenamos todas las entradas de manera lexicográfica, veremos que los bits de orden superior tienden a no cambiar con tanta frecuencia como los bits de orden inferior. Esto significa que, si también tomamos la diferencia adyacente entre las entradas, los bits de orden superior tienen una alta probabilidad de ser cero. Se aprovecha la alta probabilidad de cero mediante la elección de un cierto número de bits. Es probable que todos los bits más significativos sean cero, por lo que usamos una codificación unaria. Consulta el campo rice_parameter.

Nota histórica: La codificación Rice-delta se usó por primera vez en la versión 4 de esta API. En V5, se hicieron dos mejoras importantes: en primer lugar, la codificación Rice-delta ahora está disponible con prefijos hash de más de 4 bytes; en segundo lugar, los datos codificados ahora se tratan como big-endian para evitar un paso de clasificación costoso.

Campos
first_value

uint32

La primera entrada de los datos codificados (hashes o índices) o, si solo se codificó un índice o prefijo de hash único, el valor de esa entrada. Si el campo está vacío, la entrada es cero.

rice_parameter

int32

El parámetro Golomb-Rice. Se garantiza que este parámetro será de entre 3 y 30, inclusive.

entries_count

int32

El número de entradas que están codificadas delta en los datos codificados. Si solo se codificó un número entero, este será cero y el valor único se almacenará en first_value.

encoded_data

bytes

Los deltas codificados que se codifican con el codificador Golomb-Rice.

RiceDeltaEncoded64Bit

Es igual que RiceDeltaEncoded32Bit, excepto que este codifica números de 64 bits.

Campos
first_value

uint64

La primera entrada de los datos codificados (hashes) o, si solo se codificó un prefijo de hash, el valor de esa entrada. Si el campo está vacío, la entrada es cero.

rice_parameter

int32

El parámetro Golomb-Rice. Se garantiza que este parámetro será de entre 35 y 62, inclusive.

entries_count

int32

El número de entradas que están codificadas delta en los datos codificados. Si solo se codificó un número entero, este será cero y el valor único se almacenará en first_value.

encoded_data

bytes

Los deltas codificados que se codifican con el codificador Golomb-Rice.

SearchHashesRequest

Una solicitud que el cliente emite para buscar prefijos de hash específicos.

Está diseñado solo para buscar listas de amenazas, no en listas no amenazantes como la caché global.

Novedades de V5: Los clientes no necesitan especificar un ClientInfo ni los estados de las listas de hash en su base de datos local. Esto permite mejorar la privacidad. Además, los clientes no necesitan enviar qué tipos de amenazas les interesan.

Campos
hash_prefixes[]

bytes

Obligatorio. Los prefijos de hash que se deben buscar. Los clientes NO DEBEN enviar más de 1,000 prefijos hash. Sin embargo, después del procedimiento de procesamiento de URL, los clientes NO DEBEN enviar más de 30 prefijos hash.

Actualmente, cada prefijo de hash debe tener exactamente 4 bytes de longitud. Esto PUEDE relajarte en el futuro.

filter

string

Opcional. Si el cliente está interesado en filtrar, como recuperar solo tipos específicos de amenazas, esto se puede especificar. Si se omite, se devuelven todas las amenazas coincidentes. 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 Google Common Expression Language, que se puede encontrar en https://github.com/google/cel-spec junto con ejemplos generales. Aquí hay algunos ejemplos específicos que pueden usarse:

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

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

SearchHashesResponse

La respuesta que se muestra después de buscar hashes de amenazas.

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

Novedades de V5: Hay una separación entre FullHash y FullHashDetail. En el caso de que un hash represente un sitio que tiene múltiples amenazas (p.ej., MALWARE y SOCIAL_ENGINEERING), no es necesario enviar el hash completo dos veces como en V4. Además, la duración de la caché se simplificó en un solo campo cache_duration.

Campos
full_hashes[]

FullHash

Lista sin ordenar. La lista desordenada de hashes completos encontrados.

cache_duration

Duration

La duración de la caché del cliente. El cliente DEBE agregar esta duración a la hora actual para determinar la fecha y hora de vencimiento. Luego, el tiempo de vencimiento se aplica a cada prefijo de hash consultado por el cliente en la solicitud, sin importar cuántos hashes completos se devuelvan en la respuesta. Incluso si el servidor no devuelve hashes completos para un prefijo de hash en particular, el cliente también DEBE almacenar este dato en caché.

Solo si el campo full_hashes está vacío, el cliente PUEDE aumentar el cache_duration para determinar un nuevo vencimiento que sea posterior al especificado por el servidor. En cualquier caso, la duración aumentada de la caché no debe superar las 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 la caché para diferentes respuestas según la situación.

SizeConstraints

Las restricciones en los tamaños de las listas de hash

Campos
max_update_entries

int32

El tamaño máximo en cantidad de entradas. La actualización no contendrá más entradas que este valor, pero es posible que contenga menos entradas que este valor. DEBE ser de al menos 1,024. Si se omite o si es cero, no se establecerá ningún límite de tamaño de actualización.

max_database_entries

int32

Establece la cantidad máxima de entradas que el cliente está dispuesto a tener en la base de datos local para la lista. (ES POSIBLE que el servidor haga que el cliente almacene una cantidad inferior a esta cantidad de entradas). Si se omite o cero, no se establece ningún límite de tamaño de la base de datos.

ThreatAttribute

Atributos de las amenazas Estos atributos pueden conferir un significado adicional a una amenaza en particular, pero no afectarán el tipo de amenaza. Por ejemplo, es posible que un atributo especifique un nivel de confianza menor, mientras que un atributo diferente puede especificar un nivel de confianza más alto. Es posible que se agreguen más atributos en el futuro.

Enumeradores
THREAT_ATTRIBUTE_UNSPECIFIED Atributo desconocido. Si el servidor la muestra, el cliente ignorará por completo el FullHashDetail que lo contiene.
CANARY Indica que Threat_type no se debe usar para la aplicación.
FRAME_ONLY Indica que Threat_type solo se debe usar para la aplicación forzosa en los fotogramas.

ThreatType

Tipos de amenazas.

Enumeradores
THREAT_TYPE_UNSPECIFIED Tipo de amenaza desconocido. Si el servidor la muestra, el cliente ignorará por completo el FullHashDetail que lo contiene.
MALWARE

Tipo de amenaza de software malicioso. Un software malicioso es cualquier software o aplicación que se diseña específicamente para dañar una computadora, un dispositivo móvil, el software que lo ejecuta o a los usuarios. Su objetivo es llevar a cabo una acción malintencionada, como instalar software dañino (por ejemplo, virus) o programas sin el consentimiento del usuario.

Puedes obtener más información en este vínculo.

SOCIAL_ENGINEERING

Tipo de amenaza de ingeniería social. Las páginas de ingeniería social pretenden actuar en nombre de un tercero con la intención de confundir a los usuarios para que realicen una acción con la que solo confiarían en un agente verdadero de ese tercero. La suplantación de identidad (phishing) es un tipo de ingeniería social que engaña al usuario para que realice la acción específica de proporcionar información, como credenciales de acceso.

Puedes obtener más información en este vínculo.

UNWANTED_SOFTWARE Tipo de amenaza de software no deseado. Se denomina software no deseado a cualquier software que no cumpla con los Principios de software de Google, pero que no sea software malicioso.
POTENTIALLY_HARMFUL_APPLICATION Tipo de amenaza de la aplicación potencialmente dañina que usa Google Play Protect para Play Store.