Utilizzo dell'API Update
Panoramica
L'API Update consente alle applicazioni client di scaricare versioni con hash degli elenchi Web Risk per l'archiviazione in un database locale o in memoria. Gli URL possono quindi essere controllati localmente. Quando viene trovata una corrispondenza nel database locale, il client invia una richiesta ai server Web Risk per verificare se l'URL è incluso negli elenchi Web Risk.
Aggiornamento del database locale
Per rimanere aggiornati, i client devono aggiornare periodicamente gli elenchi Web Risk nel proprio database locale. Per risparmiare larghezza di banda, i client scaricano i prefissi hash degli URL anziché gli URL non elaborati. Ad esempio, se "www.badurl.com/" è in un elenco Web Risk, i client scaricano il prefisso dell'hash SHA256 di quell'URL anziché l'URL stesso. Nella maggior parte dei casi i prefissi hash hanno una lunghezza di 4 byte, il che significa che il costo medio della larghezza di banda per il download di una singola voce di elenco è di 4 byte prima della compressione.
Per aggiornare gli elenchi Web Risk nel database locale, invia una richiesta HTTP GET
al metodo threatLists.computeDiff
:
- La richiesta HTTP
GET
include il nome dell'elenco da aggiornare insieme ai vincoli del client per tenere conto dei limiti di memoria e larghezza di banda. - La risposta HTTP
GET
restituisce un aggiornamento completo o parziale. La risposta potrebbe restituire anche un tempo di attesa consigliato fino alla successiva operazione di differenza di calcolo.
Esempio: threatLists.computeDiff
Richiesta HTTP GET
Nell'esempio seguente, sono richieste le differenze per l'elenco MALWARE Web Risk. Per maggiori dettagli, consulta i parametri di query di threatLists.computeDiff
e le spiegazioni che seguono l'esempio di codice.
Metodo HTTP e URL:
GET https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW&key=API_KEY
Per inviare la richiesta, scegli una delle seguenti opzioni:
arricciatura
Esegui questo comando:
curl -X GET \
"https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW&key=API_KEY"
PowerShell
Esegui questo comando:
$headers = @{ }
Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://webrisk.googleapis.com/v1/threatLists:computeDiff?threatType=MALWARE&versionToken=Gg4IBBADIgYQgBAiAQEoAQ%3D%3D&constraints.maxDiffEntries=2048&constraints.maxDatabaseEntries=4096&constraints.supportedCompressions=RAW&key=API_KEY" | Select-Object -Expand Content
Dovresti ricevere una risposta JSON simile alla seguente:
{ "recommendedNextDiff": "2020-01-08T19:41:45.436722194Z", "responseType": "RESET", "additions": { "rawHashes": [ { "prefixSize": 4, "rawHashes": "AArQMQAMoUgAPn8lAE..." } ] }, "newVersionToken": "ChAIARAGGAEiAzAwMSiAEDABEPDyBhoCGAlTcIVL", "checksum": { "sha256": "wy6jh0+MAg/V/+VdErFhZIpOW+L8ulrVwhlV61XkROI=" } }
Java
Python
Elenchi Web Risk
Il campo threatType
identifica l'elenco Web Risk. Nell'esempio vengono richieste le differenze per l'elenco MALWARE Web Risk.
Token versione
Il campo versionToken
contiene lo stato client corrente dell'elenco
Web Risk.
I token di versione vengono restituiti nel campo newVersionToken
della risposta threatLists.computeDiff.
Per gli aggiornamenti iniziali, lascia vuoto il campo versionToken
.
Vincoli di dimensione
Il campo maxDiffEntries
specifica il numero totale di aggiornamenti che il client può gestire (nell'esempio, 2048). Il campo maxDatabaseEntries
specifica il numero totale di voci che il database locale può gestire (nell'esempio, 4096). I client dovrebbero impostare vincoli di dimensione per proteggere la memoria e i limiti di larghezza di banda e per evitare l'aumento degli elenchi. Per
ulteriori informazioni, consulta la sezione Aggiornamento dei vincoli.
Compressioni supportate
Nel campo supportedCompressions
sono elencati i tipi di compressione supportati dal client. Nell'esempio, il client supporta solo dati non elaborati e non compressi.
Tuttavia, Web Risk supporta tipi di compressione aggiuntivi. Per ulteriori informazioni, consulta la sezione Compressione.
Risposta HTTP GET
In questo esempio, la risposta restituisce un aggiornamento parziale per l'elenco Web Risk utilizzando il tipo di compressione richiesto.
Corpo della risposta
Il corpo della risposta include le informazioni sulle differenze (il tipo di risposta, le aggiunte e le rimozioni da applicare al database locale, il token della nuova versione e un checksum).
Nell'esempio, la risposta include anche un'ora consigliata per le differenze successive. Per maggiori dettagli, consulta il corpo della risposta threatLists.computeDiff
e le spiegazioni che seguono l'esempio di codice.
{ "responseType" : "DIFF", "recommendedNextDiff": "2019-12-31T23:59:59.000000000Z", "additions": { "compressionType": "RAW", "rawHashes": [{ "prefixSize": 4, "rawHashes": "rnGLoQ==" }] }, "removals": { "rawIndices": { "indices": [0, 2, 4] } }, "newVersionToken": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd", "checksum": { "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM=" }, "recommendedNextDiff": "2019-07-17T15:01:23.045123456Z" }
Differenze database
Il campo responseType
indicherà un aggiornamento parziale (DIFF
) o completo
(RESET
). Nell'esempio, vengono restituite differenze parziali, quindi la risposta
include sia aggiunte che rimozioni. Potrebbero esserci più insiemi di aggiunte,
ma solo un insieme di rimozioni. Per ulteriori informazioni, consulta Differenze di database.
Nuovo token di versione
Il campo newVersionToken
contiene il nuovo token di versione per l'elenco Web Risk appena aggiornato. I client devono salvare il nuovo stato per le successive richieste di aggiornamento (il campo versionToken
nella richiesta threatLists.computeDiff
.
Checksum
Il checksum consente ai client di verificare che il database locale non sia stato danneggiato. Se il checksum non corrisponde, il client deve cancellare il database e riemettere un aggiornamento con un campo versionToken
vuoto. Tuttavia, in questa situazione i client devono comunque seguire gli intervalli di tempo per gli aggiornamenti. Per saperne di più, consulta Frequenza delle richieste.
Differenza successiva consigliata
Il campo recommendedNextDiff
indica il timestamp fino a quando il client deve attendere prima di inviare un'altra richiesta di aggiornamento. Tieni presente che il periodo di attesa consigliato potrebbe essere incluso o meno nella risposta. Per ulteriori dettagli, consulta Frequenza delle richieste.
Controllo degli URL
Per verificare se un URL è in un elenco Web Risk, il client deve prima calcolare il prefisso hash e hash dell'URL. Per maggiori dettagli, consulta URL e hashing. Il client interroga il database locale per determinare se esiste una corrispondenza. Se il prefisso hash non è presente nel database locale, l'URL è considerato sicuro (ossia non è presente negli elenchi Web Risk).
Se il prefisso hash è presente nel database locale (una collisione con il prefisso hash), il client deve inviarlo ai server Web Risk per la verifica. I server restituiranno tutti gli hash SHA 256 completi che contengono il prefisso hash specificato. Se uno di questi hash completi corrisponde all'hash completo dell'URL in questione, l'URL è considerato non sicuro. Se nessuno degli hash completi corrisponde all'hash completo dell'URL in questione, quell'URL è considerato sicuro.
In nessun momento Google viene a conoscenza degli URL esaminati. Google apprende i prefissi hash degli URL, ma questi non forniscono molte informazioni sugli URL effettivi.
Per verificare se un URL è in un elenco Web Risk, invia una richiesta GET
HTTP al metodo hashes.search
:
- La richiesta HTTP
GET
include il prefisso hash dell'URL da controllare. - La risposta HTTP
GET
restituisce gli hash completi corrispondenti insieme alle scadenze positive e negative.
Esempio: hashes.search
Richiesta HTTP GET
Nell'esempio seguente, i nomi di due elenchi Web Risk e un prefisso hash vengono inviati per il confronto e la verifica. Per maggiori dettagli, consulta i parametri di query di hashes.search
e le spiegazioni che seguono l'esempio di codice.
curl \ -H "Content-Type: application/json" \ "https://webrisk.googleapis.com/v1/hashes:search?key=YOUR_API_KEY&threatTypes=MALWARE&threatTypes=SOCIAL_ENGINEERING&hashPrefix=WwuJdQ%3D%3D"
Java
Python
Elenchi Web Risk
Il campo threatTypes
identifica gli elenchi Web Risk. Nell'esempio sono identificati due elenchi: MALWARE
e SOCIAL_ENGINEERING
.
Prefissi hash delle minacce
Il campo hashPrefix
contiene il prefisso hash dell'URL che vuoi controllare. Questo campo deve contenere l'esatto prefisso hash presente nel database locale. Ad esempio, se il prefisso hash locale è di 4 byte,
il campo hashPrefix
deve avere una lunghezza di 4 byte. Se il prefisso hash locale è stato allungato a 7 byte, il campo hashPrefix
deve avere una lunghezza di 7 byte.
Risposta HTTP GET
Nell'esempio seguente, la risposta restituisce le minacce corrispondenti, contenenti gli elenchi Web Risk corrispondenti, insieme alle scadenze.
Corpo della risposta
Il corpo della risposta include le informazioni sulla corrispondenza (i nomi degli elenchi, gli hash completi e la durata della cache). Per maggiori dettagli, consulta il corpo della risposta hashes.search
e le spiegazioni che seguono l'esempio di codice.
{ "threats": [{ "threatTypes": ["MALWARE"], "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4=" "expireTime": "2019-07-17T15:01:23.045123456Z" }, { "threatTypes": ["MALWARE", "SOCIAL_ENGINEERING"], "hash": "WwuJdQxaCSH453-uytERC456gf45rFExcE23F7-hnfD=" "expireTime": "2019-07-17T15:01:23.045123456Z" }, }], "negativeExpireTime": "2019-07-17T15:01:23.045123456Z" }
Corrisponde a
Il campo threats
restituisce un hash a lunghezza intera corrispondente per il prefisso hash.
Gli URL corrispondenti a questi hash sono considerati non sicuri. Se non viene trovata alcuna corrispondenza per un prefisso hash, non viene restituito nulla; l'URL corrispondente a quel prefisso è considerato sicuro.
Ora di scadenza
I campi expireTime
e negativeExpireTime
indicano fino a quando gli hash
devono essere considerati rispettivamente non sicuri o sicuri. Per ulteriori dettagli, consulta Memorizzazione nella cache.