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 → app.example.com is in scope). scope.use_defaults defaults to true: it injects the organization's ASM scope into scanner configuration. For applications spanning multiple domains, include each domain you want to test:

  • A frontend on app.example.com calls api.example.com: add the API domain to include captured calls in the security-testing scope.
  • 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.

Extend the exploration scope to include traffic to these additional domains in security testing.

Where It Lives in the Configuration

The exploration scope is expressed as type: domain entries in the top-level global scope.allowlist. It's shared across WebApp, REST and GraphQL scanners in the profile, so use it 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's 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"

If the frontend scan captures calls to api.example.com outside the current exploration scope, include that domain using one of the 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 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.

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 (for example, domain, web_page_url, rest_api_path)
  • value: The pattern or value to match
  • operation: The matching operation (for example, equals, regex, wildcard)
  • method: For API rules, the optional HTTP method

See Scope Operations for the available operation values. regex is a full match: the pattern must cover the whole value, so wrap partial patterns in .*. domain rules match the hostname without the scheme, port or path for page and REST request targets. GraphQL operation checks in WebApp API testing compare the domain against host:port when a port is present. Subdomains aren't expanded implicitly: equals: example.com doesn't match www.example.com, ends_with: .example.com does. A rule that sets a method matches only that method; a rule that omits it matches every method. On an ip rule, contains with a CIDR value tests network membership instead of string matching.

Rule Evaluation: Each candidate is evaluated on its own, whether it's a page URL, page element, API request, domain, IP or GraphQL operation.

  1. Blocklist first: if the candidate matches any blocklist rule, it's out of scope, and no allowlist rule can bring it back
  2. Applicable rules only: only the rule groups listed below for that kind of candidate are considered; if the allowlist holds none of them, the candidate is in scope
  3. One match per group: within a group a single match is enough, and every group holding at least one rule must produce a match. Empty groups are ignored.
Candidate Allowlist rule groups checked
Page URL domain (against the host) and web_page_url
API request URL domain (against the host) and rest_api_url / rest_api_path (against the path)
API path with no host rest_api_path
Domain domain
IP address ip
GraphQL operation graphql_operation

Page URLs and API request URLs are therefore checked against two groups. Both must match, which means web_page_url and rest_api_* rules narrow the scope inside the allowed domains: they never widen it:

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

The base URL https://app.example.com/ matches the domain group but not the web_page_url group, so it's out of scope. To include it, widen the URL rule to cover it ("https://app\\.example\\.com/(dashboard/.*)?") or remove the web_page_url rules and use domain-based scope.

For regex operations, the pattern must match the target's complete value. Wrap a partial pattern in .* to match a substring. The value depends on the rule type:

  • web_page_url and rest_api_url rules match the complete URL, including the scheme and host.
  • rest_api_path rules match only the URL path.
  • graphql_operation rules match the complete operation name.

For example, /faq/.* doesn't match the web_page_url target https://app.example.com/faq/1. Use https://app\.example\.com/faq/.* to match that origin, or .*/faq/.* to match the path on every origin already allowed by the scan's domain scope.

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

extend_global_scope defaults to true for API testing and false for crawling. Set it explicitly to choose whether each scope inherits the global allowlist.

Behavior

  • Domain Matching: Only URLs matching these domains will be considered for crawling or API analysis
  • Subdomain Handling: Subdomains must be listed explicitly or matched with an ends_with rule such as .example.com
  • 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 (for example, 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, a scan on app.example.com crawls URLs on that exact domain. Use the crawling section to add domains or focus exploration on specific application sections.

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, for example:

- 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 (for example, 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 don't 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 / aren't 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 identifier values to visit for a shared URL pattern. This applies to identifiers in URL paths and fragments, including numbers and UUIDs.

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 don't 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 (for example, 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 (for example, rest_api_path, rest_api_url)
  • value: The pattern value to match
  • operation: Matching operation (for example, 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 aren't executed.

API Blocklists and Browser Requests

The api_testing blocklist controls scanner actions on matching endpoints:

  • 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.

If a page in scope makes an XHR/fetch call to a blocklisted endpoint as part of its normal behavior, the browser still executes that request. The request reaches your server and appears in the API Coverage logs as captured. No active API security check runs against it.

In practical terms:

  • A blocklisted authentication endpoint may still receive real login/refresh calls triggered by the page itself: but the scanner won't 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.

To prevent requests originated by the application, use the crawling blocklist to exclude the pages that issue those calls. To block all requests to an endpoint during the scan, enforce that restriction at your WAF/gateway. 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.

mode: read_only

frontend_dast:
  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 in scope.crawling.blocklist and authentication endpoints in scope.api_testing.blocklist
  4. Balance Coverage and Duration: Adjust visit limits (max_unique_values_per_query_param) 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