Usa la API de Update
Descripción general
La API de Update permite que tus aplicaciones cliente descarguen versiones con hash de las listas de Web Risk para el almacenamiento en una base de datos local o en la memoria. Por lo tanto, las URL se pueden verificar de forma local. Cuando se encuentra una coincidencia en la base de datos local, el cliente envía una solicitud a los servidores de Web Risk para verificar si la URL se incluye en las listas de Web Risk.
Actualiza la base de datos local
Para mantenerse actualizados, los clientes deben actualizar las listas de Web Risk en sus bases de datos locales de forma periódica. Para ahorrar ancho de banda, los clientes descargan los prefijos de hash de las URL, en lugar de las URL sin procesar. Por ejemplo, si “www.badurl.com/” está en una lista de Web Risk, los clientes descargan el prefijo de hash SHA256 de esa URL, en lugar de la URL en sí. En la mayoría de los casos, los prefijos de hash tienen 4 bytes de longitud, lo que significa que el costo promedio del ancho de banda para la descarga de una sola entrada de lista es de 4 bytes antes de la compresión.
Para actualizar las listas de Web Risk en la base de datos local, envía una solicitud GET
HTTP al método threatLists.computeDiff
:
- La solicitud
GET
HTTP incluye el nombre de la lista que se actualizará junto con las restricciones del cliente para atenerse a las limitaciones de memoria y ancho de banda. - La respuesta HTTP
GET
muestra una actualización completa o una actualización parcial. La respuesta también podría mostrar un tiempo de espera recomendado hasta la siguiente operación de diferencia de procesamiento.
Ejemplo: threatLists.computeDiff
Solicitud HTTP GET
En el siguiente ejemplo, se solicitan las diferencias para la lista de Web Risk de MALWARE. Para obtener más detalles, consulta los parámetros de búsqueda threatLists.computeDiff
y las explicaciones que siguen al ejemplo de código.
Método HTTP y URL:
GET https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW&key=API_KEY
Para enviar tu solicitud, elige una de estas opciones:
curl
Ejecuta el siguiente comando:
curl -X GET \
"https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW&key=API_KEY"
PowerShell
Ejecuta el siguiente comando:
$headers = @{ }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW&key=API_KEY" | Select-Object -Expand Content
Deberías recibir una respuesta JSON similar a la que se muestra a continuación:
{ "recommendedNextDiff": "2020-01-08T19:41:45.436722194Z", "responseType": "RESET", "additions": { "rawHashes": [ { "prefixSize": 4, "rawHashes": "AArQMQAMoUgAPn8lAE..." } ] }, "newVersionToken": "ChAIARAGGAEiAzAwMSiAEDABEPDyBhoCGAlTcIVL", "checksum": { "sha256": "wy6jh0+MAg/V/+VdErFhZIpOW+L8ulrVwhlV61XkROI=" } }
Java
Python
Listas de Web Risk
El campo threatType
identifica la lista de Web Risk. En el ejemplo, se solicitan las diferencias de la lista de Web Risk de software malicioso.
Token de la versión
El campo versionToken
contiene el estado actual del cliente de la lista de Web Risk.
Los tokens de la versión se muestran en el campo newVersionToken
de la respuesta threatLists.computeDiff.
Para las actualizaciones iniciales, deja el campo versionToken
vacío.
Restricciones de tamaño
El campo maxDiffEntries
especifica la cantidad total de actualizaciones que el cliente puede administrar (en el ejemplo, 2048). El campo maxDatabaseEntries
especifica la cantidad total de entradas que la base de datos local puede administrar (en el ejemplo, 4096). Los clientes deben establecer restricciones de tamaño para proteger la memoria
y limitaciones de ancho de banda, así como
para protegerse del crecimiento de la lista. Para obtener más información, consulta Actualiza restricciones.
Compresiones admitidas
En el campo supportedCompressions
, se enumeran los tipos de compresión que admite el cliente. En el ejemplo, el cliente solo admite datos sin procesar y sin comprimir.
Sin embargo, Web Risk admite tipos de compresión adicionales. Para obtener más información, consulta Compresión.
Respuesta HTTP GET
En este ejemplo, la respuesta muestra una actualización parcial de la lista de Web Risk con el tipo de compresión solicitado.
Cuerpo de la respuesta
En el cuerpo de la respuesta, se incluye la información de las diferencias (el tipo de respuesta, las adiciones y eliminaciones que se aplicarán a la base de datos local, el token de la versión nueva y una suma de verificación).
En el ejemplo, en la respuesta también se incluye el próximo tiempo de diferencia recomendado. Para obtener más detalles, consulta el cuerpo de la respuesta threatLists.computeDiff
y las explicaciones que siguen al ejemplo del código.
{ "responseType" : "DIFF", "recommendedNextDiff": "2019-12-31T23:59:59.000000000Z", "additions": { "compressionType": "RAW", "rawHashes": [{ "prefixSize": 4, "rawHashes": "rnGLoQ==" }] }, "removals": { "rawIndices": { "indices": [0, 2, 4] } }, "newVersionToken": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd", "checksum": { "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM=" }, "recommendedNextDiff": "2019-07-17T15:01:23.045123456Z" }
Diferencias de la base de datos
En el campo responseType
, se indicará una actualización parcial (DIFF
) o una actualización completa (RESET
). En el ejemplo, se muestran diferencias parciales, por lo que en la respuesta se incluyen las adiciones y las eliminaciones. Podría haber varios conjuntos de adiciones, pero solo un conjunto de eliminaciones. Para obtener más información, consulta Diferencias de la base de datos.
Nuevo token de versión
El campo newVersionToken
contiene el nuevo token de versión de la lista de Web Risk recientemente actualizada. Los clientes deben guardar el nuevo estado del cliente para las solicitudes de actualización posteriores (el campo versionToken
en la solicitud threatLists.computeDiff
).
Sumas de verificación
La suma de verificación permite que los clientes verifiquen que la base de datos local no haya sufrido ningún daño. Si la suma de verificación no coincide, el cliente debe borrar la base de datos y volver a emitir una actualización con un campo versionToken
vacío. Sin embargo, los clientes en esta situación aún deben respetar los intervalos de tiempo para las actualizaciones. Para obtener más información, consulta Frecuencia de solicitud.
Diferencia siguiente recomendada
En el campo recommendedNextDiff
, se indica una marca de tiempo hasta la que el cliente debe esperar antes de enviar otra solicitud de actualización. Ten en cuenta que el período de espera recomendado puede o no incluirse en la respuesta. Para obtener más detalles, consulta Frecuencia de solicitud.
Verifica las URL
Para verificar si una URL se incluyó en una lista de Web Risk, el cliente primero debe calcular el hash y el prefijo de hash de la URL. Para obtener más detalles, consulta URL y hashing. Luego, el cliente debe consultar la base de datos local para determinar si existe una coincidencia. Si el prefijo de hash no está presente en la base de datos local, se considera que la URL es segura (es decir, que no se encuentra en las listas de Web Risk).
Si el prefijo de hash está presente en la base de datos local (una colisión del prefijo de hash), el cliente debe enviar el prefijo de hash a los servidores de Web Risk para que sea verificado. Los servidores mostrarán todos los hashes SHA 256 de longitud completa que contienen el prefijo de hash proporcionado. Si uno de esos hashes de longitud completa coincide con el hash de longitud completa de la URL en cuestión, se considera que la URL no es segura. Si ninguno de los hashes de longitud completa coincide con el hash de longitud completa de la URL en cuestión, esa URL se considera segura.
Google no aprende en ningún momento las URL que estás examinando. Google sí aprende los prefijos de hash de las URL, pero estos no proporcionan mucha información sobre las URL reales.
Para verificar si una URL está en una lista de Web Risk, envía una solicitud HTTP GET
al método hashes.search
:
- En la solicitud HTTP
GET
, se incluye el prefijo de hash de la URL que se debe verificar. - La respuesta
GET
HTTP muestra los hash completos coincidentes junto con los tiempos de vencimiento positivos y negativos.
Ejemplo: hashes.search
Solicitud HTTP GET
En el siguiente ejemplo, los nombres de dos listas de Web Risk y un prefijo hash se envían para que se comparen y verifiquen. Para obtener más detalles, consulta los parámetros de búsqueda hashes.search
y las explicaciones que siguen al ejemplo de código.
curl \ -H "Content-Type: application/json" \ "https://webrisk.googleapis.com/v1/hashes:search?key=YOUR_API_KEY&threatTypes=MALWARE&threatTypes=SOCIAL_ENGINEERING&hashPrefix=WwuJdQ%3D%3D"
Java
Python
Listas de Web Risk
El campo threatTypes
identifica las listas de Web Risk. En el ejemplo, se identifican dos listas: MALWARE
y SOCIAL_ENGINEERING
.
Prefijos hash de amenazas
El campo hashPrefix
contiene el prefijo de hash de la URL que deseas verificar. Este campo debe contener el prefijo de hash exacto que se encuentra en la base de datos local. Por ejemplo, si el prefijo de hash local tiene 4 bytes de longitud, el campo hashPrefix
debe tener 4 bytes de longitud. Si el prefijo de hash local tiene una longitud de 7 bytes, el campo hashPrefix
debe ser tener 7 bytes.
Respuesta HTTP GET
En el siguiente ejemplo, la respuesta muestra las amenazas coincidentes, que contienen las listas de Web Risk con las que coincidieron, junto con los plazos de vencimiento.
Cuerpo de la respuesta
En el cuerpo de la respuesta, se incluye la información de la coincidencia (los nombres de la lista, los hashes de longitud completa y las duraciones de la caché). Para obtener más detalles, consulta el cuerpo de la respuesta hashes.search
y las explicaciones que siguen al ejemplo del código.
{ "threats": [{ "threatTypes": ["MALWARE"], "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4=" "expireTime": "2019-07-17T15:01:23.045123456Z" }, { "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"], "hash": "WwuJdQxaCSH453-uytERC456gf45rFExcE23F7-hnfD=" "expireTime": "2019-07-17T15:01:23.045123456Z" }, }], "negativeExpireTime": "2019-07-17T15:01:23.045123456Z" }
Coinciden
El campo threats
muestra un hash de longitud total que coincide con el prefijo hash.
Las URL correspondientes a estos hash se consideran inseguras. Si no se encuentra ninguna coincidencia para un prefijo hash, no se muestra nada; la URL correspondiente a ese prefijo hash se considera segura.
Fecha de expiración
En los campos expireTime
y negativeExpireTime
, se indica hasta qué punto los hashes se deben considerar como no seguros o seguros, respectivamente. Para obtener más detalles, consulta Almacenamiento en caché.