Package google.security.safebrowsing.v5alpha1

索引

SafeBrowsing

Safe Browsing API を使用すると、クライアントはウェブリソース（通常は URL）を、Google が随時更新している安全でないウェブリソースのリストに照らし合わせてチェックできます。

BatchGetHashLists

rpc BatchGetHashLists(BatchGetHashListsRequest) returns (BatchGetHashListsResponse)

一度に複数のハッシュリストを取得します。

クライアントが複数のハッシュリストを取得する必要があるのは、非常に一般的です。通常の Get メソッドを複数回使用するよりも、この方法をおすすめします。

これは、https://google.aip.dev/231 で定義されている標準のバッチ Get メソッドで、HTTP メソッドも GET です。
GetHashList

rpc GetHashList(GetHashListRequest) returns (HashList)

ハッシュリストの最新コンテンツを取得します。ハッシュリストは、脅威リストまたは脅威リスト以外（グローバルキャッシュなど）のいずれかです。

これは https://google.aip.dev/131 で定義されている標準の Get メソッドで、HTTP メソッドも GET です。
ListHashLists

rpc ListHashLists(ListHashListsRequest) returns (ListHashListsResponse)

ハッシュリストを一覧表示します。

V5 API では、このメソッドで一度返されたハッシュリストが削除されることはありません。これにより、クライアントはこのメソッドの使用をスキップして、必要なすべてのハッシュリストをハードコードするだけで済みます。

これは https://google.aip.dev/132 で定義されている標準の List メソッドで、HTTP メソッドは GET です。
SearchHashes

rpc SearchHashes(SearchHashesRequest) returns (SearchHashesResponse)

指定された接頭辞に一致する完全なハッシュを検索します。

これは、https://google.aip.dev/136 で定義されているカスタム メソッドです（カスタム メソッドとは、Google の一般的な API 開発の命名法におけるカスタム名を持つこのメソッドを指します。カスタム HTTP メソッドの使用を意味するものではありません）。

BatchGetHashListsRequest

複数のハッシュリストを同時に取得するためのリクエスト。

フィールド
names[]

string

必須。特定のハッシュリストの名前。リストは、脅威リストでも、グローバル キャッシュでも構いません。名前に重複を含めることはできません。重複があると、クライアントでエラーが発生します。
version[]

bytes

クライアントがすでに所有しているハッシュリストのバージョン。クライアントが初めてハッシュリストを取得する場合は、フィールドを空のままにしてください。それ以外の場合は、以前サーバーから受け取ったバージョンをクライアントが提供する必要があります。クライアントは、これらのバイトを操作してはなりません。

クライアントは、対応するリスト名と同じ順序でバージョンを送信する必要はありません。クライアントが 1 つのリクエストで送信するバージョンの名前の数より少ない、または多い場合があります。ただし、クライアントは、同じ名前に対応する複数のバージョンを送信してはなりません。送信した場合、クライアントはエラーを受け取ります。

従来の注意事項: API の V4 では states と呼ばれていましたが、わかりやすくするために version に名前が変更されました。
desired_hash_length

HashLength

返されたハッシュの望ましいハッシュ プレフィックス長（バイト単位）。サーバーは、指定された長さのすべてのハッシュ接頭辞を返します。

ハッシュリストが異なれば、desired_hash_length フィールドに指定できる値の要件も異なります。これは HashListMetadata の supported_hash_lengths フィールドにあります。desired_hash_length が supported_hash_lengths 内に値を指定しない場合、クライアントにエラーが返されます。

特に BatchGetHashListsRequest については、クライアントがリストごとに異なる desired_hash_length を指定することはできません。必要な場合、クライアントは複数の BatchGetHashListsRequest に分割する必要があります。
size_constraints

SizeConstraints

各リストのサイズ制約。省略した場合、制約はありません。ここに表示されるサイズはリストごとのものであり、すべてのリストで集計されるわけではありません。

BatchGetHashListsResponse

複数のハッシュリストを含むレスポンス。

フィールド
hash_lists[]

HashList

ハッシュは、リクエストで指定された順序で表示されます。

FullHash

1 つ以上の一致で識別された完全なハッシュ。

フィールド
full_hash

bytes

一致するフルハッシュ。これは SHA256 ハッシュです。長さは正確に 32 バイトになります。
full_hash_details[]

FullHashDetail

順序なしリスト。このフルハッシュに関連する詳細を識別する繰り返しフィールド。

FullHashDetail

一致するフルハッシュの詳細。

上位互換性に関する重要な注意事項: 新しい脅威の種類と脅威の属性はサーバーによって随時追加される可能性があります。これらの追加はマイナーなバージョン変更とみなされます。Google のポリシーでは API でマイナー バージョン番号を公開しない（バージョニング ポリシーについては https://cloud.google.com/apis/design/versioning を参照）ため、クライアントはクライアントによって無効とみなされる ThreatType 列挙値または ThreatAttribute 列挙値を含む FullHashDetail メッセージを受信できるようにしておく必要があります。したがって、ThreatType と ThreatAttribute のすべての列挙値の有効性をチェックするのは、クライアントの責任です。いずれかの値が無効とみなされる場合、クライアントは FullHashDetail メッセージ全体を無視しなければなりません。

フィールド
threat_type

ThreatType

脅威の種類。このフィールドが空になることはありません。
attributes[]

ThreatAttribute

順序なしリスト。それらの完全なハッシュに関する追加属性。空の場合もあります。

GetHashListRequest

ハッシュリストの取得リクエスト。脅威リストの場合もあれば、Global Cache などの脅威以外のリストである場合もあります。

V5 の新機能: わかりやすくするために、V4 では以前は states と呼ばれていましたが、version に名前が変更されました。リストに名前を付け、プラットフォーム タイプと脅威エントリタイプを削除しました。複数のリストを同じ脅威の種類にしたり、単一のリストを複数の脅威の種類に関係させたりできるようになりました。クライアントが、希望のハッシュ長を指定できる新機能が追加されました。これは、多くのクライアントの実装で問題を引き起こしている V4 の可変長ハッシュ プレフィックスへの回答の一環です。リスト内のすべてのハッシュが 1 つの長さになるため、クライアントの実装が大幅に効率化されます。制約が簡素化され、圧縮タイプが削除されました（常に圧縮が適用されます）。

フィールド
name

string

必須。このハッシュリストの名前。脅威リストの場合もあれば、グローバルキャッシュの場合もあります。
version

bytes

クライアントがすでに所有しているハッシュリストのバージョン。クライアントがハッシュリストを初めて取得する場合、このフィールドは空のままにしなければなりません。それ以外の場合、クライアントはサーバーから以前に受信したバージョンを提供すべきです。クライアントは、これらのバイトを操作してはなりません。

V5 の新機能: API の V4 では states と呼ばれていましたが、わかりやすくするために version に名前が変更されました。
desired_hash_length

HashLength

返されたハッシュの望ましいハッシュ プレフィックス長（バイト単位）。サーバーは、指定された長さのすべてのハッシュ接頭辞を返します。

ハッシュリストが異なれば、desired_hash_length フィールドに指定できる値の要件も異なります。これは HashListMetadata の supported_hash_lengths フィールドにあります。desired_hash_length で supported_hash_lengths 内の値が指定されていない場合は、エラーが返されます。
size_constraints

SizeConstraints

リストのサイズ制約。省略した場合、制約はありません。処理能力、帯域幅、ストレージが限られているすべてのデバイスに、制約を適用することをおすすめします。

HashList

名前で識別されるハッシュのリスト。

フィールド
name

string

ハッシュリストの名前。グローバル キャッシュも単なるハッシュリストであり、ここで参照できます。
version

bytes

ハッシュリストのバージョン。クライアントは、これらのバイトを操作してはなりません。
partial_update

bool

true の場合、これはクライアントがすでに持っているものに基づく追加と削除を含む部分的な差分になります。false の場合、これは完全なハッシュリストです。

false の場合、クライアントはこのハッシュリスト用にローカルに保存されているバージョンを削除しなければなりません。これは、クライアントが所有するバージョンが著しく古くなっているか、クライアントデータが破損していると考えられることを意味します。compressed_removals フィールドは空になります。

true の場合、クライアントは削除してから追加を適用することで、増分アップデートを適用しなければなりません。
compressed_removals

RiceDeltaEncoded32Bit

削除インデックスのライスデルタ エンコード バージョン。各ハッシュリストには確実に 2^32 エントリ未満なので、インデックスは 32 ビット整数として扱われ、エンコードされます。
minimum_wait_duration

Duration

クライアントがハッシュリストを再度取得するには、少なくともここで指定した時間まで待つ必要があります。省略またはゼロの場合、サーバーはクライアントに送信される追加のアップデートがあることを示すため、クライアントはすぐにフェッチすべきです。ただし、クライアント指定の制約により、クライアントはすぐに取得できません。
metadata

HashListMetadata

ハッシュリストに関するメタデータ。GetHashList メソッドでは入力されませんが、ListHashLists メソッドで入力されます。
共用体フィールド compressed_additions。加算の Rice-delta エンコード バージョン。追加したリクエストのハッシュ プレフィックスの長さは、リスト内のすべての追加で一様です。クライアントによって送信された desired_hash_length、またはクライアントがこのフィールドを省略した場合はサーバーが選択した値になります。compressed_additions は次のいずれかになります。
additions_four_bytes

RiceDeltaEncoded32Bit

4 バイトの追加値。
additions_eight_bytes

RiceDeltaEncoded64Bit

8 バイトの追加値。
additions_sixteen_bytes

RiceDeltaEncoded128Bit

16 バイトの追加値。
additions_thirty_two_bytes

RiceDeltaEncoded256Bit

32 バイトの追加値。
共用体フィールド checksum。これは、提供された更新を適用した後のデータベースに存在するすべてのハッシュの並べ替えられたリストのチェックサムです。これは、複数のハッシュ アルゴリズムを許可する「oneof」フィールドです。また、サーバーがこのフィールドを省略して（更新が提供されていない場合）、クライアントが既存のチェックサムを使用する必要があることを示すこともできます。checksum は次のいずれかになります。
sha256_checksum

bytes

すべてのハッシュの並べ替え済みリスト。SHA256 で再度ハッシュ化されます。

HashListMetadata

特定のハッシュリストに関するメタデータ。

フィールド
threat_types[]

ThreatType

順序なしリスト。空でない場合、ハッシュリストは一種の脅威リストであり、このハッシュリスト内のハッシュまたはハッシュプレフィックスに関連付けられている脅威の種類を列挙します。エントリが脅威を表していない場合、つまり、安全な種類のエントリを表す場合は、空になることがあります。
likely_safe_types[]

LikelySafeType

順序なしリスト。空でない場合、これはハッシュリストが安全な可能性のあるハッシュのリストを表し、安全であると考えられる方法を列挙することを指定します。このフィールドは、Threat_types フィールドと相互に排他的です。
mobile_optimized

bool

このリストがモバイル デバイス（Android、iOS）向けに最適化されているかどうか。
description

string

このリストに関する人が読める形式の説明。英語で書かれている。
supported_hash_lengths[]

HashLength

このハッシュリストでサポートされているハッシュ長。各ハッシュリストは少なくとも 1 つの長さをサポートします。そのため、このフィールドは空になりません。

HashLength

ハッシュリスト内のハッシュの長さ。

列挙型
HASH_LENGTH_UNSPECIFIED 長さが指定されていません。サーバーはクライアントへのレスポンスではこの値を返しませんが（supported_hash_lengths フィールドに指定）、クライアントはこの値をサーバー（desired_hash_length フィールド内）に送信することができます。この場合、サーバーはこの値を自動的に選択します。クライアントは、サーバーに値を選択させるべきです。
FOUR_BYTES 各ハッシュは 4 バイトの接頭辞です。
EIGHT_BYTES 各ハッシュは 8 バイトの接頭辞です。
SIXTEEN_BYTES 各ハッシュは 16 バイトの接頭辞です。
THIRTY_TWO_BYTES 各ハッシュは 32 バイトのフルハッシュです。

LikelySafeType

安全性が疑われるサイトの種類

なお、SearchHashesResponse には意図的に LikelySafeType が含まれていません。

列挙型
LIKELY_SAFE_TYPE_UNSPECIFIED 不明
GENERAL_BROWSING このサイトは、一般的なブラウジングには十分安全と考えられます。これはグローバル キャッシュとも呼ばれます。
CSD このサイトはおそらく安全であるため、クライアントサイド検出モデルやパスワード保護チェックを実行する必要はありません。
DOWNLOAD このサイトは安全であるため、サイトからのダウンロードをチェックする必要はありません。

ListHashListsRequest

使用可能なハッシュリストを一覧表示するリクエスト。

フィールド
page_size

int32

返されるハッシュリストの最大数。サービスが返す値はこれよりも少ないことがあります。指定しない場合、サーバーはページサイズを選択します。ページサイズはハッシュリストの数よりも大きくなることがあるため、ページ分けは不要です。
page_token

string

前回の ListHashLists 呼び出しから受け取ったページトークン。後続のページを取得するにはこれを指定します。

ListHashListsResponse

ハッシュリストに関するメタデータを含むレスポンス。

フィールド
hash_lists[]

HashList

ハッシュは任意の順序で表示されます。ハッシュリストに関するメタデータのみが含まれ、コンテンツは含まれません。
next_page_token

string

次のページを取得するために page_token として送信できるトークン。このフィールドを省略すると、後続のページはなくなります。

RiceDeltaEncoded128Bit

128 ビットの数値をエンコードする点を除き、RiceDeltaEncoded32Bit と同じです。

フィールド
first_value_hi

uint64

エンコードされたデータの最初のエントリの上位 64 ビット（ハッシュ）。フィールドが空の場合、上位 64 ビットはすべてゼロです。
first_value_lo

fixed64

エンコードされたデータの最初のエントリの下位 64 ビット（ハッシュ）。フィールドが空の場合、下位 64 ビットはすべてゼロです。
rice_parameter

int32

Golomb-Rice パラメータ。このパラメータは、99 ～ 126 の範囲であることが保証されています。
entries_count

int32

エンコードされたデータ内でデルタエンコードされたエントリの数。1 つの整数のみがエンコードされている場合はゼロになり、1 つの値が first_value に保存されます。
encoded_data

bytes

Golomb-Rice コーダーを使用してエンコードされたエンコード済みデルタ。

RiceDeltaEncoded256 ビット

256 ビットの数値をエンコードする点を除き、RiceDeltaEncoded32Bit と同じです。

フィールド
first_value_first_part

uint64

エンコードされたデータ内の最初のエントリ（ハッシュ）の最初の 64 ビット。フィールドが空の場合、最初の 64 ビットはすべてゼロです。
first_value_second_part

fixed64

エンコードされたデータの最初のエントリの 65 ～ 128 ビット目（ハッシュ）。フィールドが空の場合、65 から 128 までのビットはすべてゼロです。
first_value_third_part

fixed64

エンコードされたデータ内の最初のエントリの 129 ～ 192 ビット目（ハッシュ）。フィールドが空の場合、129 から 192 までのビットはすべてゼロです。
first_value_fourth_part

fixed64

エンコードされたデータの最初のエントリの最後の 64 ビット（ハッシュ）。フィールドが空の場合、最後の 64 ビットはすべてゼロです。
rice_parameter

int32

Golomb-Rice パラメータ。このパラメータは、227 ～ 254 の範囲であることが保証されています。
entries_count

int32

エンコードされたデータ内でデルタエンコードされたエントリの数。1 つの整数のみがエンコードされている場合はゼロになり、1 つの値が first_value に保存されます。
encoded_data

bytes

Golomb-Rice コーダーを使用してエンコードされたエンコード済みデルタ。

RiceDelta エンコード 32 ビット

Rice-Golomb のエンコードされたデータ。ハッシュまたは削除インデックスに使用されます。すべてのハッシュまたはインデックスは同じ長さであることが保証され、この長さはちょうど 32 ビットです。

一般的に、すべてのエントリを辞書順に並べ替えると、上位ビットが下位ビットほど頻繁に変更されない傾向があることがわかります。これは、エントリ間の隣接する差分も取得すると、高次のビットがゼロである可能性が高いことを意味します。これは、基本的に特定のビット数を選択することによって、この高い確率ゼロを利用します。これよりも重要なビットはすべてゼロである可能性が高いため、単項エンコードを使用します。rice_parameter フィールドをご覧ください。

過去の注意事項: Rice-delta エンコーディングは、この API の V4 で初めて使用されました。V5 では 2 つの大きな改善が行われました。1 つ目は、4 バイトを超えるハッシュ プレフィックスでライスデルタ エンコードが利用できるようになったことです。2 つ目は、コストのかかる並べ替え手順を回避するために、エンコードされたデータがビッグ エンディアンとして扱われるようになったことです。

フィールド
first_value

uint32

エンコードされたデータの最初のエントリ（ハッシュまたはインデックス）。または、単一のハッシュ プレフィックスまたはインデックスのみがエンコードされている場合は、そのエントリの値。フィールドが空の場合、エントリはゼロです。
rice_parameter

int32

Golomb-Rice パラメータ。このパラメータは、3 ～ 30 の範囲であることが保証されています。
entries_count

int32

エンコードされたデータ内でデルタエンコードされたエントリの数。1 つの整数のみがエンコードされている場合はゼロになり、1 つの値が first_value に保存されます。
encoded_data

bytes

Golomb-Rice コーダーを使用してエンコードされたエンコード済みデルタ。

RiceDelta エンコード 64 ビット

64 ビットの数値をエンコードする点を除き、RiceDeltaEncoded32Bit と同じです。

フィールド
first_value

uint64

エンコードされたデータの最初のエントリ（ハッシュ）。1 つのハッシュ プレフィックスのみがエンコードされている場合は、そのエントリの値。フィールドが空の場合、エントリはゼロです。
rice_parameter

int32

Golomb-Rice パラメータ。このパラメータは、35 ～ 62 の範囲であることが保証されています。
entries_count

int32

エンコードされたデータ内でデルタエンコードされたエントリの数。1 つの整数のみがエンコードされている場合はゼロになり、1 つの値が first_value に保存されます。
encoded_data

bytes

Golomb-Rice コーダーを使用してエンコードされたエンコード済みデルタ。

SearchHashesRequest

特定のハッシュ接頭辞を検索するためにクライアントが発行するリクエスト。

これは脅威リストのみを検索するように設計されており、グローバル キャッシュなどの脅威リスト以外は検索しません。

V5 の新機能: クライアントが ClientInfo やローカル データベース内のハッシュリストの状態を指定する必要はありません。これは、プライバシーを保護するためです。また、関心のある脅威のタイプを送信する必要がありません。

フィールド
hash_prefixes[]

bytes

必須。検索されるハッシュ接頭辞。クライアントは、1,000 個を超えるハッシュ プレフィックスを送信してはなりません。ただし、URL 処理手順に従い、クライアントは 30 個を超えるハッシュ プレフィックスを送信する必要がないべきではありません。

現在、各ハッシュ接頭辞はちょうど 4 バイトの長さである必要があります。これは今後緩和される可能性があります。
filter

string

省略可。特定の種類の脅威のみを取得するなど、フィルタリングがクライアントで必要な場合は、この値を指定できます。省略すると、一致するすべての脅威が返されます。セーフ ブラウジングによる最大限の保護を実現するために、この設定を省略することを強くおすすめします。

フィルタは、Google Common Expression Language を使用して指定します。Google Common Expression Language は、一般的な例とともに https://github.com/google/cel-spec で確認できます。ここでは、具体的な例をいくつか紹介します。

フィルタ "threat_type == ThreatType.SOCIAL_ENGINEERING" では、FullHashDetail 内の脅威の種類が SOCIAL_ENGINEERING である必要があります。識別子 "threat_type" は、現在の脅威の種類を示しています。識別子 "ThreatType" は、可能性のあるすべての脅威の種類のコレクションを指します。

フィルタ "threat_type in [ ThreatType.UNWANTED_SOFTWARE, ThreatType.MALWARE ]" では、脅威の種類が UNWANTED_SOFTWARE または MALWARE である必要があります。

SearchHashesResponse

脅威ハッシュの検索後に返されるレスポンス。

何も見つからなかった場合、サーバーは NOT_FOUND ステータス（HTTP ステータス コード 404）を返すのではなく、full_hashes フィールドを空にして OK ステータス（HTTP ステータス コード 200）を返します。

V5 の新機能: FullHash と FullHashDetail は分離されています。ハッシュが複数の脅威（MALWARE と SOCIAL_ENGINEERING の両方など）を持つサイトを表す場合、V4 のようにフルハッシュを 2 回送信する必要はありません。さらに、キャッシュ期間を単一の cache_duration フィールドに簡素化しました。

フィールド
full_hashes[]

FullHash

順序なしリスト。見つかった完全なハッシュの順序なしリスト。
cache_duration

Duration

クライアントサイドのキャッシュ期間。クライアントは、この継続時間を現在の時刻に追加して有効期限を決定しなければなりません。その後、レスポンスで返される完全なハッシュの数に関係なく、リクエストでクライアントからクエリされたすべてのハッシュ接頭辞に有効期限が適用されます。サーバーが特定のハッシュ接頭辞に対して完全なハッシュを返さない場合でも、この事実はクライアントによってキャッシュされなければなりません。

フィールド full_hashes が空である場合にのみ、クライアントは cache_duration を増やして、サーバーで指定された有効期限より後の新しい有効期限を決定しても構いません。いずれの場合も、延長されたキャッシュ期間は 24 時間以下にする必要があります。

重要: クライアントは、サーバーがすべてのレスポンスで同じキャッシュ期間を返すことを想定してはなりません。サーバーは、状況に応じて異なるレスポンスに異なるキャッシュ期間を選択しても構いません。

SizeConstraints

ハッシュリストのサイズに関する制約。

フィールド
max_update_entries

int32

エントリの最大数。更新にこの値を超えるエントリが含まれることはありませんが、更新に含まれるエントリはこの値より少なくなる可能性があります。少なくとも 1,024 でなければなりません。省略するかゼロの場合、アップデート サイズの上限は設定されません。
max_database_entries

int32

クライアントがローカル データベースにリストするエントリの最大数を設定します。（サーバーは、クライアントにこの数より少ないエントリを格納しても構いません）。省略するかゼロの場合、データベース サイズの上限は設定されません。

ThreatAttribute

脅威の属性。これらの属性は、特定の脅威に追加の意味を与える場合がありますが、脅威の種類には影響しません。たとえば、ある属性で低い信頼度を指定し、別の属性でより高い信頼度を指定する場合があります。今後、さらに多くの属性が追加される可能性があります。

列挙型
THREAT_ATTRIBUTE_UNSPECIFIED 不明な属性です。これがサーバーから返された場合、クライアントはそれを含む FullHashDetail を完全に無視します。
CANARY 適用に Threat_type を使用しないことを示します。
FRAME_ONLY Threat_type は、フレームへの適用にのみ使用することを示します。

ThreatType

脅威の種類。

列挙型
THREAT_TYPE_UNSPECIFIED 脅威の種類が不明です。これがサーバーから返された場合、クライアントはそれを含む FullHashDetail を完全に無視します。
MALWARE

マルウェアの脅威の種類。マルウェアとは、ソフトウェアまたはモバイルアプリであり、特にパソコン、モバイル デバイス、それらで実行されているソフトウェア、パソコンやモバイル デバイスのユーザーに対して有害な影響を与えることを目的として設計されたものを指します。マルウェアは、ユーザーの同意なしにソフトウェアをインストールする、ウイルスなどの有害なソフトウェアをインストールするなど、悪意のある動作を示します。

詳細につきましては、こちらをご覧ください。
SOCIAL_ENGINEERING

ソーシャル エンジニアリングの脅威の種類。ソーシャル エンジニアリング ページは、閲覧者を混乱させて、そのサードパーティの真の代理人しか信頼できないような、第三者の代理としてふさわしいと偽っています。フィッシングはソーシャル エンジニアリングの一種で、視聴者をだまして、ログイン認証情報などの特定の情報を提供させる特定のアクションを実行させます。

詳細につきましては、こちらをご覧ください。
UNWANTED_SOFTWARE 望ましくないソフトウェアの脅威の種類。望ましくないソフトウェアとは、Google のソフトウェア原則に準拠していなくても、マルウェアではないソフトウェアのことです。
POTENTIALLY_HARMFUL_APPLICATION Play ストアの Google Play プロテクトで使用される、有害な可能性があるアプリの脅威の種類。