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: https://github.com/googleapis/googleapis-gen/commit/0080f830dec37c3384157082bce279e37079ea58 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>

Author: gcf-owl-bot[bot]

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):

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

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
 

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

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

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

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