지원되는 아키텍처#

운영 컨테이너 스캔(OCS)은 linux/arm64 및 linux/amd64를 지원합니다.

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

OCS를 사용하여 클러스터의 컨테이너 이미지에서 보안 취약점을 스캔할 수 있습니다. 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 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 보고서 크기를 구성합니다.