API Navigazione sicura (v4)

Panoramica

L'API Update consente alle applicazioni client di scaricare versioni con hash degli elenchi di Navigazione sicura per l'archiviazione in un database locale. Gli URL possono quindi essere controllati localmente. Solo se viene trovata una corrispondenza nella il database locale deve inviare una richiesta ai server di Navigazione sicura per verificare se l'URL è incluso negli elenchi di Navigazione sicura.

Prima di utilizzare l'API Update, devi configurare un database locale. Navigazione sicura offre pacchetto Go utilizzabile per iniziare. Per ulteriori dettagli, consulta la sezione Configurazione del database in Database locali.

Aggiornamento del database locale

Per rimanere aggiornati, i clienti devono aggiornare periodicamente gli elenchi di Navigazione sicura nei propri un database locale. Per risparmiare larghezza di banda, i client scaricano i prefissi hash degli URL anziché i non elaborati. Ad esempio, se "www.badurl.com/" è incluso in un elenco di Navigazione sicura, i client scaricano Prefisso hash SHA256 dell'URL anziché dell'URL stesso. Nella maggior parte dei casi, i prefissi di 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 dell'elenco è di 4 byte prima della compressione.

Per aggiornare gli elenchi di Navigazione sicura nel database locale, invia una richiesta HTTP POST al metodo threatListUpdates.fetch:

• La richiesta HTTP POST include i nomi degli elenchi da aggiornare, nonché vari vincoli del cliente per tenere conto delle limitazioni di memoria e larghezza di banda.
• La risposta HTTP POST restituisce un aggiornamento completo o parziale. La risposta può anche restituire una durata minima di attesa.

Esempio: threatListUpdates.fetch

Richiesta HTTP POST

Nell'esempio seguente vengono richiesti gli aggiornamenti di un singolo elenco di Navigazione sicura.

Intestazione della richiesta

L'intestazione della richiesta include l'URL della richiesta e il tipo di contenuti. Ricordati di sostituire l'API chiave per API_KEY nell'URL.

POST https://safebrowsing.googleapis.com/v4/threatListUpdates:fetch?key=API_KEY HTTP/1.1
Content-Type: application/json

Corpo della richiesta

Il corpo della richiesta include le informazioni sul client (ID e versione) e le informazioni sull'aggiornamento (il nome elenco, stato elenco e vincoli client). Per maggiori dettagli, consulta il corpo della richiesta threatListUpdates.fetch e le spiegazioni che seguono l'esempio di codice.

{
  "client": {
    "clientId":       "yourcompanyname",
    "clientVersion":  "1.5.2"
  },
  "listUpdateRequests": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "state":           "Gg4IBBADIgYQgBAiAQEoAQ==",
    "constraints": {
      "maxUpdateEntries":      2048,
      "maxDatabaseEntries":    4096,
      "region":                "US",
      "supportedCompressions": ["RAW"]
    }
  }]
}

Dati del cliente

I campi clientID e clientVersion devono identificare in modo univoco un'implementazione del client, non un singolo utente. Le informazioni del client vengono utilizzate nei log lato server. Puoi scegliere qualsiasi nome per l'ID cliente, ma ti consigliamo di scegliere un nome che rappresenti la vera identità del cliente, ad esempio il nome della tua azienda, presentato come una sola parola, in lettere minuscole.

Elenchi di Navigazione sicura

I campi threatType, platformType e threatEntryType vengono combinati per identificare (nome) gli elenchi di Navigazione sicura. Nell'esempio, viene identificato un elenco: MALWARE/WINDOWS/URL. Prima di inviare una richiesta, assicurati che le combinazioni di tipo specificate siano valide (consulta Elenchi di Navigazione sicura).

Stato client

Il campo state include lo stato attuale del client dell'elenco di Navigazione sicura. Gli stati del client vengono restituiti nel campo newClientState della risposta threatListUpdates.fetch. Per gli aggiornamenti iniziali, lascia vuoto il campo state.

Vincoli di dimensioni

Il campo maxUpdateEntries specifica il numero totale di aggiornamenti che il client può gestire (nel esempio, 2048). Il campo maxDatabaseEntries specifica il numero totale di voci che il database locale può gestire (nell'esempio, 4096). I clienti dovrebbero impostare vincoli di dimensione al fine di proteggere i limiti di memoria e larghezza di banda e di evitare errori la crescita di Kubernetes. Per ulteriori informazioni, (vedi Aggiornamento dei vincoli).

Compressioni supportate

Il campo supportedCompressions elenca i tipi di compressione supportati dal client. Nell'esempio, il client supporta solo dati non elaborati e non compressi. Safe Browsing, tuttavia, supporta tipi di compressione aggiuntivi (vedi Compressione).

Risposta HTTP POST

In questo esempio, la risposta restituisce un aggiornamento parziale per l'elenco di Navigazione sicura utilizzando il parametro tipo di compressione richiesto.

Intestazione della risposta

L'intestazione della risposta include il codice di stato HTTP e il tipo di contenuto. I client che ricevono un codice di stato diverso da HTTP/200 devono attivare la modalità back-off (consulta la sezione Frequenza della richiesta).

HTTP/1.1 200 OK
Content-Type: application/json

Corpo della risposta

Il corpo della risposta include le informazioni sull'aggiornamento (nome dell'elenco, tipo di risposta, aggiunte e rimozioni da applicare al database locale, stato del nuovo cliente e un checksum). Nell'esempio, la risposta include anche una durata minima di attesa. Per maggiori dettagli, consulta il corpo della risposta di threatListUpdates.fetch e le spiegazioni che seguono l'esempio di codice.

{
  "listUpdateResponses": [{
    "threatType":      "MALWARE",
    "threatEntryType": "URL",
    "platformType":    "WINDOWS",
    "responseType" :   "PARTIAL_UPDATE",
    "additions": [{
      "compressionType": "RAW",
      "rawHashes": {
        "prefixSize": 4,
        "rawHashes":  "rnGLoQ=="
      }
    }],
    "removals": [{
      "compressionType": "RAW",
      "rawIndices": {
        "indices": [0, 2, 4]
      }
    }],
    "newClientState": "ChAIBRADGAEiAzAwMSiAEDABEAFGpqhd",
    "checksum": {
      "sha256": "YSgoRtsRlgHDqDA3LAhM1gegEpEzs1TjzU33vqsR8iM="
    }
  }],
  "minimumWaitDuration": "593.440s"
}

Aggiornamenti del database

Il campo responseType indica un aggiornamento parziale o completo. Nell'esempio viene restituito un aggiornamento parziale, pertanto la risposta include sia le aggiunte che le rimozioni. Possono esserci più insiemi di aggiunte, ma un solo insieme di rimozioni (consulta Aggiornamenti del database).

Stato del nuovo cliente

Il campo newClientState conserva il nuovo stato del client per l'elenco di Navigazione sicura aggiornato di recente. I client devono salvare il nuovo stato per le successive richieste di aggiornamento (il campo state nella richiesta di tipothreatListUpdates.fetch o il campo clientStates nel richiesta fullHashes.find).

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 campo state. Tuttavia, i clienti in questa situazione devono comunque seguire gli intervalli di tempo per gli aggiornamenti (consulta la sezione Frequenza della richiesta).

Durate minime di attesa

Il campo minimumWaitDuration indica che il client deve attendere 593,44 secondi (9,89 minuti) prima di inviare un'altra richiesta di aggiornamento. Tieni presente che un periodo di attesa può essere incluso o meno nel (vedi Frequenza della richiesta).

Controllo degli URL

Per verificare se un URL è presente in un elenco di Navigazione sicura, il client deve prima calcolare l'hash e l'hash del prefisso dell'URL (vedi URL e hashing). Il client esegue quindi una query sul database locale per determinare se esiste una corrispondenza. Se il prefisso hash è non presente nel database locale, l'URL viene considerato sicuro (non sulla Sfogliare gli elenchi).

Se il prefisso hash è presente nel database locale (una collisione del prefisso hash), Il client deve inviare il prefisso hash ai server di Navigazione sicura 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 a lunghezza intera dell'URL in questione, se l'URL è considerato non sicuro. Se nessuno degli hash completi corrisponde all'hash a lunghezza intera dell'URL in questione, questo URL è considerato sicuro.

In nessun momento Google viene a conoscenza degli URL che stai esaminando. Google impara l'hash prefissi degli URL, ma i prefissi hash non forniscono molte informazioni sugli URL effettivi.

Per verificare se un URL è in un elenco di Navigazione sicura, invia una richiesta POST HTTP al fullHashes.find :

• La richiesta HTTP POST può includere fino a 500 voci di minaccia.
• La richiesta HTTP POST include i prefissi hash degli URL da controllare. I clienti sono è incoraggiato a raggruppare più voci di minacce in un'unica richiesta per ridurre l'utilizzo della larghezza di banda.
• La risposta HTTP POST restituisce gli hash completi corrispondenti insieme alle durate della cache positive e negative. La risposta può anche restituire una durata minima di attesa.

Esempio: fullHashes.find

Richiesta POST HTTP

Nell'esempio seguente, vengono inviati i nomi di due elenchi di Navigazione sicura e tre prefissi hash per il confronto e la verifica.

Intestazione della richiesta

L'intestazione della richiesta include l'URL della richiesta e il tipo di contenuti. Ricorda di sostituire la tua chiave API con API_KEY nell'URL.

POST https://safebrowsing.googleapis.com/v4/fullHashes:find?key=API_KEY HTTP/1.1
Content-Type: application/json

Corpo della richiesta

Il corpo della richiesta include le informazioni sul client (ID e versione), gli stati del client e le informazioni sulla minaccia (nomi degli elenchi e prefissi hash). Per le richieste JSON, i prefissi hash devono essere inviati in formato con codifica Base64. Per ulteriori dettagli, consulta Corpo della richiesta fullHashes.find e le spiegazioni che seguono l'esempio di codice.

{
  "client": {
    "clientId":      "yourcompanyname",
    "clientVersion": "1.5.2"
  },
  "clientStates": [
    "ChAIARABGAEiAzAwMSiAEDABEAE=",
    "ChAIAhABGAEiAzAwMSiAEDABEOgH"
  ],
  "threatInfo": {
    "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
    "platformTypes":    ["WINDOWS"],
    "threatEntryTypes": ["URL"],
    "threatEntries": [
      {"hash": "WwuJdQ=="},
      {"hash": "771MOg=="},
      {"hash": "5eOrwQ=="}
    ]
  }
}

Dati del cliente

I campi clientID e clientVersion devono identificare in modo univoco un'implementazione del client, non un singolo utente. Le informazioni del client vengono utilizzate nei log lato server. Puoi scegliere un nome qualsiasi per l'ID cliente, ma ti consigliamo di scegliere un nome che rappresenti la vera identità del cliente, ad esempio il nome della tua azienda, scritto in una sola parola, in lettere minuscole.

Tutti gli stati del client

Il campo clientStates contiene gli stati del client per tutti gli elenchi di Navigazione sicura nel database locale del client. Gli stati del client vengono restituiti nel campo newClientState della risposta threatListUpdates.fetch.

Elenchi di Navigazione sicura

threatTypes, platformTypes e threatEntryTypes si combinano per identificare (nome) il Sfogliare elenchi. Nell'esempio vengono identificati due elenchi: MALWARE/WINDOWS/URL e SOCIAL_ENGINEERING/WINDOWS/URL. Prima di inviare una richiesta, assicurati che le combinazioni di tipo siano validi (consulta la sezione Elenchi di Navigazione sicura).

Prefissi hash delle minacce

L'array threatEntries contiene i prefissi hash degli URL che vuoi controllare. Il campo hash deve contenere l'esatto prefisso hash presente nel database locale. Ad esempio, se il prefisso dell'hash locale è lungo 4 byte, la voce della minaccia deve essere lunga 4 byte. Se il prefisso dell'hash locale è stato allungato a 7 byte, la voce della minaccia deve essere lunga 7 byte.

Nell'esempio, la richiesta include tre prefissi hash. Tutti e tre i prefissi verranno confrontati con ciascuno degli elenchi di Navigazione sicura per determinare se esiste un hash completo corrispondente.

Nota: l'API Update e il metodo fullHashes.find devono sempre utilizzare il campo hash, mai il campo URL (vedi ThreatEntry).

Risposta HTTP POST

Nell'esempio seguente, la risposta restituisce i dati corrispondenti, organizzati in base all'elenco di Navigazione sicura: oltre alla cache e alle durate di attesa.

Intestazione della risposta

L'intestazione della risposta include il codice di stato HTTP e il tipo di contenuto. I client che ricevono un codice di stato diverso da HTTP/200 devono eseguire il backoff (vedi Frequenza delle richieste).

HTTP/1.1 200 OK
Content-Type: application/json

Corpo della risposta

Il corpo della risposta include le informazioni sulla corrispondenza (i nomi degli elenchi e gli hash di lunghezza completa, i metadati, se disponibili, e le durate della cache). Nell'esempio, il corpo della risposta include anche una durata minima di attesa. Per ulteriori dettagli, consulta Corpo della risposta fullHashes.find e le spiegazioni che seguono l'esempio di codice.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "WwuJdQx48jP-4lxr4y2Sj82AWoxUVcIRDSk1PC9Rf-4="
    },
    "threatEntryMetadata": {
      "entries": [{
        "key": "bWFsd2FyZV90aHJlYXRfdHlwZQ==",  // base64-encoded "malware_threat_type"
        "value": "TEFORElORw=="  // base64-encoded "LANDING"
       }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "SOCIAL_ENGINEERING",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat": {
      "hash": "771MOrRPMn6xPKlCrXx_CrR-wmCk0LgFFoSgGy7zUiA="
    },
    "threatEntryMetadata": {
      "entries": []
    },
    "cacheDuration": "300.000s"
  }],
  "minimumWaitDuration": "300.000s",
  "negativeCacheDuration": "300.000s"
}

Corrisponde a

L'oggetto Corrispondenze restituisce un hash corrispondente a lunghezza intera per due dei prefissi hash. Gli URL corrispondenti a questi hash sono considerati non sicuri. Nessuna corrispondenza trovata per il terzo prefisso hash, in modo che non venga restituito nulla; l'URL corrispondente a questo prefisso hash è considerato sicuro.

Tieni presente che questo esempio abbina un hash completo a un prefisso hash. Tuttavia, potrebbero esserci più hash completi che mappano allo stesso prefisso hash.

Metadati

Il campo threatEntryMetadata è facoltativo e fornisce informazioni aggiuntive sulla corrispondenza della minaccia. Attualmente i metadati sono disponibili per l'elenco di Navigazione sicura per MALWARE/WINDOWS/URL. (vedi Metadati).

Durate della cache

I campi cacheDuration e negativeCacheDuration indicano il periodo di tempo per il quale gli hash devono essere considerati non sicuri o sicuri (vedi Memorizzazione nella cache).

Durate minime di attesa

Il campo minimumWaitDuration indica che il client deve attendere 300 secondi (5 minuti) prima inviando un'altra richiesta fullHashes. Tieni presente che un periodo di attesa potrebbe essere incluso o meno nella risposta (consulta la sezione Frequenza della richiesta).