canonical: https://jentic.com/apis/googleapis.com/websecurityscanner # Google Web Security Scanner API The Google Web Security Scanner API automates dynamic application security testing for web apps running on App Engine, Compute Engine, and Google Kubernetes Engine. It crawls a target site, executes attack vectors against discovered URLs, and reports vulnerability findings such as cross-site scripting, mixed content, outdated libraries, and insecure cookies. Scans are configured as scanConfigs, executed as scanRuns, and produce findings and crawled-URL artefacts that can be retrieved for triage in CI or security dashboards. ## For AI agents Configure and run dynamic security scans against Google Cloud-hosted web apps and pull XSS, mixed-content, and outdated-library findings. Read and write access to scan configurations and runs. ## Scope Does not handle static code analysis, secrets scanning, third-party URL safety lookups, or scanning of non-Google-Cloud workloads - use for dynamic vulnerability scanning of App Engine, Compute Engine, and GKE web apps only. ## Capabilities - Create and update scan configurations targeting App Engine, Compute Engine, or GKE-hosted URLs - Start, stop, and list scan runs to perform on-demand or scheduled vulnerability scans - Retrieve findings filtered by type such as XSS, MIXED_CONTENT, or OUTDATED_LIBRARY - Inspect crawled URLs for a scan run to validate coverage of the target application - Aggregate finding-type statistics per scan run for dashboards and triage views ## Use cases ### Continuous DAST in CI Trigger a Web Security Scanner run after every staging deploy of an App Engine or GKE app to catch newly introduced cross-site scripting, mixed content, and outdated library issues before production. The scan run is started through POST /v1/{+name}:start, and findings are pulled when the run finishes for upload to the team's defect tracker. This integrates cleanly with Cloud Build or any CI system that can hold an OAuth token for the project. Example prompt: Start a scan run for the scan config named projects/{project}/scanConfigs/{id} via POST /v1/{+name}:start, poll until the run completes, then list findings of type XSS_CALLBACK and XSS_ERROR. ### Security posture dashboard Aggregate findingTypeStats across all scan runs in a project to display a top-line view of the most common vulnerability classes affecting an organisation's Google Cloud web apps. The endpoint returns counts grouped by finding type so dashboards do not have to fetch every finding individually. Combined with the Cloud Asset inventory, this gives security teams a coverage-versus-risk picture in one place. Example prompt: Call GET /v1/{+parent}/findingTypeStats for a project and emit a CSV with finding type and count for each entry returned. ### Coverage validation for crawls After a scan, pull the list of crawled URLs to confirm that the scanner reached the intended application surface. This catches misconfigurations such as authentication walls or robots.txt rules that silently exclude pages from coverage. The crawledUrls endpoint returns the full list paginated; teams export this and diff against their URL inventory. Example prompt: List crawledUrls for the most recent scanRun under a given scanConfig and flag any URL in the inventory that is missing from the crawled set. ### Agent-driven scan triage through Jentic A security agent connected through Jentic can pull findings, group them by severity, and propose remediation tickets without engineers writing direct API client code. The agent searches Jentic for list web security findings, loads the findings list operation, and executes it scoped to a scan run. Because the OAuth credential is held in Jentic, the agent never sees the raw token. Example prompt: Through Jentic, list findings under scanRuns/{id} where findingType is OUTDATED_LIBRARY and produce a prioritised remediation list grouped by affected URL. ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /v1/{+parent}/scanConfigs | List scan configurations | | POST | /v1/{+name}:start | Start a scan run | | POST | /v1/{+name}:stop | Stop a running scan | | GET | /v1/{+parent}/findings | List findings under a scan run | | GET | /v1/{+parent}/findingTypeStats | Get aggregated finding-type counts | | GET | /v1/{+parent}/crawledUrls | List URLs crawled by a scan run | ## Key resources - **scanConfigs** — Configuration objects defining what to scan and how - **scanRuns** — Individual executions of a scan config - **findings** — Vulnerability findings produced by a scan run - **crawledUrls** — URLs the scanner reached during a run - **findingTypeStats** — Aggregated counts of findings grouped by type ## Why Jentic - **Setup:** Wiring the Web Security Scanner API by hand means setting up OAuth 2.0 for the hosting Google Cloud project, refreshing access tokens, and matching scan and findings calls against the websecurityscanner.googleapis.com host. Through Jentic you install once, import the Web Security Scanner API from the API Directory, store the OAuth credential once, and your agent calls it. - **Permission scoping:** The Web Security Scanner API puts the scan config in the URL path (/v1/{name}:start), so a rule can pin your agent to one scan config: it can start that scan and read its findings and nothing else. You choose the operations it may call, so stopping scans or deleting configs is not included unless you add it. - **Credential handling:** Your Web Security Scanner OAuth credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. Its client secret and refresh token never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'start a vulnerability scan' or 'list XSS findings', and Jentic returns the scan start or findings list operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Web Risk API** — Checks third-party URLs for phishing and malware rather than scanning your own apps - **Cloud Asset Inventory API** — Catalogues all GCP resources so security tooling knows what exists to scan - **Cloud Monitoring API** — Alert on scan run failures and finding-count regressions ## FAQ ### What authentication does the Web Security Scanner API use? It uses OAuth 2.0 (Oauth2 and Oauth2c schemes in the spec) scoped to https://www.googleapis.com/auth/cloud-platform. Through Jentic the OAuth client credentials are encrypted at rest and short-lived access tokens are minted at execution; the agent never sees the underlying refresh token. ### Can I scan apps that are not hosted on Google Cloud? No. Web Security Scanner is designed for App Engine, Compute Engine, and Google Kubernetes Engine workloads accessible from Google's network. To scan apps hosted elsewhere, use a third-party DAST product. The scanConfigs resource validates the target URL belongs to a supported Google Cloud service. ### What are the rate limits for the Web Security Scanner API? Quotas are managed per Google Cloud project in the Cloud Console under APIs and Services. Scan runs themselves are throttled to avoid impacting the target application; the per-project default is documented in the Web Security Scanner pricing page. Most teams hit quotas on findings list calls during dashboard refreshes rather than on scan starts. ### How do I start a scan run through Jentic? Search Jentic for start a web security scan, load the schema for POST /v1/{+name}:start, and execute it with the scan config name in the form projects/{project}/scanConfigs/{id}. The response is a ScanRun object whose state field reports progress until it reaches FINISHED. ### What finding types does the scanner detect? The findings endpoint returns vulnerabilities including cross-site scripting (XSS_CALLBACK, XSS_ERROR), mixed content, insecure cookies, outdated libraries, and clear-text password transmission. Each finding includes the affected URL, request body, and reproduction steps. Filter by findingType when listing under /v1/{+parent}/findings. ### Can I limit what my agent is allowed to do with the Web Security Scanner API? Yes. Jentic One is self-hosted by you, so your own rules decide which Web Security Scanner operations and credentials the agent may use. Because the scan config sits in the URL path, such as /v1/{name}:start, you can pin the agent to a single scan config so it can start that scan and read its findings and finding-type stats and nothing else. You pick the operations it may call, so stopping scan runs or deleting scan configs is excluded unless you explicitly add it.