Gemnasium 분석기 기반의 종속성 스캐닝 기능은 GitLab 17.9에서 사용 중단(deprecated)되었으며, GitLab 20.0에서 제거될 예정입니다. 단, 제거 일정은 확정되지 않았으며 필요에 따라 Gemnasium을 계속 사용할 수 있습니다. 자세한 내용은 에픽 15961을 참조하세요.

종속성 스캐닝은 CI/CD 파이프라인에 통합되어 자동으로 실행되며, 애플리케이션의 의존성에 존재하는 보안 취약점을 식별합니다. 브랜치가 머지되기 전에 스캔을 실행하여 머지 리퀘스트에서 보안 이슈를 즉시 확인할 수 있습니다. 이를 통해 코드를 머지하기 전에 잠재적인 취약점에 대한 정보를 바탕으로 의사 결정을 내릴 수 있습니다.

기본적으로 종속성 스캐닝은 런타임, 개발, 전이(중첩) 의존성을 포함하여 코드의 모든 의존성을 분석합니다. 개발 의존성은 선택적으로 스캔에서 제외할 수 있습니다.

• 개요는 종속성 스캐닝 - 고급 보안 테스트를 참조하세요.

• 이 종속성 스캐닝 문서의 인터랙티브 읽기 및 실습 데모는 종속성 스캐닝 튜토리얼 - GitLab 애플리케이션 보안 파트 3을 참조하세요.

• 다른 인터랙티브 읽기 및 실습 데모는 GitLab 애플리케이션 보안 시작하기 플레이리스트를 참조하세요.

파이프라인 외부에서 의존성의 취약점을 스캔하려면 지속적 취약점 스캐닝을 참조하세요.

종속성 스캐닝 활성화#

다음 단계에 따라 프로젝트에서 종속성 스캐닝을 활성화하세요.

분석기를 활성화하려면 다음 중 하나를 선택하세요.

• 종속성 스캐닝이 포함된 Auto DevOps를 활성화합니다.

• 사전 구성된 머지 리퀘스트를 사용합니다.

• 종속성 스캐닝을 적용하는 스캔 실행 정책을 생성합니다.

• .gitlab-ci.yml 파일을 수동으로 편집합니다.

• CI/CD 컴포넌트를 사용합니다

사전 구성된 머지 리퀘스트 사용#

이 방법은 .gitlab-ci.yml 파일에 종속성 스캐닝 템플릿이 포함된 머지 리퀘스트를 자동으로 준비합니다. 그런 다음 머지 리퀘스트를 머지하여 종속성 스캐닝을 활성화합니다.

이 방법은 기존 .gitlab-ci.yml 파일이 없거나 최소한의 구성 파일이 있을 때 가장 잘 작동합니다. 복잡한 GitLab 구성 파일이 있는 경우 파싱에 실패하고 오류가 발생할 수 있습니다. 이 경우 수동 방법을 사용하세요.

사전 요구사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한.

• .gitlab-ci.yml 파일에 test Stage가 필요합니다.

• Self-managed 러너의 경우, docker 또는 kubernetes 실행기를 사용하는 GitLab Runner.

• GitLab.com의 호스팅 러너의 경우 이 구성이 기본적으로 활성화되어 있습니다.

종속성 스캐닝을 활성화하려면:

• 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.

• 왼쪽 사이드바에서 Secure > Security configuration을 선택합니다.

• Dependency Scanning 행에서 Configure with a merge request를 선택합니다.

• Create merge request를 선택합니다.

• 머지 리퀘스트를 검토한 후 Merge를 선택합니다.

이제 파이프라인에 종속성 스캐닝 job이 포함됩니다.

.gitlab-ci.yml 파일 수동 편집#

이 방법을 사용하면 기존 .gitlab-ci.yml 파일을 수동으로 편집해야 합니다. GitLab CI/CD 구성 파일이 복잡한 경우 이 방법을 사용하세요.

사전 요구사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한.

• .gitlab-ci.yml 파일에 test Stage가 필요합니다.

• Self-managed 러너의 경우, docker 또는 kubernetes 실행기를 사용하는 GitLab Runner.

• GitLab.com의 호스팅 러너의 경우 이 구성이 기본적으로 활성화되어 있습니다.

종속성 스캐닝을 활성화하려면:

• 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.

• 왼쪽 사이드바에서 Build > Pipeline editor를 선택합니다.

• .gitlab-ci.yml 파일이 없는 경우 Configure pipeline을 선택한 다음 예시 콘텐츠를 삭제합니다.

• 다음을 .gitlab-ci.yml 파일의 맨 아래에 복사하여 붙여넣습니다. 이미 include 줄이 있는 경우 그 아래에 template 줄만 추가합니다.

include:
  - template: Jobs/Dependency-Scanning.gitlab-ci.yml

• Validate 탭을 선택한 다음 Validate pipeline을 선택합니다.

  Simulation completed successfully 메시지가 표시되면 파일이 유효한 것입니다.

• Edit 탭을 선택합니다.

• 필드를 입력합니다. Branch 필드에는 기본 브랜치를 사용하지 마세요.

• Start a new merge request with these changes 체크박스를 선택한 다음 Commit changes를 선택합니다.

• 표준 워크플로에 따라 필드를 입력한 다음 Create merge request를 선택합니다.

• 표준 워크플로에 따라 머지 리퀘스트를 검토하고 편집한 다음 Merge를 선택합니다.

이제 파이프라인에 종속성 스캐닝 job이 포함됩니다.

CI/CD 컴포넌트 사용#

종속성 스캐닝 CI/CD 컴포넌트는 Android 프로젝트만 지원합니다.

CI/CD 컴포넌트를 사용하여 애플리케이션의 종속성 스캐닝을 수행하세요. 자세한 지침은 각 컴포넌트의 README 파일을 참조하세요.

사용 가능한 CI/CD 컴포넌트#

https://gitlab.com/explore/catalog/components/dependency-scanning을 참조하세요.

이 단계를 완료한 후 다음을 수행할 수 있습니다.

• 결과 이해에 대해 자세히 알아보세요.

• 더 많은 프로젝트에 롤아웃을 계획하세요.

결과 이해#

종속성 스캐닝 결과는 여러 형식으로 제공됩니다. 파이프라인 UI에서 직접 확인하거나, 상세 스캐닝 보고서에서 확인하거나, 스캔 중 생성된 소프트웨어 구성 목록(SBOM)에서 확인할 수 있습니다.

파이프라인에서 취약점 검토#

파이프라인에서 감지된 취약점을 검토하고 머지 리퀘스트가 머지되기 전에 조치를 취하세요.

사전 요구사항:

• 프로젝트에 대한 Developer, Maintainer, 또는 Owner 권한.

파이프라인에서 종속성 스캐닝 결과를 검토하려면:

• 상단 바에서 Search or go to를 선택하고 프로젝트를 찾습니다.

• 왼쪽 사이드바에서 Build > Pipelines를 선택합니다.

• 파이프라인을 선택합니다.

• Security 탭을 선택합니다.

• 취약점을 선택하여 다음 세부 정보를 확인합니다.

  Status: 취약점이 분류되었거나 해결되었는지 여부를 나타냅니다.

  • Description: 취약점의 원인, 잠재적 영향 및 권장 해결 단계를 설명합니다.

  • Severity: 영향도에 따라 여섯 가지 수준으로 분류됩니다. 심각도 수준에 대해 자세히 알아보세요.

  • CVSS score: 심각도에 매핑되는 수치를 제공합니다.

  • EPSS: 실제 환경에서 취약점이 악용될 가능성을 보여줍니다.

  • Has Known Exploit (KEV): 특정 취약점이 이미 악용된 적이 있음을 나타냅니다.

  • Project: 취약점이 식별된 프로젝트를 강조 표시합니다.

  • Report type / Scanner: 출력 유형과 결과 생성에 사용된 스캐너를 설명합니다.

  • Reachable: 취약한 의존성이 코드에서 실제로 사용되는지 여부를 나타냅니다.

  • Scanner: 취약점을 감지한 분석기를 식별합니다.

  • Location: 취약한 의존성이 위치한 파일 이름을 표시합니다.

  • Links: 다양한 권고 데이터베이스에 등록된 취약점 증거입니다.

  • Identifiers: CVE 식별자 등 취약점을 분류하는 데 사용되는 참조 목록입니다.

종속성 스캐닝 보고서#

종속성 스캐닝은 모든 취약점의 세부 정보가 포함된 보고서를 출력합니다. 보고서는 내부적으로 처리되어 UI에 결과가 표시됩니다. 보고서는 종속성 스캐닝 job의 아티팩트로도 출력되며, gl-dependency-scanning-report.json이라는 이름으로 항상 프로젝트 루트에 생성됩니다.

종속성 스캐닝 보고서에 대한 자세한 내용은 종속성 스캐닝 보고서 스키마를 참조하세요.

CycloneDX 소프트웨어 구성 목록#

종속성 스캐닝은 감지된 각 지원 잠금 파일 또는 빌드 파일에 대해 CycloneDX 소프트웨어 구성 목록(SBOM)을 출력합니다.

CycloneDX SBOM의 특징:

• gl-sbom-<package-type>-<package-manager>.cdx.json으로 이름이 지정됩니다.

• 종속성 스캐닝 job의 job 아티팩트로 제공됩니다.

• 감지된 잠금 파일 또는 빌드 파일과 동일한 디렉터리에 저장됩니다.

예를 들어, 프로젝트가 다음 구조를 가지고 있다면:

.
├── ruby-project/
│   └── Gemfile.lock
├── ruby-project-2/
│   └── Gemfile.lock
├── php-project/
│   └── composer.lock
└── go-project/
    └── go.sum

Gemnasium 스캐너는 다음 CycloneDX SBOM을 생성합니다:

.
├── ruby-project/
│   ├── Gemfile.lock
│   └── gl-sbom-gem-bundler.cdx.json
├── ruby-project-2/
│   ├── Gemfile.lock
│   └── gl-sbom-gem-bundler.cdx.json
├── php-project/
│   ├── composer.lock
│   └── gl-sbom-packagist-composer.cdx.json
└── go-project/
    ├── go.sum
    └── gl-sbom-go-go.cdx.json

롤아웃#

단일 프로젝트의 종속성 스캐닝 결과에 충분한 자신감을 갖게 되면, 추가 프로젝트로 구현을 확장할 수 있습니다.

• 적용된 스캔 실행을 사용하여 그룹 전체에 종속성 스캐닝 설정을 적용합니다.

• 고유한 요구사항이 있는 경우, SBOM이 포함된 종속성 스캐닝을 오프라인 환경에서 실행할 수 있습니다.

지원되는 언어 및 패키지 관리자#

종속성 스캐닝은 컴파일러 및 인터프리터의 런타임 설치를 지원하지 않습니다.

종속성 스캐닝에서 지원하는 언어 및 패키지 관리자는 다음과 같습니다.

각주:

• sbt의 Java 21 LTS는 버전 1.9.7로 제한됩니다. 더 많은 sbt 버전에 대한 지원은 이슈 430335에서 추적할 수 있습니다. FIPS 모드가 활성화된 경우 지원되지 않습니다.

• FIPS 모드가 활성화된 경우 Gradle은 지원되지 않습니다.

• pnpm 잠금 파일은 번들 의존성을 저장하지 않으므로 보고되는 의존성이 npm 또는 yarn과 다를 수 있습니다.

• poetry.lock 파일이 없는 프로젝트에 대한 지원은 이슈 32774에서 추적 중입니다.

• sbt 1.0.x에 대한 지원은 GitLab 16.8에서 사용 중단되었으며, GitLab 17.0에서 제거되었습니다.

• 3.8.8 미만의 Maven에 대한 지원은 GitLab 16.9에서 사용 중단되었으며, GitLab 17.0에서 제거되었습니다.

• 이전 Python 버전에 대한 지원은 GitLab 16.9에서 사용 중단되었으며, GitLab 17.0에서 제거되었습니다.

• 설치 프로그램에 필요하므로 보고서에서 pip와 setuptools 모두 제외됩니다.

• 권고 없이 SBOM만 제공합니다. 이슈 468764를 참조하세요.

• 라이선스 감지 없음. 에픽 17037을 참조하세요.

• 잠금 파일에 동일한 패키지에 대해 환경 마커가 다른 여러 항목이 포함된 경우(예: Python <3.11의 경우 numpy==2.2.6, Python ≥3.11의 경우 numpy==2.4.1), 첫 번째 항목만 파싱하여 보고됩니다.

지원되는 개발 의존성#

개발 의존성 감지는 다음 언어 및 패키지 관리자에 대해 지원됩니다.

머지 리퀘스트 파이프라인에서 job 실행#

머지 리퀘스트 파이프라인과 함께 보안 스캐닝 도구 사용을 참조하세요.

분석기 동작 커스터마이징#

종속성 스캐닝을 커스터마이징하려면 CI/CD 변수를 사용하세요.

GitLab 분석기의 모든 커스터마이징은 기본 브랜치에 머지하기 전에 머지 리퀘스트에서 테스트하세요. 이를 이행하지 않으면 다수의 오탐(false positive)을 포함하여 예상치 못한 결과가 발생할 수 있습니다.

종속성 스캐닝 job 재정의#

job 정의를 재정의하려면(예: variables 또는 dependencies와 같은 속성 변경), 재정의할 job과 동일한 이름으로 새 job을 선언합니다. 이 새 job을 템플릿 포함 다음에 배치하고 해당 추가 키를 아래에 지정합니다.

예를 들어, 다음은 gemnasium 분석기에 대해 취약한 의존성의 자동 수정을 비활성화합니다.

include:
  - template: Jobs/Dependency-Scanning.gitlab-ci.yml

gemnasium-dependency_scanning:
  variables:
    DS_REMEDIATE: "false"

dependencies: [] 속성을 재정의하려면 앞서 설명한 대로 이 속성을 타깃으로 하는 재정의 job을 추가합니다.

include:
  - template: Jobs/Dependency-Scanning.gitlab-ci.yml

gemnasium-dependency_scanning:
  dependencies: ["build"]

사용 가능한 CI/CD 변수#

CI/CD 변수를 사용하여 종속성 스캐닝 동작을 커스터마이징할 수 있습니다.

전역 분석기 설정#

다음 변수를 사용하여 전역 종속성 스캐닝 설정을 구성할 수 있습니다.

분석기별 설정#

다음 변수는 특정 종속성 스캐닝 분석기의 동작을 구성합니다.

기타 변수#

이전 표는 사용 가능한 모든 변수의 완전한 목록이 아닙니다. 지원되고 테스트된 모든 GitLab 및 분석기 관련 변수만 포함되어 있습니다. 환경 변수와 같은 다른 많은 변수도 전달하여 올바르게 작동할 수 있습니다. 이 목록은 방대하고 완전히 문서화되지 않았습니다.

예를 들어, GitLab 외부 환경 변수 HTTPS_PROXY를 모든 종속성 스캐닝 job에 전달하려면 다음과 같이 .gitlab-ci.yml 파일에서 CI/CD 변수로 정의하세요.

variables:
  HTTPS_PROXY: "https://squid-proxy:3128"

Gradle 프로젝트에서는 프록시를 사용하기 위해 추가 변수 설정이 필요합니다.

또는 종속성 스캐닝과 같은 특정 job에서 사용할 수도 있습니다.

dependency_scanning:
  variables:
    HTTPS_PROXY: $HTTPS_PROXY

모든 변수가 테스트되지 않았으므로 일부는 작동하고 일부는 작동하지 않을 수 있습니다. 작동하지 않는 변수가 필요한 경우, 기능 요청을 제출하거나 코드에 기여하여 사용 가능하게 만드세요.

사용자 정의 TLS 인증 기관#

종속성 스캐닝은 분석기 컨테이너 이미지에 기본으로 제공되는 것 대신 SSL/TLS 연결에 사용자 정의 TLS 인증서를 사용할 수 있습니다.

사용자 정의 인증 기관에 대한 지원은 다음 버전에서 도입되었습니다.

사용자 정의 TLS 인증 기관 사용#

사전 요구사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한.

사용자 정의 TLS 인증 기관을 사용하려면:

• CI/CD 변수 ADDITIONAL_CA_CERT_BUNDLE에 X.509 PEM 공개키 인증서의 텍스트 표현을 할당합니다.

예를 들어, .gitlab-ci.yml 파일에서 인증서를 구성하려면:

variables:
  ADDITIONAL_CA_CERT_BUNDLE: |
      -----BEGIN CERTIFICATE-----
      MIIGqTCCBJGgAwIBAgIQI7AVxxVwg2kch4d56XNdDjANBgkqhkiG9w0BAQsFADCB
      ...
      jWgmPqF3vUbZE0EyScetPJquRFRKIesyJuBFMAs=
      -----END CERTIFICATE-----

프라이빗 Maven 리포지터리 인증#

의존성 분석기가 프라이빗 Maven 리포지터리로 인증하려면 CI/CD 파이프라인에 자격 증명을 구성해야 합니다. 인증 없이는 의존성 분석기가 프라이빗 의존성에 액세스할 수 없으며 스캔이 실패합니다.

자격 증명을 .gitlab-ci.yml 파일에 추가하지 마세요.

사전 요구사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한.

의존성 분석기가 프라이빗 Maven 리포지터리로 인증하도록 허용하려면:

• MAVEN_CLI_OPTS라는 이름의 프로젝트 CI/CD 변수를 생성하고, 자격 증명을 포함하도록 값을 설정합니다.

  예를 들어, mysettings.xml이라는 설정 파일, 사용자 이름 myuser, 비밀번호 verysecret을 사용한다고 가정하면 MAVEN_CLI_OPTS CI/CD 변수를 다음과 같이 설정합니다.

  --settings mysettings.xml -Drepository.password=verysecret -Drepository.user=myuser

• 서버 구성이 포함된 mysettings.xml Maven 설정 파일을 생성합니다. 파일 이름은 1단계의 --settings 옵션에 지정한 값과 일치해야 합니다.

<!-- mysettings.xml -->
<settings>
    ...
    <servers>
        <server>
            <id>private_server</id>
            <username>${repository.user}</username>
            <password>${repository.password}</password>
        </server>
    </servers>
</settings>

FIPS 지원 이미지#

GitLab은 Gemnasium 이미지의 FIPS 지원 Red Hat UBI 버전도 제공합니다. GitLab 인스턴스에서 FIPS 모드가 활성화되면 Gemnasium 스캔 job이 자동으로 FIPS 지원 이미지를 사용합니다. FIPS 지원 이미지로 수동 전환하려면 변수 DS_IMAGE_SUFFIX를 "-fips"로 설정합니다.

Gradle 프로젝트의 종속성 스캐닝과 Yarn 프로젝트의 자동 수정은 FIPS 모드에서 지원되지 않습니다.

FIPS 지원 이미지는 RedHat UBI micro를 기반으로 합니다. dnf 또는 microdnf와 같은 패키지 관리자가 없으므로 런타임에 시스템 패키지를 설치할 수 없습니다.

오프라인 환경#

인터넷을 통한 외부 리소스 액세스가 제한적이거나 제한되어 있거나 간헐적인 환경의 인스턴스는 종속성 스캐닝 job이 성공적으로 실행되기 위해 몇 가지 조정이 필요합니다. 자세한 내용은 오프라인 환경을 참조하세요.

사전 요구사항:

• 관리자 액세스.

• docker 또는 kubernetes 실행기를 사용하는 GitLab Runner.

• 종속성 스캐닝 분석기 이미지의 로컬 복사본.

• GitLab 권고 데이터베이스 액세스.

• 패키지 메타데이터 데이터베이스 액세스.

분석기 이미지의 로컬 복사본#

지원되는 모든 언어 및 프레임워크와 함께 종속성 스캐닝을 사용하려면:

• registry.gitlab.com에서 다음 기본 종속성 스캐닝 분석기 이미지를 로컬 Docker 컨테이너 레지스트리로 가져옵니다.

registry.gitlab.com/security-products/gemnasium:6
registry.gitlab.com/security-products/gemnasium:6-fips
registry.gitlab.com/security-products/gemnasium-maven:6
registry.gitlab.com/security-products/gemnasium-maven:6-fips
registry.gitlab.com/security-products/gemnasium-python:6
registry.gitlab.com/security-products/gemnasium-python:6-fips

Docker 이미지를 로컬 오프라인 Docker 레지스트리로 가져오는 프로세스는 네트워크 보안 정책에 따라 다릅니다. IT 직원과 상담하여 외부 리소스를 가져오거나 임시로 액세스할 수 있는 승인된 프로세스를 확인하세요. 이 스캐너는 새로운 정의로 주기적으로 업데이트되므로 정기적으로 다운로드하는 것이 좋습니다.

• GitLab CI/CD를 로컬 분석기를 사용하도록 구성합니다.

  CI/CD 변수 SECURE_ANALYZERS_PREFIX의 값을 로컬 Docker 레지스트리로 설정합니다. 이 예에서는 docker-registry.example.com입니다.

include:
  - template: Jobs/Dependency-Scanning.gitlab-ci.yml

variables:
  SECURE_ANALYZERS_PREFIX: "docker-registry.example.com/analyzers"

GitLab 권고 데이터베이스 액세스#

GitLab 권고 데이터베이스는 gemnasium, gemnasium-maven, gemnasium-python 분석기가 사용하는 취약점 데이터의 소스입니다. 이 분석기의 Docker 이미지에는 데이터베이스의 클론이 포함되어 있습니다. 스캔을 시작하기 전에 데이터베이스와 클론이 동기화되어 분석기가 최신 취약점 데이터를 갖도록 합니다.

오프라인 환경에서는 GitLab 권고 데이터베이스의 기본 호스트에 액세스할 수 없습니다. 대신 GitLab 러너가 액세스할 수 있는 곳에 데이터베이스를 호스팅해야 합니다. 또한 자체 일정에 따라 데이터베이스를 수동으로 업데이트해야 합니다.

데이터베이스 호스팅을 위한 옵션:

• GitLab 권고 데이터베이스 클론 사용.

• GitLab 권고 데이터베이스 복사본 사용.

GitLab 권고 데이터베이스 클론 사용#

GitLab 권고 데이터베이스 클론 사용은 가장 효율적인 방법이므로 권장됩니다.

GitLab 권고 데이터베이스 클론을 호스팅하려면:

• GitLab 러너에서 HTTP로 액세스할 수 있는 호스트에 GitLab 권고 데이터베이스를 클론합니다.

• .gitlab-ci.yml 파일에서 CI/CD 변수 GEMNASIUM_DB_REMOTE_URL의 값을 Git 리포지터리 URL로 설정합니다.

예를 들어:

variables:
  GEMNASIUM_DB_REMOTE_URL: https://users-own-copy.example.com/gemnasium-db.git

GitLab 권고 데이터베이스 복사본 사용#

GitLab 권고 데이터베이스 복사본을 사용하려면 분석기가 다운로드하는 아카이브 파일을 호스팅해야 합니다.

GitLab 권고 데이터베이스 복사본을 사용하려면:

• GitLab 러너에서 HTTP로 액세스할 수 있는 호스트에 GitLab 권고 데이터베이스 아카이브를 다운로드합니다. 아카이브는 https://gitlab.com/gitlab-org/security-products/gemnasium-db/-/archive/master/gemnasium-db-master.tar.gz에 있습니다.

• .gitlab-ci.yml 파일을 업데이트합니다.

  데이터베이스의 로컬 복사본을 사용하도록 CI/CD 변수 GEMNASIUM_DB_LOCAL_PATH를 설정합니다.

  • 데이터베이스 업데이트를 비활성화하도록 CI/CD 변수 GEMNASIUM_DB_UPDATE_DISABLED를 설정합니다.

  • 스캔이 시작되기 전에 권고 데이터베이스를 다운로드하고 압축을 해제합니다.

variables:
  GEMNASIUM_DB_LOCAL_PATH: ./gemnasium-db-local
  GEMNASIUM_DB_UPDATE_DISABLED: "true"

dependency_scanning:
  before_script:
    - wget https://local.example.com/gemnasium_db.tar.gz
    - mkdir -p $GEMNASIUM_DB_LOCAL_PATH
    - tar -xzvf gemnasium_db.tar.gz --strip-components=1 -C $GEMNASIUM_DB_LOCAL_PATH

Gradle 프로젝트에서 프록시 사용#

Gradle wrapper 스크립트는 HTTP(S)_PROXY 환경 변수를 읽지 않습니다. 자세한 내용은 Gradle 이슈 11065를 참조하세요.

사전 요구사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한.

Gradle wrapper 스크립트가 프록시를 사용하도록 하려면:

• GRADLE_CLI_OPTS CI/CD 변수를 사용하여 프록시 옵션을 지정합니다.

variables:
  GRADLE_CLI_OPTS: "-Dhttps.proxyHost=squid-proxy -Dhttps.proxyPort=3128 -Dhttp.proxyHost=squid-proxy -Dhttp.proxyPort=3128 -Dhttp.nonProxyHosts=localhost"

Maven 프로젝트에서 프록시 사용#

Maven은 HTTP(S)_PROXY 환경 변수를 읽지 않습니다. 대신 Maven 설정 파일을 사용해야 합니다.

사전 요구사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한.

Maven 의존성 스캐너가 프록시를 사용하도록 구성하려면:

• 프로젝트 리포지터리에 mysettings.xml 파일을 생성합니다. 해당 파일에 Maven 프록시 설정을 구성합니다.

  프록시 구성을 지정하는 방법에 대한 자세한 내용은 Maven 문서를 참조하세요.

• 프로젝트의 .gitlab-ci.yml 파일에서 MAVEN_CLI_OPTS CI/CD 변수를 정의하여 설정 파일 mysettings.xml을 참조합니다.

variables:
  MAVEN_CLI_OPTS: "--settings mysettings.xml"

언어 및 패키지 관리자별 설정#

언어 및 패키지 관리자별 구성은 다음 섹션을 참조하세요.

Python (pip)#

분석기가 실행되기 전에 Python 패키지를 설치해야 하는 경우, 스캔 job의 before_script에서 pip install --user를 사용해야 합니다. --user 플래그를 사용하면 프로젝트 의존성이 사용자 디렉터리에 설치됩니다. --user 옵션을 전달하지 않으면 패키지가 전역으로 설치되어 스캔되지 않고 프로젝트 의존성 목록에 표시되지 않습니다.

Python (setuptools)#

분석기가 실행되기 전에 Python 패키지를 설치해야 하는 경우, 스캔 job의 before_script에서 python setup.py install --user를 사용해야 합니다. --user 플래그를 사용하면 프로젝트 의존성이 사용자 디렉터리에 설치됩니다. --user 옵션을 전달하지 않으면 패키지가 전역으로 설치되어 스캔되지 않고 프로젝트 의존성 목록에 표시되지 않습니다.

프라이빗 PyPi 리포지터리에 자체 서명 인증서를 사용하는 경우, 이전 .gitlab-ci.yml 템플릿 외에 추가 job 구성이 필요하지 않습니다. 하지만 프라이빗 리포지터리에 연결할 수 있도록 setup.py를 업데이트해야 합니다. 다음은 구성 예시입니다.

• install_requires 목록의 각 의존성에 대해 프라이빗 리포지터리를 가리키는 dependency_links 속성을 생성하도록 setup.py를 업데이트합니다.

install_requires=['pyparsing>=2.0.3'],
dependency_links=['https://pypi.example.com/simple/pyparsing'],

• 리포지터리 URL에서 인증서를 가져와 프로젝트에 추가합니다.

printf "\n" | openssl s_client -connect pypi.example.com:443 -servername pypi.example.com | sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p' > internal.crt

• 새로 다운로드한 인증서를 가리키도록 setup.py를 업데이트합니다.

import setuptools.ssl_support
setuptools.ssl_support.cert_paths = ['internal.crt']

Python (Pipenv)#

제한된 네트워크 연결 환경에서 실행하는 경우, 프라이빗 PyPi 미러를 사용하도록 PIPENV_PYPI_MIRROR 변수를 구성해야 합니다. 이 미러에는 기본 및 개발 의존성이 모두 포함되어야 합니다.

variables:
  PIPENV_PYPI_MIRROR: https://pypi.example.com/simple

또는, 프라이빗 레지스트리를 사용할 수 없는 경우 필요한 패키지를 Pipenv 가상 환경 캐시에 로드할 수 있습니다. 이 옵션의 경우 프로젝트는 Pipfile.lock을 리포지터리에 체크인하고 기본 및 개발 패키지를 모두 캐시에 로드해야 합니다. 이 작업을 수행하는 방법은 python-pipenv 프로젝트 예시를 참조하세요.

의존성 감지#

종속성 스캐닝은 리포지터리에서 사용되는 언어를 자동으로 감지합니다. 감지된 언어와 일치하는 모든 분석기가 실행됩니다. 일반적으로 분석기 선택을 커스터마이징할 필요가 없습니다. 최상의 커버리지를 위해 전체 선택이 자동으로 사용되도록 분석기를 지정하지 마세요. 이렇게 하면 사용 중단이나 제거가 있을 때 조정할 필요가 없습니다. 그러나 변수 DS_EXCLUDED_ANALYZERS를 사용하여 선택을 재정의할 수 있습니다.

언어 감지는 CI job rules에 의존하여 지원되는 의존성 파일을 감지합니다.

Java 및 Python의 경우, 지원되는 의존성 파일이 감지되면 종속성 스캐닝은 프로젝트를 빌드하고 일부 Java 또는 Python 명령을 실행하여 의존성 목록을 가져옵니다. 다른 모든 프로젝트의 경우, 잠금 파일을 파싱하여 먼저 프로젝트를 빌드하지 않고도 의존성 목록을 가져옵니다.

모든 직접 및 전이 의존성이 분석되며, 전이 의존성의 깊이에는 제한이 없습니다.

분석기#

종속성 스캐닝은 다음 공식 Gemnasium 기반 분석기를 지원합니다.

• gemnasium

• gemnasium-maven

• gemnasium-python

분석기는 Docker 이미지로 게시되며, 종속성 스캐닝은 이를 사용하여 각 분석을 위한 전용 컨테이너를 시작합니다. 사용자 정의 보안 스캐너를 통합할 수도 있습니다.

각 분석기는 새 버전의 Gemnasium이 릴리즈될 때마다 업데이트됩니다.

분석기가 의존성 정보를 얻는 방법#

GitLab 분석기는 다음 두 가지 방법 중 하나를 사용하여 의존성 정보를 가져옵니다.

• 잠금 파일 직접 파싱.

• 패키지 관리자 또는 빌드 도구를 실행하여 파싱 가능한 의존성 정보 파일 생성 후 파싱.

잠금 파일 파싱으로 의존성 정보 가져오기#

다음 패키지 관리자는 GitLab 분석기가 직접 파싱할 수 있는 잠금 파일을 사용합니다.

각주:

• NuGet 버전 2 잠금 파일에 대한 지원은 GitLab 16.2에서 도입되었습니다.

• Yarn 버전 4에 대한 지원은 GitLab 16.11에서 도입되었습니다.

Yarn Berry에 대해 다음 기능은 지원되지 않습니다.

워크스페이스

• yarn patch

패치, 워크스페이스 또는 두 가지 모두를 포함하는 Yarn 파일은 여전히 처리되지만 이러한 기능은 무시됩니다.

패키지 관리자를 실행하여 파싱 가능한 파일 생성으로 의존성 정보 가져오기#

다음 패키지 관리자를 지원하기 위해 GitLab 분석기는 두 단계로 진행합니다.

• 패키지 관리자 또는 특정 작업을 실행하여 의존성 정보를 내보냅니다.

• 내보낸 의존성 정보를 파싱합니다.

각주:

• 이 테스트는 .tool-versions 파일에 지정된 기본 maven 버전을 사용합니다.

• Java 버전마다 다른 Gradle 버전이 필요합니다. 이전 표에 나열된 Gradle 버전은 분석기 이미지에 사전 설치되어 있습니다. 분석기가 사용하는 Gradle 버전은 프로젝트에 gradlew(Gradle wrapper) 파일이 있는지 여부에 따라 다릅니다.

  프로젝트에 gradlew 파일이 없는 경우, 분석기는 DS_JAVA_VERSION 변수(기본 버전은 17)에 지정된 Java 버전을 기반으로 사전 설치된 Gradle 버전 중 하나로 자동 전환됩니다.

  Java 8 및 11 버전의 경우 Gradle 6.7.1이 자동으로 선택되고, Java 17은 Gradle 7.6.4를 사용하며, Java 21은 Gradle 8.8을 사용합니다.

• 프로젝트에 gradlew 파일이 있는 경우, 분석기 이미지에 사전 설치된 Gradle 버전은 무시되고 gradlew 파일에 지정된 버전이 대신 사용됩니다.

• 이 테스트는 Pipfile.lock 파일이 발견되면 Gemnasium이 해당 파일에 나열된 정확한 패키지 버전을 스캔하는 데 사용함을 확인합니다.

• go build 구현 때문에, Go 빌드 프로세스는 네트워크 액세스, go mod download를 사용한 사전 로드된 mod 캐시, 또는 벤더링된 의존성이 필요합니다. 자세한 내용은 패키지 및 의존성 컴파일에 관한 Go 문서를 참조하세요.

분석기 트리거 방식#

GitLab은 rules:exists에 의존하여 리포지터리에 존재하는 지원 파일로 감지된 언어에 대한 관련 분석기를 시작합니다. 리포지터리 루트에서 최대 두 디렉터리 수준까지 검색합니다. 예를 들어, gemnasium-dependency_scanning job은 리포지터리에 Gemfile, api/Gemfile, 또는 api/client/Gemfile이 포함된 경우 활성화되지만, 유일한 지원 의존성 파일이 api/v1/client/Gemfile인 경우에는 활성화되지 않습니다.

여러 파일 처리 방법#

여러 파일을 스캔하는 동안 문제가 발생한 경우, 이 이슈에 댓글을 남겨 주세요.

Python#

GitLab은 requirements 파일 또는 잠금 파일이 감지된 디렉터리에서 하나의 설치만 실행합니다. 의존성은 감지된 첫 번째 파일에 대해서만 gemnasium-python에 의해 분석됩니다. 파일은 다음 순서로 검색됩니다.

• Pip를 사용하는 프로젝트의 경우 requirements.txt, requirements.pip, 또는 requires.txt.

• Pipenv를 사용하는 프로젝트의 경우 Pipfile 또는 Pipfile.lock.

• Poetry를 사용하는 프로젝트의 경우 poetry.lock.

• Setuptools를 사용하는 프로젝트의 경우 setup.py.

검색은 루트 디렉터리에서 시작하고 루트 디렉터리에서 빌드가 발견되지 않으면 하위 디렉터리로 계속됩니다. 따라서 루트 디렉터리의 Poetry 잠금 파일이 하위 디렉터리의 Pipenv 파일보다 먼저 감지됩니다.

Java 및 Scala#

GitLab은 빌드 파일이 감지된 디렉터리에서 하나의 빌드만 실행합니다. 여러 Gradle, Maven, sbt 빌드 또는 이들의 조합을 포함하는 대규모 프로젝트의 경우, gemnasium-maven은 감지된 첫 번째 빌드 파일의 의존성만 분석합니다. 빌드 파일은 다음 순서로 검색됩니다.

• 단일 또는 멀티 모듈 Maven 프로젝트의 경우 pom.xml.

• 단일 또는 멀티 프로젝트 Gradle 빌드의 경우 build.gradle 또는 build.gradle.kts.

• 단일 또는 멀티 프로젝트 sbt 빌드의 경우 build.sbt.

검색은 루트 디렉터리에서 시작하고 루트 디렉터리에서 빌드가 발견되지 않으면 하위 디렉터리로 계속됩니다. 따라서 루트 디렉터리의 sbt 빌드 파일이 하위 디렉터리의 Gradle 빌드 파일보다 먼저 감지됩니다. 멀티 모듈 Maven 프로젝트 및 멀티 프로젝트 Gradle 및 sbt 빌드의 경우, 하위 모듈 및 하위 프로젝트 파일은 상위 빌드 파일에 선언된 경우 분석됩니다.

JavaScript#

다음 분석기가 실행되며, 각 분석기는 여러 파일을 처리할 때 동작이 다릅니다.

• Gemnasium

  여러 잠금 파일을 지원합니다.

• Retire.js

  여러 잠금 파일을 지원하지 않습니다. 여러 잠금 파일이 있는 경우, Retire.js는 알파벳 순서로 디렉터리 트리를 탐색하면서 발견한 첫 번째 잠금 파일을 분석합니다.

gemnasium 분석기 스캔은 벤더링된 라이브러리(패키지 관리자에서 관리하지 않고 프로젝트에 체크인된 라이브러리)에 대한 JavaScript 프로젝트를 지원합니다.

Go#

여러 파일이 지원됩니다. go.mod 파일이 감지되면 분석기는 최소 버전 선택을 사용하여 빌드 목록을 생성하려고 합니다. 이 작업이 실패하면 분석기는 대신 go.mod 파일 내의 의존성을 파싱하려고 합니다.

필수 요구사항으로 go.mod 파일은 go mod tidy 명령을 사용하여 정리되어야 의존성이 올바르게 관리됩니다. 이 프로세스는 감지된 모든 go.mod 파일에 대해 반복됩니다.

PHP, C, C++, .NET, C#, Ruby, JavaScript#

이러한 언어의 분석기는 여러 잠금 파일을 지원합니다.

추가 언어 지원#

추가 언어, 패키지 관리자 및 의존성 파일에 대한 지원은 다음 이슈에서 추적 중입니다.

경고#

모든 컨테이너의 최신 버전과 모든 패키지 관리자 및 언어의 최신 지원 버전을 사용하세요. 이전 버전을 사용하면 지원되지 않는 버전이 더 이상 활성 보안 보고 및 보안 수정의 백포팅 혜택을 받지 못할 수 있으므로 보안 위험이 증가합니다.

Gradle 프로젝트#

Gradle 프로젝트의 HTML 의존성 보고서를 생성할 때 reports.html.destination 또는 reports.html.outputLocation 속성을 재정의하지 마세요. 이렇게 하면 종속성 스캐닝이 올바르게 작동하지 않습니다.

Maven 프로젝트#

격리된 네트워크에서 중앙 리포지터리가 프라이빗 레지스트리(<mirror> 지시자로 명시적으로 설정된 경우)인 경우, Maven 빌드가 gemnasium-maven-plugin 의존성을 찾지 못할 수 있습니다. 이 문제는 Maven이 기본적으로 로컬 리포지터리(/root/.m2)를 검색하지 않고 중앙 리포지터리에서 가져오려고 시도하기 때문에 발생합니다. 결과적으로 누락된 의존성에 대한 오류가 발생합니다.

해결 방법#

이 문제를 해결하려면 settings.xml 파일에 <pluginRepositories> 섹션을 추가하세요. 이렇게 하면 Maven이 로컬 리포지터리에서 플러그인을 찾을 수 있습니다.

시작하기 전에 다음 사항을 고려하세요.

• 이 해결 방법은 기본 Maven 중앙 리포지터리가 프라이빗 레지스트리에 미러링된 환경에서만 사용됩니다.

• 이 해결 방법을 적용하면 Maven이 플러그인을 위해 로컬 리포지터리를 검색하므로 일부 환경에서 보안 영향이 있을 수 있습니다. 이것이 조직의 보안 정책에 부합하는지 확인하세요.

사전 요구사항:

• 프로젝트에 대한 Maintainer 또는 Owner 권한.

settings.xml 파일을 수정하려면 다음 단계를 따르세요.

• Maven settings.xml 파일을 찾습니다. 이 파일은 일반적으로 다음 위치 중 하나에 있습니다.

  루트 사용자의 경우 /root/.m2/settings.xml.

  • 일반 사용자의 경우 ~/.m2/settings.xml.

  • 전역 설정의 경우 ${maven.home}/conf/settings.xml.

• 파일에 기존 <pluginRepositories> 섹션이 있는지 확인합니다.

• <pluginRepositories> 섹션이 이미 있는 경우 내부에 다음 <pluginRepository> 요소만 추가합니다. 그렇지 않으면 전체 <pluginRepositories> 섹션을 추가합니다.

  <pluginRepositories>
    <pluginRepository>
        <id>local2</id>
        <name>local repository</name>
        <url>file:///root/.m2/repository/</url>
    </pluginRepository>
  </pluginRepositories>

• Maven 빌드 또는 종속성 스캐닝 프로세스를 다시 실행합니다.

Python 프로젝트#

CVE-2018-20225에 문서화된 가능한 익스플로잇으로 인해 PIP_EXTRA_INDEX_URL 환경 변수를 사용할 때는 특별한 주의가 필요합니다.

pip(모든 버전)에서 문제가 발견되었습니다. pip는 사용자가 프라이빗 인덱스에서 프라이빗 패키지를 얻으려고 했더라도 가장 높은 버전 번호를 가진 버전을 설치합니다. 이는 PIP_EXTRA_INDEX_URL 옵션을 사용할 때만 영향을 미치며, 악용하려면 해당 패키지가 공개 인덱스에 이미 존재하지 않아야 합니다(따라서 공격자가 임의의 버전 번호로 패키지를 거기에 올릴 수 있습니다).

버전 번호 파싱#

경우에 따라 프로젝트 의존성의 버전이 보안 권고의 영향 범위에 있는지 확인하지 못할 수 있습니다.

예를 들어:

• 버전을 알 수 없는 경우.

• 버전이 유효하지 않은 경우.

• 버전 파싱 또는 범위 비교에 실패한 경우.

• 버전이 dev-master 또는 1.5.x와 같은 브랜치인 경우.

• 비교되는 버전이 모호한 경우. 예를 들어, 1.0.0-20241502는 하나의 버전에는 타임스탬프가 포함되고 다른 버전에는 없으므로 1.0.0-2와 비교할 수 없습니다.

이 경우 분석기는 해당 의존성을 건너뛰고 로그에 메시지를 출력합니다.

GitLab 분석기는 오탐(false positive) 또는 미탐(false negative)이 발생할 수 있으므로 가정을 하지 않습니다. 자세한 내용은 이슈 442027을 참조하세요.

Swift 프로젝트 빌드#

Swift Package Manager(SPM)는 Swift 코드의 배포를 관리하는 공식 도구입니다. 의존성 다운로드, 컴파일, 링크 프로세스를 자동화하기 위해 Swift 빌드 시스템에 통합되어 있습니다.

SPM으로 Swift 프로젝트를 빌드할 때 다음 모범 사례를 따르세요.

• Package.resolved 파일을 포함합니다.

  Package.resolved 파일은 의존성을 특정 버전으로 잠급니다. 다양한 환경에서 일관성을 보장하기 위해 항상 이 파일을 리포지터리에 커밋하세요.

git add Package.resolved
git commit -m "Add Package.resolved to lock dependencies"

• Swift 프로젝트를 빌드하려면 다음 명령을 사용합니다.

# Update dependencies
swift package update

# Build the project
swift build

• CI/CD를 구성하려면 .gitlab-ci.yml 파일에 다음 단계를 추가합니다.

swift-build:
  stage: build
  script:
    - swift package update
    - swift build

• 선택사항. 자체 서명 인증서가 있는 프라이빗 Swift 패키지 리포지터리를 사용하는 경우, 프로젝트에 인증서를 추가하고 Swift가 신뢰하도록 구성해야 할 수 있습니다.

  인증서를 가져옵니다.

echo | openssl s_client -servername your.repo.url -connect your.repo.url:443 | sed -ne '/-BEGIN CERTIFICATE-/,/-END
CERTIFICATE-/p' > repo-cert.crt

• Swift 패키지 매니페스트(Package.swift)에 다음 줄을 추가합니다.

import Foundation

#if canImport(Security)
import Security
#endif

extension Package {
    public static func addCustomCertificate() {
        guard let certPath = Bundle.module.path(forResource: "repo-cert", ofType: "crt") else {
            fatalError("Certificate not found")
        }
        SecCertificateAddToSystemStore(SecCertificateCreateWithData(nil, try! Data(contentsOf: URL(fileURLWithPath: certPath)) as CFData)!)
    }
}

// Call this before defining your package
Package.addCustomCertificate()

깨끗한 환경에서 빌드 프로세스를 항상 테스트하여 의존성이 올바르게 지정되고 자동으로 해결되는지 확인하세요.

CocoaPods 프로젝트 빌드#

CocoaPods는 Swift 및 Objective-C Cocoa 프로젝트를 위한 인기 있는 패키지 관리자입니다. iOS, macOS, watchOS, tvOS 프로젝트에서 외부 라이브러리를 관리하기 위한 표준 형식을 제공합니다.

CocoaPods를 사용하는 프로젝트를 빌드할 때 다음 모범 사례를 따르세요.

• Podfile.lock 파일을 포함합니다.

  Podfile.lock 파일은 의존성을 특정 버전으로 잠그는 데 중요합니다. 다양한 환경에서 일관성을 보장하기 위해 항상 이 파일을 리포지터리에 커밋하세요.

git add Podfile.lock
git commit -m "Add Podfile.lock to lock CocoaPods dependencies"

• 다음 중 하나를 사용하여 프로젝트를 빌드할 수 있습니다.

  xcodebuild 명령줄 도구:

# Install CocoaPods dependencies
pod install

# Build the project
xcodebuild -workspace YourWorkspace.xcworkspace -scheme YourScheme build

• Xcode IDE:

  .xcworkspace 파일을 Xcode에서 엽니다.

  • 타깃 구성표를 선택합니다.

  • Product > Build를 선택합니다. Control+B를 눌러도 됩니다.

• iOS 및 Android 앱의 빌드와 릴리즈를 자동화하는 도구인 fastlane:

  fastlane을 설치합니다.

sudo gem install fastlane

• 프로젝트에서 fastlane을 구성합니다.

fastlane init

• fastfile에 레인을 추가합니다.

lane :build do
  cocoapods
  gym(scheme: "YourScheme")
end

• 빌드를 실행합니다.

fastlane build

• 프로젝트가 CocoaPods와 Carthage를 모두 사용하는 경우 Carthage를 사용하여 의존성을 빌드할 수 있습니다.

  CocoaPods 의존성을 포함하는 Cartfile을 생성합니다.

• 다음을 실행합니다.

carthage update --platform iOS

• 선호하는 방법에 따라 프로젝트를 빌드하도록 CI/CD를 구성합니다.

  예를 들어, xcodebuild 사용:

cocoapods-build:
  stage: build
  script:
    - pod install
    - xcodebuild -workspace YourWorkspace.xcworkspace -scheme YourScheme build

• 선택사항. 프라이빗 CocoaPods 리포지터리를 사용하는 경우 프로젝트가 액세스하도록 구성해야 할 수 있습니다.

  프라이빗 spec 리포지터리를 추가합니다.

pod repo add REPO_NAME SOURCE_URL

• Podfile에서 소스를 지정합니다.

source 'https://github.com/CocoaPods/Specs.git'
source 'SOURCE_URL'

• 선택사항. 프라이빗 CocoaPods 리포지터리에서 SSL을 사용하는 경우 SSL 인증서가 올바르게 구성되어 있는지 확인합니다.

  자체 서명 인증서를 사용하는 경우 시스템의 신뢰할 수 있는 인증서에 추가합니다. .netrc 파일에서 SSL 구성을 지정할 수도 있습니다.

machine your.private.repo.url
  login your_username
  password your_password

• Podfile을 업데이트한 후 pod install을 실행하여 의존성을 설치하고 워크스페이스를 업데이트합니다.

Podfile을 업데이트한 후 항상 pod install을 실행하여 모든 의존성이 올바르게 설치되고 워크스페이스가 업데이트되었는지 확인하세요.

취약점 데이터베이스에 기여#

취약점을 찾으려면 GitLab 권고 데이터베이스를 검색할 수 있습니다. 새 취약점을 제출할 수도 있습니다.