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 — this is what you edit to pick up APIs that live on a domain different from the base URL
  • 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.

Exploration Scope

The exploration scope is the outermost boundary of the scan — the set of domains the scanner is allowed to reach at all. Everything else (crawling rules, API testing rules) operates within this boundary.

By default, the exploration scope is derived automatically from the profile's base URL (https://app.example.com → only app.example.com is in scope). That default is correct for single-domain applications, but is often too narrow in practice:

  • The frontend is on app.example.com, but it calls api.example.com — the API calls would be captured but dropped at the exploration-scope boundary before any security check runs on them.
  • A customer portal spans portal.example.com and auth.example.com.
  • A SaaS application serves static assets from cdn.example.net and issues XHR requests to backend.example.com.

In all of these cases, you need to extend the exploration scope so the scanner does not discard traffic to those extra domains.

Where it Lives in the Configuration

The exploration scope is expressed as type: domain entries in the top-level global scope.allowlist. It is shared across every scanner in the profile — WebApp, REST, GraphQL — which is what makes it the right place to declare "these are the domains this application is made of".

# Top-level global scope — this IS the exploration scope.
scope:
  allowlist:
    - type: domain
      operation: equals
      value: app.example.com       # the frontend (base URL host)
    - type: domain
      operation: equals
      value: api.example.com       # backend API called by the frontend
    - type: domain
      operation: ends_with
      value: .example.com          # any subdomain of example.com

Once this is set, the WebApp scanner:

  • Can crawl pages served from any of the listed domains when frontend_dast.scope.crawling.extend_global_scope is set to true (it is false by default).
  • Captures and actively tests API traffic going to any of those domains (because frontend_dast.scope.api_testing.extend_global_scope defaults to true).

Typical Pattern — "Pick Up APIs Outside of Scope"

The most common reason customers reach for this setting is: "the frontend scan sees calls to api.example.com but is not running security checks against them". The fix is almost always one of the two options below.

Option A — Extend the global scope.allowlist (recommended). Declares the API domain once, and every scanner on the profile picks it up:

scope:
  allowlist:
    - type: domain
      operation: equals
      value: app.example.com
    - type: domain
      operation: equals
      value: api.example.com   # <-- makes the backend API part of the scan

Option B — Scope the extension to the WebApp scan only. Useful when you want the API to be in scope for the WebApp scan but not for a separate REST/GraphQL scanner that shares the same global config:

frontend_dast:
  scope:
    api_testing:
      extend_global_scope: true   # default, shown for clarity
      allowlist:
        - type: domain
          value: api.example.com

See API Coverage & Test Selection for the full list of reasons a captured endpoint may not be tested — exploration scope is the first thing to check, but not the only one.

Legacy exploration_scope Field

Older scan configurations sometimes show a top-level exploration_scope: [ ... ] field (a flat list of domain strings). This field is deprecated and generated automatically by the platform from the profile's base URL and from Attack Surface Management (ASM) data. It is maintained for backwards compatibility only; it should not be edited by hand.

To control exploration scope today, always use scope.allowlist with type: domain entries as shown above. Manual edits to the legacy exploration_scope field will be ignored or overwritten on the next configuration save.

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
# This can be defined as a global configuration for the org.
scope:
  allowlist:
    - type: domain
      operation: ends_with
      value: app.example.com
    - type: domain
      operation: equals
      value: 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

By default, extend_global_scope is true. The only exception for this is for crawling scope, which does not extend from the global scope.

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.

By default, when running a scan on app.example.com, we will only crawl URLs on the exact domain of the app. This can be configured through the crawling section to extend to more domains and/or limit crawling to specific sections of the app.

Domain Configuration

Domain Rules

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

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

Note: We will always add a rule to match the exact domain of the app the scan is running on to limit crawling on one domain, ie:

- type: domain
  value: app.example.com
  operation: equals

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 that do not match any blocklist rule 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 that do not match any blocklist rule will be allowed.

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.

What the blocklist does and does not prevent today

The api_testing blocklist controls what the scanner itself does with a matching endpoint — specifically:

  • The crawling agent will not directly navigate to a blocklisted URL.
  • The crawling agent will not directly fire a request against a blocklisted endpoint.
  • Captured traffic matching the blocklist is not handed to the security-check engine for active fuzzing.

What the blocklist is not, today, is a network-level proxy. If the application itself — for example, a page that is in scope — makes an XHR/fetch call to a blocklisted endpoint as part of its normal load behavior, the browser will still execute that request. The request reaches your server exactly as it would in a real user session. It will only appear in the API Coverage logs as captured; no active security check will be run against it.

In practical terms:

  • A blocklisted authentication endpoint may still receive real login/refresh calls triggered by the page itself — but the scanner will not inject payloads into them.
  • A blocklisted destructive endpoint (/delete, /purge, …) is safe from scanner-initiated mutation, but a page that auto-fires such a call on mount will still fire it.

If you need to guarantee that a given endpoint is never contacted during a scan — including requests originated by the application — use the crawling blocklist to prevent the pages that issue those calls from being visited, or block the endpoint at your own WAF/gateway for the duration of the scan. A network-level proxy that enforces the api_testing blocklist on outbound browser traffic is on the roadmap.

Common Configuration Patterns

Pattern 1: Production-Safe Scanning

Restrict scanning to safe pages and skip destructive API endpoints.

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:
      allowlist:
        - type: domain
          operation: equals
          value: app.example.com # Only allow testing APIs on this exact domain

      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.

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.

frontend_dast:
  scope:
    crawling:
      allowlist:
        # We allow crawling of 2 domains
        - type: domain
          value: admin.example.com
          operation: equals
        - type: domain
          value: app.example.com
          operation: equals

      blocklist:
        - type: web_page_element_selector
          value: ".third-party-widget"

    api_testing:
      allowlist:
        # We allow API testing for these 2 domains
        - 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.

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