docs(webrisk-samples): init add samples and tests (#8810)

* docs(webrisk-samples): init add samples and tests

* added pytest to requirements

* added test and fixed lint errors

* modified acc to review comments

* modified acc to review comments

* modified acc to review comments

* deleted commented out code

Author: Sita04

webrisk/snippets/__init__.py

@@ -0,0 +1,13 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.

webrisk/snippets/compute_threatlist_diff.py

@@ -0,0 +1,81 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+# [START webrisk_compute_threatlist_diff]
+from google.cloud import webrisk_v1
+
+
+def compute_threatlist_diff(
+    threat_type: webrisk_v1.ThreatType,
+    version_token: bytes,
+    max_diff_entries: int,
+    max_database_entries: int,
+    compression_type: webrisk_v1.CompressionType,
+) -> None:
+    """Gets the most recent threat list diffs. These diffs should be applied to a local database of
+    hashes to keep it up-to-date.
+
+    If the local database is empty or excessively out-of-date,
+    a complete snapshot of the database will be returned. This Method only updates a
+    single ThreatList at a time. To update multiple ThreatList databases, this method needs to be
+    called once for each list.
+
+    Args:
+        threat_type: The threat list to update. Only a single ThreatType should be specified per request.
+            threat_type = webrisk_v1.ThreatType.MALWARE
+
+        version_token: The current version token of the client for the requested list. If the
+            client does not have a version token (this is the first time calling ComputeThreatListDiff),
+            this may be left empty and a full database snapshot will be returned.
+
+        max_diff_entries: The maximum size in number of entries. The diff will not contain more entries
+            than this value. This should be a power of 2 between 2**10 and 2**20.
+            If zero, no diff size limit is set.
+            max_diff_entries = 1024
+
+        max_database_entries: Sets the maximum number of entries that the client is willing to have in the local database.
+            This should be a power of 2 between 2**10 and 2**20. If zero, no database size limit is set.
+            max_database_entries = 1024
+
+        compression_type: The compression type supported by the client.
+            compression_type = webrisk_v1.CompressionType.RAW
+    """
+
+    webrisk_client = webrisk_v1.WebRiskServiceClient()
+
+    constraints = webrisk_v1.ComputeThreatListDiffRequest.Constraints()
+    constraints.max_diff_entries = max_diff_entries
+    constraints.max_database_entries = max_database_entries
+    constraints.supported_compressions = [compression_type]
+
+    request = webrisk_v1.ComputeThreatListDiffRequest()
+    request.threat_type = threat_type
+    request.version_token = version_token
+    request.constraints = constraints
+
+    response = webrisk_client.compute_threat_list_diff(request)
+
+    # The returned response contains the following information:
+    # https://cloud.google.com/web-risk/docs/reference/rpc/google.cloud.webrisk.v1#computethreatlistdiffresponse
+    # Type of response: DIFF/ RESET/ RESPONSE_TYPE_UNSPECIFIED
+    print(response.response_type)
+
+    # New version token to be used the next time when querying.
+    print(response.new_version_token)
+
+    # Recommended next diff timestamp.
+    print(response.recommended_next_diff)
+
+    print("Obtained threat list diff.")
+# [END webrisk_compute_threatlist_diff]

webrisk/snippets/noxfile_config.py

@@ -0,0 +1,42 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+# Default TEST_CONFIG_OVERRIDE for python repos.
+
+# You can copy this file into your directory, then it will be imported from
+# the noxfile.py.
+
+# The source of truth:
+# https://github.com/GoogleCloudPlatform/python-docs-samples/blob/main/noxfile_config.py
+
+TEST_CONFIG_OVERRIDE = {
+    # You can opt out from the test for specific Python versions.
+    "ignored_versions": ["2.7", "3.6"],
+    # Old samples are opted out of enforcing Python type hints
+    # All new samples should feature them
+    "enforce_type_hints": True,
+    # An envvar key for determining the project id to use. Change it
+    # to 'BUILD_SPECIFIC_GCLOUD_PROJECT' if you want to opt in using a
+    # build specific Cloud project. You can also use your own string
+    # to use your own Cloud project.
+    "gcloud_project_env": "GOOGLE_CLOUD_PROJECT",
+    # 'gcloud_project_env': 'BUILD_SPECIFIC_GCLOUD_PROJECT',
+    # If you need to use a specific version of pip,
+    # change pip_version_override to the string representation
+    # of the version number, for example, "20.2.4"
+    "pip_version_override": None,
+    # A dictionary you want to inject into your test. Don't put any
+    # secrets here. These values will override predefined values.
+    "envs": {},
+}

webrisk/snippets/requirements-test.txt

@@ -0,0 +1 @@
+pytest==7.2.0

webrisk/snippets/requirements.txt

@@ -0,0 +1 @@
+google-cloud-webrisk==1.9.0

webrisk/snippets/search_hashes.py

@@ -0,0 +1,59 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+# [START webrisk_search_hash]
+from google.cloud import webrisk_v1
+
+
+def search_hashes(hash_prefix: bytes, threat_type: webrisk_v1.ThreatType) -> None:
+    """Gets the full hashes that match the requested hash prefix.
+
+    This is used after a hash prefix is looked up in a threatList and there is a match.
+    The client side threatList only holds partial hashes so the client must query this method
+    to determine if there is a full hash match of a threat.
+
+    Args:
+        hash_prefix: A hash prefix, consisting of the most significant 4-32 bytes of a SHA256 hash.
+            For JSON requests, this field is base64-encoded. Note that if this parameter is provided
+            by a URI, it must be encoded using the web safe base64 variant (RFC 4648).
+            Example:
+                uri = "http://example.com"
+                sha256 = sha256()
+                sha256.update(base64.urlsafe_b64encode(bytes(uri, "utf-8")))
+                hex_string = sha256.digest()
+
+        threat_type: The ThreatLists to search in. Multiple ThreatLists may be specified.
+            For the list on threat types, see:
+            https://cloud.google.com/web-risk/docs/reference/rpc/google.cloud.webrisk.v1#threattype
+            threat_type = [webrisk_v1.ThreatType.MALWARE, webrisk_v1.ThreatType.SOCIAL_ENGINEERING]
+    """
+    webrisk_client = webrisk_v1.WebRiskServiceClient()
+
+    # Set the hashPrefix and the threat types to search in.
+    request = webrisk_v1.SearchHashesRequest()
+    request.hash_prefix = hash_prefix
+    request.threat_types = [threat_type]
+
+    response = webrisk_client.search_hashes(request)
+
+    # Get all the hashes that match the prefix. Cache the returned hashes until the time
+    # specified in threat_hash.expire_time
+    # For more information on response type, see:
+    # https://cloud.google.com/web-risk/docs/reference/rpc/google.cloud.webrisk.v1#threathash
+    for threat_hash in response.threats:
+        print(threat_hash.hash)
+
+    print("Completed searching threat hashes.")
+
+# [END webrisk_search_hash]

webrisk/snippets/search_uri.py

@@ -0,0 +1,45 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+# [START webrisk_search_uri]
+from google.cloud import webrisk_v1
+
+
+def search_uri(uri: str, threat_type: webrisk_v1.ThreatType.MALWARE) -> None:
+    """Checks whether a URI is on a given threatList.
+
+    Multiple threatLists may be searched in a single query. The response will list all
+    requested threatLists the URI was found to match. If the URI is not
+    found on any of the requested ThreatList an empty response will be returned.
+
+    Args:
+        uri: The URI to be checked for matches
+            Example: "http://testsafebrowsing.appspot.com/s/malware.html"
+
+        threat_type: The ThreatLists to search in. Multiple ThreatLists may be specified.
+            Example: threat_type = webrisk_v1.ThreatType.MALWARE
+    """
+    webrisk_client = webrisk_v1.WebRiskServiceClient()
+
+    request = webrisk_v1.SearchUrisRequest()
+    request.threat_types = [threat_type]
+    request.uri = uri
+
+    response = webrisk_client.search_uris(request)
+    if response.threat.threat_types:
+        print(f"The URI has the following threat: {response}")
+        return
+
+    print("The URL is safe!")
+# [END webrisk_search_uri]

webrisk/snippets/submit_uri.py

@@ -0,0 +1,44 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+# [START webrisk_submit_uri]
+from google.cloud import webrisk_v1
+
+
+def submit_uri(project_id: str, uri: str) -> None:
+    """Submits a URI suspected of containing malicious content to be reviewed.
+
+    Returns a google.longrunning.Operation which, once the review is complete, is updated with its result.
+    If the result verifies the existence of malicious content, the site will be added to the
+    Google's Social Engineering lists in order to protect users that could get exposed to this
+    threat in the future. Only allow-listed projects can use this method during Early Access.
+
+     Args:
+         project_id: The name of the project that is making the submission.
+         uri: The URI that is being reported for malicious content to be analyzed.
+             uri = "http://testsafebrowsing.appspot.com/s/malware.html"
+    """
+    webrisk_client = webrisk_v1.WebRiskServiceClient()
+
+    submission = webrisk_v1.Submission()
+    submission.uri = uri
+
+    request = webrisk_v1.CreateSubmissionRequest()
+    request.parent = f"projects/{project_id}"
+    request.submission = submission
+
+    response = webrisk_client.create_submission(request)
+    print(f"Submission response: {response}")
+
+# [END webrisk_submit_uri]

webrisk/snippets/test_basic_samples.py

@@ -0,0 +1,57 @@
+#  Copyright 2022 Google LLC
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+import base64
+import hashlib
+import re
+
+from _pytest.capture import CaptureFixture
+import google
+from google.cloud import webrisk_v1
+
+from .compute_threatlist_diff import compute_threatlist_diff
+from .search_hashes import search_hashes
+from .search_uri import search_uri
+from .submit_uri import submit_uri
+
+PROJECT = google.auth.default()[1]
+
+
+def test_search_uri_with_threat(capsys: CaptureFixture) -> None:
+    search_uri("http://testsafebrowsing.appspot.com/s/malware.html", webrisk_v1.ThreatType.MALWARE)
+    assert re.search("The URI has the following threat: ", capsys.readouterr().out)
+
+
+def test_search_uri_without_threat(capsys: CaptureFixture) -> None:
+    search_uri("http://testsafebrowsing.appspot.com/malware.html", webrisk_v1.ThreatType.MALWARE)
+    assert re.search("The URL is safe!", capsys.readouterr().out)
+
+
+def test_submit_uri(capsys: CaptureFixture) -> None:
+    submit_uri(PROJECT, "http://testsafebrowsing.appspot.com/s/malware.html")
+    assert re.search("Submission response: ", capsys.readouterr().out)
+
+
+def test_search_hashes(capsys: CaptureFixture) -> None:
+    uri = "http://example.com"
+    sha256 = hashlib.sha256()
+    sha256.update(base64.urlsafe_b64encode(bytes(uri, "utf-8")))
+    hex_string = sha256.digest()
+
+    search_hashes(hex_string, webrisk_v1.ThreatType.MALWARE)
+    assert re.search("Completed searching threat hashes.", capsys.readouterr().out)
+
+
+def test_compute_threatdiff_list(capsys: CaptureFixture) -> None:
+    compute_threatlist_diff(webrisk_v1.ThreatType.MALWARE, b'', 1024, 1024, webrisk_v1.CompressionType.RAW)
+    assert re.search("Obtained threat list diff.", capsys.readouterr().out)