Safe Browsing Update API（v4）

概要

Update API を使用すると、クライアント アプリケーションで、セーフ ブラウジング リストのハッシュ バージョンを ローカルデータベースに保存しますその後、URL をローカルでチェックできます。ローカル データベースで一致するものが見つかった場合にのみ、セーフ ブラウジング サーバーにリクエストを送信し、URL がセーフ ブラウジング リストに含まれているかどうかを確認します。

Update API を使用する前に、ローカル データベースを設定する必要があります。セーフ ブラウジングは、 始めるために使用できる Go パッケージです。詳細は「データベースの設定」セクションの ローカル データベース。

ローカル データベースの更新

常に最新の情報を得るため、クライアントには Google アカウントのセーフ ブラウジング リストを定期的に 使用します。帯域幅を節約するために、クライアントは未加工の URL ではなく URL のハッシュ プレフィックスをダウンロードします。たとえば、セーフ ブラウジング リストに「www.badurl.com/」が含まれている場合、クライアントは URL そのものではなく、その URL の SHA256 ハッシュ プレフィックスをダウンロードします。ほとんどの場合、ハッシュは プレフィックスの長さは 4 バイトです。つまり、1 つのリストをダウンロードするための平均帯域幅コストを 4 バイトである。

ローカル データベース内のセーフ ブラウジング リストを更新するには、HTTP POST リクエストを threatListUpdates.fetch メソッドに送信します。

• HTTP POST リクエストには、更新するリストの名前とさまざまなクライアントが含まれています。 メモリと帯域幅の制限を考慮する必要があります。
• HTTP POST レスポンスは、完全な更新または部分的な更新を返します。レスポンス 最小待機時間を返す場合もあります。

例：threatListUpdates.fetch

HTTP POST リクエスト

次の例では、1 つのセーフ ブラウジング リストの更新をリクエストしています。

リクエスト ヘッダー

リクエスト ヘッダーには、リクエスト URL とコンテンツ タイプが含まれます。URL の API_KEY は、ご利用の API キーに置き換えてください。

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

リクエスト本文

リクエストの本文には、クライアント情報（ID とバージョン）と更新情報（ リスト名、リストの状態、クライアント制約など）が含まれます。 詳しくは、 threatListUpdates.fetch リクエスト本文 コードサンプルに続く説明を確認します

{
  "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"]
    }
  }]
}

クライアント情報

clientID フィールドと clientVersion フィールドは、クライアント実装を一意に識別する必要があります。 できます。（クライアント情報はサーバーサイド ロギングで使用されます。クライアント ID には任意の名前を付けることができますが、クライアントの正確な ID を表す名前（会社名など）を 1 つの単語としてすべて小文字で指定することをおすすめします）。

セーフ ブラウジング リスト

threatType、platformType、threatEntryType フィールド 組み合わせてセーフ ブラウジング リストを識別（名前）します。この例では、1 つのリストが識別されています。 マルウェア/Windows/URLリクエストを送信する前に、指定したタイプの組み合わせが有効であることを確認してください （セーフ ブラウジング リストをご覧ください）。

クライアントの状態

state フィールドには、セーフ ブラウジング リストの現在のクライアントの状態が保持されます。（クライアントの状態は、newClientState threatListUpdates.fetch レスポンス。 最初の更新では、state フィールドは空のままにします。

サイズ制限

maxUpdateEntries フィールドは、クライアントが管理できる更新の合計数を指定します（この例では 2,048）。maxDatabaseEntries フィールドは、ローカルデータベースが管理できるエントリの合計数を指定します（この例では 4,096）。クライアントがサイズの制約を設定する メモリと帯域幅の制限を保護し 学びました。詳しくは （制約を更新するをご覧ください）。

サポートされている圧縮

supportedCompressions フィールドには、クライアントがサポートする圧縮タイプが一覧表示されます。 未加工の非圧縮データのみがサポートされます。一方 セーフ ブラウジングでは （圧縮を参照）。

HTTP POST レスポンス

この例では、レスポンスで、 要求された圧縮タイプ。

レスポンス ヘッダー

レスポンス ヘッダーには、HTTP ステータス コードが含まれます。 コンテンツタイプを指定しますHTTP/200 以外のステータス コードを受け取ったクライアントは、バックオフ モードに移行する必要がある （リクエスト頻度をご覧ください）。

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

レスポンスの本文

レスポンスの本文には更新情報（リスト名、レスポンス タイプ、 新しいクライアント アカウントの追加と削除を チェックサムなど）が含まれます。この例では、最小待ち時間もレスポンスに含まれています。詳細については、threatListUpdates.fetch レスポンスの本文とコード例に続く説明をご覧ください。

{
  "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"
}

データベースの更新

responseType フィールドは、部分更新または完全な更新を示します。この例では、部分更新が が返されるため、レスポンスには追加と削除の両方が含まれます。追加は複数セット返される可能性がありますが、削除は 1 セットのみです（データベースの更新をご覧ください）。

新しいクライアントの状態

newClientState フィールドには、新しく更新されたセーフ ブラウジング リストの新しいクライアントの状態が保持されます。 クライアントは、後続の更新リクエストのために新しいクライアントの状態を保存する必要があります（state threatListUpdates.fetch リクエスト またはclientStates fullHashes.find リクエスト）。

チェックサム

クライアントはチェックサムを使用して、ローカル データベースが破損していないことを確認できます。もし チェックサムが一致しない場合、クライアントはデータベースをクリアして空の更新を再発行する必要があります state フィールド。ただし、この状況でもクライアントは更新の時間間隔に従う必要があります。 （リクエスト頻度をご覧ください）。

最小待機時間

minimumWaitDuration フィールドは、クライアントが 593.44 秒（9.89 分）待機する必要があることを示します。 別の更新リクエストを送信してください。なお、 リクエスト頻度をご覧ください。

URL の確認

URL がセーフ ブラウジング リストに含まれているかどうかを確認するには、クライアントがまずハッシュを計算して プレフィックスを付加します（URL とハッシュ化をご覧ください）。次に、クライアントはローカル データベースにクエリを行い、一致するものがあるかどうかを判断します。ハッシュ接頭辞が 存在しない場合、その URL は安全と見なされます（ ブラウジング リストなど）に適用されます。

ハッシュ プレフィックスがローカル データベースに存在する場合（ハッシュ プレフィックスの競合）、クライアントは検証のためにハッシュ プレフィックスをセーフ ブラウジング サーバーに送信する必要があります。サーバーは、指定されたハッシュ接頭辞を含むすべてのフルレングスの SHA 256 ハッシュを返します。 これらのフルレングスのハッシュのいずれかが、問題の URL のフルレングスのハッシュと一致する場合、その URL は安全でないとみなされます。問題の URL のフルレングスのハッシュと一致するフルレングスのハッシュがない場合、その URL は安全と見なされます。

Google は、調査している URL をまったく認識しません。Google はハッシュを ハッシュ プレフィックスからは実際の URL に関する十分な情報は得られません。

URL がセーフ ブラウジング リストに含まれているかどうかを確認するには、HTTP POST リクエストを fullHashes.find メソッド:

• HTTP POST リクエストには、最大 500 個の脅威エントリを含めることができます。
• HTTP POST リクエストには、チェックする URL のハッシュ接頭辞が含まれます。帯域幅の使用量を抑えるため、複数の脅威エントリを 1 つのリクエストにバッチ処理することをおすすめします。
• HTTP POST レスポンスは、一致する完全長のハッシュと、正のハッシュと ネガティブキャッシュ期間などですレスポンスには、最小待機時間も返される場合があります。

例: fullHashes.find

HTTP POST リクエスト

次の例では、比較と確認のために 2 つのセーフ ブラウジング リストの名前と 3 つのハッシュ プレフィックスが送信されます。

リクエスト ヘッダー

リクエスト ヘッダーには、リクエスト URL とコンテンツ タイプが含まれます。URL の API_KEY は、必ず API キーに置き換えてください。

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

リクエスト本文

リクエストの本文には、クライアント情報（ID とバージョン）、クライアントの状態、 脅威情報（リスト名とハッシュ接頭辞）JSON リクエストの場合、ハッシュ接頭辞は base64 エンコード形式で送信する必要があります。詳しくは、 fullHashes.find リクエスト本文 コードサンプルに続く説明を確認します

{
  "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=="}
    ]
  }
}

クライアント情報

clientID フィールドと clientVersion フィールドは、クライアント実装を一意に識別する必要があります。 できます。（クライアント情報はサーバーサイド ロギングで使用されます。クライアント ID には任意の名前を付けることができますが、クライアントの正しい ID を表す名前（会社名など）を 1 つの単語としてすべて小文字で指定することをおすすめします）。

すべてのクライアントの状態

clientStates フィールドには、クライアントのローカル データベース内のすべてのセーフ ブラウジング リストのクライアントの状態が保持されます。（クライアントの状態は、threatListUpdates.fetch レスポンスの newClientState フィールドで返されます）。

セーフ ブラウジング リスト

threatTypes、platformTypes、threatEntryTypes フィールドを組み合わせて、セーフ ブラウジング リストを識別（名前）します。この例では、MALWARE/WINDOWS/URL と MALWARE/WINDOWS/URL という 2 つのリストが識別されています。 SOCIAL_ENGINEERING/WINDOWS/URL。リクエストを送信する前に、使用するタイプの組み合わせを 有効なリストがあることを確認します（セーフ ブラウジング リストをご覧ください）。

脅威のハッシュ プレフィックス

ThreatEntries 配列には、確認する URL のハッシュ プレフィックスが含まれています。 hash フィールドには、ローカル データベースに存在する正確なハッシュ プレフィックスを含める必要があります。たとえば、ローカル ハッシュ プレフィックスが 4 バイトの場合、脅威エントリは 4 バイトにする必要があります。ローカル ハッシュ プレフィックスが 7 バイトに延長されている場合、脅威エントリは 7 バイトにする必要があります。

この例では、リクエストに 3 つのハッシュ プレフィックスが含まれています。3 つの接頭辞がすべて比較され、 各セーフ ブラウジング リストを比較して、一致するフルレングスのハッシュがあるかどうかを判断します。

注: Update API と fullHashes.find メソッドでは、常に hash フィールドを使用し、URL フィールドは使用しないでください（ThreatEntry をご覧ください）。

HTTP POST レスポンス

次の例では、レスポンスは、一致するデータをセーフ ブラウジング リスト別に整理して、キャッシュと待機時間とともに返します。

レスポンス ヘッダー

レスポンス ヘッダーには、HTTP ステータス コードが含まれます。 コンテンツタイプを指定しますHTTP/200 以外のステータス コードを受け取ったクライアントは、バックオフする必要があります（リクエスト頻度を参照）。

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

レスポンスの本文

レスポンスの本文には一致情報（リスト名と完全長のハッシュ、 およびキャッシュ期間など）が含まれます。この例では、レスポンス本文に最小待機時間も含まれています。詳細については、fullHashes.find レスポンスの本文とコード例に続く説明をご覧ください。

{
  "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"
}

一致

Matches オブジェクトは、2 つのハッシュ プレフィックスに一致する完全長のハッシュを返します。これらのハッシュに対応する URL は安全でないとみなされます。3 番目のハッシュ接頭辞に一致するものが見つからなかった 何も返されません。このハッシュ プレフィックスに対応する URL は安全と見なされます。

この例では、1 つのフルレングスのハッシュを 1 つのハッシュ プレフィックスにマッチングさせていますが、同じハッシュ プレフィックスにマッピングされるフルハッシュが複数ある場合があります。

メタデータ

threatEntryMetadata フィールドは省略可能で、脅威の一致に関する追加情報を提供します。現在、マルウェア/Windows/URL のセーフ ブラウジング リストについてメタデータを利用できます。 （メタデータをご覧ください）。

キャッシュ期間

cacheDuration フィールドと negativeCacheDuration フィールドは、ハッシュが安全でないか安全かを判断する必要がある時間を示します（キャッシュ保存をご覧ください）。

最小待機時間

minimumWaitDuration フィールドは、クライアントが開始前に 300 秒（5 分）待機する必要があることを示します。 別の fullHashes リクエストを送信します。待ち時間は、レスポンスに含まれる場合もあれば、含まれない場合もあります（リクエストの頻度をご覧ください）。