From b136f91afe1645d401452d1eeac2f5f90c8db2e9 Mon Sep 17 00:00:00 2001
From: Hannah Baker <hbaker@gitlab.com>
Date: Tue, 11 Mar 2025 17:27:55 +0000
Subject: [PATCH] Improve DAST timeout documentation
---
.../configuration/customize_settings.md | 75 +++++++++++++++++++
1 file changed, 75 insertions(+)
diff --git a/doc/user/application_security/dast/browser/configuration/customize_settings.md b/doc/user/application_security/dast/browser/configuration/customize_settings.md
index 2dcb71a9311e9..21fc39eaa2b09 100644
--- a/doc/user/application_security/dast/browser/configuration/customize_settings.md
+++ b/doc/user/application_security/dast/browser/configuration/customize_settings.md
@@ -145,3 +145,78 @@ dast:
Adjusting these values may impact scan time because they adjust how long each browser waits for various activities to complete.
{{< /alert >}}
+
+### Page readiness timeouts
+
+Page readiness refers to the state when a page has loaded completely, its DOM has stabilized, and interactive elements are available. Proper page readiness detection is crucial for:
+
+- **Scanning accuracy**: Analyzing pages before they're fully loaded can miss content or produce false negatives.
+- **Crawl efficiency**: Waiting too long wastes scanning time, while not waiting enough misses dynamic content.
+- **Modern web application support**: Single-page applications, AJAX-heavy sites, and progressive loading patterns require sophisticated readiness detection.
+
+Using a sequence of optional configurable timeouts, the DAST scanner can detect when different parts of a page have loaded completely.
+
+#### Timeout variables
+
+Use the following CI/CD variables to customize DAST page readiness timeouts.
+For a comprehensive list, see [Available CI/CD variables](variables.md).
+
+| Timeout Variable | Default | Description |
+|:-----------------|:--------|:------------|
+| `DAST_PAGE_READY_AFTER_NAVIGATION_TIMEOUT` | `15s` | The maximum amount of time to wait for a browser to navigate from one page to another. Used during the Document Load phase for full page loads. |
+| `DAST_PAGE_READY_AFTER_ACTION_TIMEOUT` | `7s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis. Used as an alternative to `DAST_PAGE_READY_AFTER_NAVIGATION_TIMEOUT` for in-page actions that don't trigger a full page load. |
+| `DAST_PAGE_DOM_STABLE_WAIT` | `500ms` | Define how long to wait for updates to the DOM before checking a page is stable. Used at the beginning of the client-side render phase. |
+| `DAST_PAGE_DOM_READY_TIMEOUT` | `6s` | The maximum amount of time to wait for a browser to consider a page loaded and ready for analysis after a navigation completes. Controls waiting for background data fetching and DOM rendering. |
+| `DAST_PAGE_IS_LOADING_ELEMENT` | None | Selector that when no longer visible on the page, indicates to the analyzer that the page has finished loading and the scan can continue. Marks the end of the client-side render process. |
+
+#### Page loading workflow
+
+Modern web applications load in multiple stages. The DAST scanner has specific timeouts for
+each step in the process:
+
+1. **Document loading**: The browser fetches and processes the basic page structure.
+
+ 1. Fetch HTML content from the server.
+ 1. Load referenced CSS and JavaScript files.
+ 1. Parse content and renders the initial page.
+ 1. Trigger the standard "document ready" event.
+
+ This phase uses either `DAST_PAGE_READY_AFTER_NAVIGATION_TIMEOUT` (for full page loads) or `DAST_PAGE_READY_AFTER_ACTION_TIMEOUT` (for in-page actions), which sets the maximum wait time for document loading.
+
+1. **Client-Side rendering**: After initial loading, many single-page applications:
+
+ - Perform initial JavaScript execution (`DAST_PAGE_DOM_STABLE_WAIT`).
+ - Fetch background data with AJAX or other API calls.
+ - Render a DOM and performs updates based on fetched data (`DAST_PAGE_DOM_READY_TIMEOUT`).
+ - Display page loading indicators (`DAST_PAGE_IS_LOADING_ELEMENT`).
+
+ The scanner monitors these activities to determine when the page is ready for interaction.
+
+The following chart illustrates the sequence timeouts used when crawling a page:
+
+```mermaid
+%%{init: {
+ "gantt": {
+ "leftPadding": 250,
+ "sectionFontSize": 15,
+ "topPadding": 40,
+ "fontFamily": "GitLab Sans"
+ }
+}}%%
+gantt
+ dateFormat YYYY-MM-DD
+ axisFormat
+ section Document load
+ DAST_PAGE_READY_AFTER_NAVIGATION_TIMEOUT :done, nav1, 2024-01-01, 6d
+ Fetch HTML :active, nav1, 2024-01-01, 3d
+ Fetch CSS&JS :active, nav1, 2024-01-04, 3d
+ DocumentReady :milestone, nav1, 2024-01-07, 0d
+
+ section Load Data / Client-side render
+ DAST_PAGE_DOM_STABLE_WAIT :done, dom1, 2024-01-07, 3d
+ Initial JS Execution :active, dom1, 2024-01-07, 3d
+ DAST_PAGE_DOM_READY_TIMEOUT :done, ready1, 2024-01-10, 4d
+ Fetch Data :active, dom1, 2024-01-10, 2d
+ Render DOM :active, dom1, 2024-01-10, 2d
+ DAST_PAGE_IS_LOADING_ELEMENT :milestone, load1, 2024-01-14, 0d
+```
--
GitLab