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 four main areas:

  • Exploration Scope: High-level domain boundaries for the entire scan
  • Crawling Scope: Controls page crawling, element interactions, and URL visit patterns
  • API Testing Scope: Controls which API traffic is captured, analyzed, and tested
  • Crawling Tuning: Optimization settings for the crawling process (visit limits, logging)

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

Scope Rule System

The scope configuration uses a rule-based system with allowlists and blocklists to precisely define what's in scope for scanning. Each rule has:

  • type: The type of target (e.g., domain, web_page_url, rest_api_path)
  • value: The pattern or value to match
  • operation: The matching operation (e.g., equals, regex, wildcard)
  • method: For API rules, the optional HTTP method

Rule Evaluation:

  1. Blocklist takes precedence over allowlist - if a target matches any blocklist rule, it's excluded
  2. More specific rules take precedence over general rules
  3. Allowlist filtering: If allowlist rules exist, only matching targets are in scope
  4. Default behavior: If no allowlist rules exist, all targets within the exploration scope are allowed (subject to blocklist)

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
    crawling:
      # Control whether to extend from global scope (default: false for safety)
      extend_global_scope: false

      # Allowlist rules - targets that are allowed to be crawled
      allowlist:
        - type: web_page_url
          value: "https://app.example.com/dashboard/.*"
          operation: regex
        - type: web_page_url
          value: "https://app.example.com/settings/.*"
          operation: regex
        - type: domain
          value: "subdomain.example.com"
        - type: domain
          value: "cdn.example.com"

      # Blocklist rules - targets that should NOT be crawled
      blocklist:
        - type: web_page_url
          value: "/faq/.*"
          operation: regex
        - type: web_page_url
          value: "/articles/.*"
          operation: regex
        - type: web_page_url
          value: "/help/.*"
          operation: regex
        - type: web_page_url
          value: "/documentation/.*"
          operation: regex
        - type: web_page_element_selector
          value: "button.logout"
        - type: web_page_element_selector
          value: "a[href='/logout']"
        - type: web_page_element_selector
          value: ".chat-widget"
        - type: web_page_element_selector
          value: "button[data-action='delete-account']"

    # API traffic analysis and testing configuration
    api_testing:
      # Control whether to extend from global scope (default: true)
      extend_global_scope: true

      # Allowlist rules - API targets that are allowed to be tested
      allowlist:
        - type: rest_api_url
          value: "https://api.example.com/v[0-9]+/.*"
          operation: regex
        - type: rest_api_url
          value: "https://backend.example.com/graphql"
        - type: domain
          value: "api.example.com"
        - type: domain
          value: "backend.example.com"

      # Blocklist rules - API targets that should NOT be tested
      blocklist:
        - type: rest_api_path
          value: "/api/auth/.*"
          operation: regex
          method: null  # applies to all methods
        - type: rest_api_path
          value: "/api/logout"
          method: POST
        - type: rest_api_path
          value: "/api/user/delete"
          method: DELETE

  # Crawling tuning configuration - optimization settings for crawling
  crawling_tuning:
    max_unique_values_per_query_param: 10
    max_unique_fragments_per_page: 10
    max_parameterized_url_variations: 10
    only_inscope_crawling_logs: true

Scope Configuration Structure

The scope configuration is organized into two main sections:

crawling - Page Crawling Scope

Controls which pages are crawled and which elements are interacted with. Uses WebAppCrawlingScopeRule types:

  • domain - Domain patterns for crawling
  • web_page_url - URL patterns for pages
  • web_page_element_selector - CSS selectors for elements

api_testing - API Testing Scope

Controls which API traffic is analyzed and tested. Uses APITestingScopeRule types:

  • domain - Domain patterns for API traffic
  • rest_api_path - REST API path patterns (with optional method/domain)
  • rest_api_url - REST API full URL patterns (with optional method)
  • graphql_operation - GraphQL operation names

Each section supports:

  • extend_global_scope: Whether to extend from global scope configuration
  • allowlist: Rules defining what is allowed to be scanned/tested
  • blocklist: Rules defining what should NOT be scanned/tested

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

Crawling Scope Configuration

The crawling section controls which pages are crawled, how elements are interacted with, and how visit patterns are optimized. This uses a rule-based system with allowlists and blocklists to precisely define what's in scope for crawling.

Domain Configuration

Domain Rules

Additional domains that should be allowed for page crawling beyond the exploration_scope are configured using domain type rules in the allowlist.

frontend_dast:
  scope:
    crawling:
      allowlist:
        - type: domain
          value: "cdn.example.com"
        - type: domain
          value: "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

Page URL Allowlist Rules

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

frontend_dast:
  scope:
    crawling:
      allowlist:
        - type: web_page_url
          value: "https://app\\.example\\.com/dashboard/.*"
          operation: regex
        - type: web_page_url
          value: "https://app\\.example\\.com/settings/.*"
          operation: regex

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 no allowlist rules are specified, all URLs within the exploration_scope will be allowed.

Page URL Blocklist Rules

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

frontend_dast:
  scope:
    crawling:
      blocklist:
        - type: web_page_url
          value: "/faq/.*"
          operation: regex
        - type: web_page_url
          value: "/articles/.*"
          operation: regex
        - type: web_page_url
          value: "/help/.*"
          operation: regex
        - type: web_page_url
          value: "/documentation/.*"
          operation: regex

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

Element Selector Allowlist Rules

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

frontend_dast:
  scope:
    crawling:
      allowlist:
        - type: web_page_element_selector
          value: "div#main-app"
        - type: web_page_element_selector
          value: "nav.sidebar"
        - type: web_page_element_selector
          value: "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>.

Element Selector Blocklist Rules

CSS selectors defining elements that should be excluded from scanner interactions. Blocklist rules are applied after allowlist rules. These selectors are Playwright-based and support Playwright's extended selector syntax, including text-based selectors like :has-text().

frontend_dast:
  scope:
    crawling:
      blocklist:
        - type: web_page_element_selector
          value: "button.logout"
        - type: web_page_element_selector
          value: "a[href='/logout']"
        - type: web_page_element_selector
          value: ".chat-widget"
        - type: web_page_element_selector
          value: "button[data-action='delete-account']"
        - type: web_page_element_selector
          value: "iframe[src*='support']"
        - type: web_page_element_selector
          value: "button:has-text('Logout')"

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

Crawling Tuning Configuration

The crawling_tuning section controls optimization settings for the crawling process, such as visit limits and logging visibility. These settings are configured at the top level of the frontend DAST configuration, not within the scope section.

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:
  crawling_tuning:
    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:
  crawling_tuning:
    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:
  crawling_tuning:
    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:
  crawling_tuning:
    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 Testing Scope Configuration

The api_testing section controls which API traffic is captured, analyzed, and tested for security issues. The scanner observes API traffic without interfering with normal application functionality. This uses a rule-based system with allowlists and blocklists to precisely define what's in scope for API testing.

API Domain Filtering

API Domain Rules

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_testing:
      allowlist:
        - type: domain
          value: "api.example.com"
        - type: domain
          value: "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 no allowlist rules are specified, all domains within the exploration_scope will be analyzed.

API URL Filtering

API URL Allowlist Rules

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

frontend_dast:
  scope:
    api_testing:
      allowlist:
        - type: rest_api_url
          value: "https://api\\.example\\.com/v[0-9]+/.*"
          operation: regex
        - type: rest_api_url
          value: "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

API Blocklist Rules

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_testing:
      blocklist:
        - type: rest_api_path
          value: "/api/auth/.*"
          operation: regex
          method: null  # applies to all HTTP methods
        - type: rest_api_path
          value: "/api/logout"
          method: POST
        - type: rest_api_path
          value: "/api/user/delete"
          method: DELETE

Parameters:

  • type: Rule type (e.g., rest_api_path, rest_api_url)
  • value: The pattern value to match
  • operation: Matching operation (e.g., regex, equals)
  • method: HTTP method to block (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:
    crawling:
      blocklist:
        - type: web_page_url
          value: "/admin/delete/.*"
          operation: regex
        - type: web_page_url
          value: "/admin/purge/.*"
          operation: regex
        - type: web_page_element_selector
          value: "button[data-action='delete']"
        - type: web_page_element_selector
          value: "button[data-action='purge']"
        - type: web_page_element_selector
          value: "a[href*='/delete']"

    api_testing:
      blocklist:
        - type: rest_api_path
          value: "/api/.*/(delete|purge|destroy)"
          operation: regex
          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:
    crawling:
      allowlist:
        - type: web_page_url
          value: "https://app\\.example\\.com/dashboard/analytics/.*"
          operation: regex
        - type: web_page_element_selector
          value: "div#analytics-module"

    api_testing:
      allowlist:
        - type: rest_api_url
          value: "https://api\\.example\\.com/v2/analytics/.*"
          operation: regex

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:
    crawling:
      allowlist:
        - type: domain
          value: "cdn.example.com"
      blocklist:
        - type: web_page_element_selector
          value: ".third-party-widget"

    api_testing:
      allowlist:
        - type: domain
          value: "api.example.com"
        - type: domain
          value: "backend.example.com"
      blocklist:
        - type: rest_api_path
          value: "/api/auth/.*"
          operation: regex
          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:
    crawling:
      allowlist:
        - type: web_page_url
          value: "https://staging\\.example\\.com/new-feature/.*"
          operation: regex

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