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), 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 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 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.

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 dell'invio. Lo stato si trova nel campo metadata.state dell'operazione restituita.

Gli stati possibili includono RUNNING, SUCCEEDED e CLOSED. Per ulteriori informazioni su questi stati, consulta Informazioni sullo stato dell'operazione nella guida alle operazioni a lunga esecuzione.