Usa la API de Update

Resumen

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"

Para enviar tu solicitud, elige una de estas opciones:

curl

Ejecuta el siguiente comando:

curl -X GET \
-H "Authorization: Bearer "$(gcloud auth application-default print-access-token) \
"https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW"

PowerShell

Ejecuta el siguiente comando:

$cred = gcloud auth application-default print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

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"" | 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="
  }
}

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 solo si tienen limitaciones de memoria o de ancho de banda. 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.

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"

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é.