Utilizzo dell'API Submission

Questo documento descrive come inviare a Navigazione sicura gli URL che ritieni non sicuri 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.

Prima di iniziare

Contatta il team di vendita o il tuo Customer Engineer per ottenere l'accesso a questa funzionalità.

Best practice

Leggi le norme di 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. I seguenti esempi mostrano prove di violazione delle norme:

• Contenuti di ingegneria sociale che imitano un brand online legittimo (nome del brand, logo, aspetto e funzionalità), 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 blocklist di Navigazione sicura:

• Sondaggi, siti di shopping o altre frodi falsi che non dimostrano il phishing (ad esempio frodi di 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

Anteprima

Questo prodotto o funzionalità sono soggetti ai "Termini delle Offerte pre-GA" nella sezione Termini di servizio generali dei Termini specifici dei servizi. I prodotti e le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

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 con maggiore precisione 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 affidabile.
• 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 impersonato il nome (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 nella 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 compilazione di questi campi aiuta Web Risk a dare la priorità ai modelli di threat intelligence associati e a migliorarli.
• 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 ogni 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

Nota: il seguente comando presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login oppure utilizzando Cloud Shell, che consente di accedere automaticamente all'interfaccia a riga di comando gcloud. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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

Nota: il comando seguente presuppone che tu abbia eseguito l'accesso all'interfaccia a riga di comando gcloud con il tuo account utente eseguendo gcloud init o gcloud auth login. Puoi controllare l'account attualmente attivo eseguendo gcloud auth list.

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.