분석기는 CI 파이프라인 컨텍스트 내에서 실행되는 Docker 이미지로 제공됩니다. 이 가이드는 분석기 전반에 걸친 개발 및 테스트 관행을 설명합니다.

공유 모듈#

공통 동작 및 인터페이스를 위해 분석기 간에 공유되는 여러 공유 Go 모듈이 있습니다:

• command Go 패키지는 CLI 인터페이스를 구현합니다.

• common 프로젝트는 로깅, 인증서 처리, 디렉터리 검색 기능을 위한 기타 공유 모듈을 제공합니다.

• report Go 패키지의 Report 및 Finding 구조체는 JSON 리포트를 마샬링합니다.

• template 프로젝트는 새 분석기의 스캐폴딩을 제공합니다.

분석기 사용 방법#

분석기는 Docker 이미지로 제공됩니다. 예를 들어, 작업 디렉터리를 스캔하기 위해 Semgrep Docker 이미지를 실행하려면:

• 스캔하려는 소스 코드의 디렉터리로 cd합니다.

• docker login registry.gitlab.com을 실행하고 최소 read_registry 범위를 가진 사용자 이름과 개인 또는 프로젝트 액세스 토큰을 제공합니다.

• Docker 이미지를 실행합니다:

docker run \
    --interactive --tty --rm \
    --volume "$PWD":/tmp/app \
    --env CI_PROJECT_DIR=/tmp/app \
    -w /tmp/app \
    registry.gitlab.com/gitlab-org/security-products/analyzers/semgrep:latest /analyzer run

• Docker 컨테이너는 마운트된 프로젝트 디렉터리에 분석기 카테고리에 해당하는 리포트 파일명으로 리포트를 생성합니다. 예를 들어, SAST는 gl-sast-report.json이라는 파일을 생성합니다.

분석기 개발#

분석기를 업데이트하려면:

• Go 소스 코드를 수정합니다.

• 새 Docker 이미지를 빌드합니다.

• 테스트 프로젝트에 대해 분석기를 실행합니다.

• 생성된 리포트를 예상 결과와 비교합니다.

analyzer라는 이름의 Docker 이미지를 생성하는 방법은 다음과 같습니다:

docker build -t analyzer .

예를 들어, 시크릿 탐지를 테스트하려면 다음을 실행합니다:

wget https://gitlab.com/gitlab-org/security-products/ci-templates/-/raw/master/scripts/compare_reports.sh
sh ./compare_reports.sh sd test/fixtures/gl-secret-detection-report.json test/expect/gl-secret-detection-report.json \
| patch -Np1 test/expect/gl-secret-detection-report.json && Git commit -m 'Update expectation' test/expect/gl-secret-detection-report.json
rm compare_reports.sh

자신의 환경에 맞게 바이너리를 컴파일하고 로컬에서 실행할 수도 있지만, 분석기의 런타임 의존성이 없기 때문에 analyze와 run은 작동하지 않을 수 있습니다.

다음은 SpotBugs를 기반으로 한 예시입니다:

go build -o analyzer
./analyzer search test/fixtures
./analyzer convert test/fixtures/app/spotbugsXml.Xml > ./gl-sast-report.json

Secure Stage CI/CD 템플릿 및 컴포넌트#

Secure Stage는 다음 CI/CD 템플릿 및 컴포넌트의 유지 관리를 담당합니다:

• Composition Analysis

CI/CD 템플릿

Dependency-Scanning.gitlab-ci.yml

• Dependency-Scanning.latest.gitlab-ci.yml

• Container-Scanning.gitlab-ci.yml

• Container-Scanning.latest.gitlab-ci.yml

• CI/CD 컴포넌트

종속성 스캐닝

• 컨테이너 스캐닝

• Static Analysis (SAST)

CI/CD 템플릿

SAST.gitlab-ci.yml

• SAST.latest.gitlab-ci.yml

• SAST-IaC.gitlab-ci.yml

• SAST-IaC.latest.gitlab-ci.yml

• CI/CD 컴포넌트

SAST

• Secret detection

CI/CD 템플릿

Secret-Detection.gitlab-ci.yml

• Secret-Detection.latest.gitlab-ci.yml

• CI/CD 컴포넌트

시크릿 탐지

변경 사항은 항상 그룹의 CI/CD 템플릿과 컴포넌트 모두에 적용되어야 하며, 해당 변경 사항을 최신 CI/CD 템플릿에도 적용해야 하는지 여부를 반드시 판단해야 합니다.

분석기는 오프라인 환경을 위한 Secure-Binaries.gitlab-ci.yml 파일에서도 참조됩니다. 변경 사항이 있을 때 이 파일도 동기화 상태를 유지하도록 하십시오.

실행 기준#

SAST 활성화에는 GitLab CI/CD 구성에 사전 정의된 템플릿 포함이 필요합니다.

다음 독립적인 기준에 따라 프로젝트에서 실행해야 할 분석기가 결정됩니다:

• SAST 템플릿은 rules:exists를 사용하여 특정 파일의 존재 여부에 따라 실행할 분석기를 결정합니다. 예를 들어, Brakeman 분석기는 .rb 파일과 Gemfile이 있을 때 실행됩니다.

• 각 분석기는 실제 분석을 수행하기 전에 사용자 정의 가능한 매치 인터페이스를 실행합니다. 예를 들어: Flawfinder는 C/C++ 파일을 확인합니다.

• 일반 파일 확장자에서 실행되는 일부 분석기의 경우 CI/CD 변수를 기반으로 한 확인이 있습니다. 예를 들어: Kubernetes 매니페스트는 YAML로 작성되므로, Kubesec은 SCAN_KUBERNETES_MANIFESTS가 true로 설정된 경우에만 실행됩니다.

1단계는 프로젝트에 적합하지 않은 분석기를 실행하는 데 낭비되는 컴퓨팅 할당량을 방지하는 데 도움이 됩니다. 그러나 기술적 한계로 인해 대규모 프로젝트에서는 사용할 수 없습니다. 따라서 2단계는 불일치하는 분석기가 조기에 종료될 수 있도록 최종 확인 역할을 합니다.

분석기 테스트 방법#

종속성 스캐닝 분석기가 테스트 프로젝트를 사용하여 분석기를 테스트하기 위해 다운스트림 파이프라인 기능을 어떻게 사용하는지에 대한 동영상 안내:

Sec가 분석기를 엔드 투 엔드로 테스트하기 위해 GitLab의 다운스트림 파이프라인 기능을 활용하는 방법

로컬 변경 사항 테스트#

분석기의 공유 모듈(예: command 또는 report)에서 로컬 변경 사항을 테스트하려면 go mod replace 지시문을 사용하여 원격으로 태그된 command 버전 대신 로컬 변경 사항이 반영된 command를 로드할 수 있습니다. 예를 들어:

go mod edit -replace gitlab.com/gitlab-org/security-products/analyzers/command/v3=/local/path/to/command

또는 go.mod 파일을 직접 업데이트하여 동일한 결과를 얻을 수 있습니다:

module gitlab.com/gitlab-org/security-products/analyzers/awesome-analyzer/v2

replace gitlab.com/gitlab-org/security-products/analyzers/command/v3 => /path/to/command

require (
    ...
    gitlab.com/gitlab-org/security-products/analyzers/command/v3 v2.19.0
)

Docker에서 로컬 변경 사항 테스트#

go.mod 파일의 replace와 함께 Docker를 사용하려면:

• command의 내용을 분석기 디렉터리에 복사합니다. cp -r /path/to/command path/to/analyzer/command.

• 분석기의 Dockerfile에 복사 명령문을 추가합니다: COPY command /command.

• replace 명령문을 업데이트하여 위 단계에서 COPY 명령문의 대상과 일치하도록 합니다: replace gitlab.com/gitlab-org/security-products/analyzers/command/v3 => /command

컨테이너 오케스트레이션 호환성 테스트#

사용자는 containerd, Podman, 또는 skopeo와 같은 Docker 이외의 도구를 사용하여 컨테이너를 오케스트레이션하고 분석기를 실행할 수 있습니다. 이러한 도구와의 호환성을 보장하기 위해, 정기적으로 예약된 파이프라인을 사용하여 모든 분석기를 테스트합니다. 테스트가 실패하면 Slack 알림이 발송됩니다.

분석기 Docker 이미지를 빌드할 때 호환성 문제를 방지하려면 기본 Docker 독점 미디어 타입 대신 OCI 미디어 타입을 사용하십시오.

정기적인 테스트 외에도 ci-templates 리포지터리의 사용자를 위한 호환성을 보장합니다:

• ci-templates docker-test.yml 템플릿을 사용하는 분석기는 tests를 포함하여 Docker 이미지가 지원되는 Docker 도구와 올바르게 작동하는지 확인합니다.

이러한 테스트는 머지 리퀘스트 파이프라인 및 예약된 파이프라인에서 실행되며, 이미지가 지원되는 Docker 도구를 손상시킬 경우 릴리스를 방지합니다.

• ci-templates docker.yml 템플릿은 분석기 이미지를 빌드할 때 docker buildx 명령에 oci-mediatypes=true를 지정합니다. 이는 Docker 독점 미디어 타입이 아닌 OCI 미디어 타입을 사용하여 이미지를 빌드합니다.

새 분석기를 생성하거나 기존 분석기 이미지의 위치를 변경할 때, 정기 테스트에 추가하거나 자동화된 테스트가 포함된 공유 ci-templates를 사용하는 것을 고려하십시오.

분석기 스크립트#

analyzer-scripts 리포지터리에는 대부분의 분석기와 상호 작용하는 데 사용할 수 있는 스크립트가 포함되어 있습니다. 이 스크립트를 사용하면 GitLab CI와 유사한 환경에서 분석기를 빌드, 실행, 디버그할 수 있으며, 분석기의 변경 사항을 로컬에서 검증하는 데 특히 유용합니다.

자세한 내용은 프로젝트 README를 참조하십시오.

버전 관리 및 릴리스 프로세스#

GitLab Security Products는 GitLab MAJOR.MINOR와 독립적인 버전 관리 시스템을 사용합니다. 모든 제품은 시맨틱 버전 관리(Semantic Versioning)의 변형을 사용하며 Docker 이미지로 제공됩니다.

Major는 호환성이 깨지는 변경이 허용되는 GitLab의 새로운 메이저 릴리스마다 증가합니다. Minor는 새로운 기능에 대해 증가하며, Patch는 버그 수정을 위해 예약되어 있습니다.

분석기는 다음 방식을 따라 Docker 이미지로 릴리스됩니다:

• 기본 브랜치에 푸시될 때마다 edge 이미지 태그가 재정의됩니다

• awesome-feature 브랜치에 푸시될 때마다 해당하는 awesome-feature 이미지 태그가 생성됩니다

• 각 Git 태그는 해당하는 Major.Minor.Patch 이미지 태그를 생성합니다. 수동 job을 통해 해당 Major 및 latest 이미지 태그를 이 Major.Minor.Patch를 가리키도록 재정의할 수 있습니다.

대부분의 경우 MAJOR 이미지에 의존하는 것이 좋습니다. MAJOR 이미지는 도구에 대한 최신 권고 사항이나 패치로 자동으로 업데이트됩니다. 포함된 CI 템플릿은 메이저 버전에 고정되어 있지만, 원하는 경우 사용자가 버전을 직접 재정의할 수 있습니다.

새 분석기 Docker 이미지를 릴리스하는 두 가지 옵션이 있습니다:

• 수동 릴리스 프로세스

• 자동 릴리스 프로세스

다음 다이어그램은 새 분석기 버전이 릴리스될 때 생성되는 Docker 태그를 설명합니다:

graph LR

A1[git tag v1.1.0]--> B1(run CI pipeline) B1 -->|build and tag patch| D1[1.1.0] B1 -->|tag minor| E1[1.1] B1 -->|retag major| F1[1] B1 -->|retag latest| G1[latest]

A2[git tag v1.1.1]--> B2(run CI pipeline) B2 -->|build and tag patch| D2[1.1.1] B2 -->|retag minor| E2[1.1] B2 -->|retag major| F2[1] B2 -->|retag latest| G2[latest]

A3[push to default branch]--> B3(run CI pipeline) B3 -->|build and tag edge| D3[edge]

지속적 배포 흐름에 따라, GitLab Rails 애플리케이션에 대응 요소가 없는 새로운 컴포넌트의 경우 언제든지 릴리스할 수 있습니다. 컴포넌트가 기존 애플리케이션과 통합되기 전까지, 반복 작업이 표준 릴리스 주기 및 프로세스에 의해 차단되어서는 안 됩니다.

수동 릴리스 프로세스#

• 새 분석기에 대한 CHANGELOG.md 항목이 올바른지 확인합니다.

• 릴리스 소스(일반적으로 master 또는 main 브랜치)의 파이프라인이 통과 상태인지 확인합니다.

• 프로젝트 창의 왼쪽에 있는 Deployments 메뉴를 선택한 다음 Releases 하위 메뉴를 선택하여 분석기 프로젝트의 새 릴리스를 생성합니다.

• New release를 선택하여 New Release 페이지를 엽니다.

Tag name 드롭다운에서 CHANGELOG.md에 사용된 버전(예: v2.4.2)을 입력하고, 태그를 생성하는 옵션(여기서는 Create tag v2.4.2)을 선택합니다.

• Release title 텍스트 박스에 위에서 사용한 것과 동일한 버전(예: v2.4.2)을 입력합니다.

• Release notes 텍스트 박스에 CHANGELOG.md의 해당 버전에 있는 내용을 복사하여 붙여넣습니다.

• 다른 모든 설정은 기본값으로 유지합니다.

• Create release를 선택합니다.

위 프로세스를 따르고 새 릴리스를 생성하면, 위에서 제공한 Tag name으로 새 Git 태그가 생성됩니다. 이는 주어진 태그 버전으로 새 파이프라인을 트리거하고 새 분석기 Docker 이미지가 빌드됩니다.

분석기가 analyzer.yml 템플릿을 사용하는 경우, 위의 New release 프로세스의 일부로 트리거된 파이프라인이 자동으로 새 버전의 분석기 Docker 이미지에 태그를 지정하고 배포합니다.

분석기가 analyzer.yml 템플릿을 사용하지 않는 경우, 새 버전의 분석기 Docker 이미지에 수동으로 태그를 지정하고 배포해야 합니다:

• 프로젝트 창의 왼쪽에 있는 CI/CD 메뉴를 선택한 다음 Pipelines 하위 메뉴를 선택합니다.

• 이전에 사용한 것과 동일한 태그(예: v2.4.2)로 새 파이프라인이 현재 실행 중이어야 합니다.

• 파이프라인이 완료되면 blocked 상태가 됩니다.

• 창의 오른쪽에 있는 Manual job 재생 버튼을 선택하고 tag version을 선택하여 새 버전의 분석기 Docker 이미지에 태그를 지정하고 배포합니다.

릴리스 job을 트리거할 Git 태그를 언제 생성할지는 최선의 판단으로 결정하십시오. 결정하기 어렵다면 다른 사람들의 의견을 구하십시오.

자동 릴리스 프로세스#

자동 릴리스 프로세스를 사용하기 전에 다음을 수행해야 합니다:

• CI/CD 환경 변수로 CREATE_GIT_TAG: true를 구성합니다.

• CI/CD 프로젝트 설정에서 Variables를 확인합니다:

프로젝트가 gitlab-org/security-products/analyzers 네임스페이스 아래에 있는 경우, GITLAB_TOKEN 환경 변수를 자동으로 상속하므로 추가 작업이 필요하지 않습니다.

• 프로젝트가 gitlab-org/security-products/analyzers 네임스페이스 아래에 있지 않은 경우, 새로운 마스킹 및 숨김 GITLAB_TOKEN CI/CD 환경 변수를 생성하고 그 값을 아래 자동 릴리스 프로세스에 사용되는 서비스 계정 섹션에 설명된 @gl-service-dev-secure-analyzers-automation 계정의 Personal Access Token으로 설정해야 합니다.

위 단계가 완료되면 자동 릴리스 프로세스가 다음과 같이 실행됩니다:

• 프로젝트 관리자가 MR을 기본 브랜치에 머지합니다.

• 기본 파이프라인이 트리거되고 upsert git tag job이 실행됩니다.

CHANGELOG.md의 가장 최근 버전이 Git 태그 중 하나와 일치하는 경우, 이 job은 아무 작업도 수행하지 않습니다.

• 그렇지 않으면 이 job은 releases API를 사용하여 새 릴리스 및 Git 태그를 자동으로 생성합니다. 버전과 메시지는 프로젝트의 CHANGELOG.md 파일에서 가장 최근 항목으로부터 가져옵니다.

• 새 Git 태그에 대해 파이프라인이 자동으로 트리거됩니다. 이 파이프라인은 분석기의 latest, major, minor, patch Docker 이미지를 릴리스합니다.

자동 릴리스 프로세스에 사용되는 서비스 계정#

서비스 계정의 액세스 토큰 범위 또는 GITLAB_TOKEN 변수 권한에 대한 변경 사항은 섹션의 Slack 채널에 공지해야 합니다.

서비스 계정의 토큰 교체#

@gl-service-dev-secure-analyzers-automation 서비스 계정의 GITLAB_TOKEN은 위에 나열된 Expiry Date전에 다음 절차에 따라 반드시 교체해야 합니다:

• gl-service-dev-secure-analyzers-automation 사용자로 로그인합니다.

이 계정의 자격 증명을 보유한 관리자 목록은 서비스 계정 액세스 요청에서 확인할 수 있습니다.

관리자는 공유 GitLab 1password 보관소에서 로그인 자격 증명을 찾을 수 있습니다.

• gl-service-dev-secure-analyzers-automation 서비스 계정에 대해 api 범위를 가진 새 Personal Access Token을 생성합니다.

• 공유 GitLab 1password 보관소에서 GitLab API Token - gl-service-dev-secure-analyzers-automation 계정의 password 필드를 2단계에서 생성한 새 Personal Access Token으로 업데이트하고, 토큰이 만료되는 시점을 나타내도록 Expires at 필드를 설정합니다.

• 자동 릴리스 프로세스에 사용되는 서비스 계정 테이블에서 GITLAB_TOKEN 필드의 만료 날짜를 업데이트합니다.

• 위의 2단계에서 생성한 새 Personal Access Token으로 다음 변수를 설정합니다:

  다음 변수는 반드시 마스킹 및 숨김 처리해야 합니다.

각주:

이 프로젝트에 대해 GITLAB_TOKEN을 명시적으로 설정하는 것은 포스트-분석기 프로젝트를 analyzers 네임스페이스로 이동 (#582004)이 완료된 후 제거할 수 있습니다.

• ci-templates 프로젝트는 upsert git tag job이 새 릴리스를 생성할 수 있도록 GITLAB_TOKEN이 필요합니다.

교체가 필요한 다른 토큰#

분석기 릴리스 후 수행할 단계#

• 새 버전의 분석기 Docker 이미지가 태그되고 배포된 후, 해당 테스트 프로젝트로 테스트합니다.

• 관련 그룹 Slack 채널에 릴리스를 공지합니다. 예시 메시지:

FYI I've just released ANALYZER_NAME ANALYZER_VERSION. LINK_TO_RELEASE

푸시된 Git 태그는 절대 삭제하지 마십시오. Go 패키지 레지스트리에서 해당 태그가 사용되고/또는 캐시될 가능성이 높습니다.

중요 수정 사항 또는 패치 백포팅#

이전 버전에 중요한 수정 사항 또는 패치를 백포팅하려면 아래 단계를 따르십시오.

• 수정 사항을 백포팅하려는 태그에서 새 브랜치를 생성합니다(아직 없는 경우).

예를 들어, 최신 안정 태그가 v4이고 v3에 수정 사항을 백포팅하는 경우 v3이라는 새 브랜치를 생성합니다.

• 방금 생성한 브랜치를 타깃으로 하는 머지 리퀘스트를 제출합니다.

• 승인되면 머지 리퀘스트를 해당 브랜치에 머지합니다.

• 브랜치에 대한 새 태그를 생성합니다.

• 분석기에 자동 릴리스 프로세스가 활성화된 경우 새 버전이 릴리스됩니다.

• 그렇지 않은 경우 수동 릴리스 프로세스를 따라 새 버전을 릴리스해야 합니다.

• 참고: 릴리스 파이프라인은 최신 edge 태그를 재정의하므로 해당 태그의 회귀를 방지하기 위해 가장 최근 릴리스 파이프라인의 tag edge job을 다시 실행해야 할 수 있습니다.

메이저 버전 릴리스를 위한 분석기 준비#

이 프로세스는 다음 그룹에 적용됩니다:

• Composition Analysis

• Static Analysis

• Secret Detection

다른 그룹은 자체적인 메이저 버전 릴리스 프로세스를 문서화할 책임이 있습니다.

메이저 버전 릴리스에 호환성이 깨지는 변경 사항이 포함되어 있는지 여부에 따라 다음 시나리오 중 하나를 선택합니다:

• 호환성이 깨지는 변경 없는 메이저 버전 릴리스

• 호환성이 깨지는 변경이 있는 메이저 버전 릴리스

호환성이 깨지는 변경 없는 메이저 버전 릴리스#

현재 분석기 릴리스가 v{N}이라고 가정합니다:

• 보호된 태그 및 브랜치 구성.

• 메이저 릴리스의 마일스톤 동안 default 브랜치에 더 이상 머지할 변경 사항이 없을 때:

default 브랜치에서 v{N} 브랜치를 생성합니다.

• CHANGELOG.md 파일에 다음 변경 사항만 포함하는 새 머지 리퀘스트를 default 브랜치에 생성하고 머지합니다:

## v{N+1}.0.0
- Major version release (!)

• 예약된 파이프라인 구성.

• CI/CD 템플릿 및 컴포넌트에서 메이저 분석기 버전 업그레이드

호환성이 깨지는 변경이 있는 메이저 버전 릴리스#

현재 분석기 릴리스가 v{N}이라고 가정합니다:

• 보호된 태그 및 브랜치 구성.

• 호환성이 깨지는 변경 사항을 "스테이징"하기 위한 새 브랜치 v{N+1}을 생성합니다.

• 메이저 릴리스 마일스톤에 이르는 마일스톤 동안:

호환성이 깨지지 않는 변경 사항을 default 브랜치(즉, master 또는 main)에 머지합니다

• 호환성이 깨지는 변경 사항을 v{N+1} 브랜치에 머지하고, 각 변경에 대해 CHANGELOG.md 파일에 별도의 release candidate 항목을 생성합니다:

## v{N+1}.0.0-rc.0
- some breaking change (!123)

release candidates를 사용하면 semver 가이드라인에 따라 메이저 버전 업데이트에서만 호환성이 깨지는 변경 사항을 적용하는 원칙을 준수하면서 모든 호환성이 깨지는 변경 사항을 단일 메이저 버전 업그레이드로 릴리스할 수 있습니다.

• 메이저 릴리스의 마일스톤 동안 default 또는 v{N+1} 브랜치에 더 이상 머지할 변경 사항이 없을 때:

default 브랜치에서 v{N} 브랜치를 생성합니다.

• v{N+1} 브랜치에서 모든 release candidate 체인지로그 항목을 v{N+1}의 단일 항목으로 통합하는 머지 리퀘스트를 생성합니다.

예를 들어, CHANGELOG.md에 v{N+1} 버전에 대한 다음과 같은 3개의 release candidate 항목이 포함되어 있는 경우:

## v{N+1}.0.0-rc.2
- yet another breaking change (!125)

## v{N+1}.0.0-rc.1
- another breaking change (!124)

## v{N+1}.0.0-rc.0
- some breaking change (!123)

그러면 새 머지 리퀘스트는 모든 release candidate 항목을 단일 항목으로 결합하여 CHANGELOG.md를 v{N+1}의 단일 메이저 릴리스로 업데이트해야 합니다:

## v{N+1}.0.0
- yet another breaking change (!125)
- another breaking change (!124)
- some breaking change (!123)

• v{N+1} 브랜치의 모든 호환성이 깨지는 변경 사항을 default 브랜치에 머지하는 머지 리퀘스트를 생성합니다.

• default 브랜치에 이제 v{N+1} 브랜치의 모든 변경 사항이 포함되므로 v{N+1} 브랜치를 삭제합니다.

• 예약된 파이프라인 구성.

• CI/CD 템플릿 및 컴포넌트에서 메이저 분석기 버전 업그레이드.

보호된 태그 및 브랜치 구성#

• 프로젝트에 대해 와일드카드 v*가 보호된 태그 및 보호된 브랜치 모두로 설정되어 있는지 확인합니다.

• gl-service-dev-secure-analyzers-automation 서비스 계정이 보호된 태그를 Allowed to create로 설정되어 있는지 확인합니다.

자세한 내용은 공식 지원 이미지 섹션의 3.1 단계를 참조하십시오.

예약된 파이프라인 구성#

• 세 개의 예약된 파이프라인이 존재하는지 확인하고, 필요한 경우 생성하며, 모든 파이프라인에 PUBLISH_IMAGES: true를 설정합니다:

Republish images v{N} (v{N} 브랜치 대상)

이 예약된 파이프라인은 새로 생성해야 합니다

• Daily build (default 브랜치 대상)

이 예약된 파이프라인은 이미 존재해야 합니다

• Republish images v{N-1} (v{N-1} 브랜치 대상)

이 예약된 파이프라인은 이미 존재해야 합니다

• v{N-2} 브랜치에 대한 예약된 파이프라인이 존재하는 경우 삭제합니다(두 개의 이전 메이저 버전만 지원).

CI/CD 템플릿 및 컴포넌트에서 메이저 분석기 버전 업그레이드#

모든 v{N+1} 분석기의 이미지가 registry.gitlab.com/security-products/:에서 사용 가능하게 되면, 그룹에 속하는 Secure Stage CI/CD 템플릿 및 컴포넌트에서 각 분석기의 메이저 버전을 업그레이드하는 새 머지 리퀘스트를 생성합니다.

새 분석기 개발#

새로운 프레임워크와 도구를 지원하기 위해 새 분석기 프로젝트를 구축해야 하는 경우가 있습니다. 이 경우 라이선스 및 코드 표준을 포함하여 엔지니어링 오픈 소스 가이드라인을 따라야 합니다.

또한 GitLab 애플리케이션에 통합될 사용자 정의 분석기를 작성하려면 최소한의 기능 세트가 필요합니다:

체크리스트#

기본 도구가 다음 항목을 갖추고 있는지 확인합니다:

• 허용적 소프트웨어 라이선스.

• 헤드리스 실행(CLI 도구).

• GitLab Runner의 Linux 또는 Windows Docker 실행기를 사용하여 실행되도록 Docker 이미지로 패키징할 수 있는 번들 가능한 의존성.

• 파일 이름 또는 확장자를 기반으로 탐지할 수 있는 호환 가능한 프로젝트.

• 오프라인 실행(인터넷 액세스 없음) 또는 사용자 정의 프록시 및/또는 CA 인증서를 사용하도록 구성 가능.

• 이미지가 다른 컨테이너 오케스트레이션 도구와 호환됩니다(컨테이너 오케스트레이션 호환성 테스트 참조).

Dockerfile#

Dockerfile은 GitLab이라는 이름의 비권한 사용자를 사용해야 합니다. 이는 컨테이너가 관리자(root) 사용자로 실행되는 것을 허용하지 않는 Red Hat OpenShift 인스턴스와의 호환성을 제공하기 위해 필요합니다. 비권한 사용자로 컨테이너를 실행할 때 염두에 두어야 할 특정 제한 사항이 있습니다. 예를 들어 Docker 파일시스템에 쓰여야 하는 파일에는 GitLab 사용자에 대한 적절한 권한이 필요합니다. 자세한 내용은 다음 머지 리퀘스트를 참조하십시오: Docker 이미지에서 root 대신 GitLab 사용자 사용.

최소 취약점 데이터#

필수 필드의 전체 목록은 security-report-schemas를 참조하십시오.

security-report-schema 리포지터리에는 각 리포트 유형에 대한 필수 필드를 나열하는 JSON 스키마가 포함되어 있습니다:

• 컨테이너 스캐닝

• DAST

• 종속성 스캐닝

• SAST

• 시크릿 탐지

리포트 스키마와의 호환성#

GitLab에 아티팩트로 업로드된 보안 리포트는 수집되기 전에 검증됩니다.

보안 리포트 스키마는 SchemaVer(MODEL-REVISION-ADDITION)를 사용하여 버전 관리됩니다. Sec 섹션은 security-report-schemas 프로젝트와 GitLab 및 스키마 버전의 호환성을 담당합니다. 스키마 변경 사항은 제품 전체의 지원 중단 가이드라인을 따라야 합니다.

새 MODEL 버전이 도입될 때 새 스키마를 채택하는 분석기는 이 새 스키마 버전을 공급하지 않는 GitLab 배포가 오류나 경고 없이 보안 리포트를 계속 수집할 수 있도록 보장할 책임이 있습니다.

이는 여러 방법으로 달성할 수 있습니다:

• 분석기에서 여러 스키마 버전에 대한 지원을 구현합니다. GitLab 버전을 기반으로 분석기는 GitLab에서 지원하는 최신 스키마 버전을 사용하여 보안 리포트를 내보냅니다.

장점: 분석기가 런타임에 사용할 최선의 버전을 결정할 수 있습니다.

• 단점: 구현 노력과 복잡성 증가.

• 새 분석기 메이저 버전을 릴리스합니다. 최신 MODEL 스키마 버전을 공급하지 않는 인스턴스는 MODEL-1 버전을 사용하여 리포트를 내보내는 분석기 버전을 계속 사용합니다.

장점: 분석기 코드를 단순하게 유지합니다.

• 단점: 유지 관리해야 할 추가 분석기 버전이 생깁니다.

• 새 스키마 사용을 지연합니다. 이는 스키마에 없는 속성을 리포트에 포함할 수 있는 additionalProperties=true에 의존합니다. 새 분석기 메이저 버전은 일반적인 케이던스로 릴리스됩니다.

장점: 유지 관리할 추가 분석기 없이 분석기 코드를 단순하게 유지합니다.

• 단점: 스키마 검증 없이 발생하는 위험 증가 및/또는 위험 완화를 위한 노력 증가.

어떤 경로를 따를지 확실하지 않은 경우 security-report-schemas 관리자에게 문의하십시오.

컨테이너 이미지의 위치#

보안 분석기용 컨테이너 이미지는 두 곳에 게시됩니다:

• registry.gitlab.com/security-products 네임스페이스의 공식 지원 이미지, 예를 들어:

registry.gitlab.com/security-products/semgrep:5

• 프로젝트 네임스페이스의 임시 개발 이미지, 예를 들어:

registry.gitlab.com/gitlab-org/security-products/analyzers/semgrep/tmp:d27d44a9b33cacff0c54870a40515ec5f2698475

공식 지원 이미지#

보안 템플릿에서 참조하는 공식 지원 이미지의 위치는 다음과 같습니다:

registry.gitlab.com/security-products/:

예를 들어, SAST.gitlab-ci.yml 템플릿의 semgrep-sast job은 컨테이너 이미지 registry.gitlab.com/security-products/semgrep:5를 참조합니다.

이 위치에 이미지를 푸시하려면:

• https://gitlab.com/security-products/에 새 프로젝트를 생성합니다.

예를 들어: https://gitlab.com/security-products/semgrep

이 프로젝트의 이미지는 registry.gitlab.com/security-products/:에 게시됩니다.

예를 들어: registry.gitlab.com/security-products/semgrep:5

• https://gitlab.com/security-products/ 프로젝트를 다음과 같이 구성합니다:

다음 권한을 추가합니다:

Maintainer: @gitlab-org/secure/managers

• Developer: @gl-service-dev-secure-analyzers-automation

이는 자동 릴리스 프로세스에 사용되는 서비스 계정이 registry.gitlab.com/security-products/:에 이미지를 푸시할 수 있도록 하기 위해 필요합니다.

• 다음 프로젝트 설정을 구성합니다:

Settings -> Packages and registries

Protected container image tags

보호된 컨테이너 이미지 태그가 없는지 확인합니다. 설정에 다음과 같이 표시되어야 합니다: No container image tags are protected.

이 설정의 근거를 설명하는 이 댓글을 참조하십시오.

• Settings -> General -> Visibility, project features, permissions

Project visibility

Public

• Additional options

Users can request access

Disabled

• Issues

Disabled

• Repository

Only Project Members

• Merge Requests

Disabled

• Forks

Disabled

• Git Large File Storage (LFS)

Disabled

• CI/CD

Disabled

• Container Registry

Everyone with access

• Analytics, Requirements, Security and compliance, Wiki, Snippets, Package registry, Model experiments, Model registry, Pages, Monitor, Environments, Feature flags, Infrastructure, Releases, GitLab Duo

Disabled

• https://gitlab.com/gitlab-org/security-products/analyzers/에 있는 분석기 프로젝트에 대해 다음 옵션을 구성합니다:

와일드카드 v*를 보호된 태그로 추가합니다.

gl-service-dev-secure-analyzers-automation 서비스 계정이 보호된 태그를 생성하도록 허용된 계정 목록에 명시적으로 추가되어 있는지 확인합니다. 이는 upsert git tag job이 분석기 프로젝트에 대한 새 릴리스를 생성할 수 있도록 하기 위해 필요합니다.

• 와일드카드 v*를 보호된 브랜치로 추가합니다.

• CI/CD 환경 변수

  SEC_REGISTRY_PASSWORD 변수는 반드시 마스킹 및 숨김 처리해야 합니다.

위 변수는 ci-templates 프로젝트의 tag_image.sh 스크립트에서 컨테이너 이미지를 registry.gitlab.com/security-products/:에 푸시하는 데 사용됩니다.

예시는 semgrep CI/CD Variables를 참조하십시오.

임시 개발 이미지#

임시 개발 이미지의 위치는 다음과 같습니다:

registry.gitlab.com/gitlab-org/security-products/analyzers//tmp:

예를 들어, semgrep 분석기의 개발 이미지 중 하나는 다음과 같습니다:

registry.gitlab.com/gitlab-org/security-products/analyzers/semgrep/tmp:7580d6b037d93646774de601be5f39c46707bf04

컨테이너 레지스트리에 쓰기 액세스 권한이 있는 사람 수를 제한하기 위해, 개발 프로젝트의 컨테이너 레지스트리는 https://gitlab.com/gitlab-org/security-products/analyzers/에 있는 프로젝트에 대해 다음 프로젝트 기능 및 권한 설정을 구성하여 비공개로 설정해야 합니다:

• Settings -> General -> Visibility, project features, permissions

Container Registry

Only Project Members

Sec 섹션의 각 그룹은 다음 사항에 대한 책임이 있습니다:

• 아티팩트의 지원 중단 및 제거 일정 관리와 이를 위한 이슈 생성.

• 새 위치에 프로젝트 생성 및 구성.

• 릴리스 아티팩트를 새 위치로 푸시하도록 빌드 구성.

• 각자의 지원 계약에 따라 이전 위치의 이미지 제거 또는 유지.

컨테이너 이미지 일일 재빌드#

분석기 이미지는 의존하는 베이스 이미지의 벤더가 제공하는 패치를 자주 자동으로 가져오기 위해 매일 재빌드됩니다.

이 프로세스는 현재 MAJOR 릴리스와 일치하는 GitLab 버전에서 사용되는 이미지에만 적용됩니다. 매일 새 버전을 릴리스하는 것이 아니라 이미지의 각 활성 변형을 재빌드하고 해당 태그를 덮어쓰는 것이 목적입니다:

• MAJOR.MINOR.PATCH 이미지 태그 (예: 4.1.7)

• MAJOR.MINOR 이미지 태그 (예: 4.1)

• MAJOR 이미지 태그 (예: 4)

• latest 이미지 태그

재빌드 프로세스의 구현은 프로젝트에 따라 다를 수 있지만, 공유 CI 구성이 개발 ci-templates 프로젝트에서 이를 달성하는 데 도움이 되도록 제공됩니다.

GitLab Advanced SAST(GLAS)에 새 언어 지원 추가#

이 가이드는 엔지니어가 GLAS에 새 언어 지원을 평가하고 추가하는 데 도움이 됩니다. 이 가이드라인은 엄격한 요구 사항이 아니라 언어 지원을 확장할 때 일관된 품질을 보장하기 위한 것입니다.

언어 지원 준비 기준#

분석기 품질 표준을 유지하면서 특정 언어에 맞게 이 가이드라인을 조정합니다.

이 가이드라인은 GLAS에 PHP 지원을 추가한 경험에서 나온 것으로(이슈 #514210 참조), 새 언어 지원이 프로덕션에 준비되었는지 판단하는 데 도움이 됩니다.

품질 준비#

파일 간 분석 기능#

• 타깃 언어에서 가장 일반적인 의존성 관리 패턴 지원

• 언어별 일반적인 포함 메커니즘 지원

탐지 품질#

• 지원하는 CWE 전반에 걸쳐 정밀도 80% 이상

• 지원하는 각 CWE에 대한 포괄적인 테스트 코퍼스

• 언어 생태계의 인기 있는 프레임워크 대상 테스트

커버리지 준비#

우선순위 기반 커버리지#

• 언어와 관련된 중요한 인젝션 취약점 반드시 포함

• 일반적인 보안 잘못 구성 반드시 포함

• 업계 표준(OWASP Top 10, SANS CWE Top 25)과 일치해야 함

• 언어에서 일반적으로 발견되는 고영향 취약점에 집중

지원 준비#

문서화 요구 사항#

• 지원 언어 문서에 언어 목록 및 설명

• 새 언어 칼럼으로 CWE 커버리지 테이블 업데이트

• 지원하는 모든 CWE 올바르게 표시

• 알려진 제한 사항 명확히 문서화

성능 준비#

표준 성능 기준#

• 중간 규모 애플리케이션: 10분 미만

• 매우 큰 애플리케이션: 멀티 코어 옵션으로 30분 미만

벤치마크 정의#

• 벤치마킹을 위한 대표적인 코드베이스 정의

• 일반적인 프레임워크 및 라이브러리 포함

Go의 보안 및 빌드 수정#

Go로 구현된 Secure 분석기의 Dockerfile은 MINOR 리비전이 아닌 Go의 MAJOR 릴리스를 참조해야 합니다. 이렇게 하면 분석기를 컴파일하는 데 사용되는 Go 버전에 특정 시점에 사용 가능한 모든 보안 수정 사항이 포함됩니다. 예를 들어, 분석기의 멀티 스테이지 Dockerfile은 분석기 CLI를 빌드하는 데 golang:1.15-alpine 이미지를 사용해야 하며, golang:1.15.4-alpine은 사용하지 않아야 합니다.

Go의 MINOR 리비전이 릴리스되고 보안 수정 사항이 포함된 경우, 프로젝트 관리자는 Secure 분석기를 재빌드해야 하는지 확인해야 합니다. 빌드에 사용된 Go 버전은 릴리스에 해당하는 build job의 로그에 나타나며, strings 명령을 사용하여 Go 바이너리에서도 추출할 수 있습니다.

분석기의 최신 이미지가 영향받는 Go 버전으로 빌드된 경우 재빌드해야 합니다. 이미지를 재빌드하기 위해 관리자는 다음 중 하나를 수행할 수 있습니다:

• 안정 릴리스에 해당하는 Git 태그에 대한 새 파이프라인 트리거

• BUILD 번호를 증가시켜 새 Git 태그 생성

• 기본 브랜치에 대한 파이프라인 트리거 및 PUBLISH_IMAGES 변수를 비어 있지 않은 값으로 설정

어떤 방법이든 새 Docker 이미지가 빌드되고 동일한 이미지 태그인 MAJOR.MINOR.PATCH 및 MAJOR로 게시됩니다.

이 워크플로는 동일한 MAJOR 릴리스의 MINOR 리비전 간 전체 호환성을 가정합니다. 호환성 문제가 있는 경우 테스트를 실행할 때 프로젝트 파이프라인이 실패합니다. 이 경우 Dockerfile에서 MINOR 리비전의 Go를 참조하고 호환성 문제가 해결될 때까지 해당 예외를 문서화해야 할 수 있습니다.

MINOR 리비전의 Go는 Dockerfile에서 참조되지 않으므로 프로젝트 체인지로그에 언급되지 않습니다.

변경 사항이 빌드 관련이며 체인지로그 항목이 필요하지 않을 때 빌드 태그를 사용하는 것이 합리적인 경우가 있습니다. 예를 들어, Docker 이미지를 새 레지스트리 위치로 푸시하는 경우입니다.

재빌드를 위한 Git 태그#

분석기를 재빌드하기 위해 새 Git 태그를 생성할 때, 새 태그는 이전과 동일한 MAJOR.MINOR.PATCH 버전을 가지지만 BUILD 번호(semver에 정의된 대로)가 증가합니다.

예를 들어, 분석기의 최신 릴리스가 v1.2.3이고 해당 Docker 이미지가 영향받는 Go 버전으로 빌드된 경우, 관리자는 이미지를 재빌드하기 위해 Git 태그 v1.2.3+1을 생성합니다. 최신 릴리스가 v1.2.3+1이면 v1.2.3+2를 생성합니다.

빌드 번호는 이미지 태그에서 자동으로 제거됩니다. 예를 들어, gemnasium 프로젝트에서 Git 태그 v1.2.3+1을 생성하면 파이프라인이 이미지를 재빌드하고 gemnasium:1.2.3으로 푸시합니다.

재빌드를 위해 생성된 Git 태그에는 새 빌드가 필요한 이유를 설명하는 간단한 메시지가 있습니다. 예시: Rebuild with Go 1.15.6. 태그에는 릴리스 노트가 없으며 릴리스도 생성되지 않습니다.

분석기를 재빌드하기 위해 새 Git 태그를 생성하려면 다음 단계를 따르십시오:

• 새 Git 태그를 생성하고 메시지를 제공합니다

git tag -a v1.2.3+1 -m "Rebuild with Go 1.15.6"

• 태그를 리포지터리에 푸시합니다

git push origin --tags

• Git 태그에 대한 새 파이프라인이 트리거되고 새 이미지가 빌드되고 태그됩니다.

• 전체 테스트 스위트를 실행하고 새로 태그된 이미지에 대한 새 취약점 리포트를 생성하기 위해 master 브랜치에 대한 새 파이프라인을 실행합니다. 이는 3단계에서 트리거된 릴리스 파이프라인이 테스트의 일부 집합만 실행하기 때문에 필요합니다. 예를 들어 container scanning 분석을 수행하지 않습니다.

월간 릴리스 프로세스#

이 작업은 매월 18일에 수행해야 합니다. 단, 이는 소프트 마감일이며 며칠 후에 수행해도 문제가 없습니다.

먼저, 이 리포지터리의 스크립트를 사용하여 릴리스를 위한 새 이슈를 생성합니다: ./scripts/release_issue.rb MAJOR.MINOR. 이 이슈가 전체 릴리스 프로세스를 안내합니다. 일반적으로 다음 작업을 수행해야 합니다:

• GitLab 문서에서 지원되는 기술 목록을 확인합니다.

SAST에서 지원되는 언어

• DS에서 지원되는 언어

• LS에서 지원되는 언어

• 벤더링된 CI/CD 템플릿에서 CI job 정의가 여전히 정확한지 확인하고 docker run 시 모든 ENV 변수가 Docker 컨테이너에 전파되는지 확인합니다.

SAST 벤더링된 CI/CD 템플릿

• 종속성 스캐닝 벤더링된 CI/CD 템플릿

• 컨테이너 스캐닝 CI/CD 템플릿

필요한 경우 마지막 Git 태그에 해당하는 파이프라인으로 이동하여 이 이미지의 빌드를 제어하는 수동 job을 트리거합니다.

의존성 업데이트#

분석기 소스 코드에서 사용되는 의존성 및 업스트림 스캐너(있는 경우)는 분석기 유형에 따라 다른 방식으로 업데이트됩니다:

• SAST 분석기는 업데이트가 가능해지는 즉시 Renovate GitLab Bot을 통해 자동 의존성 업데이트를 받습니다. Renovate를 사용한 SAST 자동 의존성 업데이트를 참조하십시오.

• 시크릿 탐지 분석기는 SastBot을 통해 월별 케이던스로 의존성 업데이트를 받습니다. SastBot을 사용한 시크릿 탐지 자동 의존성 업데이트를 참조하십시오.

Renovate를 사용한 SAST 자동 의존성 업데이트#

SAST는 Renovate GitLab Bot을 사용하여 의존성 업데이트를 위한 머지 리퀘스트 및 체인지로그 항목을 자동으로 생성합니다.

Renovate GitLab Bot으로 새 분석기의 자동 의존성 업데이트를 활성화하려면, SAST 분석기 추가에 표시된 패턴을 따라 머지 리퀘스트를 제출하여 분석기를 추가합니다.

자동화된 체인지로그 업데이트 의존성 업데이트가 있는 머지 리퀘스트의 체인지로그 항목은 다음과 같이 자동으로 생성됩니다:

• 머지 리퀘스트를 생성하기 전에 Renovate GitLab Bot은 postUpgradeTasks에 나열된 명령을 실행합니다.

postUpgradeTasks는 changelogParserCommand를 실행하며, 이는 changelog-parser 커맨드 라인 도구를 실행합니다.

changelog-parser 커맨드 라인 도구는 {{MERGE_REQUEST_ID}} 플레이스홀더 텍스트를 포함하는 새 마이너 체인지로그 항목을 자동으로 삽입합니다. 예를 들어:

## v1.1.0
- Update `report` module from `1.2.3` to `1.2.4` (!{{MERGE_REQUEST_ID}})

• Renovate GitLab Bot은 의존성 업데이트와 체인지로그 항목이 포함된 새 머지 리퀘스트를 생성합니다.

• 머지 리퀘스트에서 새 파이프라인이 트리거되며, analyzer.yml 템플릿에 포함된 update changelog mrid job이 실행됩니다.

update changelog mrid job은 {{MERGE_REQUEST_ID}} 플레이스홀더 텍스트를 실제 머지 리퀘스트 ID로 교체하는 커밋을 생성합니다.

SastBot을 사용한 시크릿 탐지 자동 의존성 업데이트#

시크릿 탐지 팀은 내부 도구(SastBot)를 사용하여 파이프라인 기반 시크릿 탐지 분석기의 의존성 관리를 자동화합니다. SastBot은 매월 8일에 MR을 생성하고 검토를 위해 팀원들에게 할당을 배분합니다. 프로세스에 대한 자세한 내용은 의존성 업데이트 자동화를 참조하십시오.

SastBot은 각 job에 대해 서로 다른 액세스 토큰이 필요합니다. 예약된 파이프라인 job을 실행할 때 토큰을 검색하기 위해 DEP_GITLAB_TOKEN 환경 변수를 사용합니다.