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:

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.
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 (Privilege Escalation with Asymmetric Permissions), two separate scan profiles must be configured with reversed Main User assignments to test both attack directions.
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 Tenant Isolation scenarios where multiple tenants must be validated against a single privileged account.

Configuration Approaches¶

Escape provides three configuration strategies for multi-user access control testing, each suited to different levels of specificity and customization requirements. All configurations are supported in both API Testing and WebApp Testing modes and apply to both Tenant Isolation and Privilege Escalation testing scenarios.

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

Escape's AI-powered configuration system enables access control 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, whether testing Tenant Isolation or Privilege Escalation.

Configuration Example (Tenant Isolation):

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.

For more complex scenarios with multiple isolation requirements, use XML prompting to structure your rules clearly:

security_tests:
  tenant_isolation:
    main_user: 'user1'
    natural_language_rule: |
      <isolation_rules>
        <rule priority="critical" category="data_access">
          User's private notes and documents must never be visible to other users.
          Check both the note content and metadata (title, created_at, author).
        </rule>
        <rule priority="high" category="resource_ownership">
          Each user should only see their own:
          - Projects and project members
          - API keys and authentication tokens
          - Billing information and payment methods
        </rule>
        <rule priority="medium" category="organization_isolation">
          Within multi-organization contexts, ensure that:
          - Organization A users cannot access Organization B's resources
          - Shared resources are explicitly marked and properly scoped
        </rule>
      </isolation_rules>

      <exceptions>
        <allowed>Public profiles and usernames are intentionally shared across users</allowed>
        <allowed>Shared workspace resources with explicit collaboration permissions</allowed>
        <allowed>System-wide notifications and announcements</allowed>
      </exceptions>

      <detection_hints>
        Look for user IDs, tenant IDs, or organization IDs in API responses.
        Pay special attention to list endpoints that might leak other users' data.
        Check if filtering by user/tenant parameters is properly enforced.
      </detection_hints>

Configuration Example (Privilege Escalation):

security_tests:
  tenant_isolation:
    main_user: 'admin' # Administrative user as victim
    natural_language_rule: |
      Ensure that standard members cannot access administrative endpoints or perform privileged operations:
      - Members cannot access user management endpoints
      - Members cannot modify system configuration
      - Members cannot view audit logs
      - Members cannot access billing information

Why XML prompting? XML provides clear structure for complex authorization rules, allowing you to separate different types of isolation requirements (data access, resource ownership, organization boundaries, privilege levels) and specify priorities and exceptions that help the AI generate more accurate detection rules.

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:

Issue Reporting:

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

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 both Tenant Isolation and Privilege Escalation scenarios where domain-specific access control requirements 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 configuration employs response fingerprinting to automatically detect authorization failures across the majority of API architectures without requiring custom rule definition. This approach is effective for both Tenant Isolation and Privilege Escalation testing.

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 (whether different tenants or different privilege levels), the response fingerprints differ. A match indicates that both users received substantively identical data, suggesting the API failed to apply proper authorization filtering based on user identity or privilege level.

Validation Criteria:

Both requests are authenticated (not anonymous access scenarios)
The same API endpoint is targeted with equivalent parameters
Only the authentication credentials differ between requests
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 authorization validation and provides effective coverage for both Tenant Isolation and Privilege Escalation scenarios. It requires minimal configuration while delivering high-confidence detection for most authorization bypass scenarios across multi-tenant architectures and role-based access control systems.

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 isolated based on user identity or privilege level, 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 across users or privilege levels
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 isolation across tenants or privilege boundaries
Compliance Requirements: Regulatory mandates require validation of specific PII or PHI field isolation across user contexts or access levels

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.