Business logic scanning

Business logic scanning uses an AI agent to find vulnerabilities in how your application enforces its own rules. Pattern-based analyzers like SAST often miss these vulnerabilities, because the code is valid and only the intent is wrong.

What business logic scanning finds

Business logic scanning looks for vulnerabilities like:

• Broken object-level authorization (BOLA), also called insecure direct object references (IDOR). For example, an endpoint loads an invoice by the ID in the URL, and does not check that the invoice belongs to the authenticated user.
• Missing authorization. For example, an administrative action checks that the user is authenticated, but not that the user is an administrator.
• Mass assignment. For example, an update endpoint passes every request parameter to the model, so a user can change their own role or is_admin attribute.

How business logic scanning works

Business logic scanning runs as a GitLab Duo Agent Platform foundational flow, not as a job in your CI/CD pipeline. You do not add a template or a job to your .gitlab-ci.yml file.

A scan starts in one of these ways:

Turn on business logic scanning

Prerequisites:

• A GitLab Ultimate subscription.
• GitLab Duo Agent Platform turned on for the top-level group.
• The bl_security_analyzer feature flag enabled for the top-level group. To show results, the agentic_analyzer_security_ingestion feature flag must also be enabled for each project you scan. On GitLab Self-Managed, an administrator must enable these feature flags.

To turn on business logic scanning:

1. As a user with the Owner role for the top-level group, turn on foundational flows, including the Business Logic Security Scan flow.
2. Attach the business logic scan profile to each project you want to scan. Until the scan profile UI is available, attach the profile with the GraphQL API.

Automatic merge request scans

When a project has the business logic scan profile attached, a scan runs on each merge request:

• The scan runs on the merge request’s head pipeline: either a merge request pipeline or a branch pipeline of an open merge request.
• The scan starts after the pipeline succeeds. If the pipeline fails, or the project has no CI/CD pipelines, no scan runs.
• The scan checks only the files the merge request adds or modifies.
• The user who ran the pipeline must be a human user with at least the Developer role and access to GitLab Duo Agent Platform.

These merge requests are not scanned:

• Merge requests from a fork.
• Merge requests that only delete files.
• Merge requests whose pipeline was run by a bot, like a project access token or a service account.
• Merge train pipelines, and merge request pipelines that a newer commit has replaced.

Because a merge request scan checks only the changed files, it is a partial scan, like GitLab Advanced SAST diff-based scanning. Vulnerabilities in files that it did not scan are not reported as fixed.

Scheduled default-branch scans

Scheduled scans are not available yet. Automatic scans do not run on the default branch. To scan the default branch, start a scan from GitLab Duo Chat or with the API.

Start a scan from GitLab Duo Chat

To scan the whole repository, start a scan from GitLab Duo Chat. The scan checks the default branch, and runs as a GitLab Duo Agent Platform session that you can follow. Results appear in the vulnerability report.

Prerequisites:

• You must have at least the Developer role for the project.
• You must meet the GitLab Duo Agent Platform prerequisites.
• The bl_security_analyzer, agentic_analyzer_security_ingestion, and duo_chat_flow_commands feature flags must be enabled, and the Business Logic Security Scan flow must be turned on. The project does not need the business logic scan profile.

To start a scan:

1. In the top bar, select Search or go to and find your project.
2. Open GitLab Duo Chat and ensure the Agentic toggle is turned on.
3. In the chat text box, type /flow: and select Business Logic Security Scan.
4. Send the command without any other text.
5. Follow the scan in the agent session. When the session finishes, the results appear in the vulnerability report.

The scan’s CI/CD job runs as the flow’s service account.

Start a scan with the API

You can start a full scan of the default branch with the GitLab Duo Agent Platform flows API. The scan runs on your behalf, with your permissions and your GitLab Duo Agent Platform access, and checks the whole repository. Results appear in the vulnerability report.

Prerequisites:

• You must have at least the Developer role for the project.
• You must have a personal access token with the api scope.
• The bl_security_analyzer and agentic_analyzer_security_ingestion feature flags must be enabled, and the Business Logic Security Scan flow must be turned on. The project does not need the business logic scan profile.

To start a scan, send a request:

curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --data "project_id=<project_id>" \
  --data "workflow_definition=bl_security/experimental" \
  --data "start_workflow=true" \
  --url "https://gitlab.example.com/api/v4/ai/duo_workflows/workflows"

Instead of workflow_definition, you can pass ai_catalog_item_consumer_id with the ID of the project’s Business Logic Security Scan flow consumer. To get the ID, use the GraphQL aiCatalogConfiguredItems query, as described in look up the consumer ID.

To scan only the files a merge request changes, pass the merge request IID as the goal, and the merge request’s source branch as the source_branch. The merge request must not come from a fork. On any branch other than the default branch, the BL_TARGET_FILES CI/CD variable, when set, replaces the merge request’s changed files. Otherwise, the scan checks the whole repository.

View results

Business logic scanning reports vulnerabilities in the same places as other security scanners:

• In the merge request security widget, for merge request scans.
• In the vulnerability report, for scans of the default branch.

Configure a scan

To change how business logic scanning runs, add project CI/CD variables. Set the environment scope to All (default). Variables with other scopes are ignored.

Protected and file-type variables are ignored. Define these as regular, unprotected variables with the * environment scope.

The scan reads these variables from the project’s CI/CD settings when it starts. Variables set in .gitlab-ci.yml or when you run a pipeline do not apply.

Known issues

Business logic scanning has the following known issues:

• When a merge request changes more than 400 files, or its diff is too large to collect, the scan does not limit itself to the changed files. It runs a full scan of the repository instead, and the result is not a partial scan.
• A scan analyzes up to a fixed amount of code. A scan that reaches this limit still counts as a full scan. Vulnerabilities in code that the scan skipped can be marked as no longer detected, and reappear in a later scan.
• Scans run only when the feature flags in the prerequisites are enabled. Automatic scans run only for the users described in automatic merge request scans.
• Scheduled scans are not available yet. For details, see scheduled default-branch scans.
• A scan from GitLab Duo Chat always runs on the default branch. If you add a merge request number or other text after the flow command, the scan still checks the whole repository. It does not check the merge request’s changes. Send the command without any other text. To scan a merge request’s changes, use the API.

Cost

Each scan is a GitLab Duo Agent Platform session, and consumes GitLab Credits. A scan of a large merge request, or of a whole repository, uses more than a scan of a small change.