Skip to content

Configuration Fundamentals

Main User and Testing Direction

Multi-user security testing in Escape follows a unidirectional testing model centered on the Main User concept. Understanding this model is critical for correct configuration.

Main User Role:

The Main User serves two distinct functions in the testing process:

  1. Exploration Authority: The Main User's authentication context is utilized for application crawling and endpoint discovery. Only features, pages, and API endpoints accessible to the Main User will be included in the security assessment.
  2. Victim Perspective: The Main User is treated as the victim in access control testing scenarios. Other configured users attempt to access data and resources belonging to the Main User.

Testing Direction:

Access control testing is performed exclusively in one direction: from Other Users toward the Main User. This means:

  • If a scan is configured with User A (Main User), User B, and User C, the following tests are performed:
    • User B attempting to access User A's data
    • User C attempting to access User A's data
  • The following tests are NOT performed:
    • User B attempting to access User C's data
    • User C attempting to access User B's data

Implications for Configuration:

This unidirectional model has important consequences for scan design:

  • Feature Coverage Limitation: If the Main User lacks access to specific application features, those features will not be tested for authorization vulnerabilities, even if Other Users have access to them.
  • Bidirectional Testing Requirement: For scenarios requiring bidirectional authorization validation (Use Case 3: Asymmetric Permission Testing), two separate scan profiles must be configured with reversed Main User assignments.
  • Multiple User Consolidation: Multiple users can be configured in a single scan profile when all users should be tested for their ability to access the Main User's data. This is efficient for scenarios where multiple roles or tenants must be validated against a single privileged account.

Network Configuration Requirement

WebApp DAST Multi-User Testing:

When conducting multi-user testing in WebApp DAST mode, the following network parameter must be included in the scan configuration:

network:
  ff_frontend_next_sender: true

This parameter enables the API request replay functionality required for multi-user authorization testing in browser-based scan modes. Without this configuration, credential replay across different user contexts will not function correctly.

API DAST Multi-User Testing:

This network parameter is not required for API DAST scans, as the API request replay mechanism is enabled by default in direct API testing modes.

Configuration Approaches

Escape provides three configuration strategies for Tenant Isolation testing, each suited to different levels of specificity and customization requirements. All configurations are supported in both API DAST and WebApp DAST modes.

Approach 1: Natural Language Rule Generation (AI-Assisted)

Escape's AI-powered configuration system enables tenant isolation rules to be defined through natural language descriptions. An LLM analyzes the provided description and generates appropriate detection logic tailored to the specified use case.

Configuration Example:

security_tests:
  tenant_isolation:
    main_user: 'user1' # Primary user for exploration and baseline establishment
    natural_language_rule: |
      Ensure that a user's notes cannot be accessed by other users.

How This Works:

The natural language description is processed by Escape's agentic system, which generates a set of detection rules that validate the specified authorization boundary. The generated rules can be reviewed in the scan logs by searching for [Agentic - Tenant Isolation].

Rule Generation Visibility:

The AI-generated detection logic is transparently displayed during scan execution:

rule-generation.png

Issue Reporting:

When a tenant isolation violation is detected, the specific rule that triggered the finding is displayed alongside the vulnerability details:

alert-found.png

When to Use This Approach:

This method is recommended when authorization boundaries can be clearly articulated in business logic terms, and when rapid configuration without deep technical rule definition is desired. It is particularly effective for domain-specific isolation requirements that would be cumbersome to express in low-level detection predicates.

Natural Language Rule Complexity:

The effectiveness of AI-generated rules depends on the clarity and specificity of the natural language description. Overly complex or ambiguous descriptions may result in suboptimal rule generation. For optimal results:

  • Provide clear, specific descriptions of the authorization boundary
  • Include concrete examples of what should and should not be accessible
  • Reference specific features, endpoints, or data types when applicable
  • Review the generated rules in scan logs (search for [Agentic - Tenant Isolation]) to verify correctness

If the natural language description proves difficult to articulate or the generated rules are insufficiently precise, consider using Approach 3 (Custom Detection Rules) for explicit rule definition.

Approach 2: Default Fingerprint-Based Detection

Escape's default tenant isolation configuration employs response fingerprinting to automatically detect authorization failures across the majority of API architectures without requiring custom rule definition.

Configuration Example:

security_tests:
  tenant_isolation:
    main_user: 'user1' # Primary user for exploration and baseline establishment
    other_users:
      detect: # Conditions that indicate broken tenant isolation
      # Triggers when authenticated requests return identical response fingerprints across users
      - if_: request.is_authenticated
        is_: true
      - if_: helpers.fingerprints.same
        is_: true

Detection Logic:

This configuration validates that when the same API request is issued by different authenticated users, the response fingerprints differ. A match indicates that both users received substantively identical data, suggesting the API failed to apply proper authorization filtering.

Validation Criteria:

  1. Both requests are authenticated (not anonymous access scenarios)
  2. The same API endpoint is targeted with equivalent parameters
  3. Only the authentication credentials differ between requests
  4. Response fingerprints are analyzed for semantic equivalence

Fingerprint Analysis:

Escape's fingerprinting algorithm normalizes responses by excluding expected per-user variations (session tokens, timestamps, request IDs) while preserving semantic content structure. This approach provides robust detection across diverse API response formats (JSON, XML, GraphQL) without requiring schema-specific configuration.

When to Use This Approach:

This default configuration is recommended for initial tenant isolation validation and provides effective coverage for standard multi-tenant architectures. It requires minimal configuration while delivering high-confidence detection for most authorization bypass scenarios.

Approach 3: Custom Detection Rules (Precision Targeting)

For complex scenarios where responses contain expected per-user variations (timestamps, user-specific metadata, localization data) but specific data elements must remain tenant-isolated, custom detection rules enable precision targeting of authorization boundaries.

Configuration Example:

security_tests:
  tenant_isolation:
    main_user: user1
    other_users:
      detect:
        # JSON path-based detection: Validates specific fields remain distinct across users
        - if: helpers.json_matches.all
          jq: '.notes[].content'  # Extract note content from all notes in response
          is: true  # Trigger if extracted values are identical across users
        # Regex-based detection: Identifies presence of user-specific data in other users' responses
        - if: helpers.regex_matches.all
          regex: '.*User 1 Private Note.*'  # Pattern matching sensitive data
          is: true  # Trigger if pattern found in both users' responses

Use Case for Custom Rules:

Custom detection rules are essential when:

  • Partial Response Variation: API responses include dynamic per-user elements (timestamps, request IDs, session data) that cause fingerprint mismatches, while authorization-sensitive data remains identical
  • Nested Data Structures: Authorization failures occur in specific nested fields or array elements within larger response objects
  • Pattern-Based Detection: Specific data values, identifiers, or text patterns must be validated for cross-user isolation
  • Compliance Requirements: Regulatory mandates require validation of specific PII or PHI field isolation

Detector Extensibility:

The detect block supports the complete range of detectors documented in Custom Rules - Detectors, including:

  • JSON path extraction with JQ queries
  • Regular expression pattern matching
  • Response code analysis
  • Header inspection
  • Composite boolean logic (AND, OR, NOT operations)

This extensibility enables arbitrarily complex authorization validation logic to be expressed declaratively.