Utilizzo dell'API Submission

Questo documento descrive come inviare gli URL che ritieni non sicuri a Navigazione sicura per l'analisi e come controllare in modo asincrono i risultati di questi invii. Gli URL che violano le Norme di Navigazione sicura vengono aggiunti al servizio Navigazione sicura.

Modifiche principali all'API Web Risk Submission

  • Nuovi ordini ed espansioni chiusi: non accettiamo più nuovi contratti o espansioni per l'API Web Risk Submission.
  • Blocco delle funzionalità in vigore: l'API è in un blocco formale delle funzionalità. Non introdurremo più nuove funzionalità o miglioramenti.
  • Rinnovi finali: l'ultima data per rinnovare i contratti esistenti è il 31 dicembre 2026. Tutti i rinnovi hanno un limite di durata massimo di un anno.
  • Disponibilità del servizio: i servizi esistenti rimangono operativi con correzioni di bug critici, aggiornamenti della sicurezza e assistenza standard fino alla fine del contratto attivo. Il ritiro completo avverrà entro e non oltre il 31 dicembre 2027.

Best practice

Leggi le norme per la navigazione sicura

L'API Web Risk Submission verifica i contenuti dei URL inviati che violano le norme di Navigazione sicura. Gli sviluppatori di API devono assicurarsi che gli URL inviati presentino prove evidenti di violazione di queste norme. Gli esempi seguenti mostrano prove di violazione delle norme:

  • Contenuti di ingegneria sociale che imitano un brand online legittimo (nome del brand, logo, aspetto), avvisi di sistema, utilizzano URL ingannevoli o richiedono agli utenti di inserire credenziali sensibili come un nome utente o una password.
  • Un sito che ospita un eseguibile di malware noto.

Non inviare i seguenti tipi di URL perché è improbabile che vengano aggiunti alla lista bloccata di Navigazione sicura:

  • Sondaggi, siti di shopping o altre frodi che non dimostrano il phishing (ad esempio frodi con criptovalute).
  • Spam contenente giochi e scommesse, violenza o contenuti per adulti che non sono phishing o malware.

Migliora il rilevamento

Ti consigliamo di utilizzare i campi ThreatInfo e ThreatDiscovery per fornire ulteriori informazioni sulle richieste. In questo modo, il rilevamento potrebbe migliorare. Per saperne di più, consulta le best practice per l'utilizzo dell'API Submission.

Tassonomia e targeting per brand

Puoi fornire segnalazioni di abusi più accurate e dettagliate utilizzando i seguenti componenti facoltativi nell'oggetto ThreatInfo: abuseSubtype e targetedBrand. Questi campi aiutano Web Risk ad analizzare in modo più accurato le entità di destinazione e a migliorare i modelli di rilevamento.

abuseSubtype

Il campo abuseSubtype fornisce una classificazione granulare della minaccia. Assicurati che questo campo sia impostato solo quando abuseType principale è SOCIAL_ENGINEERING; in caso contrario, viene restituito un errore.

I valori abuseSubtype supportati includono:

  • BANK_PHISHING: Phishing che si spaccia per una banca o un istituto finanziario attendibile.
  • CRYPTO_EXCHANGE_PHISHING: Phishing che si spaccia per una piattaforma di trading di criptovalute.
  • SOCIAL_MEDIA_PLATFORM_PHISHING: Phishing che si spaccia per una piattaforma di social media.
  • RETAIL_PHISHING: Phishing che si spaccia per una piattaforma di vendita al dettaglio consolidata.
  • EMAIL_PROVIDER_PHISHING: Phishing che si spaccia per un servizio email.
  • ENTERTAINMENT_PHISHING: Phishing che si spaccia per un servizio di intrattenimento.
  • GOVERNMENT_AGENCY_PHISHING: Phishing che si spaccia per un ente statale per ottenere informazioni che consentono l'identificazione personale (PII), come un numero di previdenza sociale o un numero di identificazione del contribuente.
  • PACKAGE_TRACKING_SCAM: Imitazione di un servizio di spedizione per ottenere PII o dettagli di pagamento.
  • FAKE_SUPPORT_SCAM: siti web ingannevoli che dichiarano falsi problemi del dispositivo per indurre gli utenti a condividere PII o a contattare truffatori.
  • GOVERNMENT_FINE_SCAM: Contenuti ingannevoli che affermano che una multa civica in sospeso deve essere pagata.
  • FAKE_PRIZE_SCAM: pagine ingannevoli che offrono premi o ricompense non realistici.
  • OTHER_PHISHING / OTHER_SCAM: attacchi di ingegneria sociale che non rientrano nelle altre categorie indicate qui.

targetedBrand

L'oggetto targetedBrand identifica l'entità presa di mira dalle campagne di phishing e ingegneria sociale.

  • brandName: Il nome riconoscibile del brand o dell'azienda di cui viene impersonato il nome (ad esempio, Altostrat).
  • domain: Il dominio legittimo del brand di cui viene eseguita l'usurpazione (ad esempio, altostrat.com).

Note importanti per i partecipanti all'anteprima

  • Coerenza nella tassonomia: il phishing rimane classificato nel tipo di minaccia SOCIAL_ENGINEERING (anziché in un tipo principale PHISHING separato) per garantire la coerenza in tutta la suite di API Web Risk e Navigazione sicura.
  • Categorie escluse: le sottocategorie per MALWARE e UNWANTED_SOFTWARE sono escluse da questa release.
  • Gestione delle minacce non elencate: se i contenuti inviati non corrispondono a un sottotipo specifico, utilizza OTHER_PHISHING o OTHER_SCAM. Ti consigliamo di utilizzare il campo comments in ThreatJustification per descrivere l'attacco.
  • Facoltativo, ma consigliato: la fornitura di questi campi aiuta Web Risk a dare la priorità e a migliorare i modelli di threat intelligence associati.
  • Fase di anteprima: i valori e il comportamento dell'enumerazione per questa funzionalità sono soggetti a modifiche.

Inviare URL

Per inviare un URL, invia una richiesta HTTP POST al metodo projects.uris.submit.

  • L'API Submission supporta un URL per richiesta. Per controllare più URL, devi inviare una richiesta separata per ciascun URL.

  • L'URL deve essere valido, ma non deve essere canonico. Per saperne di più, consulta RFC 2396.

  • La risposta HTTP POST restituisce un long-running operation. Per saperne di più su come recuperare il risultato dell'invio e controllare lo stato di un invio, consulta Operazioni a lunga esecuzione.

Esempio

Metodo HTTP e URL: 

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

Corpo JSON della richiesta: 

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

Per inviare la richiesta, scegli una di queste opzioni:

curl

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

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

Salva il corpo della richiesta in un file denominato request.json, quindi esegui il comando seguente: 

$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

Dovresti ricevere una risposta JSON simile alla seguente:

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

Controllare lo stato dell'invio

Utilizza project-number e operation-id della risposta per controllare lo stato dei contenuti inviati. Lo stato si trova nel campo metadata.state dell'operazione restituita.

Gli stati possibili includono RUNNING, SUCCEEDED e CLOSED. Per saperne di più su questi stati, consulta Informazioni sullo stato dell'operazione nella guida Operazioni a lunga esecuzione.