CI 트리거

코드를 푸시하거나 병합 요청(PR/MR)을 생성할 때 보안 스캔을 자동 실행하려면 CI 파이프라인에 스캔 트리거 단계를 추가합니다. 소스코드와 컨테이너 이미지가 같은 방식으로 연동됩니다. 시간 기반 정기 실행은 스캔 스케줄에서 설명합니다.

설정 위치 : 서비스 사이드바 [설정] > 자동화 > CI 트리거 탭
방식 : 파이프라인이 인바운드 웹훅을 호출(토큰 인증)
지원 유형 : 소스코드(Git), 컨테이너 이미지
지원 도구 : GitLab CI, GitHub Actions, Jenkins 등

CI 트리거 화면 — 서비스 설정의 CI 트리거 탭. 토큰을 발급하고 트리거를 활성화한 뒤, 파이프라인에 추가할 웹훅 스니펫을 확인합니다.

지원 유형

CI 트리거는 서비스별로 설정합니다. 서비스 유형에 따라 실행할 수 있는 스캔과 스캔 대상이 다릅니다.

서비스 유형	실행 가능한 스캔	스캔 대상
소스코드 (Git)	SAST, SCA, SBOM, IaC, Secret	등록 시 지정한 브랜치의 Git 소스(최신 커밋)
컨테이너 이미지	이미지 SCA, SBOM, 이미지 하드닝	레지스트리 이미지(지정 이미지 또는 최신 이미지 자동)

실제로 선택할 수 있는 스캔 종류는 해당 서비스에서 활성화한 분석으로 제한됩니다.

웹 서비스, 서버/호스트, SBOM 업로드, 바이너리 파일은 CI 대상이 아닙니다

웹 서비스, 서버 / 호스트, SBOM 업로드, 바이너리 파일은 CI 트리거를 지원하지 않습니다. 이 유형들은 각 분석 탭에서 수동 실행하거나 서비스의 스캔 스케줄로 주기 실행합니다.

설정 절차

서비스의 [설정] > 자동화 > CI 트리거 탭에서 진행합니다.

토큰 발급 : 인증 토큰을 발급합니다.
- 토큰은 발급 시 한 번만 표시되므로 즉시 복사합니다.
- 재발급하면 기존 토큰은 바로 무효화됩니다.
트리거 활성화 + 스캔 종류 선택 : 트리거를 활성화하고, 푸시 시 실행할 스캔 종류를 선택합니다. 컨테이너 이미지 유형은 스캔 대상 이미지를 다음 중 하나로 정합니다.
- 특정 이미지를 지정해 스캔합니다.
- 최신 이미지(자동) : CI 가 방금 빌드/푸시한 이미지를 매번 스캔합니다.
CI 비밀변수로 저장 : 발급한 토큰을 CI 도구의 비밀변수 VULINDER_CI_TOKEN 으로 등록합니다. 토큰을 코드에 평문으로 포함하지 마세요.
파이프라인에 스니펫 추가 : 아래 도구별 스니펫을 저장소에 추가합니다. CI 트리거 탭에는 서비스에 맞는 정확한 인바운드 웹훅 URL 과 스니펫이 함께 표시됩니다.
커밋/푸시 : 파이프라인이 실행되며 해당 단계에서 스캔이 자동으로 큐에 등록됩니다.

호출 규격

CI 트리거는 파이프라인 단계에서 인바운드 웹훅을 호출하는 방식입니다. 요청에는 서비스 ID 를 포함하지 않으며, 토큰으로 대상 서비스를 식별합니다.

메서드/주소 : POST <인바운드 웹훅 URL> (형식: .../api/v1/webhook/ci/scan). 정확한 주소는 CI 트리거 탭에 표시됩니다.
헤더 : X-CI-Token: <발급받은 토큰>
본문(JSON, 선택) : { "branch": "...", "commit": "..." }. 두 값을 보내도 스캔 대상은 바뀌지 않으며, 항상 등록 시 지정한 브랜치의 최신 상태를 스캔합니다.
응답(200) : { "queued": [...], "failed": [...] }. 큐에 등록된 스캔과 실패한 항목을 함께 반환합니다.

도구별 스니펫

토큰은 각 도구의 비밀변수(VULINDER_CI_TOKEN)로 참조하고, 아래 <인바운드 웹훅 URL> 은 CI 트리거 탭에 표시된 주소로 변경합니다.

GitLab CI

CI/CD 설정의 Variables 에 VULINDER_CI_TOKEN 을 (Masked) 변수로 등록한 뒤 .gitlab-ci.yml 에 추가합니다.

vulinder-security-scan:
  stage: test
  image: curlimages/curl:latest
  script:
    - >
      curl -fsS -X POST "<인바운드 웹훅 URL>"
      -H "X-CI-Token: $VULINDER_CI_TOKEN"
      -H "Content-Type: application/json"
      -d "{\"branch\":\"$CI_COMMIT_REF_NAME\",\"commit\":\"$CI_COMMIT_SHA\"}"

GitHub Actions

저장소 Settings 의 Secrets and variables > Actions 에 VULINDER_CI_TOKEN 을 등록한 뒤 .github/workflows/vulinder-security.yml 로 추가합니다.

name: Vulinder Security Scan
on: [push, pull_request]
jobs:
  trigger-scan:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Vulinder scan
        run: |
          curl -fsS -X POST "<인바운드 웹훅 URL>" \
            -H "X-CI-Token: ${{ secrets.VULINDER_CI_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d "{\"branch\":\"${{ github.ref_name }}\",\"commit\":\"${{ github.sha }}\"}"

Jenkins

Manage Jenkins 의 Credentials 에 VULINDER_CI_TOKEN 을 Secret text 자격증명으로 등록한 뒤 Jenkinsfile 에 추가합니다.

pipeline {
  agent any
  stages {
    stage('Vulinder Security Scan') {
      steps {
        withCredentials([string(credentialsId: 'VULINDER_CI_TOKEN', variable: 'VULINDER_CI_TOKEN')]) {
          sh '''
            curl -fsS -X POST "<인바운드 웹훅 URL>" \
              -H "X-CI-Token: $VULINDER_CI_TOKEN" \
              -H "Content-Type: application/json" \
              -d "{\"branch\":\"${GIT_BRANCH}\",\"commit\":\"${GIT_COMMIT}\"}"
          '''
        }
      }
    }
  }
}

동작과 제한

인증 실패(401) : 다음 경우 요청이 거부됩니다.
- 토큰이 없거나 올바르지 않은 경우
- 트리거가 비활성 상태인 경우. 토큰이 유효해도 인바운드 요청이 차단됩니다.
호출 빈도 제한 : 무효 토큰을 이용한 반복 요청을 방지하기 위해 IP 당 분당 30회로 제한합니다.
진행 중 스캔 상한 : 한 서비스에 진행 중인 스캔이 상한을 초과하면 요청이 일시적으로 거부됩니다(429). 이 경우 CI 에서 잠시 후 다시 시도합니다.
중복 요청 병합 : 같은 서비스에 동일한 스캔이 짧은 간격으로 중복 요청되면 자동으로 하나로 병합됩니다.
네이티브 저장소 웹훅 : 현재는 CI 파이프라인 연동 방식만 지원합니다. 저장소 Settings 의 네이티브 웹훅 연동은 준비 중입니다.

지원 유형​

설정 절차​

호출 규격​

도구별 스니펫​

GitLab CI​

GitHub Actions​

Jenkins​

동작과 제한​

관련 문서​