Índice
SafeBrowsing(interfaz)BatchGetHashListsRequest(mensaje)BatchGetHashListsResponse(mensaje)FullHash(mensaje)FullHash.FullHashDetail(mensaje)GetHashListRequest(mensaje)HashList(mensaje)HashListMetadata(mensaje)HashListMetadata.HashLength(enumeración)LikelySafeType(enumeración)ListHashListsRequest(mensaje)ListHashListsResponse(mensaje)RiceDeltaEncoded128Bit(mensaje)RiceDeltaEncoded256Bit(mensaje)RiceDeltaEncoded32Bit(mensaje)RiceDeltaEncoded64Bit(mensaje)SearchHashesRequest(mensaje)SearchHashesResponse(mensaje)SearchUrlsRequest(mensaje)SearchUrlsResponse(mensaje)SizeConstraints(mensaje)ThreatAttribute(enumeración)ThreatType(enumeración)ThreatUrl(mensaje)
Navegación segura
Las APIs de Safe Browsing permiten que los clientes verifiquen los recursos web (generalmente URLs) con las listas de recursos web no seguros de Google, que se actualizan constantemente.
| BatchGetHashLists |
|---|
|
Obtiene varias listas de hash a la vez. Es muy común que un cliente necesite obtener varias listas de hash. Se prefiere 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 lo define https://google.aip.dev/231, y el método HTTP también es GET. |
| GetHashList |
|---|
|
Obtiene el contenido más reciente de una lista de hashes. Una lista de hashes puede ser una lista de amenazas o una lista que no sea de amenazas, como la caché global. Este es un método Get estándar según se define en https://google.aip.dev/131, y el método HTTP también es GET. |
| ListHashLists |
|---|
|
Enumera las listas de hashes. En la API v5, Google nunca quitará una lista de hashes que este método haya mostrado. Esto permite que los clientes omitan el uso de este método y simplemente codifiquen de forma rígida todas las listas de hash que necesiten. Este es un método List estándar según se define en https://google.aip.dev/132, y el método HTTP es GET. |
| SearchHashes |
|---|
|
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). |
| SearchUrls |
|---|
|
Busca URLs que coincidan con amenazas conocidas. Se verifica cada URL y sus expresiones de sufijo de host y prefijo de ruta (hasta una profundidad limitada). Esto significa que la respuesta puede contener URLs que no se incluyeron en la solicitud, pero que son expresiones de las URLs solicitadas. |
BatchGetHashListsRequest
Es la solicitud para obtener varias listas de hash al mismo tiempo.
| Campos | |
|---|---|
names[] |
Obligatorio. Son los nombres de las listas de hash específicas. La lista PUEDE ser una lista de amenazas o la caché global. Los nombres NO deben contener duplicados. Si lo hicieran, el cliente recibirá un error. |
version[] |
Son 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 quedar vacío. De lo contrario, el cliente debe proporcionar las versiones que recibió anteriormente 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 las listas correspondientes. El cliente puede enviar menos o más versiones en una solicitud de las que hay nombres. Sin embargo, el cliente NO DEBE enviar varias versiones que correspondan al mismo nombre. Si lo hiciera, el cliente recibirá un error. Nota histórica: En la versión 4 de la API, este campo se llamaba |
size_constraints |
Son las restricciones de tamaño de cada lista. Si se omite, no hay restricciones. Ten en cuenta que los tamaños que se indican aquí son por lista, no agregados en todas las listas. |
BatchGetHashListsResponse
Es la respuesta que contiene varias listas de hashes.
| Campos | |
|---|---|
hash_lists[] |
Son las listas de hash en el mismo orden que se indica en la solicitud. |
FullHash
Es el hash completo identificado con una o más coincidencias.
| Campos | |
|---|---|
full_hash |
Es el hash completo coincidente. Este es el hash SHA256. La longitud será exactamente de 32 bytes. |
full_hash_details[] |
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.
| Campos | |
|---|---|
threat_type |
Es el tipo de amenaza. Este campo nunca estará vacío. |
attributes[] |
Lista sin ordenar. Son atributos adicionales sobre esos hashes completos. Puede estar vacío. |
GetHashListRequest
Es una solicitud para obtener una lista de hashes, que puede ser una lista de amenazas o una lista de no amenazas, como la caché global.
Novedades de la versión 5: Lo que antes se llamaba states en la versión 4 se renombró como version para mayor claridad. Ahora, las listas tienen nombres, y se quitaron los tipos de plataformas y los tipos de entradas de amenazas. Ahora es posible que varias listas tengan el mismo tipo de amenaza o que una sola lista se preocupe por varios tipos de amenazas. A diferencia de los prefijos de hash de longitud variable de la versión 4, 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 |
Obligatorio. Es el nombre de esta lista de hashes en particular. Puede ser una lista de amenazas o la caché global. |
version |
Es 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 hashes, este campo DEBE dejarse vacío. De lo contrario, el cliente DEBE proporcionar la versión que recibió anteriormente del servidor. El cliente NO DEBE manipular esos bytes. Novedades de la versión 5: En la versión 4 de la API, se llamaba |
size_constraints |
Son las restricciones de tamaño de la lista. Si se omite, no hay restricciones. Se recomienda aplicar restricciones en todos los dispositivos con potencia de procesamiento, ancho de banda o almacenamiento limitados. |
HashList
Es una lista de hashes identificados por su nombre.
| Campos | |
|---|---|
name |
Es el nombre de la lista de hashes. Ten en cuenta que la caché global también es solo una lista de hash y se puede consultar aquí. |
version |
Es la versión de la lista de hashes. El cliente NO DEBE manipular esos bytes. |
partial_update |
Cuando es verdadero, se trata de un diff parcial que contiene adiciones y eliminaciones según lo que ya tiene el cliente. Cuando es falso, esta es la lista de hash completa. Si es falso, el cliente DEBE borrar cualquier versión almacenada localmente de esta lista de hashes. Esto significa que la versión que posee el cliente está muy desactualizada o se cree que los datos del cliente están dañados. El campo Cuando es verdadero, el cliente DEBE aplicar una actualización incremental aplicando primero las eliminaciones y, luego, las adiciones. |
compressed_removals |
Es la versión codificada con Rice-delta de los índices de eliminación. Dado que cada lista de hash tiene menos de 2^32 entradas, los índices se tratan como números enteros de 32 bits y se codifican. |
minimum_wait_duration |
Los clientes deben esperar al menos este tiempo para volver a obtener la lista de hashes. Si se omite o es cero, los clientes DEBEN recuperar los datos de inmediato, ya que indica que el servidor tiene una actualización adicional para enviar al cliente, pero no pudo hacerlo debido a las restricciones especificadas por el cliente. |
sha256_checksum |
Es la lista ordenada de todos los hashes, con un nuevo hash SHA256. Es la suma de verificación de la lista ordenada de todos los hashes presentes en la base de datos después de aplicar la actualización proporcionada. En el caso de que no se hayan proporcionado actualizaciones, el servidor omitirá este campo para indicar que el cliente debe usar la suma de verificación existente. |
metadata |
Son los metadatos sobre la lista de hashes. El método |
Campo de unión compressed_additions. Es la versión codificada con Rice-delta de las adiciones. Las longitudes de los prefijos hash de los elementos agregados son uniformes en todos los elementos agregados de la lista. Las direcciones (compressed_additions) solo pueden ser una de las siguientes opciones: |
|
additions_four_bytes |
Las adiciones de 4 bytes. |
additions_eight_bytes |
Son las adiciones de 8 bytes. |
additions_sixteen_bytes |
Las adiciones de 16 bytes. |
additions_thirty_two_bytes |
Las adiciones de 32 bytes |
HashListMetadata
Son los metadatos sobre una lista de hash en particular.
| Campos | |
|---|---|
threat_types[] |
Lista sin ordenar. Si no está vacío, especifica que la lista de hashes es un tipo de lista de amenazas y enumera el tipo de amenazas asociadas con los hashes o los prefijos de hash en esta lista. Puede estar vacío si la entrada no representa una amenaza, es decir, en el caso de que represente un tipo probablemente seguro. |
likely_safe_types[] |
Lista sin ordenar. Si no está vacío, especifica que la lista de hashes representa una lista de hashes probablemente seguros y enumera las formas en que se consideran probablemente seguros. Este campo se excluye mutuamente con el campo threat_types. |
description |
Es una descripción legible sobre esta lista. Está escrito en inglés. |
hash_length |
Es la longitud de hash admitida para esta lista de hashes. Cada lista de hash admitirá exactamente una longitud. Si se introduce una longitud de hash diferente para el mismo conjunto de tipos de amenazas o tipos seguros, se introducirá como una lista separada con un nombre distinto y un conjunto de longitud de hash respectivo. |
HashLength
Es la longitud de los hashes en una lista de hashes.
| Enums | |
|---|---|
HASH_LENGTH_UNSPECIFIED |
Longitud sin especificar. |
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 intencionalmente no contiene LikelySafeType.
| Enums | |
|---|---|
LIKELY_SAFE_TYPE_UNSPECIFIED |
Desconocido. |
GENERAL_BROWSING |
Es probable que este sitio sea lo suficientemente seguro para la navegación general. 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 verificar las descargas. |
ListHashListsRequest
Es la solicitud para enumerar las listas de hash disponibles.
| Campos | |
|---|---|
page_size |
Es la cantidad máxima de listas de hash que se devolverá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 mayor que la cantidad de listas de hash, de modo que no sea necesaria la paginación. |
page_token |
Un token de página, recibido desde una llamada |
ListHashListsResponse
Es la respuesta que contiene metadatos sobre las listas de hashes.
| Campos | |
|---|---|
hash_lists[] |
Las listas de hash se muestran en un orden arbitrario. Solo se incluirán los metadatos sobre las listas de hashes, no el contenido. |
next_page_token |
Un token, que se puede enviar como |
RiceDeltaEncoded128Bit
Es igual que RiceDeltaEncoded32Bit, excepto que codifica números de 128 bits.
| Campos | |
|---|---|
first_value_hi |
Son 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 ceros. |
first_value_lo |
Son los 64 bits inferiores de la primera entrada en los datos codificados (hashes). Si el campo está vacío, los 64 bits inferiores son todos cero. |
rice_parameter |
Es el parámetro de Golomb-Rice. Se garantiza que este parámetro se encuentra entre 99 y 126, inclusive. |
entries_count |
Es la cantidad de entradas que se codifican con delta en los datos codificados. Si solo se codificó un número entero, este será cero y el valor único se almacenará en |
encoded_data |
Son los deltas codificados con el codificador de Golomb-Rice. |
RiceDeltaEncoded256Bit
Es igual que RiceDeltaEncoded32Bit, excepto que codifica números de 256 bits.
| Campos | |
|---|---|
first_value_first_part |
Son los primeros 64 bits de la primera entrada de los datos codificados (hashes). Si el campo está vacío, los primeros 64 bits son todos ceros. |
first_value_second_part |
Bits del 65 al 128 de la primera entrada en los datos codificados (hashes). Si el campo está vacío, los bits del 65 al 128 son todos cero. |
first_value_third_part |
Bits del 129 al 192 de la primera entrada en los datos codificados (hashes). Si el campo está vacío, los bits del 129 al 192 son todos cero. |
first_value_fourth_part |
Son 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 ceros. |
rice_parameter |
Es el parámetro de Golomb-Rice. Se garantiza que este parámetro se encuentre entre 227 y 254, inclusive. |
entries_count |
Es la cantidad de entradas que se codifican con delta en los datos codificados. Si solo se codificó un número entero, este será cero y el valor único se almacenará en |
encoded_data |
Son los deltas codificados con el codificador de Golomb-Rice. |
RiceDeltaEncoded32Bit
Son los datos codificados de Rice-Golomb. Se usa para los hashes o los índices de eliminación. Se garantiza que cada hash o índice aquí tiene la misma longitud, y esta longitud es exactamente de 32 bits.
En general, si ordenamos todas las entradas de forma lexicográfica, observaremos que los bits de orden superior no suelen cambiar con tanta frecuencia como los bits de orden inferior. Esto significa que, si también consideramos la diferencia adyacente entre las entradas, los bits de orden superior tienen una alta probabilidad de ser cero. Esto aprovecha la alta probabilidad de cero eligiendo esencialmente una cierta cantidad de bits; es probable que todos los bits más significativos que este sean cero, por lo que usamos la 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 la versión 5, se realizaron dos mejoras significativas: en primer lugar, la codificación Rice-delta ahora está disponible con prefijos de hash de más de 4 bytes; en segundo lugar, los datos codificados ahora se tratan como big-endian para evitar un paso de ordenamiento costoso.
| Campos | |
|---|---|
first_value |
Es la primera entrada en los datos codificados (hashes o índices) o, si solo se codificó un prefijo de hash o un índice, el valor de esa entrada. Si el campo está vacío, la entrada es cero. |
rice_parameter |
Es el parámetro de Golomb-Rice. Se garantiza que este parámetro se encuentra entre 3 y 30, inclusive. |
entries_count |
Es la cantidad de entradas que se codifican con delta en los datos codificados. Si solo se codificó un número entero, este será cero y el valor único se almacenará en |
encoded_data |
Son los deltas codificados con el codificador de Golomb-Rice. |
RiceDeltaEncoded64Bit
Es igual que RiceDeltaEncoded32Bit, excepto que codifica números de 64 bits.
| Campos | |
|---|---|
first_value |
Es la primera entrada en 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 |
Es el parámetro de Golomb-Rice. Se garantiza que este parámetro se encuentra entre 35 y 62, inclusive. |
entries_count |
Es la cantidad de entradas que se codifican con delta en los datos codificados. Si solo se codificó un número entero, este será cero y el valor único se almacenará en |
encoded_data |
Son los deltas codificados con el codificador de Golomb-Rice. |
SearchHashesRequest
Es una solicitud que el cliente emite para buscar prefijos de hash específicos.
Está diseñado para buscar solo en las listas de amenazas y no en las listas que no son de amenazas, como la caché global.
Novedades de la versión 5: Los clientes no necesitan especificar un ClientInfo ni los estados de las listas de hashes en su base de datos local. Esta medida es para mejorar la privacidad. Además, los clientes no necesitan enviar los tipos de amenazas que les interesan.
| Campos | |
|---|---|
hash_prefixes[] |
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 de hash. Actualmente, cada prefijo de hash debe tener exactamente 4 bytes de longitud. Esta restricción SE PUEDE relajar en el futuro. |
filter |
Opcional. Si el cliente desea aplicar filtros, por ejemplo, para recuperar solo tipos específicos de amenazas, puede especificarlo. Si se omite, se devuelven todas las amenazas que coinciden. Se recomienda omitir este paso 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 El filtro |
SearchHashesResponse
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 full_hashes 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 que tiene 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 cache_duration.
| Campos | |
|---|---|
full_hashes[] |
Lista sin ordenar. Es la lista no ordenada de hashes completos encontrados. |
cache_duration |
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 el campo 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. |
SearchUrlsRequest
Es una solicitud que el cliente emite para buscar amenazas que coincidan con las URLs especificadas.
Está diseñado para buscar solo en las listas de amenazas y no en las listas que no son de amenazas, como la caché global.
| Campos | |
|---|---|
urls[] |
Obligatorio. Son las URLs que se buscarán. Los clientes NO DEBEN enviar más de 50 URLs. |
SearchUrlsResponse
Es la respuesta que se devuelve después de buscar amenazas que coincidan con las URLs especificadas.
Si no se encuentra nada, el servidor devolverá un estado OK (código de estado HTTP 200) con el campo threats vacío, en lugar de devolver un estado NOT_FOUND (código de estado HTTP 404).
| Campos | |
|---|---|
threats[] |
Lista sin ordenar. Es la lista no ordenada de coincidencias de amenazas encontradas. Cada entrada contiene una URL y los tipos de amenazas que se encontraron que coinciden con esa URL. El tamaño de la lista puede ser mayor que la cantidad de URLs en la solicitud, ya que se habrán considerado todas las expresiones de la URL. |
cache_duration |
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 URL que consulta el cliente en la solicitud, independientemente de cuántas URLs se muestren en la respuesta. Incluso si el servidor no devuelve coincidencias para una URL en particular, el cliente TAMBIÉN DEBE almacenar en caché este hecho. Si el campo 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. |
SizeConstraints
Son las restricciones sobre los tamaños de las listas de hash.
| Campos | |
|---|---|
max_update_entries |
Es 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. Debe ser de 1,024 como mínimo. Si se omite o es cero, no se establece ningún límite de tamaño de actualización. |
max_database_entries |
Establece la cantidad máxima de entradas que el cliente está dispuesto a tener en la base de datos local para la lista. (El servidor PUEDE hacer que el cliente almacene menos de esta cantidad de entradas). Si se omite o es cero, no se establece ningún límite de tamaño de la base de datos. |
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 atributo 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 no se debe usar threat_type para la aplicación. |
FRAME_ONLY |
Indica que el threat_type solo se debe usar para la aplicación de políticas en fotogramas. |
ThreatType
Tipos de amenazas
| Enums | |
|---|---|
THREAT_TYPE_UNSPECIFIED |
Tipo de amenaza desconocido. Si el servidor devuelve este valor, el cliente debe ignorar el objeto FullHashDetail que lo contiene. |
MALWARE |
Es el 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 |
Es el tipo de amenaza de ingeniería social. Las páginas de ingeniería social afirman falsamente actuar en nombre de un tercero con la intención de confundir a los usuarios para que realicen una acción en la que solo confiarían en un agente real de ese tercero. El 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 |
Es el tipo de amenaza de software no deseado. El software no deseado es cualquier software que no cumple con los Principios de Software de Google, pero no es software malicioso. |
POTENTIALLY_HARMFUL_APPLICATION |
Es el tipo de amenaza de aplicación potencialmente dañina que usa Google Play Protect para Play Store. |
ThreatUrl
Es una URL que coincide con una o más amenazas.
| Campos | |
|---|---|
url |
Es la URL solicitada que coincidió con una o más amenazas. |
threat_types[] |
Lista sin ordenar. Es la lista no ordenada de amenazas según las cuales se clasifica la URL. |