Skip to content

BOLA Agent

The BOLA (Broken Object-Level Authorization) Agent autonomously tests authorization boundaries and access control mechanisms using multi-user authentication.

Capabilities

  • Tenant Isolation Testing: Tests data segregation between accounts with equivalent permission levels
  • Privilege Escalation Detection: Tests authorization controls between users with different privilege levels
  • Horizontal Authorization Testing: Validates tenant isolation boundaries
  • Vertical Authorization Testing: Validates privilege escalation boundaries

Configuration

Basic Configuration

Enable the BOLA agent:

ai_pentesting:
  enabled: true
  agents:
    bola:
      enabled: true

Multi-User Configuration

Configure users for authorization testing:

authentication:
  presets:
    - type: bearer_token
      users:
        - username: admin@tenant-a.com
          token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
          role: admin
          main_user: true
        - username: user@tenant-a.com
          token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
          role: user
        - username: admin@tenant-b.com
          token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
          role: admin

User-level fields:

  • main_user: Designates the user used for application exploration and as the victim in authorization testing (only one per scan)
  • role: Optional string describing user role (e.g., "admin", "user") to help the agent understand permission levels

BOLA Agent Options: test_mode and natural_language

You can tune how the BOLA agent behaves by setting test_mode and natural_language under ai_pentesting.agents.bola. Both are optional but improve relevance and reduce false positives.

test_mode

Type: privilege_escalation | tenant_isolation (optional)

Tells the agent which authorization scenario you are testing so it can focus its strategy and interpretation.

Value When to use What the agent emphasizes
tenant_isolation Users from different tenants with equivalent roles (e.g. Admin Tenant A vs Admin Tenant B). Horizontal boundaries: no user should see or modify another tenant’s data.
privilege_escalation Users with different privilege levels in the same tenant (e.g. Member vs Admin). Vertical boundaries: lower-privilege users must not access privileged resources or actions.

Example – tenant isolation (multi-tenant SaaS):

ai_pentesting:
  enabled: true
  agents:
    bola:
      enabled: true
      test_mode: tenant_isolation

authentication:
  presets:
    - type: bearer_token
      users:
        - username: admin@company-a.com
          token: <token_a>
          role: admin
          main_user: true
        - username: admin@company-b.com
          token: <token_b>
          role: admin

Example – privilege escalation (RBAC within one org):

ai_pentesting:
  enabled: true
  agents:
    bola:
      enabled: true
      test_mode: privilege_escalation

authentication:
  presets:
    - type: bearer_token
      users:
        - username: admin@company.com
          token: <admin_token>
          role: admin
          main_user: true
        - username: member@company.com
          token: <member_token>
          role: member

If you omit test_mode, the agent infers the scenario from the configured users and roles.

natural_language

Type: string (optional)

A short description of your authorization rules and context. The agent uses it to:

  • Prefer attack steps that match your real authorization model
  • Better distinguish real issues from intended behavior (e.g. shared read-only resources)
  • Interpret responses in line with your security expectations

Example – tenant isolation with natural language:

ai_pentesting:
  enabled: true
  agents:
    bola:
      enabled: true
      test_mode: tenant_isolation
      natural_language: |
        Each tenant's projects, documents, and settings must be strictly isolated.
        Users from Tenant A must never read or modify Tenant B's data, even with
        equivalent admin roles. Shared resources are read-only and explicitly
        marked as public.

Example – privilege escalation with natural language:

ai_pentesting:
  enabled: true
  agents:
    bola:
      enabled: true
      test_mode: privilege_escalation
      natural_language: |
        Members can view and edit their own profile and team projects.
        Only admins may manage users, change org settings, or access audit logs.
        Billing and subscription data are admin-only.

Tip: For additional control over how findings are classified (e.g. to reduce false positives), you can also define security_tests.tenant_isolation.natural_language_rule. That rule is used when the agent evaluates whether a finding is a real vulnerability or an intended feature. See Multi-User Testing for examples.

Testing Direction

The agent follows a unidirectional testing model:

  • Other users attempt to access the Main User's data and resources
  • Only endpoints accessible to the Main User are tested
  • For bidirectional testing, run separate scans with different main users

Tenant Isolation (symmetric permissions):

  • Configure users from different tenants with equivalent roles
  • Single-direction testing suffices (bidirectional by nature)

Privilege Escalation (asymmetric permissions):

  • Configure users with different privilege levels
  • May require bidirectional testing for comprehensive coverage

Requirements

  • Multiple Users: Requires at least two configured users
  • Authentication: Valid authentication required for all users
  • Main User: One user must be designated as main_user: true

Limitations

  • Requires multiple configured users
  • Authentication dependent
  • Tests within configured scope boundaries
  • Limited by scan timeout settings