Skip to content

WebApp Testing — Scope Configuration

Overview

The scope configuration controls which pages are crawled, which elements are interacted with, and which API traffic is analyzed during WebApp Testing scans. The configuration is organized into three main areas:

  • Exploration Scope: High-level domain boundaries for the entire scan
  • Page Scope: Controls page crawling, element interactions, and URL visit patterns
  • API Scope: Controls which API traffic is captured, analyzed, and tested

This separation enables precise control over scan coverage while optimizing scan duration and resource utilization.

Complete Configuration Example

The following configuration demonstrates all available scope options and can be used as a template:

# High-level exploration scope - defines the domain boundaries
exploration_scope:
  - app.example.com
  - dashboard.example.com

frontend_dast:
  scope:
    # Page crawling and interaction configuration
    pages:
      # Subdomains configuration
      extra_allowed_domains:
        - subdomain.example.com
        - cdn.example.com

      # URL pattern filtering
      allowlist_url_patterns:
        - https://app\.example\.com/dashboard/.*
        - https://app\.example\.com/settings/.*

      blocklist_patterns:
        - /faq/.*
        - /articles/.*
        - /help/.*
        - /documentation/.*

      # Element interaction filtering
      allowlist_element_selectors:
        - div#main-app
        - nav.sidebar
        - section.dashboard

      blocklist_element_selectors:
        - button.logout
        - a[href="/logout"]
        - .chat-widget
        - button[data-action="delete-account"]

      # Visit limits for optimization
      max_unique_values_per_query_param: 10
      max_unique_fragments_per_page: 10
      max_parameterized_url_variations: 10

      # Crawling log visibility
      only_inscope_crawling_logs: true

    # API traffic analysis and testing configuration
    api:
      # Domain filtering
      allowlist_domains:
        - api.example.com
        - backend.example.com

      # URL pattern filtering
      allowlist_url_patterns:
        - https://api\.example\.com/v[0-9]+/.*
        - https://backend\.example\.com/graphql

      # Skip security checks on specific endpoints
      skipped_url_patterns:
        - url_pattern: /api/auth/.*
          method: null  # applies to all methods
        - url_pattern: /api/logout
          method: POST
        - url_pattern: /api/user/delete
          method: DELETE

Exploration Scope

The exploration_scope defines the top-level domain boundaries for the entire scan. All page and API scope configurations operate within these boundaries.

exploration_scope:
  - app.example.com
  - dashboard.example.com

Behavior

  • Domain Matching: Only URLs matching these domains will be considered for crawling or API analysis
  • Subdomain Handling: Subdomains must be explicitly listed unless configured in extra_allowed_domains
  • Default Behavior: If not specified, the domain is derived from the base URL of the application

Use Cases

  • Multi-domain Applications: Applications spanning multiple domains (e.g., main app + admin panel)
  • Microservices Architecture: Frontend and backend services on different domains
  • Third-party Integrations: Including CDN or asset domains in the scan scope

Page Scope Configuration

The pages section controls which pages are crawled, how elements are interacted with, and how visit patterns are optimized.

Domain Configuration

extra_allowed_domains

Additional domains that should be allowed for page crawling beyond the exploration_scope.

frontend_dast:
  scope:
    pages:
      extra_allowed_domains:
        - cdn.example.com
        - static.example.com

Use Cases:

  • Applications using subdomains for different features
  • Content delivery networks (CDNs) hosting application assets
  • Multi-tenant applications with dynamic subdomains

URL Pattern Filtering

Pages allowlist_url_patterns

Regular expressions defining which page URLs are permitted to be visited. If specified, only URLs matching at least one pattern will be crawled.

frontend_dast:
  scope:
    pages:
      allowlist_url_patterns:
        - https://app\.example\.com/dashboard/.*
        - https://app\.example\.com/settings/.*

Use Cases:

  • Focused Scanning: Limit scan to specific application sections (e.g., admin panel only)
  • Differential Scanning: Scan only newly deployed features in CI/CD pipelines
  • Compliance Requirements: Restrict testing to specific modules for regulatory reasons

Note: If not set, all URLs within the exploration_scope will be allowed.

blocklist_patterns

Regular expressions defining which page URLs should be excluded from crawling. Blocklist patterns are applied after allowlist patterns.

frontend_dast:
  scope:
    pages:
      blocklist_patterns:
        - /faq/.*
        - /articles/.*
        - /help/.*
        - /documentation/.*

Use Cases:

  • Optimization: Skip static content pages that don't contain security-relevant functionality
  • Rate Limiting: Avoid pages that trigger expensive operations or external API calls
  • Stability: Exclude pages known to cause issues during automated testing

Element Interaction Filtering

allowlist_element_selectors

CSS selectors defining zones within pages where the scanner is permitted to interact with elements. When specified, only elements matching these selectors will be clicked, filled, or otherwise interacted with.

frontend_dast:
  scope:
    pages:
      allowlist_element_selectors:
        - div#main-app
        - nav.sidebar
        - section.dashboard

Use Cases:

  • Focused Testing: Restrict interactions to specific UI components
  • Complex Layouts: Avoid navigation bars, footers, or promotional content
  • Performance: Reduce scan time by targeting specific application areas

Example: Using div#main-content will interact only with elements inside <div id="main-content">...</div>.

blocklist_element_selectors

CSS selectors defining elements that should be excluded from scanner interactions. Blocklist selectors are applied after allowlist selectors.

frontend_dast:
  scope:
    pages:
      blocklist_element_selectors:
        - button.logout
        - a[href="/logout"]
        - .chat-widget
        - button[data-action="delete-account"]
        - iframe[src*="support"]

Use Cases:

  • Prevent Disruption: Avoid logout buttons, session termination, or destructive actions
  • Third-party Widgets: Exclude chat widgets, analytics iframes, or external integrations
  • Stability: Skip elements that trigger modals or redirects outside the application

Visit Limits and Optimization

max_unique_values_per_query_param

The maximum number of different values to test for each query parameter on the same page path. Already tested values can be revisited without counting against the limit.

frontend_dast:
  scope:
    pages:
      max_unique_values_per_query_param: 10

Example:

For the /search page with parameter q, if set to 5:

  • /search?q=test1 ✓ (allowed)
  • /search?q=test2 ✓ (allowed)
  • /search?q=test3 ✓ (allowed)
  • /search?q=test4 ✓ (allowed)
  • /search?q=test5 ✓ (allowed)
  • /search?q=test6 ✗ (blocked)

Note: The limit applies independently to each query parameter (q, filter, page are tracked separately).

max_unique_fragments_per_page

The maximum number of different fragments (anchors) to visit for the same page path. Single Page Applications with route fragments containing / are not limited by this setting.

frontend_dast:
  scope:
    pages:
      max_unique_fragments_per_page: 10

Example:

For /page.html, if set to 5:

  • /page.html#section1 ✓ (allowed)
  • /page.html#section2 ✓ (allowed)
  • /page.html#section3 ✓ (allowed)
  • /page.html#section4 ✓ (allowed)
  • /page.html#section5 ✓ (allowed)
  • /page.html#section6 ✗ (blocked)

max_parameterized_url_variations

The maximum number of different parameter values to test for parameterized URL patterns. The scanner detects numeric and UUID segments in URL paths and replaces them with {param} to create patterns.

frontend_dast:
  scope:
    pages:
      max_parameterized_url_variations: 10

Example:

URLs /users/123/profile and /users/456/profile both match pattern /users/{param}/profile:

  • /users/123/profile ✓ (allowed, variation 1)
  • /users/456/profile ✓ (allowed, variation 2)
  • /users/789/profile ✓ (allowed, variation 3)
  • ... up to 10 variations
  • /users/999/profile ✗ (blocked if limit reached)

Crawling Log Visibility

only_inscope_crawling_logs

Controls whether the crawling logs under the "Crawling" tab display only in-scope URLs or all discovered URLs.

frontend_dast:
  scope:
    pages:
      only_inscope_crawling_logs: true
  • true (default): Only in-scope URLs are reported
  • false: All discovered URLs are reported, including out-of-scope URLs

Use Cases:

  • Debugging: Set to false to see all URLs the scanner encountered
  • Scope Validation: Verify that scope configuration is correctly filtering URLs

API Scope Configuration

The api section controls which API traffic is captured, analyzed, and tested for security issues. The scanner observes API traffic without interfering with normal application functionality.

API Domain Filtering

allowlist_domains

Domains that are permitted for API traffic analysis. If specified, only API requests to these domains will be analyzed and tested.

frontend_dast:
  scope:
    api:
      allowlist_domains:
        - api.example.com
        - backend.example.com

Use Cases:

  • Backend Separation: Focus testing on specific backend services
  • Third-party APIs: Include or exclude external API integrations
  • Microservices: Target specific microservices in a complex architecture

Note: If not set, all domains within the exploration_scope will be analyzed.

API URL Pattern Filtering

API allowlist_url_patterns

Regular expressions defining which API URLs are permitted for analysis and testing.

frontend_dast:
  scope:
    api:
      allowlist_url_patterns:
        - https://api\.example\.com/v[0-9]+/.*
        - https://backend\.example\.com/graphql

Use Cases:

  • API Versioning: Test only specific API versions (e.g., v2 endpoints only)
  • Endpoint Selection: Focus on specific API paths or services
  • GraphQL/REST Separation: Target specific API types

Security Check Exclusions

skipped_url_patterns

Patterns defining API endpoints where security checks should be skipped. The API traffic is still captured and analyzed, but active security testing is disabled.

frontend_dast:
  scope:
    api:
      skipped_url_patterns:
        - url_pattern: /api/auth/.*
          method: null  # applies to all HTTP methods
        - url_pattern: /api/logout
          method: POST
        - url_pattern: /api/user/delete
          method: DELETE

Parameters:

  • url_pattern: Regular expression matching the API URL
  • method: HTTP method to skip (optional, null applies to all methods)

Use Cases:

  • Authentication Endpoints: Observe login/logout traffic without running active tests
  • Destructive Operations: Skip security checks on delete/purge endpoints
  • Rate-limited Endpoints: Avoid triggering rate limits on sensitive APIs
  • Payment Processing: Exclude financial transaction endpoints from active testing

Important: This is more granular than completely excluding URLs from scope—the traffic is still captured for analysis, but security checks are not executed.

Common Configuration Patterns

Pattern 1: Production-Safe Scanning

Restrict scanning to safe pages and skip destructive API endpoints.

exploration_scope:
  - app.example.com

frontend_dast:
  mode: read-only
  scope:
    pages:
      blocklist_patterns:
        - /admin/delete/.*
        - /admin/purge/.*

      blocklist_element_selectors:
        - button[data-action="delete"]
        - button[data-action="purge"]
        - a[href*="/delete"]

    api:
      skipped_url_patterns:
        - url_pattern: /api/.*/(delete|purge|destroy)
          method: null

Pattern 2: Focused Feature Testing

Test only a specific feature or module in the application.

exploration_scope:
  - app.example.com

frontend_dast:
  scope:
    pages:
      allowlist_url_patterns:
        - https://app\.example\.com/dashboard/analytics/.*

      allowlist_element_selectors:
        - div#analytics-module

    api:
      allowlist_url_patterns:
        - https://api\.example\.com/v2/analytics/.*

Pattern 3: Multi-Domain Application

Scan an application spanning multiple domains with targeted API testing.

exploration_scope:
  - app.example.com
  - admin.example.com

frontend_dast:
  scope:
    pages:
      extra_allowed_domains:
        - cdn.example.com

      blocklist_element_selectors:
        - .third-party-widget

    api:
      allowlist_domains:
        - api.example.com
        - backend.example.com

      skipped_url_patterns:
        - url_pattern: /api/auth/.*
          method: null

Pattern 4: CI/CD Differential Scanning

Scan only newly deployed pages in a CI/CD pipeline.

exploration_scope:
  - staging.example.com

frontend_dast:
  scope:
    pages:
      allowlist_url_patterns:
        - https://staging\.example\.com/new-feature/.*

      max_unique_values_per_query_param: 5
      max_parameterized_url_variations: 5

Best Practices

  1. Start Broad, Then Narrow: Begin with default scope, analyze crawling logs, then refine with allowlists and blocklists
  2. Use Blocklists for Optimization: Exclude static content, documentation, and help pages to reduce scan duration
  3. Protect Authentication Flows: Always blocklist logout buttons and add authentication endpoints to skipped_url_patterns
  4. Balance Coverage and Duration: Adjust visit limits (max_unique_values_per_query_param, etc.) based on application size and scan time requirements
  5. Test Scope Configuration: Use only_inscope_crawling_logs: false during initial setup to validate scope rules
  6. Document Scope Decisions: Maintain comments in configuration explaining why specific patterns are included or excluded