Utiliser l'API Submission

Ce document explique comment envoyer des URL que vous pensez être dangereuses à la navigation sécurisée pour analyse, et comment vérifier de manière asynchrone les résultats de ces envois. Toutes les URL qui enfreignent les Règles de navigation sécurisée sont ajoutées au service de navigation sécurisée.

Principaux changements apportés à l'API Web Risk Submission

• Fermeture des nouvelles commandes et des extensions : nous n'acceptons plus de nouveaux contrats ni d'extensions pour l'API Web Risk Submission.
• Gel des fonctionnalités en vigueur : l'API est officiellement gelée. Nous n'ajoutons plus de fonctionnalités ni d'améliorations.
• Derniers renouvellements : la date limite pour renouveler les contrats existants est le 31 décembre 2026. La durée maximale de chaque renouvellement est d'un an.
• Disponibilité des services : les services existants restent opérationnels avec les corrections de bugs critiques, les mises à jour de sécurité et l'assistance standard jusqu'à la fin de votre contrat actif. La suppression complète aura lieu au plus tard le 31 décembre 2027.

Bonnes pratiques

Consultez le Règlement de la 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. Les développeurs d'API doivent s'assurer que les URL envoyées présentent des preuves claires de non-respect de ces règles. Voici des exemples de preuves de non-respect des règles :

• Contenus d'ingénierie sociale imitant une marque en ligne légitime (nom de marque, logo, apparence), des alertes système, utilisant des URL trompeuses ou demandant aux utilisateurs de saisir des identifiants sensibles tels qu'un nom d'utilisateur ou un mot de passe.
• Un site hébergeant un exécutable de logiciel malveillant connu.

N'envoyez pas les types d'URL suivants, car il est peu probable qu'ils soient ajoutés à la liste noire de la navigation sécurisée :

• Enquêtes, sites d'achat ou autres escroqueries fictifs qui ne relèvent pas de l'hameçonnage (comme les escroqueries liées aux cryptomonnaies)
• Spam contenant des contenus pour adultes, violents ou liés aux jeux d'argent et de hasard, 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 contributions. Cela peut aider à améliorer la détection. Pour en savoir plus, consultez les bonnes pratiques d'utilisation de l'API Submission.

Taxonomie et ciblage de marques

Vous pouvez fournir des signalements 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 acceptées sont 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 de trading 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), comme 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 permettant d'identifier personnellement l'utilisateur ou des informations de paiement.
• FAKE_SUPPORT_SCAM : sites Web trompeurs qui prétendent que l'appareil présente des problèmes pour inciter les utilisateurs à partager des informations permettant de les identifier personnellement ou à contacter des escrocs.
• GOVERNMENT_FINE_SCAM : contenu trompeur affirmant qu'une amende civique impayée doit être réglée.
• FAKE_PRIZE_SCAM : pages trompeuses proposant des récompenses ou des prix irréalistes.
• OTHER_PHISHING / OTHER_SCAM : attaques d'ingénierie sociale qui n'appartiennent 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 dont l'identité est usurpée (par exemple, Altostrat).
• domain : domaine légitime de la marque usurpée (par exemple, altostrat.com).

Remarques importantes pour les participants à la version Preview

• Cohérence de la taxonomie : l'hameçonnage reste classé dans le type de menace SOCIAL_ENGINEERING (plutôt que dans un type parent PHISHING distinct) pour assurer la cohérence dans 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.
• Gérer les menaces non listées : si votre échantillon envoyé ne correspond à aucun 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 d'être modifiés.

Envoyer des URL

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

• 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 n'a pas besoin d'être canonique. Pour en savoir plus, consultez la norme RFC 2396.

• La réponse HTTP POST renvoie une opération de type long-running operation. Pour savoir comment récupérer le résultat de l'envoi et vérifier son état, consultez 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 -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"

$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 project-number et 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 Comprendre l'état des opérations dans le guide sur les opérations de longue durée.