Descripción general
La API de Update permite que las aplicaciones cliente descarguen versiones con codificación hash de las listas de Navegación segura para en una base de datos local. Luego, es posible verificar las URLs de forma local. Solo si se encuentra una coincidencia en el base de datos local, si el cliente necesita enviar una solicitud a los servidores de Navegación segura para verificarla si la URL se incluye en las listas de Navegación segura.
Antes de usar la API de Update, debes configurar una base de datos local. La Navegación segura proporciona un paquete de Go que puedes usar para comenzar. Para obtener más detalles, consulta la sección Configuración de bases de datos en Bases de datos locales.
Actualiza la base de datos local
Para mantenerse actualizados, los clientes deben actualizar las listas de Navegación segura en sus bases de datos locales de forma periódica. Para ahorrar ancho de banda, los clientes descargan los prefijos hash de las URLs en lugar del URLs sin procesar. Por ejemplo, si "www.urlmal.com/" está en una lista de Navegación segura, los clientes descargan el Hay un 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 Navegación segura en la base de datos local, envía una solicitud POST HTTP al
threatListUpdates.fetch
método:
- La solicitud
POSTHTTP incluye los nombres de las listas que se actualizarán junto con varias restricciones del cliente para atenerse a las limitaciones de memoria y ancho de banda. - La respuesta HTTP
POSTmuestra una actualización completa o una actualización parcial. La respuesta puede mostrar una duración de espera mínima.
Ejemplo: threatListUpdates.fetch
Solicitud HTTP POST
En el siguiente ejemplo, se solicitan las actualizaciones para una sola lista de Navegación segura.
Encabezado de la solicitud
El encabezado de la solicitud incluye la URL de la solicitud y el tipo de contenido. Recuerda sustituir tu clave de API por API_KEY en la URL.
POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1 Content-Type: application/json
Cuerpo de la solicitud
El cuerpo de la solicitud incluye la información del cliente (ID y versión) y la información de actualización (el nombre de la lista, el estado de la lista y las restricciones del cliente). Para obtener más detalles, consulta el cuerpo de la solicitud threatListUpdates.fetch y las explicaciones que siguen al ejemplo de código.
{ "client": { "clientId": "yourcompanyname", "clientVersion": "1.5.2" }, "listUpdateRequests": [{ "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "state": "Gg4IBBADIgYQgBAiAQEoAQ==", "constraints": { "maxUpdateEntries": 2048, "maxDatabaseEntries": 4096, "region": "US", "supportedCompressions": ["RAW"] } }] }
Información del cliente
Los campos clientID y clientVersion deben identificar de manera inequívoca a una implementación cliente, no a una
usuario individual. (La información del cliente se usa en el registro del lado del servidor. Puedes elegir
cualquier nombre para el ID de cliente, pero te sugerimos que elijas uno que represente la verdadera identidad del
cliente, como el nombre de su empresa, presentados todas en una sola palabra y en minúsculas).
Listas de Navegación segura
Los campos threatType, platformType y threatEntryType se combinan para identificar (nombre) las listas de Navegación segura. En el ejemplo, se identifica una lista:
SOFTWARE MALICIOSO/WINDOWS/URL. Antes de enviar una solicitud, asegúrate de que las combinaciones de tipos que especifiques sean válidas (consulta las listas de Navegación segura).
Estado del cliente
El campo state contiene el estado actual del cliente de la lista de Navegación segura.
(Los estados del cliente se muestran en el campo newClientState de la respuesta threatListUpdates.fetch).
Para las actualizaciones iniciales, deja el campo state vacío.
Restricciones de tamaño
El campo maxUpdateEntries especifica el número 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 las limitaciones de memoria y ancho de banda, así como de protección
el crecimiento. Para obtener más información,
(consulta Actualiza las 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, la Navegación segura admite
tipos de compresión (consulta Compresión).
Respuesta HTTP POST
En este ejemplo, la respuesta devuelve una actualización parcial para la lista de Navegación segura con el parámetro tipo de compresión solicitada.
Encabezado de respuesta
El encabezado de respuesta incluye el código de estado HTTP y el tipo de contenido. Los clientes que reciben un código de estado distinto de HTTP/200 deben ingresar al modo de retirada. (consulta Frecuencia de las solicitudes).
HTTP/1.1 200 OK Content-Type: application/json
Cuerpo de la respuesta
El cuerpo de la respuesta incluye la información de actualización (el nombre de la lista, el tipo de respuesta, adiciones y eliminaciones que se aplicarán a la base de datos local, el cliente nuevo estado y una suma de comprobación). En el ejemplo, la respuesta también incluye una duración de espera mínima. Para ver más detalles, consulta la cuerpo de respuesta dethreatListUpdates.fetch y las explicaciones que siguen al ejemplo del código.
{
"listUpdateResponses": [{
"threatType": "MALWARE",
"threatEntryType": "URL",
"platformType": "WINDOWS",
"responseType" : "PARTIAL_UPDATE",
"additions": [{
"compressionType": "RAW",
"rawHashes": {
"prefixSize": 4,
"rawHashes": "rnGLoQ=="
}
}],
"removals": [{
"compressionType": "RAW",
"rawIndices": {
"indices": [0, 2, 4]
}
}],
"newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
"checksum": {
"sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
}
}],
"minimumWaitDuration": "593.440s"
}Actualizaciones de bases de datos
El campo responseType indicará una actualización parcial o completa. En el ejemplo, se muestra una actualización parcial, por lo que la respuesta incluye las adiciones y las eliminaciones. Puede haber varios conjuntos de adiciones, pero solo un conjunto de eliminaciones (consulta Actualizaciones de la base de datos).
Estado de cliente nuevo
El campo newClientState contiene el nuevo estado de cliente para la lista de Navegación segura recientemente actualizada.
Los clientes deben guardar el nuevo estado del cliente para las solicitudes de actualización posteriores (el campo state en la solicitud threatListUpdates.fetch o el campo clientStates en la solicitud fullHashes.find).
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 el botón
de suma de comprobación no coincide, el cliente debe borrar la base de datos y volver a emitir una actualización con una
state. Sin embargo, los clientes en esta situación deben seguir los intervalos de tiempo para las actualizaciones.
(consulta Frecuencia de las solicitudes).
Duraciones de espera mínimas
En el campo minimumWaitDuration, se indica que el cliente debe esperar 593.44 segundos (9.89 minutos) antes de enviar otra solicitud de actualización. Ten en cuenta que el período de espera puede o no incluirse en el
(consulta Frecuencia de las solicitudes).
Verifica las URL
Para verificar si una URL se incluyó en una lista de Navegación segura, el cliente primero debe calcular el hash y el prefijo de hash de la URL (consulta URL y hashing). Luego, el cliente consulta 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 (no se encuentra en las listas de Navegación segura).
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 Navegación segura para que sea verificado. Los servidores mostrarán todos los hash SHA 256 de longitud completa que contengan 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 completos coincide con el hash completo de la URL en cuestión, la URL se considera segura.
Google no aprende en ningún momento las URL que estás examinando. Google aprende el hash prefijos de las URLs, pero los prefijos hash no proporcionan mucha información sobre las URLs reales.
Para comprobar si una URL está en una lista de Navegación segura, envía una solicitud POST HTTP al
fullHashes.find
método:
- La solicitud HTTP
POSTpuede incluir hasta 500 entradas de amenazas. - En la solicitud HTTP
POST, se incluyen los prefijos de hash de las URLs que se deben verificar. Los clientes son se recomienda agrupar varias entradas de amenazas en una sola solicitud para reducir el uso del ancho de banda. - La respuesta HTTP
POSTmuestra los hash completos coincidentes junto con las duraciones de caché positivas y negativas. La respuesta también puede mostrar una duración mínima de espera.
Ejemplo: fullHashes.find
Solicitud HTTP POST
En el siguiente ejemplo, se envían los nombres de dos listas de Navegación segura y tres prefijos hash para que se comparen y verifiquen.
Encabezado de la solicitud
El encabezado de la solicitud incluye la URL de la solicitud y el tipo de contenido. Recuerda reemplazar
tu clave de API para API_KEY en la URL.
POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1 Content-Type: application/json
Cuerpo de la solicitud
En el cuerpo de la solicitud, se incluye la información del cliente (ID y versión), los estados del cliente y la información de amenazas (los nombres de las listas y los prefijos de hash). En el caso de las solicitudes JSON, los prefijos de hash deben enviarse en formato codificado en base64. Para obtener más detalles, consulta la Cuerpo de la solicitud de fullHashes.find y las explicaciones que siguen al ejemplo del código.
{
"client": {
"clientId": "yourcompanyname",
"clientVersion": "1.5.2"
},
"clientStates": [
"ChAIARABGAEiAzAwMSiAEDABEAE=",
"ChAIAhABGAEiAzAwMSiAEDABEOgH"
],
"threatInfo": {
"threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"],
"platformTypes": ["WINDOWS"],
"threatEntryTypes": ["URL"],
"threatEntries": [
{"hash": "WwuJdQ=="},
{"hash": "771MOg=="},
{"hash": "5eOrwQ=="}
]
}
}Información del cliente
Los campos clientID y clientVersion deben identificar de forma única una implementación de cliente, no un usuario individual. (La información del cliente se usa en el registro del servidor. Puedes elegir cualquier nombre para el
ID de cliente, pero te sugerimos que elijas un nombre que represente la verdadera identidad del cliente, como
el nombre de tu empresa, presentado en una sola palabra y en minúsculas).
Todos los estados del cliente
El campo clientStates contiene los estados de cliente de todas las listas de Navegación segura en
la base de datos local del cliente. (Los estados del cliente se muestran en el campo newClientState de la respuesta threatListUpdates.fetch).
Listas de Navegación segura
Los campos threatTypes, platformTypes y threatEntryTypes se combinan para identificar (nombre) las listas de Navegación segura. En el ejemplo, se identifican dos listas: MALWARE/WINDOWS/URL y SOCIAL_ENGINEERING/WINDOWS/URL. Antes de enviar una solicitud, asegúrate de que las combinaciones de tipos que
que especificas son válidos (consulta Listas de Navegación segura).
Prefijos hash de amenazas
La matriz de las entradas de amenazas contiene los prefijos hash de las URL que quieres comprobar.
El campo hash 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, la entrada de amenaza debe tener 4 bytes de longitud. Si el botón
el prefijo de hash local se alargó a 7 bytes y, luego, la entrada de la amenaza debe tener 7 bytes de largo.
En el ejemplo, la solicitud incluye tres prefijos de hash. Los tres prefijos se compararán con cada una de las listas de Navegación segura para determinar si hay un hash de longitud completa que coincida.
Nota: La API de Update y el método fullHashes.find siempre deben usar el campo hash, nunca el campo URL (consulta ThreatEntry).
Respuesta HTTP POST
En el siguiente ejemplo, la respuesta devuelve los datos coincidentes, organizados por lista de Navegación segura. junto con las duraciones de caché y espera.
Encabezado de respuesta
El encabezado de respuesta incluye el código de estado HTTP y el tipo de contenido. Los clientes que reciben un código de estado distinto de HTTP/200 deben retirarse (consulta Frecuencia de solicitudes).
HTTP/1.1 200 OK Content-Type: application/json
Cuerpo de la respuesta
El cuerpo de la respuesta incluye la información de coincidencia (los nombres de las listas y los hashes completos, los metadatos, si están disponibles, y las duraciones de la caché). En el ejemplo, el cuerpo de la respuesta también incluye un la duración mínima de espera. Para obtener más detalles, consulta la Cuerpo de la respuesta de fullHashes.find y las explicaciones que siguen al ejemplo del código.
{ "matches": [{ "threatType": "MALWARE", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": { "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4=" }, "threatEntryMetadata": { "entries": [{ "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==", // base64-encoded "malware_threat_type" "value": "TEFORElORw==" // base64-encoded "LANDING" }] }, "cacheDuration": "300.000s" }, { "threatType": "SOCIAL_ENGINEERING", "platformType": "WINDOWS", "threatEntryType": "URL", "threat": { "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA=" }, "threatEntryMetadata": { "entries": [] }, "cacheDuration": "300.000s" }], "minimumWaitDuration": "300.000s", "negativeCacheDuration": "300.000s" }
Combinaciones
El objeto Matches muestra un hash coincidente de longitud completa para dos de los prefijos de hash. Las URLs correspondientes a estos hashes se consideran poco seguros. No se encontró ninguna coincidencia para el tercer prefijo hash, por lo que no se muestra nada; la URL correspondiente a este prefijo hash se considera segura.
Ten en cuenta que este ejemplo hace coincidir un hash de longitud completa con un prefijo de hash. sin embargo, podría haber en varios hashes completos que se asignan al mismo prefijo de hash.
Metadatos
El campo threatEntryMetadata es opcional y proporciona información adicional sobre la coincidencia de amenazas. Actualmente, los metadatos están disponibles para la lista de Navegación segura de MALWARE/WINDOWS/URL (consulta Metadatos).
Duraciones de la caché
Los campos cacheDuration y negativeCacheDuration indican la cantidad.
de tiempo los hashes se deben
se consideran inseguros o seguros (consulta Almacenamiento en caché).
Duraciones de espera mínimas
El campo minimumWaitDuration indica que el cliente debe esperar 300 segundos (5 minutos) antes
enviando otra solicitud fullHashes. Ten en cuenta que se puede incluir o no un período de espera en la respuesta.
(consulta Frecuencia de las solicitudes).