Usar la API de envío

En este documento, se describe cómo enviar a la Navegación segura para su análisis las URLs que sospechas que son inseguras y cómo verificar de forma asíncrona los resultados de estos envíos. Todas las URLs que se confirmen como infractoras de las Políticas de la Navegación segura se agregan al servicio de la Navegación segura.

Cambios clave en la API de Web Risk Submission

  • Se cerraron los pedidos y las expansiones nuevos: Ya no aceptamos contratos ni expansiones nuevos para la API de Web Risk Submission.
  • Congelamiento de funciones en efecto: La API está en un congelamiento de funciones formal. Ya no lanzaremos nuevas funciones ni mejoras.
  • Renovaciones finales: La fecha final para renovar los contratos existentes es el 31 de diciembre de 2026. Todas las renovaciones tienen un límite de plazo máximo de un año.
  • Disponibilidad del servicio: Los servicios existentes siguen operativos con correcciones de errores críticos, actualizaciones de seguridad y asistencia estándar hasta el final de tu contrato activo. La baja completa se producirá a más tardar el 31 de diciembre de 2027.

Prácticas recomendadas

Lee las Políticas de Navegación Segura

La API de Web Risk Submission valida que las URLs enviadas rendericen contenido que incumpla las políticas de la Navegación segura. Los desarrolladores de APIs deben asegurarse de que las URLs enviadas tengan evidencia clara de incumplimiento de estas políticas. En los siguientes ejemplos, se muestra evidencia de incumplimiento de políticas:

  • Contenido de ingeniería social que imita una marca en línea legítima (nombre de la marca, logotipo, aspecto y estilo), alertas del sistema, usa URLs engañosas o solicita a los usuarios que ingresen credenciales sensibles, como un nombre de usuario o una contraseña
  • Un sitio que aloja un archivo ejecutable de software malicioso conocido

No envíes los siguientes tipos de URLs, ya que es poco probable que se agreguen a la lista de bloqueo de la Navegación segura:

  • Encuestas falsas, sitios de compras o cualquier otra estafa que no demuestre phishing (como las estafas de criptomonedas)
  • Spam que incluye contenido para adultos, de violencia o de juegos de apuestas que no es phishing ni software malicioso

Mejorar la detección

Te recomendamos que uses los campos ThreatInfo y ThreatDiscovery para proporcionar información adicional sobre los envíos. Esto podría ayudar a mejorar la detección. Para obtener más información, consulta Prácticas recomendadas para usar la API de Submission.

Segmentación por taxonomía y por marca

Puedes proporcionar informes de abuso más precisos y detallados si usas los siguientes componentes opcionales en el objeto ThreatInfo: abuseSubtype y targetedBrand. Estos campos ayudan a la Navegación segura a analizar con mayor precisión las entidades objetivo y a mejorar los modelos de detección.

abuseSubtype

El campo abuseSubtype proporciona una clasificación detallada de la amenaza. Asegúrate de que este campo esté configurado solo cuando el abuseType principal sea SOCIAL_ENGINEERING; de lo contrario, se devolverá un error.

Los valores de abuseSubtype admitidos incluyen los siguientes:

  • BANK_PHISHING: Suplantación de identidad (phishing) que se hace pasar por un banco o una entidad financiera de confianza.
  • CRYPTO_EXCHANGE_PHISHING: Phishing que se hace pasar por una plataforma de comercio de criptomonedas.
  • SOCIAL_MEDIA_PLATFORM_PHISHING: Phishing que se hace pasar por una plataforma de redes sociales.
  • RETAIL_PHISHING: Suplantación de identidad (phishing) que se hace pasar por una plataforma de venta minorista establecida.
  • EMAIL_PROVIDER_PHISHING: Phishing que se hace pasar por un servicio de correo electrónico.
  • ENTERTAINMENT_PHISHING: Suplantación de identidad (phishing) que se hace pasar por un servicio de entretenimiento.
  • GOVERNMENT_AGENCY_PHISHING: Phishing que se hace pasar por un organismo gubernamental para obtener información de identificación personal (PII), como un número de seguridad social o un número de identificación del contribuyente.
  • PACKAGE_TRACKING_SCAM: Imitar un servicio de envío para obtener información personal identificable o detalles de pago
  • FAKE_SUPPORT_SCAM: Sitios web engañosos que afirman que hay problemas falsos con el dispositivo para engañar a los usuarios y que compartan su PII o se comuniquen con estafadores.
  • GOVERNMENT_FINE_SCAM: Contenido engañoso que afirma que se debe pagar una multa cívica pendiente.
  • FAKE_PRIZE_SCAM: Páginas engañosas que ofrecen recompensas o premios poco realistas
  • OTHER_PHISHING o OTHER_SCAM: Ataques de ingeniería social que no pertenecen a las otras categorías mencionadas aquí.

targetedBrand

El objeto targetedBrand identifica la entidad a la que se dirigen las campañas de phishing y de ingeniería social.

  • brandName: Es el nombre reconocible de la marca o la empresa que se suplanta (por ejemplo, Altostrat).
  • domain: Es el dominio legítimo de la marca que se suplanta (por ejemplo, altostrat.com).

Notas importantes para los participantes de la versión preliminar

  • Coherencia en la taxonomía: El phishing sigue categorizado en el tipo de amenaza SOCIAL_ENGINEERING (en lugar de un tipo principal PHISHING independiente) para garantizar la coherencia en el conjunto de APIs de Navegación segura y Web Risk.
  • Categorías excluidas: Las subcategorías de MALWARE y UNWANTED_SOFTWARE se excluyen de esta versión.
  • Cómo controlar las amenazas no incluidas en la lista: Si tu envío no se asigna a un subtipo específico, usa OTHER_PHISHING o OTHER_SCAM. Te recomendamos que uses el campo comments en ThreatJustification para describir el ataque.
  • Opcional, pero se recomienda: Proporcionar estos campos ayuda a Web Risk a priorizar y mejorar los modelos de inteligencia contra amenazas asociados.
  • Fase de vista previa: Los valores de enumeración y el comportamiento de esta función están sujetos a cambios.

Envía URLs

Para enviar una URL, envía una solicitud HTTP POST al método projects.uris.submit.

  • La API de Submission admite una URL por solicitud. Si deseas verificar varias URL, debes enviar una solicitud diferente para cada una.

  • La URL debe ser válida, pero no es necesario que esté canonizada. Para obtener más información, consulta RFC 2396.

  • La respuesta HTTP POST muestra una long-running operation. Para obtener más información sobre cómo recuperar el resultado de la entrega y verificar el estado de una entrega, consulta Operaciones de larga duración.

Ejemplo

Método HTTP y URL:

POST https://webrisk.googleapis.com/v1/projects/project-id/uris:submit

Cuerpo JSON de la solicitud:

{
  "submission": {
    "uri": "https://www.example.com/login.html"
  }
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://webrisk.googleapis.com/v1/projects/project-id/uris:submit"

PowerShell

Guarda el cuerpo de la solicitud en un archivo llamado request.json y ejecuta el siguiente comando: 

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

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://webrisk.googleapis.com/v1/projects/project-id/uris:submit" | Select-Object -Expand Content

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

{
  "name": "projects/project-number/operations/operation-id",
}

Cómo verificar el estado del envío

Usa project-number y operation-id de la respuesta para verificar el estado del envío. El estado se encuentra en el campo metadata.state de la operación devuelta.

Los estados posibles incluyen RUNNING, SUCCEEDED y CLOSED. Para obtener más información sobre estos estados, consulta Understanding Operation Status en la guía de Operaciones de larga duración.