--- title: "Business Logic Testing" description: "How to do business logic testing with StackHawk" url: https://docs.stackhawk.com/hawkscan/business-logic-testing/ --- # Business Logic Testing Business logic testing is a more comprehensive approach to API security testing that examines how endpoints work together rather than treating them in isolation. Instead of only validating inputs and outputs for individual endpoints, business logic testing considers the **actual functionality and workflows** that your APIs implement. Consider a simple e-commerce application with an `/addItem` endpoint and a `/checkout` endpoint. Traditional testing might call these independently, validating inputs and outputs separately. Business logic testing recognizes these endpoints as part of a connected workflow—items must be added before checkout occurs, cart totals should match item prices, and payment processing follows specific business rules. This contextual understanding enables detection of vulnerabilities that isolated endpoint testing would miss. ## Coverage of OWASP API Vulnerabilities Business logic testing addresses several critical API security risks identified by OWASP: - **[BOLA (Broken Object Level Authorization)](https://owasp.org/API-Security/editions/2023/en/0xa1-broken-object-level-authorization/)** - Testing whether users can access objects they’re not authorized to view - **[BOPLA (Broken Object Property Level Authorization)](https://owasp.org/API-Security/editions/2023/en/0xa3-broken-object-property-level-authorization/)** - Validating that users can only modify properties they have access to - **[BFLA (Broken Function Level Authorization)](https://owasp.org/API-Security/editions/2023/en/0xa5-broken-function-level-authorization/)** - Verifying that privileged functions remain protected from unauthorized access - Additional business logic vulnerabilities specific to your application’s workflows ## Configuration Approach StackHawk provides several plugins that vary in configuration complexity and testing depth. There is a direct relationship between how much the scanner knows about your system and the number of vulnerabilities it can identify. This creates a trade-off between ease of configuration and scan comprehensiveness. The plugins are organized from simple (minimal configuration required) to advanced (significant configuration effort, maximum testing depth), allowing you to select the appropriate level based on your security requirements and available resources. ## Least Configuration StackHawk provides several out-of-the-box plugins designed for business logic testing with minimal configuration overhead. These plugins automatically detect common authorization and access control vulnerabilities without requiring deep knowledge of your application’s internal business rules. While these plugins are not enabled by default, they can be quickly activated through [policy management](https://docs.stackhawk.com/platform/policy-management/), allowing you to begin testing for business logic vulnerabilities immediately. The following plugins are available for easy enablement: - **422002** - [Multi user tenancy check](https://docs.stackhawk.com/vulnerabilities/422002/) - Validates tenant isolation in multi-tenant applications - **421004** - [Possible Broken Object Property Level Authorization](https://docs.stackhawk.com/vulnerabilities/421004/) (BOPLA) - Identifies potential property-level authorization issues - **422003** - [Possible Broken Function Level Authorization](https://docs.stackhawk.com/vulnerabilities/422003/) - Flags likely function-level authorization weaknesses HawkScan 6.6.0 removed the single-identity API authorization rules 40051, 40054, 40055 and 40056. With only one identity, those rules couldn’t confirm an authorization flaw and raised false HIGH alerts. To test authorization with real second identities, use [multi-profile testing](#medium-configuration-multi-profile-testing). ## Medium Configuration: Multi-Profile Testing Multi-profile testing extends HawkScan’s business logic capabilities by scanning your API from multiple user perspectives simultaneously. This approach discovers authorization vulnerabilities that single-user scanning cannot detect. When configured with multiple authentication profiles, HawkScan performs cross-user access testing: - Attempts to access resources discovered by one user profile using credentials from another - Tests whether mutating operations (create, update, delete) respect authorization boundaries - Identifies privilege escalation paths between regular users and privileged accounts This configuration requires: - An OpenAPI specification (which enables smart crawl plan generation) - Multiple test user accounts in your staging or test environment - Valid credentials for each profile ### How Multi-Profile Testing Works When you configure multiple authentication profiles, HawkScan executes a comprehensive testing strategy: 1. **Discovery Phase**: HawkScan crawls your API endpoints using each configured profile, capturing resource identifiers (such as user IDs, order IDs, or document references) from API responses. 2. **Cross-Profile BOLA Testing**: The scanner attempts to read resources discovered by one profile using another profile’s credentials. For example, if Profile A discovers `/api/orders/12345`, HawkScan tests whether Profile B can access that same order. 3. **Cross-Profile BFLA Testing**: The scanner attempts mutating operations (POST, PUT, DELETE) across profile boundaries, testing whether non-privileged users can perform privileged actions. The `isPrivileged` flag marks administrative or elevated-access profiles. This enables HawkScan to specifically test whether unprivileged users can access privileged-only functionality. ### Requirements Multi-profile testing requires the following: - **OpenAPI Specification**: Your API must have an OpenAPI spec configured. HawkScan uses this to generate a smart crawl plan that understands your API’s structure and data relationships. See [OpenAPI Configuration](https://docs.stackhawk.com/hawkscan/configuration/openapi-configuration/). - **Multiple Test Accounts**: Create dedicated test user accounts in your application. At minimum, configure two profiles representing different authorization levels (e.g., a regular user and an admin user). - **Test Environment with Representative Data**: Your staging or test environment should contain data patterns similar to production so that cross-user access tests are meaningful. > **Warning:** Multi-profile testing performs cross-user access attempts. Always run these scans against staging or test environments, never against production systems with real customer data. ### Configuration #### Basic Two-Profile Configuration The simplest multi-profile setup uses two user accounts to test cross-user access. The main authentication block defines how to authenticate, and the profiles section provides credentials for each user: ```yaml # stackhawk.yml app: applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX env: Test host: ${APP_HOST:https://api.example.com} openApiConf: filePath: openapi.yaml authentication: loggedInIndicator: "HTTP.*2[0-9][0-9]\\s*O[kK](\\s*)|HTTP.*3[0-9][0-9].*" loggedOutIndicator: "HTTP.*4[0-9][0-9](\\s*)Unauthorized.*" usernamePassword: type: JSON loginPath: /api/auth/login usernameField: email passwordField: password scanUsername: ${USER_A_EMAIL} scanPassword: ${USER_A_PASSWORD} tokenAuthorization: type: HEADER value: Authorization tokenType: Bearer tokenExtraction: type: TOKEN_PATH value: token testPath: path: /api/users/me success: "HTTP.*200.*" profiles: - name: userA userNamePassword: username: ${USER_A_EMAIL} password: ${USER_A_PASSWORD} - name: userB userNamePassword: username: ${USER_B_EMAIL} password: ${USER_B_PASSWORD} ``` The main authentication block defines the login flow and requires credentials via `scanUsername`/`scanPassword`. The `profiles` section provides credentials for each user being tested - at least two profiles are required for business logic testing to compare access across users. #### Configuration with Privileged User Mark administrative accounts with `isPrivileged: true` to test privilege escalation: ```yaml # stackhawk.yml app: applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX env: Test host: ${APP_HOST:https://api.example.com} openApiConf: filePath: openapi.yaml authentication: loggedInIndicator: "HTTP.*2[0-9][0-9]\\s*O[kK](\\s*)|HTTP.*3[0-9][0-9].*" loggedOutIndicator: "HTTP.*4[0-9][0-9](\\s*)Unauthorized.*" usernamePassword: type: JSON loginPath: /api/auth/login usernameField: email passwordField: password scanUsername: ${REGULAR_USER_EMAIL} scanPassword: ${REGULAR_USER_PASSWORD} tokenAuthorization: type: HEADER value: Authorization tokenType: Bearer tokenExtraction: type: TOKEN_PATH value: token testPath: path: /api/users/me success: "HTTP.*200.*" profiles: - name: regularUser userNamePassword: username: ${REGULAR_USER_EMAIL} password: ${REGULAR_USER_PASSWORD} - name: adminUser isPrivileged: true userNamePassword: username: ${ADMIN_USER_EMAIL} password: ${ADMIN_USER_PASSWORD} ``` Both users are defined in the `profiles` section. The admin user is marked with `isPrivileged: true`, enabling HawkScan to test whether the regular user can access endpoints and resources that should only be available to the admin. #### Configuration with Global Parameters Use `globalParameters` to define user-specific values that HawkScan includes in API requests: ```yaml # stackhawk.yml app: applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX env: Test host: ${APP_HOST:https://api.example.com} openApiConf: filePath: openapi.yaml authentication: loggedInIndicator: "HTTP.*2[0-9][0-9]\\s*O[kK](\\s*)|HTTP.*3[0-9][0-9].*" loggedOutIndicator: "HTTP.*4[0-9][0-9](\\s*)Unauthorized.*" usernamePassword: type: JSON loginPath: /api/auth/login usernameField: email passwordField: password scanUsername: ${TENANT_A_EMAIL} scanPassword: ${TENANT_A_PASSWORD} tokenAuthorization: type: HEADER value: Authorization tokenType: Bearer tokenExtraction: type: TOKEN_PATH value: token testPath: path: /api/users/me success: "HTTP.*200.*" profiles: - name: tenantA userNamePassword: username: ${TENANT_A_EMAIL} password: ${TENANT_A_PASSWORD} globalParameters: tenantId: tenant-a-id-123 userId: user-a-id-456 - name: tenantB userNamePassword: username: ${TENANT_B_EMAIL} password: ${TENANT_B_PASSWORD} globalParameters: tenantId: tenant-b-id-789 userId: user-b-id-012 ``` Global parameters are useful for multi-tenant applications where tenant identifiers must be included in requests, or when your API requires user-specific path parameters that can’t be discovered by smart crawling. ### Profile Authentication Methods Each profile provides credentials that work with the main authentication configuration. Profiles support three authentication methods: - **userNamePassword**: Provides `username` and `password` credentials that use the main authentication’s login flow (loginPath, type, etc.) - **external**: Provides pre-obtained authentication tokens (JWT tokens, API keys, or session cookies) via `authTokens` - **authScript**: References a custom authentication script defined in `hawkAddOn.scripts` for complex authentication flows The main `authentication` block defines how credentials are used (login endpoint, token extraction, authorization headers). Profiles simply provide different credentials for each user. For detailed authentication configuration, see [Authenticated Scanning](https://docs.stackhawk.com/hawkscan/authenticated-scanning/). ### OpenAPI Integration Multi-profile testing works best with an OpenAPI specification. When configured, HawkScan generates a smart crawl plan that: - Understands the structure of your API endpoints - Identifies resource relationships and parameter patterns - Enables more effective cross-profile access testing Configure your OpenAPI specification using `app.openApiConf`. See [OpenAPI Configuration](https://docs.stackhawk.com/hawkscan/configuration/openapi-configuration/) for setup instructions. ### Detected Vulnerabilities Multi-profile testing enables detection of: - **BOLA (Broken Object Level Authorization)**: When one user can read another user’s resources, such as accessing `/api/orders/{orderId}` for orders belonging to a different user. - **BFLA (Broken Function Level Authorization)**: When unprivileged users can perform privileged operations, such as a regular user accessing admin-only endpoints or performing administrative actions. These findings appear in your scan results alongside other vulnerabilities detected by HawkScan. ### Attributing Findings to a Profile When a scan runs with more than one authentication profile, each finding’s evidence is prefixed with the profile it was found under: ``` [profile=adminUser] ...evidence... ``` Findings are otherwise grouped by plugin, so without this prefix a vulnerability found as `regularUser` would be indistinguishable from the same vulnerability found as `adminUser`. The prefix is applied after secret redaction, and single-profile scans are unaffected. ### Choosing Scan Coverage Per Profile By default, configuring more than one authentication profile switches your scan to business-logic coverage: only the cross-profile BOLA and BFLA plugins run, against every profile. Your configured `policyName`, `includedPlugins`, and any organization-level policy are **not** applied in this mode. > **Note:** Before HawkScan 6.4.0 this was the only behavior available, and it applied silently. From 6.4.0 onward it remains the default, but `--profile-scan-mode` lets you choose. Use `--profile-scan-mode` (`PROFILE_SCAN_MODE`) to control the tradeoff between coverage and scan time: | Mode | Coverage | When to use it | | - | - | - | | `business-logic` *(default)* | Cross-profile BOLA/BFLA only, against every profile. | You are specifically hunting authorization flaws, and you run a separate single-profile scan for everything else. | | `primary-full` | Your full scan policy against one profile, BOLA/BFLA against the rest. | The common case — full vulnerability coverage plus authorization testing, without multiplying scan time by the number of profiles. | | `all-full` | Your full scan policy against every profile. | Your application exposes materially different functionality per role and you need each surface scanned in full. | With `primary-full`, choose which profile gets the full policy using `--full-scan-profile` (`FULL_SCAN_PROFILE`). If you omit it, the first profile declared in your configuration is used. ```shell hawk scan --profile-scan-mode=primary-full --full-scan-profile=adminUser ``` > **Warning:** Scan time grows with the number of profiles scanned in full. `all-full` against four profiles runs your entire policy four times. Start with `primary-full` and widen only if you need to. In `primary-full` and `all-full` modes, BOLA and BFLA are no longer added for you — plugins `422004` (Cross Platform BOLA) and `422005` (Cross Platform BFLA) run only if your own scan policy enables them. Enable them through [policy management](https://docs.stackhawk.com/platform/policy-management/) if you want authorization testing alongside full coverage. ### Best Practices For effective multi-profile testing: 1. **Use Descriptive Profile Names**: Names like `regularUser` and `adminUser` make scan results easier to interpret. 2. **Create Dedicated Test Accounts**: Use accounts specifically created for security testing, not shared or personal accounts. 3. **Include Role Diversity**: Configure profiles that represent different authorization levels in your application (regular users, managers, admins). 4. **Prepare Test Data**: Ensure your test environment has resources owned by each test user so cross-access attempts are meaningful. 5. **Use Environment Variables**: Store credentials in environment variables (e.g., `${USER_A_PASSWORD}`) rather than hardcoding them in your configuration file. ## Most Configuration For organizations requiring the deepest level of business logic testing, StackHawk’s custom scripting functionality provides complete flexibility to model your application’s specific workflows and business rules. Using the full power of the HawkScan Testing Engine (HSTE), you can create tailored test scripts that precisely match your system’s unique logic patterns, user roles, and authorization models. Custom scripts enable you to: - Define multi-step workflows that mirror real user interactions - Test complex authorization scenarios specific to your business domain - Validate state changes and data consistency across related endpoints - Model role-based access patterns unique to your application This approach requires investment in understanding both your application architecture and the HSTE scripting capabilities, but delivers the most comprehensive business logic vulnerability detection possible. For detailed guidance on implementing custom test scripts, see the [Scripting documentation](https://docs.stackhawk.com/scripting/).