Utiliser l'API Submission

Ce document explique comment envoyer des URL que vous pensez ne pas être sécurisées à l'équipe chargée de la navigation sécurisée pour qu'elle les analyse, et comment vérifier de manière asynchrone les résultats de ces envois. Toutes les URL confirmées comme étant conformes aux règles de navigation sécurisée sont ajoutées au service de navigation sécurisée.

Avant de commencer

Contactez le service commercial ou votre ingénieur client pour accéder à cette fonctionnalité.

Bonnes pratiques

Consulter les règles de navigation sécurisée

L'API Submission Web Risk vérifie que les URL envoyées affichent un contenu qui enfreint les règles de navigation sécurisée policies. Les développeurs d'API doivent s'assurer que les URL envoyées présentent des preuves claires de violation de ces règles. Voici quelques exemples de violation des règles :

  • Contenu d'ingénierie sociale qui imite une marque en ligne légitime (nom de marque, logo, apparence), alertes système, utilisation d'URL trompeuses ou demande aux utilisateurs de saisir des identifiants sensibles tels qu'un nom d'utilisateur ou un mot de passe.
  • Site hébergeant un exécutable de logiciel malveillant connu.

N'envoyez pas les types d'URL suivants, car ils ne seront probablement pas ajoutés à la liste de blocage de la navigation sécurisée :

  • Faux sondages, sites d'achat ou autres escroqueries qui ne démontrent pas d'hameçonnage (escroqueries liées aux cryptomonnaies, par exemple).
  • Spam contenant des jeux d'argent, de la violence ou du contenu pour adultes qui ne sont pas de l'hameçonnage ni des logiciels malveillants.

Améliorer la détection

Nous vous recommandons d'utiliser les champs ThreatInfo et ThreatDiscovery pour fournir des informations supplémentaires sur les envois. Cela peut contribuer à améliorer la détection. Pour en savoir plus, consultez les bonnes pratiques d'utilisation de l'API Submission.

Taxonomie et ciblage de marque

Vous pouvez fournir des rapports d'abus plus précis et détaillés en utilisant les composants facultatifs suivants dans l'objet ThreatInfo : abuseSubtype et targetedBrand. Ces champs aident Web Risk à analyser plus précisément les entités ciblées et à améliorer les modèles de détection.

abuseSubtype

Le champ abuseSubtype fournit une classification précise de la menace. Assurez-vous que ce champ n'est défini que lorsque le abuseType principal est SOCIAL_ENGINEERING. Sinon, une erreur est renvoyée.

Les valeurs abuseSubtype compatibles incluent les suivantes :

  • BANK_PHISHING : hameçonnage se faisant passer pour une banque ou une entité financière de confiance.
  • CRYPTO_EXCHANGE_PHISHING : hameçonnage se faisant passer pour une plate-forme d'échange de cryptomonnaies.
  • SOCIAL_MEDIA_PLATFORM_PHISHING : hameçonnage se faisant passer pour une plate-forme de réseaux sociaux.
  • RETAIL_PHISHING : hameçonnage se faisant passer pour une plate-forme de vente au détail établie.
  • EMAIL_PROVIDER_PHISHING : hameçonnage se faisant passer pour un service de messagerie.
  • ENTERTAINMENT_PHISHING : hameçonnage se faisant passer pour un service de divertissement.
  • GOVERNMENT_AGENCY_PHISHING : hameçonnage se faisant passer pour un organisme gouvernemental afin d'obtenir des informations permettant d'identifier personnellement l'utilisateur (PII), telles qu'un numéro de sécurité sociale ou un numéro d'identification fiscale.
  • PACKAGE_TRACKING_SCAM : imitation d'un service de livraison pour obtenir des informations personnelles ou des informations de paiement.
  • FAKE_SUPPORT_SCAM : sites Web trompeurs affirmant que les appareils présentent de faux problèmes pour inciter les utilisateurs à partager des informations personnelles ou à contacter des escrocs.
  • GOVERNMENT_FINE_SCAM : contenu trompeur affirmant qu'une amende civile impayée doit être réglée.
  • FAKE_PRIZE_SCAM : pages trompeuses offrant des récompenses ou des prix irréalistes.
  • OTHER_PHISHING / OTHER_SCAM : attaques d'ingénierie sociale n'appartenant pas aux autres catégories mentionnées ici.

targetedBrand

L'objet targetedBrand identifie l'entité ciblée par les campagnes d'hameçonnage et d'ingénierie sociale.

  • brandName : nom reconnaissable de la marque ou de l'entreprise usurpée (par exemple, Altostrat).
  • domain : domaine légitime de la marque usurpée (par exemple, altostrat.com).

Remarques importantes pour les participants à l'aperçu

  • Cohérence de la taxonomie : l'hameçonnage reste classé sous le type de menace SOCIAL_ENGINEERING (plutôt qu'un type parent PHISHING distinct) pour garantir la cohérence entre la suite d'API Web Risk et Navigation sécurisée.
  • Catégories exclues : les sous-catégories de MALWARE et UNWANTED_SOFTWARE sont exclues de cette version.
  • Gestion des menaces non listées : si votre échantillon envoyé ne correspond pas à un sous-type spécifique, utilisez OTHER_PHISHING ou OTHER_SCAM. Nous vous recommandons d'utiliser le champ comments dans ThreatJustification pour décrire l'attaque.
  • Facultatif, mais recommandé : fournir ces champs aide Web Risk à hiérarchiser et à améliorer les modèles de renseignements sur les menaces associés.
  • Phase d'aperçu : les valeurs d'énumération et le comportement de cette fonctionnalité sont susceptibles de changer.

Envoyer des URL

Pour envoyer une URL, envoyez une requête HTTP POST à la projects.uris.submit méthode.

  • L'API Submission accepte une URL par requête. Pour vérifier plusieurs URL, vous devez envoyer une requête distincte pour chaque URL.

  • L'URL doit être valide, mais pas canonique. Pour en savoir plus, consultez la norme RFC 2396.

  • La réponse HTTP POST renvoie une long-running operation. Pour en savoir plus sur la récupération du résultat de l'envoi et la vérification de son état, consultez la section Opérations de longue durée.

Exemple

Méthode HTTP et URL : 

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

Corps JSON de la requête : 

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

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante : 

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

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante : 

$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

Vous devriez recevoir une réponse JSON de ce type :

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

Vérifier l'état de l'envoi

Utilisez le project-number et le operation-id de la réponse pour vérifier l'état de l'envoi. L'état se trouve dans le champ metadata.state de l'opération renvoyée.

Les états possibles sont RUNNING, SUCCEEDED et CLOSED. Pour en savoir plus sur ces états, consultez la section Comprendre l'état des opérations du guide Opérations de longue durée.