# WebApp Testing Session Management

Session management maintains authenticated state throughout security scans. While [authentication configuration](<https://docs.escape.tech/documentation/platform/authentication/index.md>) handles initial credential acquisition, session management prevents unintentional logout during scanning activities such as parallel browsing, page reloads, and security injection testing.

## Complete Configuration Example

The following configuration provides comprehensive session management for applications requiring maximum stability:

```yaml
frontend_dast:
  # Resource constraints
  parallel_workers: 1

  # Prevent logout through element interaction
  scope:
    crawling:
      blocklist:
        # Standard logout elements
        - type: web_page_element_selector
          value: "button:has-text('Sign Out')"
        - type: web_page_element_selector
          value: "button:has-text('Logout')"
        - type: web_page_element_selector
          value: "[data-testid='logout-button']"
        - type: web_page_element_selector
          value: "[data-action='logout']"
        - type: web_page_element_selector
          value: "a[href*='/logout']"

        # Destructive actions
        - type: web_page_element_selector
          value: "button:has-text('Delete Account')"
        - type: web_page_element_selector
          value: "[data-action='delete-account']"
        - type: web_page_element_selector
          value: "button:has-text('Change Password')"

    # Prevent API checks on sensitive authentication endpoints
    api_testing:
      blocklist:
        - type: rest_api_path
          value: ".*/api/auth/.*"
          operation: regex
        - type: rest_api_path
          value: "/api/token/refresh"
          method: POST
        - type: rest_api_path
          value: ".*/api/session/.*"
          operation: regex
```

## Session Management Modes

### Standard Mode (Default)

Parallel workers use separate pages (tabs) in a shared browser context. Cookies and same-origin local storage are shared; sessionStorage and in-memory JavaScript state remain page-local.

```yaml
frontend_dast:
  parallel_workers: 3  # 3 pages in a shared browser context
```

This mode is optimal for stateless applications with long-lived JWT tokens.

### Single Page Worker Mode

A single page worker keeps exploration in one page, reducing resets of page-local state. `single_page_worker: true` automatically uses one worker.

```yaml
frontend_dast:
  single_page_worker: true
```

**Use Cases**:

- Applications losing state on page reload
- Critical WebSocket connections requiring persistence
- Single-use CSRF tokens without refresh mechanisms

## Logout Detection and Automatic Reauthentication

`frontend_dast.logout_detection` is enabled by default. `auto_reauthenticate` and `agentic_detection_enabled` also default to `true`. Detection uses page content, redirections and session-cookie patterns.

```yaml
frontend_dast:
  logout_detection:
    enabled: true
    auto_reauthenticate: true
    logged_in_indicator_regex_patterns:
      - 'Sign out'
      - 'Dashboard'
    check_url: https://app.example.com/account
    ignore_url_patterns:
      - '/marketing'
```

Use `logged_in_indicator_regex_patterns` for content that indicates a logged-in session. `check_url` checks a stable account page in a new tab in the shared context instead of the worker's current page. `ignore_url_patterns` skips detection on matching worker URLs. Both pattern lists are empty by default, and `check_url` is unset.

The default `logout_redirection_url_patterns` are `/login`, `/signout`, `/logout`, `/sign-out` and `/sign-in`. Customize `session_cookie_regex_patterns` if your session cookies don't match the built-in patterns. See the [configuration reference](<https://docs.escape.tech/documentation/reference/configuration-schemas/webapp-dast/index.md>) for all fields.

## Preventing Session Termination

### Frontend Element Blocking

The scanner includes built-in protection against common logout elements. Application-specific logout patterns can be added using explicit configuration with [Playwright locator syntax](<https://playwright.dev/docs/locators>), as shown in the following example:

```yaml
frontend_dast:
  scope:
    crawling:
      blocklist:
        # Text-based logout buttons
        - type: web_page_element_selector
          value: "button:has-text('Sign Out')"
        - type: web_page_element_selector
          value: "button:has-text('Logout')"
        - type: web_page_element_selector
          value: "a:has-text('Log out')"

        # Data attribute selectors
        - type: web_page_element_selector
          value: "[data-testid='logout-button']"
        - type: web_page_element_selector
          value: "[data-action='logout']"

        # URL-based navigation
        - type: web_page_element_selector
          value: "a[href*='/logout']"
        - type: web_page_element_selector
          value: "a[href*='/sign-out']"

        # Destructive account management
        - type: web_page_element_selector
          value: "button:has-text('Delete Account')"
        - type: web_page_element_selector
          value: "[data-action='delete-account']"
        - type: web_page_element_selector
          value: "button:has-text('Change Password')"

        # Session termination
        - type: web_page_element_selector
          value: "button:has-text('End Session')"
        - type: web_page_element_selector
          value: "[data-action='clear-session']"
```

**Advanced Selectors**:

For applications with dynamic or context-sensitive logout elements:

```yaml
frontend_dast:
  scope:
    crawling:
      blocklist:
        # Proximity-based blocking
        - type: web_page_element_selector
          value: "button:near(:text('Are you sure you want to log out?'))"

        # Modal confirmation buttons
        - type: web_page_element_selector
          value: ".modal button:has-text('Confirm')"
        - type: web_page_element_selector
          value: "[role='dialog'] [data-action='confirm']"

        # Compound selectors
        - type: web_page_element_selector
          value: "[class*='danger']:has-text('Delete')"

        # ARIA label matching
        - type: web_page_element_selector
          value: "[aria-label*='sign out' i]"
        - type: web_page_element_selector
          value: "[aria-label*='log out' i]"
```

> [!WARNING]
>
> **Selector Validation**
>
> Element selectors should be validated in development environments before production deployment. Overly broad selectors may prevent legitimate functionality testing, while insufficiently specific selectors may fail to prevent logout interactions.

### API Traffic Injection Prevention

During frontend scans, captured API traffic undergoes security testing. This can inadvertently trigger session invalidation when authentication endpoints receive malformed payloads.

**Vulnerable Scenarios**:

- Token refresh endpoints receiving injection payloads
- Session management APIs being parameter-fuzzed
- User profile endpoints receiving unauthorized payloads
- MFA verification receiving invalid codes

#### Option 1: Disable API Security Testing

```yaml
frontend_dast:
  security_checks_enabled:
    - ACTIVE_PAGE_CHECKS
    - PASSIVE_PAGE_CHECKS
    - NETWORK_CHECKS
    # API_CHECKS excluded
```

#### Option 2: Selective Endpoint Exclusion

```yaml
frontend_dast:
  scope:
    api_testing:
      blocklist:
        - type: rest_api_path
          value: ".*/api/auth/.*"
          operation: regex
          method: POST
        - type: rest_api_path
          value: "/api/token/refresh"
          method: POST
        - type: rest_api_path
          value: ".*/api/session/.*"
          operation: regex
        - type: rest_api_path
          value: ".*/api/mfa/.*"
          operation: regex
```

Use `operation: regex` when the path value is a regular expression. Omit `method` to exclude all methods for that path.

#### Option 3: Exclude Authentication Endpoints

```yaml
frontend_dast:
  scope:
    api_testing:
      blocklist:
        - type: rest_api_path
          value: ".*/api/auth/.*"
          operation: regex
        - type: rest_api_path
          value: "/api/token/refresh"
          method: POST
```

Control authentication traffic at the endpoint level using the API testing blocklist. There's no phase-level toggle. Block API checks on login or token refresh endpoints that must remain stable to avoid invalidating sessions.

## Troubleshooting Session Loss

When scans exhibit authentication loss symptoms (reduced coverage, authorization errors, redirect to login pages), the following diagnostic sequence should be applied:

1. **Verify Initial Authentication**

   Confirm successful authentication establishment:

   ```yaml
   authentication:
     validation: true
   ```
2. **Review Logout Detection**

   Configure a reliable login indicator or `check_url` using [Logout Detection and Automatic Reauthentication](<#logout-detection-and-automatic-reauthentication>).
3. **Reduce Parallelism**

   ```yaml
   frontend_dast:
     parallel_workers: 1
   ```
4. **Block Logout Elements**

   Add application-specific logout selectors as documented above.
5. **Exclude Authentication Endpoints**

   Prevent API injection on authentication endpoints as documented above.
6. **Enable Single Page Worker**

   ```yaml
   frontend_dast:
     single_page_worker: true
     parallel_workers: 1
   ```

### Common Session Loss Patterns

**Immediate Session Loss**: Authentication validates successfully, but first crawled page shows unauthenticated state.

- **Causes**: Cookie domain mismatch, localStorage not injected, expired CSRF tokens
- **Resolution**: Verify cookie configuration in authentication preset

**Gradual Degradation**: Initial pages scan successfully, but coverage decreases over time with increasing authentication errors.

- **Causes**: Session timeout, token refresh not triggered, rate limiting
- **Resolution**: Configure token refresh in [authentication preset](<https://docs.escape.tech/documentation/platform/authentication/index.md>), reduce `parallel_workers`

**Intermittent Failures**: Random pages fail authentication while most succeed.

- **Causes**: Race conditions, session concurrency limitations, sporadic logout element interaction
- **Resolution**: Add comprehensive logout element blocking, reduce to 1 worker

## Configuration Templates

**Maximum Stability**:

```yaml
frontend_dast:
  parallel_workers: 1
  scope:
    crawling:
      blocklist:
        - type: web_page_element_selector
          value: "button:has-text('Sign Out')"
        - type: web_page_element_selector
          value: "[data-action='logout']"
        - type: web_page_element_selector
          value: "a[href*='/logout']"
    api_testing:
      blocklist:
        - type: rest_api_path
          value: ".*/api/auth/.*"
          operation: regex
```

**Balanced Reliability and Performance**:

```yaml
frontend_dast:
  parallel_workers: 2
  scope:
    crawling:
      blocklist:
        - type: web_page_element_selector
          value: "button:has-text('Sign Out')"
    api_testing:
      blocklist:
        - type: rest_api_path
          value: "/api/auth/login"
          method: POST
        - type: rest_api_path
          value: "/api/token/refresh"
          method: POST
```

**Performance-Optimized** (for robust stateless authentication):

```yaml
frontend_dast:
  parallel_workers: 3
  scope:
    crawling:
      blocklist:
        - type: web_page_element_selector
          value: "button:has-text('Logout')"
```

## Advanced Scenarios

### Large-Scale Application Configuration

Large e-commerce sites with thousands of product pages require efficient crawling strategies:

```yaml
frontend_dast:
  parallel_workers: 3
  security_checks_enabled:
    - PASSIVE_PAGE_CHECKS
    - API_CHECKS
  scope:
    crawling:
      blocklist:
        - type: web_page_url
          value: ".*/product/[0-9]+/reviews.*"
          operation: regex
        - type: web_page_url
          value: ".*/category/.*/page/[0-9]+.*"
          operation: regex
  crawling_tuning:
    max_parameterized_url_variations: 5
```

This configuration balances comprehensive coverage with practical scan duration by avoiding repetitive content patterns.

### Session-Based Vs Token-Based Authentication

**Session-Based (Stateful)**: Applications using server-side session storage require logging in and testing within the same browser session to prevent session conflicts.

**Token-Based (Stateless)**: JWT or similar stateless tokens still need valid credentials throughout the scan. Use [logout detection](<#logout-detection-and-automatic-reauthentication>) to handle session loss.

### Multi-User Session Management

When scanning with [multiple authenticated users](<https://docs.escape.tech/documentation/platform/authentication/index.md>), session management configuration applies uniformly across all authenticated user contexts.

### Cross-Domain Session Management

Applications with authentication domains separate from application domains require auth domain inclusion in scope:

```yaml
frontend_dast:
  scope:
    crawling:
      allowlist:
        - type: domain
          value: app.example.com
        - type: domain
          value: auth.example.com
```

## Related Documentation

- [Authentication Configuration](<https://docs.escape.tech/documentation/platform/authentication/index.md>)
- [Performance Tuning](<https://docs.escape.tech/documentation/dast/webapp-testing/performance-tuning/index.md>)
- [Production-Safe Scanning](<https://docs.escape.tech/documentation/dast/webapp-testing/safe-mode/index.md>)
- [Configuration Reference](<https://docs.escape.tech/documentation/reference/configuration-schemas/webapp-dast/index.md>)