docs: Add documentation for enums (#256)

* docs: Add documentation for enums

fix: Add context manager return types

chore: Update gapic-generator-python to v1.8.1
PiperOrigin-RevId: 503210727

Source-Link: googleapis/googleapis@a391fd1

Source-Link: googleapis/googleapis-gen@0080f83
Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiMDA4MGY4MzBkZWMzN2MzMzg0MTU3MDgyYmNlMjc5ZTM3MDc5ZWE1OCJ9

* 🦉 Updates from OwlBot post-processor

See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md

Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>

packages/google-cloud-websecurityscanner/google/cloud/websecurityscanner_v1/services/web_security_scanner/client.py

@@ -1554,7 +1554,7 @@ def sample_list_finding_type_stats():
         # Done; return the response.
         return response
 
-    def __enter__(self):
+    def __enter__(self) -> "WebSecurityScannerClient":
         return self
 
     def __exit__(self, type, value, traceback):

packages/google-cloud-websecurityscanner/google/cloud/websecurityscanner_v1/types/finding.py

@@ -101,7 +101,20 @@ class Finding(proto.Message):
     """
 
     class Severity(proto.Enum):
-        r"""The severity level of a vulnerability."""
+        r"""The severity level of a vulnerability.
+
+        Values:
+            SEVERITY_UNSPECIFIED (0):
+                No severity specified. The default value.
+            CRITICAL (1):
+                Critical severity.
+            HIGH (2):
+                High severity.
+            MEDIUM (3):
+                Medium severity.
+            LOW (4):
+                Low severity.
+        """
         SEVERITY_UNSPECIFIED = 0
         CRITICAL = 1
         HIGH = 2

packages/google-cloud-websecurityscanner/google/cloud/websecurityscanner_v1/types/finding_addon.py

@@ -175,7 +175,57 @@ class Xss(proto.Message):
     """
 
     class AttackVector(proto.Enum):
-        r"""Types of XSS attack vector."""
+        r"""Types of XSS attack vector.
+
+        Values:
+            ATTACK_VECTOR_UNSPECIFIED (0):
+                Unknown attack vector.
+            LOCAL_STORAGE (1):
+                The attack comes from fuzzing the browser's
+                localStorage.
+            SESSION_STORAGE (2):
+                The attack comes from fuzzing the browser's
+                sessionStorage.
+            WINDOW_NAME (3):
+                The attack comes from fuzzing the window's
+                name property.
+            REFERRER (4):
+                The attack comes from fuzzing the referrer
+                property.
+            FORM_INPUT (5):
+                The attack comes from fuzzing an input
+                element.
+            COOKIE (6):
+                The attack comes from fuzzing the browser's
+                cookies.
+            POST_MESSAGE (7):
+                The attack comes from hijacking the post
+                messaging mechanism.
+            GET_PARAMETERS (8):
+                The attack comes from fuzzing parameters in
+                the url.
+            URL_FRAGMENT (9):
+                The attack comes from fuzzing the fragment in
+                the url.
+            HTML_COMMENT (10):
+                The attack comes from fuzzing the HTML
+                comments.
+            POST_PARAMETERS (11):
+                The attack comes from fuzzing the POST
+                parameters.
+            PROTOCOL (12):
+                The attack comes from fuzzing the protocol.
+            STORED_XSS (13):
+                The attack comes from the server side and is
+                stored.
+            SAME_ORIGIN (14):
+                The attack is a Same-Origin Method Execution
+                attack via a GET parameter.
+            USER_CONTROLLABLE_URL (15):
+                The attack payload is received from a
+                third-party host via a URL that is
+                user-controllable
+        """
         ATTACK_VECTOR_UNSPECIFIED = 0
         LOCAL_STORAGE = 1
         SESSION_STORAGE = 2
@@ -226,7 +276,15 @@ class Xxe(proto.Message):
     """
 
     class Location(proto.Enum):
-        r"""Locations within a request where XML was substituted."""
+        r"""Locations within a request where XML was substituted.
+
+        Values:
+            LOCATION_UNSPECIFIED (0):
+                Unknown Location.
+            COMPLETE_REQUEST_BODY (1):
+                The XML payload replaced the complete request
+                body.
+        """
         LOCATION_UNSPECIFIED = 0
         COMPLETE_REQUEST_BODY = 1
 

packages/google-cloud-websecurityscanner/google/cloud/websecurityscanner_v1/types/scan_config.py

@@ -77,7 +77,20 @@ class ScanConfig(proto.Message):
     """
 
     class UserAgent(proto.Enum):
-        r"""Type of user agents used for scanning."""
+        r"""Type of user agents used for scanning.
+
+        Values:
+            USER_AGENT_UNSPECIFIED (0):
+                The user agent is unknown. Service will default to
+                CHROME_LINUX.
+            CHROME_LINUX (1):
+                Chrome on Linux. This is the service default
+                if unspecified.
+            CHROME_ANDROID (2):
+                Chrome on Android.
+            SAFARI_IPHONE (3):
+                Safari on IPhone.
+        """
         USER_AGENT_UNSPECIFIED = 0
         CHROME_LINUX = 1
         CHROME_ANDROID = 2
@@ -88,6 +101,14 @@ class RiskLevel(proto.Enum):
         impact scanning will minimize requests with the potential to
         modify data. To achieve the maximum scan coverage, NORMAL risk
         level is recommended.
+
+        Values:
+            RISK_LEVEL_UNSPECIFIED (0):
+                Use default, which is NORMAL.
+            NORMAL (1):
+                Normal scanning (Recommended)
+            LOW (2):
+                Lower impact scanning
         """
         RISK_LEVEL_UNSPECIFIED = 0
         NORMAL = 1
@@ -96,6 +117,16 @@ class RiskLevel(proto.Enum):
     class ExportToSecurityCommandCenter(proto.Enum):
         r"""Controls export of scan configurations and results to
         Security Command Center.
+
+        Values:
+            EXPORT_TO_SECURITY_COMMAND_CENTER_UNSPECIFIED (0):
+                Use default, which is ENABLED.
+            ENABLED (1):
+                Export results of this scan to Security
+                Command Center.
+            DISABLED (2):
+                Do not export results of this scan to
+                Security Command Center.
         """
         EXPORT_TO_SECURITY_COMMAND_CENTER_UNSPECIFIED = 0
         ENABLED = 1

packages/google-cloud-websecurityscanner/google/cloud/websecurityscanner_v1/types/scan_config_error.py

@@ -46,6 +46,140 @@ class Code(proto.Enum):
         r"""Output only.
         Defines an error reason code.
         Next id: 44
+
+        Values:
+            CODE_UNSPECIFIED (0):
+                There is no error.
+            OK (0):
+                There is no error.
+            INTERNAL_ERROR (1):
+                Indicates an internal server error.
+                Please DO NOT USE THIS ERROR CODE unless the
+                root cause is truly unknown.
+            APPENGINE_API_BACKEND_ERROR (2):
+                One of the seed URLs is an App Engine URL but
+                we cannot validate the scan settings due to an
+                App Engine API backend error.
+            APPENGINE_API_NOT_ACCESSIBLE (3):
+                One of the seed URLs is an App Engine URL but
+                we cannot access the App Engine API to validate
+                scan settings.
+            APPENGINE_DEFAULT_HOST_MISSING (4):
+                One of the seed URLs is an App Engine URL but
+                the Default Host of the App Engine is not set.
+            CANNOT_USE_GOOGLE_COM_ACCOUNT (6):
+                Google corporate accounts can not be used for
+                scanning.
+            CANNOT_USE_OWNER_ACCOUNT (7):
+                The account of the scan creator can not be
+                used for scanning.
+            COMPUTE_API_BACKEND_ERROR (8):
+                This scan targets Compute Engine, but we
+                cannot validate scan settings due to a Compute
+                Engine API backend error.
+            COMPUTE_API_NOT_ACCESSIBLE (9):
+                This scan targets Compute Engine, but we
+                cannot access the Compute Engine API to validate
+                the scan settings.
+            CUSTOM_LOGIN_URL_DOES_NOT_BELONG_TO_CURRENT_PROJECT (10):
+                The Custom Login URL does not belong to the
+                current project.
+            CUSTOM_LOGIN_URL_MALFORMED (11):
+                The Custom Login URL is malformed (can not be
+                parsed).
+            CUSTOM_LOGIN_URL_MAPPED_TO_NON_ROUTABLE_ADDRESS (12):
+                The Custom Login URL is mapped to a
+                non-routable IP address in DNS.
+            CUSTOM_LOGIN_URL_MAPPED_TO_UNRESERVED_ADDRESS (13):
+                The Custom Login URL is mapped to an IP
+                address which is not reserved for the current
+                project.
+            CUSTOM_LOGIN_URL_HAS_NON_ROUTABLE_IP_ADDRESS (14):
+                The Custom Login URL has a non-routable IP
+                address.
+            CUSTOM_LOGIN_URL_HAS_UNRESERVED_IP_ADDRESS (15):
+                The Custom Login URL has an IP address which
+                is not reserved for the current project.
+            DUPLICATE_SCAN_NAME (16):
+                Another scan with the same name
+                (case-sensitive) already exists.
+            INVALID_FIELD_VALUE (18):
+                A field is set to an invalid value.
+            FAILED_TO_AUTHENTICATE_TO_TARGET (19):
+                There was an error trying to authenticate to
+                the scan target.
+            FINDING_TYPE_UNSPECIFIED (20):
+                Finding type value is not specified in the
+                list findings request.
+            FORBIDDEN_TO_SCAN_COMPUTE (21):
+                Scan targets Compute Engine, yet current
+                project was not whitelisted for Google Compute
+                Engine Scanning Alpha access.
+            FORBIDDEN_UPDATE_TO_MANAGED_SCAN (43):
+                User tries to update managed scan
+            MALFORMED_FILTER (22):
+                The supplied filter is malformed. For
+                example, it can not be parsed, does not have a
+                filter type in expression, or the same filter
+                type appears more than once.
+            MALFORMED_RESOURCE_NAME (23):
+                The supplied resource name is malformed (can
+                not be parsed).
+            PROJECT_INACTIVE (24):
+                The current project is not in an active
+                state.
+            REQUIRED_FIELD (25):
+                A required field is not set.
+            RESOURCE_NAME_INCONSISTENT (26):
+                Project id, scanconfig id, scanrun id, or
+                finding id are not consistent with each other in
+                resource name.
+            SCAN_ALREADY_RUNNING (27):
+                The scan being requested to start is already
+                running.
+            SCAN_NOT_RUNNING (28):
+                The scan that was requested to be stopped is
+                not running.
+            SEED_URL_DOES_NOT_BELONG_TO_CURRENT_PROJECT (29):
+                One of the seed URLs does not belong to the
+                current project.
+            SEED_URL_MALFORMED (30):
+                One of the seed URLs is malformed (can not be
+                parsed).
+            SEED_URL_MAPPED_TO_NON_ROUTABLE_ADDRESS (31):
+                One of the seed URLs is mapped to a
+                non-routable IP address in DNS.
+            SEED_URL_MAPPED_TO_UNRESERVED_ADDRESS (32):
+                One of the seed URLs is mapped to an IP
+                address which is not reserved for the current
+                project.
+            SEED_URL_HAS_NON_ROUTABLE_IP_ADDRESS (33):
+                One of the seed URLs has on-routable IP
+                address.
+            SEED_URL_HAS_UNRESERVED_IP_ADDRESS (35):
+                One of the seed URLs has an IP address that
+                is not reserved for the current project.
+            SERVICE_ACCOUNT_NOT_CONFIGURED (36):
+                The Web Security Scanner service account is
+                not configured under the project.
+            TOO_MANY_SCANS (37):
+                A project has reached the maximum number of
+                scans.
+            UNABLE_TO_RESOLVE_PROJECT_INFO (38):
+                Resolving the details of the current project
+                fails.
+            UNSUPPORTED_BLACKLIST_PATTERN_FORMAT (39):
+                One or more blacklist patterns were in the
+                wrong format.
+            UNSUPPORTED_FILTER (40):
+                The supplied filter is not supported.
+            UNSUPPORTED_FINDING_TYPE (41):
+                The supplied finding type is not supported.
+                For example, we do not provide findings of the
+                given finding type.
+            UNSUPPORTED_URL_SCHEME (42):
+                The URL scheme of one or more of the supplied
+                URLs is not supported.
         """
         _pb_options = {"allow_alias": True}
         CODE_UNSPECIFIED = 0

packages/google-cloud-websecurityscanner/google/cloud/websecurityscanner_v1/types/scan_run.py

@@ -87,14 +87,40 @@ class ScanRun(proto.Message):
     """
 
     class ExecutionState(proto.Enum):
-        r"""Types of ScanRun execution state."""
+        r"""Types of ScanRun execution state.
+
+        Values:
+            EXECUTION_STATE_UNSPECIFIED (0):
+                Represents an invalid state caused by
+                internal server error. This value should never
+                be returned.
+            QUEUED (1):
+                The scan is waiting in the queue.
+            SCANNING (2):
+                The scan is in progress.
+            FINISHED (3):
+                The scan is either finished or stopped by
+                user.
+        """
         EXECUTION_STATE_UNSPECIFIED = 0
         QUEUED = 1
         SCANNING = 2
         FINISHED = 3
 
     class ResultState(proto.Enum):
-        r"""Types of ScanRun result state."""
+        r"""Types of ScanRun result state.
+
+        Values:
+            RESULT_STATE_UNSPECIFIED (0):
+                Default value. This value is returned when
+                the ScanRun is not yet finished.
+            SUCCESS (1):
+                The scan finished without errors.
+            ERROR (2):
+                The scan finished with errors.
+            KILLED (3):
+                The scan was terminated by user.
+        """
         RESULT_STATE_UNSPECIFIED = 0
         SUCCESS = 1
         ERROR = 2

packages/google-cloud-websecurityscanner/google/cloud/websecurityscanner_v1/types/scan_run_error_trace.py

@@ -52,6 +52,33 @@ class Code(proto.Enum):
         r"""Output only.
         Defines an error reason code.
         Next id: 8
+
+        Values:
+            CODE_UNSPECIFIED (0):
+                Default value is never used.
+            INTERNAL_ERROR (1):
+                Indicates that the scan run failed due to an
+                internal server error.
+            SCAN_CONFIG_ISSUE (2):
+                Indicates a scan configuration error, usually due to
+                outdated ScanConfig settings, such as starting_urls or the
+                DNS configuration.
+            AUTHENTICATION_CONFIG_ISSUE (3):
+                Indicates an authentication error, usually
+                due to outdated ScanConfig authentication
+                settings.
+            TIMED_OUT_WHILE_SCANNING (4):
+                Indicates a scan operation timeout, usually
+                caused by a very large site.
+            TOO_MANY_REDIRECTS (5):
+                Indicates that a scan encountered excessive
+                redirects, either to authentication or some
+                other page outside of the scan scope.
+            TOO_MANY_HTTP_ERRORS (6):
+                Indicates that a scan encountered numerous errors from the
+                web site pages. When available, most_common_http_error_code
+                field indicates the most common HTTP error code encountered
+                during the scan.
         """
         CODE_UNSPECIFIED = 0
         INTERNAL_ERROR = 1