히스토리

• GitLab 19.5에서 bl_security_analyzer(experiment 유형)와 agentic_analyzer_security_ingestion(gitlab_com_derisk 유형)이라는 기능 플래그와 함께 도입되었습니다. 기본적으로 비활성화되어 있습니다.
• GitLab Duo Chat에서 스캔을 시작하려면 duo_chat_flow_commands(wip 유형)라는 기능 플래그도 필요합니다. 기본적으로 비활성화되어 있습니다.

비즈니스 로직 스캔은 AI 에이전트를 사용해 애플리케이션이 자체 규칙을 적용하는 방식의 취약점을 찾습니다. SAST와 같은 패턴 기반 분석기는 코드가 유효하고 의도만 잘못된 경우가 많아 이러한 취약점을 놓치는 경우가 많습니다.

비즈니스 로직 스캔이 찾는 항목#

비즈니스 로직 스캔은 다음과 같은 취약점을 찾습니다.

• 객체 수준 인가 결함(BOLA). 안전하지 않은 직접 객체 참조(IDOR)라고도 합니다. 예를 들어 엔드포인트가 URL의 ID로 송장을 불러오지만, 해당 송장이 인증된 사용자의 것인지 확인하지 않습니다.
• 인가 누락. 예를 들어 관리 작업에서 사용자가 인증되었는지는 확인하지만, 사용자가 관리자인지는 확인하지 않습니다.
• 대량 할당. 예를 들어 업데이트 엔드포인트가 모든 요청 파라미터를 모델에 전달하므로, 사용자가 자신의 role 또는 is_admin 속성을 변경할 수 있습니다.

비즈니스 로직 스캔의 동작 방식#

비즈니스 로직 스캔은 CI/CD 파이프라인의 job이 아니라 GitLab Duo Agent Platform 기반 플로로 실행됩니다. .gitlab-ci.yml 파일에 템플릿이나 job을 추가하지 않습니다.

스캔은 다음 방법 중 하나로 시작됩니다.

비즈니스 로직 스캔 켜기#

사전 요구 사항:

• GitLab Ultimate 구독.
• 최상위 그룹에 GitLab Duo Agent Platform이 켜져 있어야 합니다.
• 최상위 그룹에 bl_security_analyzer 및 agentic_analyzer_security_ingestion 기능 플래그가 활성화되어 있어야 합니다. agentic_analyzer_security_ingestion이 없으면 스캔 결과가 취약점 보고서에 표시되지 않습니다. GitLab Self-Managed에서는 관리자가 이 기능 플래그를 활성화해야 합니다.

비즈니스 로직 스캔을 켜는 방법은 다음과 같습니다.

1. 최상위 그룹에서 Owner 권한이 있는 사용자로 Business Logic Security Scan 플로를 포함해 기반 플로를 켭니다.
2. 스캔하려는 각 프로젝트에 비즈니스 로직 스캔 프로필을 연결합니다. 스캔 프로필 UI를 사용할 수 있기 전까지는 GraphQL API로 프로필을 연결합니다.

머지 리퀘스트 자동 스캔#

프로젝트에 비즈니스 로직 스캔 프로필이 연결되어 있으면 각 머지 리퀘스트에서 스캔이 실행됩니다.

• 스캔은 머지 리퀘스트의 헤드 파이프라인, 즉 머지 리퀘스트 파이프라인 또는 열려 있는 머지 리퀘스트의 브랜치 파이프라인에서 실행됩니다.
• 스캔은 파이프라인이 성공한 뒤에 시작됩니다. 파이프라인이 실패하거나 프로젝트에 CI/CD 파이프라인이 없으면 스캔이 실행되지 않습니다.
• 스캔은 머지 리퀘스트가 추가하거나 수정한 파일만 확인합니다.
• 파이프라인을 실행한 사용자는 Developer 이상의 권한이 있고 GitLab Duo Agent Platform에 접근할 수 있는 일반 사용자여야 합니다.

다음 머지 리퀘스트는 스캔되지 않습니다.

• 포크에서 온 머지 리퀘스트.
• 파일 삭제만 포함하는 머지 리퀘스트.
• 프로젝트 액세스 토큰이나 서비스 계정과 같은 봇이 파이프라인을 실행한 머지 리퀘스트.
• 머지 트레인 파이프라인과, 더 새로운 커밋으로 대체된 머지 리퀘스트 파이프라인.

머지 리퀘스트 스캔은 변경된 파일만 확인하므로 GitLab Advanced SAST의 diff 기반 스캔과 마찬가지로 부분 스캔입니다. 스캔하지 않은 파일의 취약점은 해결된 것으로 보고되지 않습니다.

기본 브랜치 예약 스캔#

예약 스캔은 아직 사용할 수 없습니다. 자동 스캔은 기본 브랜치에서 실행되지 않습니다. 기본 브랜치를 스캔하려면 GitLab Duo Chat에서 스캔을 시작하거나 API로 시작합니다.

GitLab Duo Chat에서 스캔 시작#

전체 리포지터리를 스캔하려면 GitLab Duo Chat에서 스캔을 시작합니다. 스캔은 기본 브랜치를 확인하며, 진행 상황을 따라갈 수 있는 GitLab Duo Agent Platform 세션으로 실행됩니다. 결과는 취약점 보고서에 표시됩니다.

사전 요구 사항:

• 프로젝트에서 Developer 이상의 권한이 있어야 합니다.
• GitLab Duo Agent Platform 사전 요구 사항을 충족해야 합니다.
• bl_security_analyzer, agentic_analyzer_security_ingestion, duo_chat_flow_commands 기능 플래그가 활성화되어 있고 Business Logic Security Scan 플로가 켜져 있어야 합니다. 프로젝트에 비즈니스 로직 스캔 프로필은 필요하지 않습니다.

스캔을 시작하는 방법은 다음과 같습니다.

1. 상단 표시줄에서 Search or go to를 선택하고 프로젝트를 찾습니다.
2. GitLab Duo Chat을 열고 Agentic 토글이 켜져 있는지 확인합니다.
3. 채팅 텍스트 상자에 /flow:를 입력하고 Business Logic Security Scan을 선택합니다.
4. 다른 텍스트 없이 명령을 보냅니다.
5. 에이전트 세션에서 스캔 진행 상황을 따라갑니다. 세션이 끝나면 결과가 취약점 보고서에 표시됩니다.

스캔의 CI/CD job은 플로의 서비스 계정으로 실행됩니다.

API로 스캔 시작#

GitLab Duo Agent Platform 플로 API로 기본 브랜치의 전체 스캔을 시작할 수 있습니다. 스캔은 사용자의 권한과 GitLab Duo Agent Platform 액세스로 사용자를 대신해 실행되며 전체 리포지터리를 확인합니다. 결과는 취약점 보고서에 표시됩니다.

사전 요구 사항:

• 프로젝트에서 Developer 이상의 권한이 있어야 합니다.
• api 스코프가 있는 개인 액세스 토큰이 있어야 합니다.
• bl_security_analyzer 및 agentic_analyzer_security_ingestion 기능 플래그가 활성화되어 있고 Business Logic Security Scan 플로가 켜져 있어야 합니다. 프로젝트에 비즈니스 로직 스캔 프로필은 필요하지 않습니다.

스캔을 시작하려면 요청을 보냅니다.

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"

workflow_definition 대신 프로젝트의 Business Logic Security Scan 플로 컨슈머 ID와 함께 ai_catalog_item_consumer_id를 전달할 수 있습니다. ID를 가져오려면 컨슈머 ID 조회에 설명된 대로 GraphQL aiCatalogConfiguredItems 쿼리를 사용합니다.

머지 리퀘스트가 변경한 파일만 스캔하려면 머지 리퀘스트 IID를 goal로, 머지 리퀘스트의 소스 브랜치를 source_branch로 전달합니다. 머지 리퀘스트는 포크에서 온 것이면 안 됩니다. 기본 브랜치가 아닌 브랜치에서는 BL_TARGET_FILES CI/CD 변수가 설정되어 있으면 머지 리퀘스트의 변경 파일을 대체합니다. 그렇지 않으면 스캔은 전체 리포지터리를 확인합니다.

결과 보기#

비즈니스 로직 스캔은 다른 보안 스캐너와 같은 위치에 취약점을 보고합니다.

• 머지 리퀘스트 스캔의 경우 머지 리퀘스트 보안 위젯.
• 기본 브랜치 스캔의 경우 취약점 보고서.

스캔 구성#

비즈니스 로직 스캔이 실행되는 방식을 변경하려면 프로젝트 CI/CD 변수를 추가합니다. 환경 스코프를 **All (default)**로 설정합니다. 다른 스코프의 변수는 무시됩니다.

보호된 변수와 파일 유형 변수는 무시됩니다. 이러한 값은 * 환경 스코프의 일반 비보호 변수로 정의합니다.

스캔은 시작할 때 프로젝트의 CI/CD 설정에서 이 변수를 읽습니다. .gitlab-ci.yml이나 파이프라인을 실행할 때 설정한 변수는 적용되지 않습니다.

알려진 문제#

비즈니스 로직 스캔에는 다음과 같은 알려진 문제가 있습니다.

• 머지 리퀘스트가 400개를 넘는 파일을 변경하거나 diff가 너무 커서 수집할 수 없으면 스캔이 변경된 파일로 범위를 제한하지 않습니다. 대신 리포지터리 전체 스캔을 실행하며, 결과는 부분 스캔이 아닙니다.
• 스캔은 정해진 양까지의 코드를 분석합니다. 이 한도에 도달한 스캔도 전체 스캔으로 계산됩니다. 스캔이 건너뛴 코드의 취약점은 더 이상 탐지되지 않는 것으로 표시되었다가 이후 스캔에서 다시 나타날 수 있습니다.
• 스캔은 사전 요구 사항의 기능 플래그가 활성화된 경우에만 실행됩니다. 자동 스캔은 머지 리퀘스트 자동 스캔에 설명한 사용자에게만 실행됩니다.
• 예약 스캔은 아직 사용할 수 없습니다. 자세한 내용은 기본 브랜치 예약 스캔을 참조합니다.
• GitLab Duo Chat에서 시작한 스캔은 항상 기본 브랜치에서 실행됩니다. 플로 명령 뒤에 머지 리퀘스트 번호나 다른 텍스트를 추가해도 스캔은 여전히 전체 리포지터리를 확인합니다. 머지 리퀘스트의 변경 사항은 확인하지 않습니다. 다른 텍스트 없이 명령을 보냅니다. 머지 리퀘스트의 변경 사항을 스캔하려면 API를 사용합니다.

비용#

각 스캔은 GitLab Duo Agent Platform 세션이며 GitLab Credits를 사용합니다. 큰 머지 리퀘스트나 전체 리포지터리를 스캔하면 작은 변경을 스캔할 때보다 더 많이 사용합니다.