공유 모듈
분석기 사용 방법
분석기 개발
- 실행 기준
분석기 테스트 방법
- 로컬 변경 사항 테스트
  - 도커에서 로컬 변경 사항 테스트
분석기 스크립트
버전 및 릴리스 프로세스
새로운 분석기 개발
- 체크리스트
- 컨테이너 이미지의 위치
Go의 보안 및 빌드 수정
- Git 태그 다시 빌드하기
- 매월 릴리스 프로세스
  - 의존성 업데이트

보안 섹션 분석기 개발

분석기는 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 .

예를 들어, Secret Detection을 테스트하려면 다음을 실행합니다:

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

실행 기준

SAST를 활성화하려면 GitLab CI/CD 구성에 미리 정의된 템플릿을 포함해야 합니다.

프로젝트에서 실행할 분석기를 결정하는 다음 독립적인 기준이 있습니다:

SAST 템플릿은 특정 파일의 존재 여부를 기반으로 분석기를 실행할지 여부를 결정하기 위해 rules:exists를 사용합니다. 예를 들어, Brakeman 분석기는 .rb 파일과 Gemfile이 있는 경우 실행됩니다.
각 분석기는 실제 분석을 수행하기 전에 사용자 정의 match interface를 실행합니다. 예를 들어: Flawfinder는 C/C++ 파일을 확인합니다.
일부 분석기는 일반 파일 확장자를 기반으로 확인하는 CI/CD 변수를 기반으로합니다. 예를 들어: Kubernetes 매니페스트는 YAML로 작성되므로 SCAN_KUBERNETES_MANIFESTS가 true로 설정되어 있는 경우에만 Kubesec가 실행됩니다.

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

분석기 테스트 방법

의존성 스캐닝 분석기가 테스트 프로젝트를 사용하여 분석기를 테스트하기 위해 하류 파이프라인 기능을 사용하는 방법에 대한 비디오 안내:

로컬 변경 사항 테스트

분석기의 공유 모듈(예: 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
)

도커에서 로컬 변경 사항 테스트

go.mod 파일에서 replace와 함께 도커를 사용하려면:

command의 내용을 분석기의 디렉토리로 복사합니다. cp -r /path/to/command path/to/analyzer/command.
분석기의 Dockerfile에 복사 명령문을 추가합니다: COPY command /command.
위 단계에서 COPY 명령문의 대상과 일치하도록 replace 문을 업데이트합니다: replace gitlab.com/gitlab-org/security-products/analyzers/command/v3 => /command

분석기 스크립트

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

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

버전 및 릴리스 프로세스

GitLab Security Products는 GitLab Rails의 MAJOR.MINOR와 별개의 버전 시스템을 사용합니다. 모든 제품은 Semantic Versioning의 변형을 사용하며 Docker 이미지로 제공됩니다.

패치 버전 업데이트는 일반적으로 기존 도구의 마이너 버전 업데이트에 해당하는 특정 하위 도구(예: bandit)의 마이너 버전 업데이트에 해당합니다. 이를 통해 스캐너에 대한 중요한 변경 사항에 대한 마이너 버전 업데이트를 예약하는 유연성을 갖출 수 있습니다. 포장된 스캐너에 의해 도입된 호환되지 않는 변경 사항의 경우, 새로운 분석기를 별도의 저장소에 만드는 것을 고려해야 합니다.

분석기는 다음과 같은 방식으로 Docker 이미지로 릴리스됩니다:

기본 브랜치로의 각 푸시는 edge 이미지 태그를 덮어씁니다.
awesome-feature 브랜치로의 각 푸시는 해당 awesome-feature 이미지 태그를 생성합니다.
각 Git 태그는 해당하는 Major.Minor.Patch 이미지 태그를 생성합니다. 수동 작업을 통해 해당 Major 및 latest 이미지 태그를이 Major.Minor.Patch로 지정하도록 재정의할 수 있습니다.

대부분의 경우, 최신 경고 또는 도구의 패치와 자동으로 최신 상태를 유지하도록 설정된 MAJOR 이미지에 의존하는 것이 좋습니다. 우리가 포함된 CI 템플릿을 고정시킴에 따라 사용자들이 직접 버전을 재정의할 수도 있지만, 사용자들은 직접 버전을 재정의할 수도 있습니다.

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

수동 릴리스 프로세스
자동 릴리스 프로세스

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

GitLab의 지속적 배포 흐름에 따라, GitLab Rails 응용 프로그램에 해당하는 새로운 구성요소의 경우, 해당 구성 요소는 언제든지 릴리스 할 수 있습니다. 구성 요소가 기존 응용 프로그램과 통합되기 전까지는 표준 릴리스 주기 및 프로세스에 의해 반복이 차단되어서는 안 됩니다.

수동 릴리스 프로세스

새로운 분석기에 대한 CHANGELOG.md 항목이 올바른지 확인합니다.
릴리스 소스(일반적으로 master 또는 main 브랜치)가 통과하는 파이프라인을 가지고 있는지 확인합니다.
프로젝트 창의 왼쪽에 있는 배포 메뉴를 선택한 후 릴리스 하위 메뉴를 선택하여 분석기 프로젝트에 대한 새 릴리스를 생성합니다.
새 릴리스 페이지를 열기 위해 새 릴리스를 선택합니다.
1. 태그 이름 드롭다운에서 CHANGELOG.md에서 사용된 것과 동일한 버전(예: v2.4.2)을 입력한 다음 태그를 만드는 옵션을 선택합니다(여기에서 태그 생성 v2.4.2).
2. 릴리스 제목 텍스트 상자에 위와 동일한 버전(예: v2.4.2)을 입력합니다.
3. 릴리스 노트 텍스트 상자에 CHANGELOG.md의 해당 버전에서 노트를 복사하여 붙여넣습니다.
4. 다른 모든 설정은 기본값으로 유지합니다.
5. 릴리스 생성을 선택합니다.

위 프로세스를 따라 새 릴리스를 생성한 후에는 Tag 이름과 동일한 이름의 새 Git 태그가 생성됩니다. 이에 따라 주어진 태그 버전과 함께 새 분석기 도커 이미지가 빌드됩니다.

만약 분석기가 analyzer.yml 템플릿을 사용하는 경우, 위의 새 릴리스 프로세스를 트리거하는 파이프라인은 자동으로 분석기 도커 이미지의 새 버전을 태그하고 배포합니다.

만약 분석기가 analyzer.yml 템플릿을 사용하지 않는다면, 분석기 도커 이미지의 새 버전을 수동으로 태그하고 배포해야 합니다:

프로젝트 창의 왼쪽에 있는 CI/CD 메뉴를 선택한 후 파이프라인 하위 메뉴를 선택합니다.
이전에 사용한 것과 동일한 태그(예: v2.4.2)로 실행 중인 새 파이프라인이 있어야 합니다.
파이프라인이 완료되면 blocked 상태가 됩니다.
창의 오른쪽에 있는 수동 작업 재생 버튼을 선택하고 새 분석기 도커 이미지의 버전을 태그하고 배포하기 위해 tag version을 선택합니다.

Git 태그를 생성할 시점을 판단하기 위해 최선의 의견을 내야 합니다. 판단을 할 수 없는 경우 다른 사람의 의견을 물어보세요.

자동 릴리스 프로세스

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

CI/CD 환경 변수로 CREATE_GIT_TAG: true를 구성합니다.
CI/CD 프로젝트 설정의 Variables를 확인합니다. 프로젝트가 이미 프로젝트 그룹에서 GITLAB_TOKEN 환경 변수를 상속받지 않는 경우, API에 대한 완전한 읽기/쓰기 액세스를 갖는 프로젝트 액세스 토큰을 생성하고 이 토큰을 참조하는 GITLAB_TOKEN을 CI/CD 환경 변수로 구성합니다.

위 단계를 완료한 후, 자동 릴리스 프로세스는 다음과 같이 실행됩니다:

프로젝트 유지자가 MR을 기본 브랜치에 병합합니다.
기본 파이프라인이 트리거되고 upsert git tag 작업이 실행됩니다.
- CHANGELOG.md의 가장 최근 버전이 Git 태그 중 하나와 일치하는 경우, 이 작업은 무시됩니다.
- 그렇지 않은 경우, 이 작업은 프로젝트의 CHANGELOG.md 파일의 가장 최근 항목에서 버전 및 메시지를 가져와 새 릴리스와 Git 태그를 자동으로 생성합니다.
새로운 Git 태그를 위해 자동으로 파이프라인이 트리거됩니다. 해당 파이프라인은 분석기의 latest, major, minor, patch Docker 이미지를 릴리스합니다.

분석기 릴리스 이후 수행해야 할 단계

분석기 도커 이미지의 새 버전이 태그되고 배포된 후 해당 버전과 관련된 테스트 프로젝트에서 테스트합니다.
관련 그룹 Slack 채널에 릴리스를 공지합니다. 예시 메시지:

FYI, ANALYZER_NAME ANALYZER_VERSION을(를) 릴리스했습니다. LINK_TO_RELEASE

한 번 푸시된 Git 태그를 삭제하지 마세요. 해당 태그가 사용되거나/또는 Go 패키지 레지스트리에서 캐시될 가능성이 높습니다.

새로운 분석기 개발

가끔은 새로운 프레임워크 및 도구를 지원하기 위해 새로운 분석기 프로젝트를 구축해야 할 때가 있습니다. 이러한 경우 저희 엔지니어링 오픈 소스 지침 및 코드 표준을 따라야 합니다.

또한, GitLab 애플리케이션에 통합될 사용자 정의 분석기를 작성하기 위해서는 최소한의 기능 집합이 필요합니다:

체크리스트

기본 도구

[ ] 허용되는 소프트웨어 라이선스가 있습니다.
[ ] 헤드리스 실행 (CLI 도구)
[ ] Docker 이미지로 패키지화될 수 있는 종속성을 번들로 제공하며, GitLab Runner의 Linux 또는 Windows Docker executor를 사용하여 실행할 수 있습니다.
[ ] 호환되는 프로젝트는 파일 이름 또는 확장자를 기반으로 감지될 수 있습니다.
[ ] 오프라인 실행(인터넷 액세스 없음) 또는 사용자 정의 프록시 및/또는 CA 인증서를 사용하도록 구성할 수 있습니다.

Dockerfile

Dockerfile은 GitLab이라는 관리 권한이 없는 사용자를 사용해야 합니다. 이것이 필요한 이유는 Red Hat OpenShift 인스턴스와의 호환성을 제공하기 위한 것입니다. Red Hat OpenShift는 컨테이너가 관리자(root) 사용자로 실행되는 것을 허용하지 않습니다. 관리 권한 없는 사용자로 컨테이너를 실행하는 경우 특정 제한 사항을 염두에 두어야 합니다. 예를 들면 Docker 파일 시스템에 기록해야 하는 파일에는 GitLab 사용자의 적절한 권한이 필요합니다. 자세한 내용은 다음 병합 요청을 참조하세요: Docker 이미지에서 root 대신 GitLab 사용자 사용.

최소한의 취약점 데이터

전체 필수 필드 목록은 security-report-schemas를 참조하세요.

security-report-schema 리포지토리에는 각 보고서 유형에 대한 필수 필드가 나열된 JSON 스키마가 포함되어 있습니다.

컨테이너 이미지의 위치

컨테이너 레지스트리에 쓰기 액세스를 가진 사람 수를 제한하기 위해 모든 이미지는 아래 위치에 발행되어야 합니다.

그룹: https://gitlab.com/security-products/
프로젝트 경로: https://gitlab.com/security-products/<이름> (예시)
레지스트리 주소: registry.gitlab.com/security-products/<이름>[/<이미지_이름>]:[태그]
권한
- 최상위 그룹
  - 도우미: @gitlab-org/secure/managers, @gitlab-org/govern/managers
- 프로젝트 레벨
  - read_registry 및 write_registry 액세스가 있는 배포 토큰을 사용하여 이미지를 푸시합니다.
  - 토큰은 생성자에 의해 보호됨 및 가리기 변수로 원본 프로젝트(즉, security-products 네임스페이스 하위의 프로젝트)에 입력됩니다.
프로젝트 설정
- 가시성, 프로젝트 기능, 권한
  - 프로젝트 가시성: 공개. “사용자가 액세스 요청을 할 수 없음” 선택 해제.
  - 이슈: 사용 안 함.
  - 저장소: “프로젝트 멤버만”으로 설정. 사용 안 함: 병합 요청, 포크, Git LFS, 패키지, CI/CD.
  - 남은 항목 사용 안 함: 분석, 요구 사항, 위키, 코드 스니펫, 페이지, 작업.
- 서비스 데스크: 사용 안 함

Sec 섹션의 각 그룹은 다음을 책임져야 합니다:

그들의 아티팩트에 대한 폐기 및 제거 일정을 관리하고 이를 위한 이슈를 생성합니다.
새 위치에 프로젝트를 구성하고 구성합니다.
릴리스 아티팩트를 새 위치로 푸시하기 위한 빌드를 구성합니다.
지원 계약에 따라 이전 위치에 있는 이미지를 제거하거나 유지합니다.

Go의 보안 및 빌드 수정

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

MINOR 리비전의 Go가 출시되고 보안 수정이 포함된 경우, 프로젝트 유지 관리자는 보안 분석기가 다시 빌드되어야 하는지 확인해야 합니다. 해당 릴리스에 해당하는 빌드 작업 로그에서 사용된 Go 버전을 확인할 수 있으며, strings 명령을 사용하여 Go 이진 파일에서도 확인할 수 있습니다.

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

안정적인 릴리스에 대한 Git 태그에 대한 새로운 파이프라인을 트리거합니다.
BUILD 번호가 증가된 새 Git 태그를 생성합니다.
기본 브랜치에 대한 파이프라인을 트리거하고 PUBLISH_IMAGES 변수를 비어 있지 않은 값으로 설정합니다.

어느 방법이든 새로운 Docker 이미지가 빌드되어 동일한 이미지 태그인 MAJOR.MINOR.PATCH 및 MAJOR로 발행됩니다.

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

Dockerfile에 참조되지 않기 때문에 MINOR 리비전의 Go는 프로젝트 변경 로그에 언급되지 않습니다.

빌드와 관련된 변경이며 변경 로그 항목이 필요하지 않은 경우에는 빌드 태그를 사용하는 것이 타당한 경우가 있을 수 있습니다. 예를 들어, 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 태그에는 새로운 빌드가 필요한 이유를 설명하는 간단한 메시지가 포함됩니다. 예: Go 1.15.6으로 다시 빌드. 태그에는 릴리스 노트도 없고 릴리스도 생성되지 않습니다.

분석기를 다시 빌드하기 위해 새로운 Git 태그를 생성하려면 다음 단계를 따르세요:

새로운 Git 태그를 생성하고 메시지를 제공합니다.
```
git tag -a v1.2.3+1 -m "Go 1.15.6으로 다시 빌드"
```
태그를 레포지토리에 푸시합니다.
```
git push origin --tags
```
Git 태그에 대한 새로운 파이프라인이 트리거되고 새 이미지가 빌드되고 태깅됩니다.
3. 단계에서 트리거된 릴리스 파이프라인은 일부 테스트만 실행하므로, 새로운 이미지에 대한 master 브랜치의 새 파이프라인을 실행하여 모든 테스트 스위트를 실행하고 새로운 취약점 보고서를 생성해야 합니다. 이는 예를 들어, Container Scanning 분석을 수행하지 않습니다.

매월 릴리스 프로세스

이는 매월 18일에 수행되어야 합니다. 그러나 이는 유연한 마감일이며 몇 일 후에 수행해도 문제가 없습니다.

먼저, 스크립트를 사용하여 릴리스를 위한 새로운 이슈를 만드세요: ./scripts/release_issue.rb MAJOR.MINOR. 이 이슈를 통해 전체 릴리스 프로세스를 안내받을 수 있습니다. 일반적으로 다음 작업을 수행해야 합니다:

GitLab 문서에서 지원되는 기술 목록을 확인하세요.
Vendored CI/CD 템플릿에서 CI 작업 정의가 여전히 정확한지 확인하고 docker run에 따른 모든 ENV 변수가 Docker 컨테이너로 전파되는지 확인하세요.
필요한 경우, 마지막 Git 태그에 해당하는 파이프라인으로 이동하여 이 이미지의 빌드를 제어하는 수동 작업을 트리거하세요.
파이프라인에서 사용되는 현재 봇 계정
- 계정 이름: @group_2452873_bot
  - 사용: 릴리스/태그 생성에 사용됨
  - 소속: 그룹 gitlab-org/security-products
  - 최대 역할: Developer
  - 연관된 GITLAB_TOKEN의 유효 범위:
  - 연관된 GITLAB_TOKEN의 만료 날짜:

의존성 업데이트

분석기 소스에 사용된 모든 종속성 및 상위 스캐너(있는 경우)는 주로 보안 수정과 호환되는 변경 사항을 포함하는 월간 주기로 업데이트됩니다.

Static Analysis 팀은 모든 SAST 분석기의 종속성 관리를 자동화하기 위해 내부적으로 사용자 지정 도구인 (SastBot)를 사용합니다. SastBot은 매월 8일에 MR을 생성하고 이를 Static Analysis 팀 구성원들에게 리뷰를 진행하기 위해 할당합니다. 프로세스에 대한 자세한 내용은 Dependency Update Automation을 참조하세요.