히스토리

• GitLab 15.4에서 starboard 지시자가 더 이상 사용 중단됨. starboard 지시자는 GitLab 16.0에서 제거될 예정입니다.

지원되는 아키텍처#

GitLab agent for Kubernetes 16.10.0 이상 및 GitLab agent Helm Chart 1.25.0 이상에서 운영 컨테이너 스캔(OCS)은 linux/arm64 및 linux/amd64를 지원합니다. 이전 버전에서는 linux/amd64만 지원됩니다.

운영 컨테이너 스캔 활성화#

OCS를 사용하여 클러스터의 컨테이너 이미지에서 보안 취약점을 스캔할 수 있습니다. GitLab agent for Kubernetes 16.9 이상에서 OCS는 이미지에서 취약점을 스캔하기 위해 Trivy를 감싼 래퍼 이미지를 사용합니다. GitLab 16.9 이전에는 OCS가 Trivy 이미지를 직접 사용했습니다.

OCS는 agent config 또는 프로젝트의 스캔 실행 정책을 사용하여 일정에 따라 실행하도록 구성할 수 있습니다.

에이전트 구성을 통해 활성화#

에이전트 구성을 통해 Kubernetes 클러스터 내의 이미지 스캔을 활성화하려면 스캔이 실행될 시기를 나타내는 CRON 표현식이 있는 cadence 필드와 함께 에이전트 구성에 container_scanning 구성 블록을 추가합니다.

container_scanning:
  cadence: '0 0 * * *' # Daily at 00:00 (Kubernetes cluster time)

cadence 필드는 필수입니다. GitLab은 cadence 필드에 대해 다음 유형의 CRON 구문을 지원합니다:

• 지정된 시간에 하루에 한 번의 일일 cadence. 예: 0 18 * * *
• 지정된 요일 및 시간에 일주일에 한 번의 주간 cadence. 예: 0 13 * * 0

기본적으로 운영 컨테이너 스캔은 취약점을 위한 어떠한 워크로드도 스캔하지 않습니다. 스캔할 네임스페이스를 선택하는 데 사용할 수 있는 namespaces 필드와 함께 vulnerability_report 블록을 설정할 수 있습니다. 예를 들어 default, kube-system 네임스페이스만 스캔하려면 다음 구성을 사용할 수 있습니다:

container_scanning:
  cadence: '0 0 * * *'
  vulnerability_report:
    namespaces:
      - default
      - kube-system

모든 대상 네임스페이스에 대해 다음 워크로드 리소스의 모든 이미지가 기본적으로 스캔됩니다:

• Pod
• ReplicaSet
• ReplicationController
• StatefulSet
• DaemonSet
• CronJob
• Job

Trivy Kubernetes 리소스 감지 구성으로 이를 사용자 정의할 수 있습니다.

스캔 실행 정책을 통해 활성화#

스캔 실행 정책을 사용하여 Kubernetes 클러스터의 이미지 스캔을 활성화하려면 스캔 실행 정책 편집기를 사용하여 새 일정 규칙을 생성합니다.

운영 컨테이너 스캔은 GitLab 파이프라인과 독립적으로 작동합니다. 완전히 자동화되어 있으며 스캔 실행 정책에 구성된 예약된 시간에 새 스캔을 시작하는 Kubernetes 에이전트에 의해 관리됩니다. 에이전트는 스캔을 수행하고 결과를 GitLab에 다시 보고하기 위해 클러스터 내에 전용 Job을 생성합니다.

Kubernetes 에이전트가 연결된 클러스터 내에서 운영 컨테이너 스캔을 활성화하는 정책 예시:

- name: Enforce container scanning in cluster connected through my-gitlab-agent for default and kube-system namespaces
  enabled: true
  rules:
  - type: schedule
    cadence: '0 10 * * *'
    agents:
      <agent-name>:
        namespaces:
        - 'default'
        - 'kube-system'
  actions:
  - scan: container_scanning

일정 규칙의 키는 다음과 같습니다:

• cadence (필수): 스캔이 실행될 시기를 나타내는 CRON 표현식
• agents:<agent-name> (필수): 스캔에 사용할 에이전트 이름
• agents:<agent-name>:namespaces (필수): 스캔할 Kubernetes 네임스페이스.

스캔 실행 정책 문서 내에서 전체 스키마를 볼 수 있습니다.

멀티 클러스터 구성에 대한 OCS 취약점 해결#

OCS를 사용한 정확한 취약점 추적을 보장하려면 OCS가 활성화된 각 클러스터에 대해 별도의 GitLab 프로젝트를 생성해야 합니다. 여러 클러스터가 있는 경우 각 클러스터에 하나의 프로젝트를 사용해야 합니다.

OCS는 각 스캔 후 현재 스캔 취약점을 이전에 감지된 취약점과 비교하여 클러스터에서 더 이상 발견되지 않는 취약점을 해결합니다. 현재 스캔에 더 이상 없는 이전 스캔의 취약점은 GitLab 프로젝트에서 해결됩니다.

동일한 프로젝트에 여러 클러스터가 구성된 경우 한 클러스터(예: 프로젝트 A)의 OCS 스캔이 다른 클러스터(예: 프로젝트 B)에서 이전에 감지된 취약점을 해결하여 잘못된 취약점 보고가 발생할 수 있습니다.

스캐너 리소스 요구 사항 구성#

기본적으로 스캐너 파드의 기본 리소스 요구 사항은 다음과 같습니다:

requests:
  cpu: 100m
  memory: 100Mi
  ephemeral_storage: 1Gi
limits:
  cpu: 500m
  memory: 500Mi
  ephemeral_storage: 3Gi

resource_requirements 필드로 사용자 정의할 수 있습니다.

container_scanning:
  resource_requirements:
    requests:
      cpu: '0.2'
      memory: 200Mi
      ephemeral_storage: 2Gi
    limits:
      cpu: '0.7'
      memory: 700Mi
      ephemeral_storage: 4Gi

CPU에 소수 값을 사용하는 경우 값을 문자열로 형식 지정합니다.

Trivy K8s Wrapper용 사용자 정의 저장소#

스캔 중에 OCS는 Trivy K8s Wrapper 저장소의 이미지를 사용하여 파드를 배포합니다. 이 파드는 Trivy Kubernetes에서 생성된 취약점 보고서를 OCS로 전송합니다.

클러스터의 방화벽이 Trivy K8s Wrapper 저장소에 대한 접근을 제한하는 경우 사용자 정의 저장소에서 이미지를 가져오도록 OCS를 구성할 수 있습니다. 호환성을 위해 사용자 정의 저장소가 Trivy K8s Wrapper 저장소를 미러링하는지 확인합니다.

container_scanning:
  trivy_k8s_wrapper_image:
    repository: "your-custom-registry/your-image-path"

스캔 타임아웃 구성#

히스토리

• GitLab 17.7에서 도입됨.

기본적으로 Trivy 스캔은 5분 후에 타임아웃됩니다. 에이전트 자체는 연결된 구성 맵을 읽고 취약점을 전송하는 데 추가로 15분을 제공합니다.

Trivy 타임아웃 기간을 사용자 정의하려면:

• scanner_timeout 필드에 초 단위로 기간을 지정합니다.

예시:

container_scanning:
  scanner_timeout: "3600s" # 60 minutes

Trivy 보고서 크기 구성#

히스토리

• GitLab 17.7에서 도입됨.

기본적으로 Trivy 보고서는 대부분의 스캔에 충분한 100 MB로 제한됩니다. 그러나 많은 워크로드가 있는 경우 한도를 늘려야 할 수 있습니다.

이렇게 하려면:

• report_max_size 필드에 바이트 단위로 한도를 지정합니다.

예시:

container_scanning:
  report_max_size: "300000000" # 300 MB

Trivy Kubernetes 리소스 감지 구성#

히스토리

• GitLab 17.9에서 도입됨.

기본적으로 Trivy는 다음 Kubernetes 리소스 유형을 찾아 스캔 가능한 이미지를 검색합니다:

• Pod
• ReplicaSet
• ReplicationController
• StatefulSet
• DaemonSet
• CronJob
• Job
• Deployment

예를 들어 "활성" 이미지만 스캔하기 위해 Trivy가 검색하는 Kubernetes 리소스 유형을 제한할 수 있습니다.

이렇게 하려면:

• resource_types 필드로 리소스 유형을 지정합니다:

  container_scanning:
    vulnerability_report:
      resource_types:
        - Deployment
        - Pod
        - Job
  

Trivy 보고서 아티팩트 삭제 구성#

히스토리

• GitLab 17.9에서 도입됨.

기본적으로 Kubernetes용 GitLab 에이전트는 스캔이 완료된 후 Trivy 보고서 아티팩트를 삭제합니다.

원시 상태로 보고서를 볼 수 있도록 에이전트가 보고서 아티팩트를 보존하도록 구성할 수 있습니다.

이렇게 하려면:

• delete_report_artifact를 false로 설정합니다:

  container_scanning:
    delete_report_artifact: false
  

Trivy 심각도 임계값 필터 구성#

히스토리

• GitLab 18.4에서 도입됨.

OCS는 기본적으로 모든 심각도 수준의 취약점을 스캔합니다.

특정 심각도 수준 이상의 취약점만 보고하려면 구성 변수 severity_threshold를 해당 값으로 설정합니다. 심각도 임계값을 설정한 후 선택한 심각도 미만의 취약점은 더 이상 취약점 보고서, API 페이로드 및 기타 보고 메커니즘에 반환되지 않습니다.

이를 통해 조직의 위험 허용 기준을 충족하는 취약점에 집중할 수 있습니다.

지원되는 임계값 값은 UNKNOWN, LOW, MEDIUM, HIGH, CRITICAL입니다.

예를 들어 높음 및 심각 심각도의 취약점을 보고하려면:

container_scanning:
  severity_threshold: "HIGH"

클러스터 취약점 보기#

GitLab에서 취약점 정보를 보려면:

1. 상단 표시줄에서 검색 또는 이동을 선택하고 에이전트 구성 파일이 포함된 프로젝트를 찾습니다.
2. 운영 > Kubernetes 클러스터를 선택합니다.
3. 에이전트 탭을 선택합니다.
4. 에이전트를 선택하여 클러스터 취약점을 봅니다.

이 정보는 운영 취약점에서도 찾을 수 있습니다.

비공개 이미지 스캔#

히스토리

• GitLab 16.4에서 도입됨.

비공개 이미지를 스캔하기 위해 스캐너는 이미지 풀 시크릿(직접 참조 및 서비스 계정에서)에 의존하여 이미지를 가져옵니다.

알려진 이슈#

GitLab agent for Kubernetes 16.9 이상에서 운영 컨테이너 스캔:

• 최대 100 MB의 Trivy 보고서를 처리합니다. 이전 릴리스에서는 이 한도가 10 MB입니다.
• GitLab agent for Kubernetes가 fips 모드에서 실행될 때 비활성화됩니다.

트러블슈팅#

Error running Trivy scan. Container terminated reason: OOMKilled#

스캔할 리소스가 너무 많거나 스캔 중인 이미지가 큰 경우 OCS가 OOM 오류로 실패할 수 있습니다.

이를 해결하려면 사용 가능한 메모리 양을 늘리기 위해 리소스 요구 사항을 구성합니다.

Pod ephemeral local storage usage exceeds the total limit of containers#

기본 임시 스토리지가 낮은 Kubernetes 클러스터에서 OCS 스캔이 실패할 수 있습니다. 예를 들어 GKE 오토파일럿은 기본 임시 스토리지를 1 GB로 설정합니다. 이는 큰 이미지로 네임스페이스를 스캔할 때 OCS에 필요한 모든 데이터를 저장하기에 충분한 공간이 없을 수 있으므로 OCS에 문제가 됩니다.

이를 해결하려면 사용 가능한 임시 스토리지 양을 늘리기 위해 리소스 요구 사항을 구성합니다.

이 문제를 나타내는 다른 메시지는 다음과 같습니다: OCS Scanning pod evicted due to low resources. Please configure higher resource limits.

Error running Trivy scan due to context timeout#

Trivy가 스캔을 완료하는 데 너무 오래 걸리는 경우 OCS가 스캔을 완료하지 못할 수 있습니다. 기본 스캔 타임아웃은 5분이며 에이전트가 결과를 읽고 취약점을 전송하는 데 추가로 15분이 있습니다.

이를 해결하려면 사용 가능한 메모리 양을 늘리기 위해 스캐너 타임아웃을 구성합니다.

trivy report size limit exceeded#

생성된 Trivy 보고서 크기가 기본 최대 한도보다 큰 경우 OCS가 이 오류로 실패할 수 있습니다.

이를 해결하려면 허용되는 Trivy 보고서의 최대 크기를 늘리기 위해 최대 Trivy 보고서 크기를 구성합니다.