Descripción general
La API de Update permite que tus aplicaciones cliente descarguen versiones con hash de las listas de Navegación segura para almacenarlas en una base de datos local. Las URLs se pueden verificar de forma local. Solo si se encuentra una coincidencia en la base de datos local, el cliente debe enviar una solicitud a los servidores de Navegación segura para verificar si la URL está incluida 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 la base de datos en Bases de datos locales.
Actualiza la base de datos local
Para mantenerse al día, los clientes deben actualizar periódicamente las listas de Navegación segura en su base de datos local. Para ahorrar ancho de banda, los clientes descargan los prefijos hash de las URL en lugar de las URL sin procesar. Por ejemplo, si "www.badurl.com/" está en una lista de Navegación segura, los clientes descargan el prefijo hash SHA256 de esa URL en lugar de la URL en sí. En la mayoría de los casos, los prefijos de hash tienen una longitud de 4 bytes, lo que significa que el costo de ancho de banda promedio de descargar 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 HTTP POST al método threatListUpdates.fetch:
- La solicitud HTTP
POSTincluye los nombres de las listas que se actualizarán junto con varias restricciones de cliente para tener en cuenta 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 también 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 la 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 y el estado de la lista, y las restricciones del cliente). Para obtener más detalles, consulta el cuerpo de la solicitudthreatListUpdates.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 única una implementación 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 uno que represente la verdadera identidad del cliente, como el nombre de tu empresa, presentado como una sola palabra, en letras 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: MALWARE/WINDOWS/URL. Antes de enviar una solicitud, asegúrate de que las combinaciones de tipos que especifiques sean válidas (consulta 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 de los clientes 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 la cantidad total de actualizaciones que el cliente puede administrar (en el ejemplo, 2,048). El campo maxDatabaseEntries especifica la cantidad total de entradas que puede administrar la base de datos local (en el ejemplo, 4,096). Los clientes deben establecer restricciones de tamaño para proteger las limitaciones de memoria y ancho de banda, y para evitar el crecimiento de las listas. Para obtener más información, consulta Actualiza las restricciones.
Compresiones admitidas
El campo supportedCompressions enumera 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 adicionales (consulta Compresión).
Respuesta HTTP POST
En este ejemplo, la respuesta muestra una actualización parcial para la lista de Navegación segura con el tipo de compresión solicitado.
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 solicitud).
HTTP/1.1 200 OK Content-Type: application/json
Cuerpo de la respuesta
El cuerpo de la respuesta incluye la información de la actualización (el nombre de la lista, el tipo de respuesta, las adiciones y eliminaciones que se aplicarán a la base de datos local, el nuevo estado de cliente y una suma de verificación). En el ejemplo, la respuesta también incluye una duración mínima de espera. Para obtener más detalles, consulta el cuerpo de la respuestathreatListUpdates.fetch y las explicaciones que siguen al ejemplo de 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 tanto adiciones como eliminaciones. Puede haber varios conjuntos de adiciones, pero solo un conjunto de eliminaciones (consulta Actualizaciones de bases de datos).
Estado de cliente nuevo
El campo newClientState contiene el nuevo estado de cliente para la lista de Navegación segura recién actualizada.
Los clientes deben guardar el nuevo estado del cliente para las solicitudes de actualización posteriores (el campo state en la solicitudthreatListUpdates.fetch o el campo clientStates en la solicitud fullHashes.find).
Sumas de verificación
La suma de verificación permite a los clientes verificar que la base de datos local no haya sufrido daños. 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 state vacío. Sin embargo, los clientes en esta situación deben seguir los intervalos de tiempo para las actualizaciones (consulta Frecuencia de solicitud).
Duraciones mínimas de espera
El campo minimumWaitDuration indica que el cliente debe esperar 593.44 segundos (9.89 minutos) antes de enviar otra solicitud de actualización. Ten en cuenta que un período de espera puede incluirse o no en la respuesta (consulta la Frecuencia de solicitud).
Verifica las URL
Para verificar si una URL está en una lista de Navegación segura, el cliente primero debe procesar el hash y el prefijo de hash de la URL (consulta URL y hash). Luego, el cliente consulta la base de datos local para determinar si hay una coincidencia. Si el prefijo de hash no está presente en la base de datos local, la URL se considera segura (no en las listas de Navegación segura).
Si el prefijo de hash está presente en la base de datos local (una colisión de prefijos de hash), el cliente debe enviar el prefijo de hash a los servidores de Navegación segura para su verificación. Los servidores mostrarán todos los hash SHA 256 de longitud completa que contengan el prefijo de hash dado. Si uno de esos hashes completos coincide con el de la URL en cuestión, se considera que no es segura. Si ninguno de los hashes completos coincide con el de la URL en cuestión, se considera que esa URL es segura.
Google no aprende en ningún momento las URL que estás examinando. Google aprende los prefijos hash de las URLs, pero no proporcionan mucha información sobre las URLs reales.
Para verificar si una URL está en una lista de Navegación segura, envía una solicitud HTTP POST al método fullHashes.find:
- La solicitud HTTP
POSTpuede incluir hasta 500 entradas de amenazas. - La solicitud HTTP
POSTincluye los prefijos hash de las URLs que se deben verificar. Se recomienda a los clientes que agreguen varias entradas de amenazas en una sola solicitud para reducir el uso del ancho de banda. - La respuesta HTTP
POSTmuestra los hashes de longitud completa coincidentes junto con las duraciones de caché positivas y negativas. La respuesta puede mostrar una duración de espera mínima.
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 su comparación y verificación.
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/fullHashes:find?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), los estados del cliente y la información de las amenazas (los nombres de la lista y los prefijos hash). Para las solicitudes JSON, los prefijos hash se deben enviar con codificación base64. Para obtener más detalles, consulta el cuerpo de la solicitud fullHashes.find y las explicaciones que siguen al ejemplo de 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 manera única una implementación 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 uno que represente la verdadera identidad del cliente, como el nombre de tu empresa, presentado como una sola palabra, en letras minúsculas.
Todos los estados del cliente
El campo clientStates contiene los estados de cliente para todas las listas de Navegación segura de la base de datos local del cliente. (los estados de los clientes 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 especifiques sean válidas (consulta Listas de navegación segura).
Prefijos hash de amenazas
El array ThreatEntries contiene los prefijos hash de las URLs que quieres verificar.
El campo hash debe contener el prefijo hash exacto que está presente en la base de datos local. Por ejemplo, si el prefijo hash local tiene 4 bytes, la entrada de la amenaza debe tenerla. Si el prefijo hash local se alargó a 7 bytes, la entrada de la amenaza debe tener una longitud de 7 bytes.
En el ejemplo, la solicitud incluye tres prefijos 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 coincidente.
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 muestra los datos coincidentes, organizados por la lista de Navegación segura, junto con la duración de la caché y los tiempos de 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 solicitud).
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 la lista y los hashes de longitud completa, los metadatos, si están disponibles, y las duraciones de la caché). En el ejemplo, el cuerpo de la respuesta también incluye una duración mínima de espera. Para obtener más detalles, consulta el cuerpo de respuesta fullHashes.find y las explicaciones que siguen al ejemplo de 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"
}
Mostrar coincidencias
El objeto Matches muestra un hash de longitud completa coincidente para dos de los prefijos de hash. Las URLs que corresponden a estos hashes se consideran no seguras. No se encontró ninguna coincidencia para el tercer prefijo de hash, por lo que no se muestra nada; la URL correspondiente a este prefijo de 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 varios hashes completos que se asignen al mismo prefijo de hash.
Metadata
El campo threatEntryMetadata es opcional y proporciona información adicional sobre la coincidencia de la amenaza. 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 que los hashes se deben considerar no seguros o seguros (consulta Almacenamiento en caché).
Duraciones mínimas de espera
El campo minimumWaitDuration indica que el cliente debe esperar 300 segundos (5 minutos) antes de enviar otra solicitud fullHashes. Ten en cuenta que un período de espera puede incluirse o no en la respuesta (consulta la Frecuencia de solicitud).