Safe Browsing Lookup API (Version 4)

Übersicht

Mit der Lookup API können Client-Anwendungen Anfragen an die Safe Browsing- um zu prüfen, ob URLs auf einer Safe Browsing-Liste stehen. Wird eine URL auf einem oder werden die übereinstimmenden Informationen zurückgegeben.

URLs prüfen

Wenn du prüfen möchtest, ob eine URL auf einer Safe Browsing-Liste steht, sende eine HTTP-POST-Anfrage an den threatMatches.find :

• Die HTTP-POST-Anfrage kann bis zu 500 URLs enthalten. Die URLs müssen gültig sein (siehe RFC 2396) Sie müssen jedoch nicht kanonisiert oder codiert werden.
• In der HTTP-POST-Antwort werden die übereinstimmenden URLs zusammen mit der Cache-Dauer zurückgegeben.

Beispiel: ThreatMatches.find

HTTP-POST-Anfrage

Im folgenden Beispiel werden zwei Safe Browsing-Listen und drei URLs an den Server gesendet, ob es eine Übereinstimmung gibt.

Anfrageheader

Der Anfrageheader enthält die Anfrage-URL und den Inhaltstyp. Denken Sie daran, Ihren API-Schlüssel für API_KEY in der URL.

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

Anfragetext

Der Anfragetext enthält die Clientinformationen (ID und Version) sowie Informationen zur Bedrohung (Listennamen und URLs). Weitere Informationen finden Sie in der threatMatches.find-Anfragetext und die Erklärungen nach dem Codebeispiel.

  {
    "client": {
      "clientId":      "yourcompanyname",
      "clientVersion": "1.5.2"
    },
    "threatInfo": {
      "threatTypes":      ["MALWARE", "SOCIAL_ENGINEERING"],
      "platformTypes":    ["WINDOWS"],
      "threatEntryTypes": ["URL"],
      "threatEntries": [
        {"url": "http://www.urltocheck1.org/"},
        {"url": "http://www.urltocheck2.org/"},
        {"url": "http://www.urltocheck3.com/"}
      ]
    }
  }

Kundeninformationen

Die Felder clientID und clientVersion sollten eine Clientimplementierung eindeutig identifizieren, keine einzelner Nutzer. (Client-Informationen werden für das serverseitige Logging und Accounting verwendet. Zur Auswahl stehen einen beliebigen Namen für die Client-ID. Wir empfehlen jedoch, einen Namen zu wählen, der die tatsächliche Identität der (z. B. der Name Ihres Unternehmens, dargestellt als ein Wort und in Kleinbuchstaben).

Safe Browsing-Listen

Die Felder threatType, platformType und threatEntryType zur Identifizierung (Name) von Safe Browsing-Listen kombiniert. In diesem Beispiel werden zwei Listen identifiziert: MALWARE/WINDOWS/URL und SOCIAL_ENGINEERING/WINDOWS/URL. Prüfen Sie vor dem Senden einer Anfrage, ob der Typ der von Ihnen angegebene Kombinationen sind gültig (siehe Safe Browsing-Listen).

Bedrohungs-URLs

In diesem Beispiel enthält das Array threatEntries drei URLs (urltocheck1.org, urltocheck2.org, und urltocheck3.org), die mit den beiden Safe Browsing-Listen abgeglichen werden.

Hinweis:Für die Lookup API und die Methode threatMatches sollte immer das Feld URL verwendet werden. und niemals das Feld hash (siehe ThreatEntry).

HTTP POST-Antwort

Im folgenden Beispiel gibt die Antwort eine Übereinstimmung zurück: der beiden im Feld die sich auf einer der beiden Safe Browsing-Listen befinden, die in der Anfrage angegeben sind.

Antwortheader

Der Antwortheader enthält den HTTP-Statuscode und den Inhaltstyp.

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

Antworttext

Der Antworttext enthält die Übereinstimmungsinformationen (die Listennamen und URLs auf diese Listen, die Metadaten (falls verfügbar) und die Cache-Dauer). Weitere Informationen finden Sie in der threatMatches.find Antworttext und die Erklärungen nach dem Codebeispiel.

Hinweis:Wenn es keine Übereinstimmungen gibt (wenn also keine der angegebenen URLs angegeben wurde) in der Anfrage auf einer der in der Anfrage angegebenen Listen gefunden werden), wird die HTTP-Antwort POST gibt einfach ein leeres Objekt im Antworttext zurück.

{
  "matches": [{
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck1.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key": "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }, {
    "threatType":      "MALWARE",
    "platformType":    "WINDOWS",
    "threatEntryType": "URL",
    "threat":          {"url": "http://www.urltocheck2.org/"},
    "threatEntryMetadata": {
      "entries": [{
        "key":   "malware_threat_type",
        "value": "landing"
     }]
    },
    "cacheDuration": "300.000s"
  }]
}

Übereinstimmungen

Das matches-Objekt enthält die Namen der Safe Browsing-Listen und die URLs (falls es gibt eine Übereinstimmung. In diesem Beispiel wurden zwei URLs (urltocheck1.org und urltocheck2.org) auf einer der folgenden Seiten gefunden: die Safe Browsing-Listen (MALWARE/WINDOWS/URL) auf, sodass die übereinstimmenden Informationen zurückgegeben werden. Die dritte URL (urltocheck3.org) wurde auf keiner der Listen gefunden. Für diese URL werden daher keine Informationen zurückgegeben.

Metadaten

Das Feld threatEntryMetadata ist optional und enthält zusätzliche Informationen zu den Abgleich mit den Bedrohungen. Derzeit sind Metadaten für die Safe Browsing-Liste für MALWARE/WINDOWS/URL verfügbar. (siehe Metadaten).

Cache-Dauer

Das Feld „cacheDuration“ gibt an, wie lange die URL als unsicher gelten muss (siehe Caching).