REST Resource: projects.scanConfigs.scanRuns

Resource: ScanRun

A ScanRun is a output-only resource representing an actual run of the scan. Next id: 12

JSON representation 
{
  "name": string,
  "executionState": enum (ExecutionState),
  "resultState": enum (ResultState),
  "startTime": string,
  "endTime": string,
  "urlsCrawledCount": string,
  "urlsTestedCount": string,
  "hasVulnerabilities": boolean,
  "progressPercent": integer,
  "errorTrace": {
    object (ScanRunErrorTrace)
  },
  "warningTraces": [
    {
      object (ScanRunWarningTrace)
    }
  ]
}
Fields
name

string

The resource name of the ScanRun. The name follows the format of 'projects/{projectId}/scanConfigs/{scanConfigId}/scanRuns/{scanRunId}'. The ScanRun IDs are generated by the system.
executionState

enum (ExecutionState)

The execution state of the ScanRun.
resultState

enum (ResultState)

The result state of the ScanRun. This field is only available after the execution state reaches "FINISHED".
startTime

string (Timestamp format)

The time at which the ScanRun started.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
endTime

string (Timestamp format)

The time at which the ScanRun reached termination state - that the ScanRun is either finished or stopped by user.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
urlsCrawledCount

string (int64 format)

The number of URLs crawled during this ScanRun. If the scan is in progress, the value represents the number of URLs crawled up to now.
urlsTestedCount

string (int64 format)

The number of URLs tested during this ScanRun. If the scan is in progress, the value represents the number of URLs tested up to now. The number of URLs tested is usually larger than the number URLS crawled because typically a crawled URL is tested with multiple test payloads.
hasVulnerabilities

boolean

Whether the scan run has found any vulnerabilities.
progressPercent

integer

The percentage of total completion ranging from 0 to 100. If the scan is in queue, the value is 0. If the scan is running, the value ranges from 0 to 100. If the scan is finished, the value is 100.
errorTrace

object (ScanRunErrorTrace)

If resultState is an ERROR, this field provides the primary reason for scan's termination and more details, if such are available.
warningTraces[]

object (ScanRunWarningTrace)

A list of warnings, if such are encountered during this scan run.

ExecutionState

Types of ScanRun execution state.

Enums
EXECUTION_STATE_UNSPECIFIED Represents an invalid state caused by internal server error. This value should never be returned.
QUEUED The scan is waiting in the queue.
SCANNING The scan is in progress.
FINISHED The scan is either finished or stopped by user.

ResultState

Types of ScanRun result state.

Enums
RESULT_STATE_UNSPECIFIED Default value. This value is returned when the ScanRun is not yet finished.
SUCCESS The scan finished without errors.
ERROR The scan finished with errors.
KILLED The scan was terminated by user.

ScanRunErrorTrace

Output only. Defines an error trace message for a ScanRun.

JSON representation 
{
  "code": enum (Code),
  "scanConfigError": {
    object (ScanConfigError)
  },
  "mostCommonHttpErrorCode": integer
}
Fields
code

enum (Code)

Indicates the error reason code.
scanConfigError

object (ScanConfigError)

If the scan encounters SCAN_CONFIG_ISSUE error, this field has the error message encountered during scan configuration validation that is performed before each scan run.
mostCommonHttpErrorCode

integer

If the scan encounters TOO_MANY_HTTP_ERRORS, this field indicates the most common HTTP error code, if such is available. For example, if this code is 404, the scan has encountered too many NOT_FOUND responses.

Code

Output only. Defines an error reason code. Next id: 8

Enums
CODE_UNSPECIFIED Default value is never used.
INTERNAL_ERROR Indicates that the scan run failed due to an internal server error.
SCAN_CONFIG_ISSUE Indicates a scan configuration error, usually due to outdated ScanConfig settings, such as startingUrls or the DNS configuration.
AUTHENTICATION_CONFIG_ISSUE Indicates an authentication error, usually due to outdated ScanConfig authentication settings.
TIMED_OUT_WHILE_SCANNING Indicates a scan operation timeout, usually caused by a very large site.
TOO_MANY_REDIRECTS Indicates that a scan encountered excessive redirects, either to authentication or some other page outside of the scan scope.
TOO_MANY_HTTP_ERRORS Indicates that a scan encountered numerous errors from the web site pages. When available, mostCommonHttpErrorCode field indicates the most common HTTP error code encountered during the scan.
STARTING_URLS_CRAWL_HTTP_ERRORS Indicates that some of the starting web urls returned HTTP errors during the scan.

ScanConfigError

Defines a custom error message used by CreateScanConfig and UpdateScanConfig APIs when scan configuration validation fails. It is also reported as part of a ScanRunErrorTrace message if scan validation fails due to a scan configuration error.

JSON representation 
{
  "code": enum (Code),
  "fieldName": string
}
Fields
code

enum (Code)

Indicates the reason code for a configuration failure.
fieldName

string

Indicates the full name of the ScanConfig field that triggers this error, for example "scanConfig.max_qps". This field is provided for troubleshooting purposes only and its actual value can change in the future.

Code

Output only. Defines an error reason code. Next id: 45

Enums
CODE_UNSPECIFIED There is no error.
OK There is no error.
INTERNAL_ERROR Indicates an internal server error. Please DO NOT USE THIS ERROR CODE unless the root cause is truly unknown.
APPENGINE_API_BACKEND_ERROR 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 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 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 Google corporate accounts can not be used for scanning.
CANNOT_USE_OWNER_ACCOUNT The account of the scan creator can not be used for scanning.
COMPUTE_API_BACKEND_ERROR This scan targets Compute Engine, but we cannot validate scan settings due to a Compute Engine API backend error.
COMPUTE_API_NOT_ACCESSIBLE 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 The Custom Login URL does not belong to the current project.
CUSTOM_LOGIN_URL_MALFORMED The Custom Login URL is malformed (can not be parsed).
CUSTOM_LOGIN_URL_MAPPED_TO_NON_ROUTABLE_ADDRESS The Custom Login URL is mapped to a non-routable IP address in DNS.
CUSTOM_LOGIN_URL_MAPPED_TO_UNRESERVED_ADDRESS 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 The Custom Login URL has a non-routable IP address.
CUSTOM_LOGIN_URL_HAS_UNRESERVED_IP_ADDRESS The Custom Login URL has an IP address which is not reserved for the current project.
DUPLICATE_SCAN_NAME Another scan with the same name (case-sensitive) already exists.
INVALID_FIELD_VALUE A field is set to an invalid value.
FAILED_TO_AUTHENTICATE_TO_TARGET There was an error trying to authenticate to the scan target.
FINDING_TYPE_UNSPECIFIED Finding type value is not specified in the list findings request.
FORBIDDEN_TO_SCAN_COMPUTE Scan targets Compute Engine, yet current project was not whitelisted for Google Compute Engine Scanning Alpha access.
FORBIDDEN_UPDATE_TO_MANAGED_SCAN User tries to update managed scan
MALFORMED_FILTER 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 The supplied resource name is malformed (can not be parsed).
PROJECT_INACTIVE The current project is not in an active state.
REQUIRED_FIELD A required field is not set.
RESOURCE_NAME_INCONSISTENT Project id, scanconfig id, scanrun id, or finding id are not consistent with each other in resource name.
SCAN_ALREADY_RUNNING The scan being requested to start is already running.
SCAN_NOT_RUNNING The scan that was requested to be stopped is not running.
SEED_URL_DOES_NOT_BELONG_TO_CURRENT_PROJECT One of the seed URLs does not belong to the current project.
SEED_URL_MALFORMED One of the seed URLs is malformed (can not be parsed).
SEED_URL_MAPPED_TO_NON_ROUTABLE_ADDRESS One of the seed URLs is mapped to a non-routable IP address in DNS.
SEED_URL_MAPPED_TO_UNRESERVED_ADDRESS 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 One of the seed URLs has on-routable IP address.
SEED_URL_HAS_UNRESERVED_IP_ADDRESS One of the seed URLs has an IP address that is not reserved for the current project.
SERVICE_ACCOUNT_NOT_CONFIGURED The Web Security Scanner service account is not configured under the project.
TOO_MANY_SCANS A project has reached the maximum number of scans.
UNABLE_TO_RESOLVE_PROJECT_INFO Resolving the details of the current project fails.
UNSUPPORTED_BLACKLIST_PATTERN_FORMAT One or more blacklist patterns were in the wrong format.
UNSUPPORTED_FILTER The supplied filter is not supported.
UNSUPPORTED_FINDING_TYPE The supplied finding type is not supported. For example, we do not provide findings of the given finding type.
UNSUPPORTED_URL_SCHEME The URL scheme of one or more of the supplied URLs is not supported.
CLOUD_ASSET_INVENTORY_ASSET_NOT_FOUND CAI is not able to list assets.

ScanRunWarningTrace

Output only. Defines a warning trace message for ScanRun. Warning traces provide customers with useful information that helps make the scanning process more effective.

JSON representation 
{
  "code": enum (Code)
}
Fields
code

enum (Code)

Indicates the warning code.

Code

Output only. Defines a warning message code. Next id: 6

Enums
CODE_UNSPECIFIED Default value is never used.
INSUFFICIENT_CRAWL_RESULTS Indicates that a scan discovered an unexpectedly low number of URLs. This is sometimes caused by complex navigation features or by using a single URL for numerous pages.
TOO_MANY_CRAWL_RESULTS Indicates that a scan discovered too many URLs to test, or excessive redundant URLs.
TOO_MANY_FUZZ_TASKS Indicates that too many tests have been generated for the scan. Customer should try reducing the number of starting URLs, increasing the QPS rate, or narrowing down the scope of the scan using the excluded patterns.
BLOCKED_BY_IAP Indicates that a scan is blocked by IAP.
NO_STARTING_URL_FOUND_FOR_MANAGED_SCAN Indicates that no seed is found for a scan

Methods

get

 Gets a ScanRun.

list

 Lists ScanRuns under a given ScanConfig, in descending order of ScanRun stop time.

stop

 Stops a ScanRun.