Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

아티팩트 보호 정책 구성

이 문서에서는 아티팩트 보호 정책을 만들고 관리하는 방법을 설명합니다. 서비스, 기능, 이점에 대한 개요는 아티팩트 보호 개요를 참고하세요.

시작하기 전에

아티팩트 보호 정책을 만들려면 먼저 Security Command Center에서 아티팩트 보호를 사용 설정하고 필요한 Identity and Access Management (IAM) 역할과 권한을 획득해야 합니다.

그런 다음 Google Cloud 콘솔에서 또는 Google Cloud CLI를 사용하여 정책을 만들 수 있습니다.

아티팩트 보호 사용 설정

Security Command Center 서비스 구성의 단계에 따라 아티팩트 보호를 사용 설정합니다.

필요한 역할

아티팩트 보호를 사용하는 데 필요한 권한을 얻으려면 관리자에게 프로젝트 또는 조직에 대한 다음 Identity and Access Management (IAM) 역할을 부여해 달라고 요청하세요.

Artifact Scan Guard 평가 관리자 (roles/artifactscanguard.policyEvaluator)

이 역할은 Google Cloud 콘솔을 사용하거나 다음 Google Cloud CLI 명령어를 실행하여 부여할 수 있습니다.

프로젝트

  gcloud organizations add-iam-policy-binding PROJECT_ID \
        --member="serviceAccount:YOUR_SERVICE_ACCOUNT_EMAIL" \
        --role="roles/artifactscanguard.policyEvaluator" \

다음을 바꿉니다.

PROJECT_ID
YOUR_SERVICE_ACCOUNT_EMAIL

조직

  gcloud organizations add-iam-policy-binding ORGANIZATION_ID \
        --member="serviceAccount:YOUR_SERVICE_ACCOUNT_EMAIL" \
        --role="roles/artifactscanguard.policyEvaluator" \

다음을 바꿉니다.

ORGANIZATION_ID
YOUR_SERVICE_ACCOUNT_EMAIL

역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

아티팩트 보호 역할에 대한 자세한 내용은 아티팩트 보호 역할 및 권한을 참고하세요.

Google Cloud 콘솔에서 정책 만들기

Google Cloud 콘솔에서 아티팩트 보호 정책을 만들려면 다음 단계를 따르세요.

Google Cloud 콘솔에서 보안 > 규칙으로 이동하여 아티팩트 보호 정책 만들기 또는 정책 만들기를 클릭합니다.
정책의 정책 ID와 설명을 입력한 다음 계속을 클릭합니다.
정책 범위 및 작업을 선택합니다.
- CI/CD 플랫폼
  - 커넥터 선택: 이 정책과 연결해야 하는 커넥터입니다. 선택한 커넥터와 연결된 모든 CI/CD 빌드에 대해 이 정책이 평가됩니다.
  도움말: 아직 커넥터를 만들지 않은 경우 커넥터 관리를 클릭하여 CI/CD 통합 페이지를 엽니다. CI/CD 환경에 대한 커넥터를 만든 후 정책 만들기 페이지로 돌아가 새로고침을 클릭하여 커넥터 옵션을 새로고침합니다.
  - 정책 작업: 정책 위반 시 취할 조치를 선택합니다.
    - 정책을 준수하지 않는 빌드 차단
    - 알림이 있는 빌드 통과: 연결된 빌드 파이프라인에 CI/CD 스캐너 정책 평가 결과가 표시됩니다.
- 레지스트리
  - 컨테이너 분석 프로젝트: 조직에만 적용되며 프로젝트에는 적용되지 않습니다. 이 정책을 적용할 Google Cloud 프로젝트를 추가합니다.
  - Artifact Registry 저장소: 이 정책을 적용할 저장소를 선택합니다. 유효한 Artifact Registry 저장소여야 합니다. 비워 두면 정책이 모든 저장소에 적용됩니다.
  - 정책 작업: 정책 위반 시 취할 조치를 선택합니다.
    - 감사 전용: 정책이 평가되고 위반사항이 리소스를 차단하지 않고 감사 목적으로 로깅됩니다. 위반사항을 확인하려면 ListArtifactPoliciesEvaluations 및 GetArtifactPoliciesEvaluation을 사용하여 API를 호출해야 합니다.
    - 허용 제어: 정책이 평가되는 동안 위반이 발생하면 리소스가 진행되지 않도록 차단됩니다.
      - Binary Authorization 정책을 테스트 실행 모드로 설정: 자세한 내용은 테스트 실행 모드 사용 설정을 참고하세요.
      - Binary Authorization 프로젝트: 프로젝트가 아닌 조직에만 적용됩니다. Google Cloud 승인 제어를 적용할 프로젝트를 추가합니다.
      - GKE 클러스터: 비워 두면 모든 GKE 클러스터에 허용 제어가 적용됩니다.
      - Binary Authorization 정책 재정의: 승인 제어를 위한 Binary Authorization 정책을 업데이트하려면 이 체크박스를 선택해야 합니다.
- 런타임
  - 런타임 프로젝트: 이는 프로젝트가 아닌 조직에만 적용됩니다. GKE 클러스터가 포함된 런타임 프로젝트를 추가합니다.
  - GKE 클러스터: 이 정책을 적용할 GKE 클러스터를 선택합니다. 비워 두면 선택한 프로젝트의 모든 GKE 클러스터에 정책이 적용됩니다.
정책 규칙을 정의합니다. 정책 규칙은 환경에서 허용되는 취약점과 패키지를 결정하는 기준입니다. 정책 규칙에는 다음이 포함됩니다.
- 심각도 기준: 정책 평가에 포함될 취약점의 최소 심각도 수준을 설정합니다. 취약점이 이 기준점을 충족하거나 초과해야 포함됩니다.
  
  예를 들어 규칙을 Medium으로 구성하면 평가에 모든 Medium, High, Critical 취약점이 포함됩니다.
- 취약점 수 기준: 다른 정책 필터가 적용된 후 허용되는 최대 취약점 수를 설정합니다. 이러한 특정 필터링된 취약점의 수가 한도를 초과하는 경우에만 정책이 위반됩니다.
  
  예를 들어 심각도 기준을 높음으로 설정하고, 수정사항이 없는 취약점을 제외하고, 개수 기준을 5로 설정하면 높음 또는 심각으로 평가된 수정 가능한 취약점이 5개를 초과하는 경우 빌드가 실패합니다.
- 취약점 상태: 수정사항이 제공되는 취약점만 포함할지 여부를 지정합니다. 이를 통해 모든 취약점 또는 수정 가능한 취약점만 타겟팅하여 우선순위에 따라 해결할 수 있습니다.
- 예외 및 제한사항: 이 섹션에서는 일반 정책을 재정의하는 특정 허용 또는 차단을 만들 수 있습니다.
  - 제외된 CVE: 지정된 기간 동안 사용자 환경에서 허용되는 것으로 간주되는 CVE를 지정합니다. 이는 임시 해결 방법을 구현하는 데 유용합니다. 이러한 예외의 만료일을 설정할 수 있습니다. 이 날짜 이후에는 취약점이 더 이상 허용되지 않으며 정책이 실패합니다.
  - 제한된 CVE: 심각도 등급과 관계없이 항상 차단할 CVE를 지정합니다. 이는 특정 애플리케이션이나 인프라에 고유한 위험을 나타내는 취약점을 표시하는 데 특히 유용합니다.
  - 허용된 패키지: 보안으로 간주되는 패키지를 나열합니다. 패키지 버전을 정의할 수 있습니다. 그렇지 않으면 모든 버전이 허용됩니다.
  - 제한된 패키지: 제한할 패키지를 나열합니다. 제한된 패키지로 인해 정책이 실패합니다. 패키지 버전을 정의할 수 있습니다. 그렇지 않으면 모든 버전이 제한됩니다.
만들기를 클릭합니다.

사용 가능한 아티팩트 보호 정책은 규칙 페이지의 표에 나열됩니다.

Google Cloud CLI를 사용하여 정책 만들기

이 섹션에서는 아티팩트 보호에 사용할 수 있는 gcloud CLI 명령어와 사용 방법을 설명합니다.

Google Cloud CLI 기본 요건

gcloud CLI 버전이 559.0.0 이상인지 확인합니다.
프로젝트를 구성 프로젝트로 설정합니다.

이렇게 하려면 다음 gcloud CLI 명령어를 실행합니다.

   gcloud components update --version=559.0.0
   gcloud config set project PROJECT_ID

Google Cloud CLI 명령어

create

gcloud alpha scc artifact-guard policies create \
    (POLICY --location=LOCATION (--organization=ORGANIZATION_ID | --project=PROJECT_NUMBER)) \
    --policy-file-path=PATH_TO_FILE

POLICY: 정책의 전체 식별자로, 다음 형식 중 하나입니다.
- {organizations/ORGANIZATION_ID/locations/LOCATION/policies/POLICY_ID}
- {projects/PROJECT_NUMBER/locations/LOCATION/policies/POLICY_ID}
- {policy_id -location=LOCATION (--organization=ORGANIZATION_ID | --project=PROJECT_NUMBER)}
PATH_TO_FILE: 정책 정의가 포함된 YAML 문서의 로컬 경로입니다. YAML 파일 구조에 관한 자세한 내용은 이 문서의 YAML 파일 섹션을 참고하세요.

get

gcloud alpha scc artifact-guard policies describe \
    (POLICY --location=LOCATION (--organization=ORGANIZATION_ID | --project=PROJECT_NUMBER))

POLICY: 정책의 전체 식별자로, 다음 형식 중 하나입니다.
- {organizations/ORGANIZATION_ID/locations/LOCATION/policies/POLICY_ID}
- {projects/PROJECT_NUMBER/locations/LOCATION/policies/POLICY_ID}
- {policy_id -location=LOCATION (--organization=ORGANIZATION_ID | --project=PROJECT_NUMBER)}

list

gcloud alpha scc artifact-guard policies list PARENT

PARENT: 조직 또는 프로젝트입니다. 상위 리소스에 허용되는 형식은 다음과 같습니다.
- {organizations/ORGANIZATION_ID/locations/LOCATION}
- {projects/PROJECT_NUMBER/locations/LOCATION}

delete

gcloud alpha scc artifact-guard policies delete \
    (POLICY --location=LOCATION (--organization=ORGANIZATION_ID | --project=PROJECT_NUMBER)) \
    [--etag=ETAG]

POLICY: 정책의 전체 식별자로, 다음 형식 중 하나입니다.
- {organizations/ORGANIZATION_ID/locations/LOCATION/policies/POLICY_ID}
- {projects/PROJECT_NUMBER/locations/LOCATION/policies/POLICY_ID}
- {policy_id -location=LOCATION (--organization=ORGANIZATION_ID | --project=PROJECT_NUMBER)}
etag: 선택사항입니다. 동시 실행 제어용입니다. 리소스의 ETag가 일치하는 경우에만 요청이 진행됩니다.

update

gcloud alpha scc artifact-guard policies update \
    (POLICY --location=LOCATION (--organization=ORGANIZATION_ID | --project=PROJECT_NUMBER)) \
    --policy-file-path=PATH_TO_FILE [--allow-missing] \
    [--update-mask=UPDATE_MASK]

POLICY: 정책의 전체 식별자로, 다음 형식 중 하나입니다.
- {organizations/ORGANIZATION_ID/locations/LOCATION/policies/POLICY_ID}
- {projects/PROJECT_NUMBER/locations/LOCATION/policies/POLICY_ID}
- {policy_id -location=LOCATION (--organization=ORGANIZATION_ID | --project=PROJECT_NUMBER)}
PATH_TO_FILE: 업데이트할 필드의 정의가 포함된 YAML 문서의 로컬 경로입니다.
allow_missing: 선택사항인 불리언입니다. true는 지정된 정책이 없는 경우 새 정책을 만듭니다.
update-mask: 업데이트할 필드의 쉼표로 구분된 목록입니다. 빈 문자열 또는 '*'는 전체 정책 업데이트를 의미합니다. 업데이트 마스크에 유효한 필드는 다음과 같습니다.
- display_name
- description
- scope
- enablement_state
- vulnerability_policy
- annotations

YAML 파일

아티팩트 보호 정책 정의의 YAML 파일은 다음 템플릿을 따라야 합니다.

  displayName: <Human readable display name for the policy>
  description: <Description of the policy>

  vulnerabilityPolicy: # (at least one of these rules must be defined)
    exemptedCves:
      - id: <cve-id-1>
        gracePeriodExpirationTime: <optional-grace-period-expiration-time>
      - id: <cve-id-2>
        gracePeriodExpirationTime: <optional-grace-period-expiration-time>

    maxAllowedSeverity: <The maximum severity allowed in the detected
    vulnerabilities. The severity values can be LOW, MEDIUM, HIGH, CRITICAL>

    maximumAllowedVulnerabilities: <The maximum number of vulnerabilities that
    can be detected>

    excludeUnfixable: <Whether to exclude the vulnerabilities without an
    available fix from the purview of the policy evaluation>

    restrictedCves:
      - <restricted-cve-id-1>
      - <restricted-cve-id-2>

    allowedPackages:
      - name: <allowed_package_name_1>
        version: <optional_version_of_allowed_package_1. If unspecified, all the
        versions of the package are allowed>
      - name: <allowed_package_name_2>
        version: <optional_version_of_allowed_package_2>

    restrictedPackages:
      - name: <restricted_package_name_1>
        version: <optional_version_of_restricted_package_1. If unspecified, all
        the versions of the package are restricted>
      - name: <restricted_package_name_2>
        version: <optional_version_of_restricted_package_2>

  scope:
    pipeline:
      connectorIds:
        - <connector_id_1>
        - <connector_id_2>
      enforcementAction: <action to take in case the policy evaluation fails.
      The supported values are AUDIT_ONLY or BLOCK_BUILD>

    registry:
      projectIds:
        - <project_id_1>
      garRepositoryNamePatterns:
        - <repository_name_pattern_1>
      imageNamePatterns:
        - <image_name_pattern_1>
      enforcementAction: <AUDIT_ONLY or ADMISSION_CONTROL>
      admissionControl:
        deploymentProjectIds:
          - <project_id_1>
        gkeClusterNames:
          - <cluster_name_1>
        dryRun: <bool>
        overrideBinauthzPolicy: <bool>

    runtime:
        deploymentProjectIds:
          - <project_id_1>
        gkeClusterNames:
          - <cluster_name_1>
        dryRun: <bool>
        overrideBinauthzPolicy: <bool>
        enforcementAction: <AUDIT_ONLY or BLOCK_DEPLOYMENT>

  enablementState: <The enablement state of the policy. The supported values are
  ACTIVE, INACTIVE>

다음은 샘플 아티팩트 보호 정책 파일입니다.

  displayName: 'A sample policy'
  description: Vulnerability Policy
  vulnerabilityPolicy:
    exemptedCves:
      - id: CVE-2022-40897
        gracePeriodExpirationTime: '2026-09-10T18:58:08Z'
      - id: CVE-2024-6345
    maxAllowedSeverity: MEDIUM
    maximumAllowedVulnerabilities: 5
    excludeUnfixable: true
    restrictedCves:
      - CVE-2013-4392
      - CVE-2024-4143
    allowedPackages:
      - name: systemd
        version: '257.7'
      - name: util-linux
    restrictedPackages:
      - name: ncurses
        version: 6.5+20250216
      - name: setuptools
  scope:
    pipeline:
      connectorIds:
        - organizations/123/locations/global/connectors/demoConnector
      enforcementAction: BLOCK_BUILD
    registry:
      projectIds:
        - projects/my-registry-project-id
        - projects/another-registry-project
      garRepositoryNamePatterns:
        - us-west1-docker.pkg.dev/my-registry-project-id/my-repo
        - gcr.io/team-a/internal-artifacts
      imageNamePatterns:
        - my-repo/service-a:.*
        - my-repo/service-b:v1\..*
      enforcementAction: ADMISSION_CONTROL
      admissionControl:
        deploymentProjectIds:
          - projects/my-deployment-project
        gkeClusterNames:
          - //container.googleapis.com/projects/my-deployment-project/locations/us-central1/clusters/gke-cluster-a
          - //container.googleapis.com/projects/my-deployment-project/locations/us-central1/clusters/gke-cluster-b
        dryRun: true
        overrideBinauthzPolicy: true
    runtime:
      deploymentProjectIds:
        - projects/my-deployment-project
      gkeClusterNames:
        - //container.googleapis.com/projects/my-deployment-project/locations/us-central1/clusters/gke-cluster-a
        - //container.googleapis.com/projects/my-deployment-project/locations/us-central1/clusters/gke-cluster-b
      dryRun: false
      overrideBinauthzPolicy: false
      enforcementAction: BLOCK_DEPLOYMENT
  enablementState: ACTIVE

성능 및 제한사항

상위 리소스당 최대 정책 수: 상위 리소스 (조직 또는 프로젝트)는 최대 1,000개의 정책을 정의할 수 있습니다. 여기에는 아티팩트 보호 내에서 구성된 모든 유형의 보안 정책이 포함됩니다.
상위 리소스당 최대 취약점 정책 수: 전체 정책 한도 내에서 취약점 발견 결과에 중점을 둔 정책 수에 제한이 있습니다. 상위 리소스 (조직 또는 프로젝트)에는 취약점을 타겟팅하는 정책이 최대 500개 있을 수 있습니다.
파이프라인당 최대 정책 수: 빌드 시간 적용을 위해 아티팩트 보호 정책이 통합된 각 개별 CI/CD 파이프라인의 경우 최대 100개의 정책이 허용됩니다.
정책별 주간 최대 업데이트 수: 각 정책에 대해 매주 최대 100개의 업데이트를 할 수 있습니다.
정책당 최대 파이프라인 커넥터 수: 각 정책에는 최대 100개의 파이프라인 커넥터가 연결될 수 있습니다.
정책당 최대 예외 및 제한 CVE: 각 정책은 최대 100개의 CVE를 예외로 지정하고 제한할 수 있습니다.
정책당 허용 및 제한된 최대 패키지 수: 각 정책에서 최대 100개의 패키지를 허용하고 제한할 수 있습니다.

추가 제약 조건은 문제 해결을 참고하세요.

문제 해결

이 섹션에서는 아티팩트 보호 정책 필드와 일반적인 오류 및 해결 방법을 간략하게 설명합니다.

정책 검증

정책을 만들거나 업데이트할 때 아티팩트 보호는 정책 정의를 검증합니다. 유효성 검사에 실패하면 아티팩트 보호가 요청을 거부하고 자세한 오류 메시지를 제공합니다.

일반 정책 필드

이름	설명	필수	제약조건	샘플 값
상위 요소	정책의 애플리케이션 범위를 정의합니다.	예	`global` 위치의 정책만 지원됩니다.	`organizations/123/locations/global` `projects/123/locations/global`
정책 ID	정책의 고유 식별자입니다.	예	최대 100자(영문 기준) 문자로 시작하고 영숫자 문자로 끝나야 하며 문자, 숫자, 하이픈 또는 밑줄만 포함해야 합니다.	`my-policy-1`
표시 이름	정책의 사람이 읽을 수 있는 이름입니다.	아니요	최대 63자(영문 기준) 고유한 값을 사용하는 것이 좋습니다.	`My vulnerability policy`
설명	정책에 대한 설명입니다.	아니요	최대 2,048자(영문 기준)	`Checks for critical vulnerabilities.`
정책 유형	정의되는 정책의 유형입니다.	예	`vulnerability_policy`만 지원됩니다.	`vulnerability_policy`
사용 설정 상태	정책의 사용 설정 상태입니다.	예	`ACTIVE` 또는 `INACTIVE`이어야 합니다.	`ACTIVE`

취약점 정책

이름	설명	다중 값	제약조건	샘플 값
maximumAllowedVulnerabilities	정책 위반 전에 허용되는 최대 취약점 수입니다.	아니요	설정된 경우 음수가 아닌 숫자여야 합니다.	`10`
maxAllowedSeverity	정책에서 허용하는 취약점의 최대 심각도입니다.	아니요	`LOW`, `MEDIUM`, `HIGH` 또는 `CRITICAL`이어야 합니다.
exemptedCves	이 정책에서 제외된 CVE 목록입니다.	예	최대 100개의 항목 각 ID는 `CVE-YYYY-NNNN` 형식이어야 합니다. 유예 기간 만료일은 제공된 경우 유효한 타임스탬프여야 합니다. `restrictedCves`와 겹칠 수 없습니다.	`- id: CVE-2024-12345` `gracePeriodExpirationTime: 2027-01-01T00:00:00Z` `- id: CVE-2025-4000`
restrictedCves	이 정책에 의해 명시적으로 허용되지 않는 CVE 목록입니다.	예	최대 100개의 항목 각 ID는 `CVE-YYYY-NNNN` 형식이어야 합니다. `exemptedCves`와 겹칠 수 없습니다.	`- CVE-2024-54321` `- CVE-2025-5001`
allowedPackages	허용된 패키지 목록으로, 다른 규칙을 재정의할 수 있습니다.	예	최대 100개의 항목 패키지 이름은 비워 둘 수 없습니다. `restrictedPackages`와 충돌할 수 없습니다.	`- name: nginx` `version: 1.0` `- name: python` `version: 3.12.4`
restrictedPackages	명시적으로 허용되지 않는 패키지 목록입니다.	예	최대 100개의 항목 패키지 이름은 비워 둘 수 없습니다. `allowedPackages`와 충돌할 수 없습니다.	`- name: npm` `version: 9.0.0`
excludeUnfixable	사용 가능한 수정사항이 없는 취약점을 제외할지 여부입니다.	아니요	부울. 기본값은 `false`입니다.	`true`
exemptionDaysPostDisclosure	공개일 후 취약점을 제외할 일수입니다.	아니요	설정된 경우 음수가 아닌 숫자여야 합니다. 기본값은 `0`입니다.	`30`

정책 범위

파이프라인 범위

이름	설명	필수	제약조건	샘플 값
connectorIds	CI/CD 파이프라인 스캔 중에 정책이 적용되는 커넥터 ID 목록입니다.	예	최소 1개 항목, 최대 100개 항목 조직 또는 프로젝트가 CI/CD 스캔에 온보딩되어야 합니다. 각 ID는 올바른 형식을 따라야 하고, 조직 또는 프로젝트에 속해야 하며, 기존 커넥터를 가리켜야 합니다.	`organizations/123/locations/global/connectors/connector-1` `projects/123/locations/global/connectors/connector-1`
enforcementAction	정책을 위반할 때 취할 조치입니다.	예	`AUDIT_ONLY` 또는 `BLOCK_BUILD` 중 하나여야 합니다.	`BLOCK_BUILD`

레지스트리 범위

이름	설명	필수	제약조건	샘플 값
projectIds	정책이 적용되는 프로젝트 ID 목록입니다.	아니요	최소 1개의 항목이 있어야 합니다. 각 ID는 유효한 Google Cloud 프로젝트 ID여야 합니다.	`projects/123, projects/456`
garRepositoryNamePatterns	Google Cloud Artifact Registry 저장소 이름 패턴 목록입니다.	아니요	최대 100개 항목 유효한 Google Cloud Artifact Registry 저장소 패턴이어야 합니다.	`us-west1-docker.pkg.dev/my-project/my-repo, gcr.io/team-a/*`
imageNamePatterns	정규화된 이미지 이름의 정규 표현식 패턴입니다.	아니요	최대 100개 항목 유효한 정규 표현식이어야 합니다.	`'my-repo/service-a:.', 'my-repo/service-b:v1..'`
enforcementAction	정책을 위반할 때 취할 조치입니다.	예	`AUDIT_ONLY` 또는 `ADMISSION_CONTROL` 중 하나여야 합니다.	`ADMISSION_CONTROL`
admissionControl	승인 제어의 구성 세부정보입니다.	아니요	`enforcementAction`이 `ADMISSION_CONTROL`인 경우 있어야 합니다.

런타임 범위

런타임 범위는 아티팩트 보호가 GKE 환경 내에서 활성 상태로 실행되는 컨테이너 이미지를 모니터링할 수 있도록 지원합니다. 이 범위에 정책이 적용되면 지정된 프로젝트 또는 클러스터에 배포된 이미지의 정책 메타데이터로 Security Command Center 취약점 발견 항목이 자동으로 개선됩니다.

이름	설명	필수	제약조건	샘플 값
projectIds	GKE 클러스터가 배포되고 취약점 평가가 사용 설정된 프로젝트 ID 목록입니다.	예	조직 수준에서 선택해야 합니다.	`projects/my-gke-deployment-123`
gkeClusterNames	정책을 평가해야 하는 특정 GKE 클러스터입니다.	아니요	조직 또는 프로젝트 수준에서 선택할 수 있습니다.	`projects/prod-env/locations/us-central1/clusters/main-cluster`

모니터링되는 GKE 클러스터에서 실행되는 컨테이너 이미지가 정책을 위반하면 다음과 같이 ArtifactGuardPolicies 메타데이터가 Security Command Center 취약점 발견 항목 메시지에 추가됩니다.

// Added to the SCC 'message Finding'
ArtifactGuardPolicies artifact_guard_policies = X;

message ArtifactGuardPolicies {
  string resource_id = 1;     // e.g., //us-docker.pkg.dev/google-samples/containers/gke/security/...
  repeated Policy failing_policies = 2;
}

message Policy {
  enum Type {
    TYPE_UNSPECIFIED = 0;
    VULNERABILITY = 1;
  }
  Type type = 1;
  string policy_id = 2;     // e.g., organizations/3392779/locations/global/policies/prod-policy
  string failure_reason = 3;     // e.g., severity=HIGH AND max_vuln_count=2
}

시정 조치

BLOCK_BUILD 및 BLOCK_DEPLOYMENT 작업의 경우 정책 평가에서 권장되는 시정 조치를 반환합니다. 하지만 이 권장사항을 사용하여 파이프라인 구성에서 실제 적용을 구성해야 합니다.

정책 삭제

활성 정책은 삭제할 수 없으며 FAILED_PRECONDITION오류가 발생합니다. 정책을 삭제하려면 먼저 상태를 Inactive로 설정하세요.

일반적인 오류

다음 표에는 일반적인 오류와 해결 방법이 나와 있습니다.

오류 메시지 힌트	원인	해결 방법
parent는 필수입니다	요청에 상위 필드가 누락되었습니다.	다음 형식 중 하나로 유효한 상위 요소를 제공합니다. `organizations/{org_id}/locations/global` `parents/{project_number}/locations/global`
정책 정의가 필요함	요청에 정책 객체가 누락되었습니다.	요청에 유효한 정책 객체를 제공합니다.
표시 이름의 최대 길이는...	표시 이름이 63자(영문 기준)를 초과합니다.	표시 이름을 63자(영문 기준) 이하로 줄이세요.
설명의 최대 길이는...	설명이 2,048자(영문 기준)를 초과합니다.	설명을 2,048자 이하로 줄이세요.
정책 유형은 필수 항목입니다.	요청에 정책 유형 (예: `vulnerabilityPolicy`)이 누락되었습니다.	정책에 `vulnerabilityPolicy` 또는 기타 정책 유형을 추가합니다.
enablement state is invalid(사용 설정 상태가 잘못됨)	잘못되었거나 지원 중단된 사용 설정 상태가 사용되었습니다.	`ACTIVE` 또는 `INACTIVE`을 사용합니다.
범위는 필수 항목입니다	범위 (파이프라인, 레지스트리 또는 런타임)가 정의되지 않았습니다.	정책에 유효한 범위를 하나 이상 추가합니다.
CVE 이름은 다음 형식이어야 합니다...	`exemptedCves` 또는 `restrictedCves`의 CVE ID가 잘못되었습니다.	모든 CVE ID가 `CVE-YYYY-NNNN` 형식을 따르는지 확인합니다.
CVE ... 는 예외로 처리하거나 제한할 수 없습니다	`exemptedCves`와 `restrictedCves`에 동일한 CVE ID가 있습니다.	목록 중 하나에서 CVE를 삭제합니다.
패키지 이름은 비워 둘 수 없습니다.	`allowedPackages` 또는 `restrictedPackages`의 패키지 이름이 비어 있습니다.	모든 패키지의 이름을 입력합니다.
package ... cannot be allowed and restricted	동일한 패키지가 `allowedPackages`와 `restrictedPackages`에 모두 나열되어 있습니다.	목록 중 하나에서 패키지를 삭제합니다.
커넥터 ID는 필수 항목입니다.	파이프라인 범위에 `connectorIds` 필드가 없습니다.	커넥터 ID를 하나 이상 제공하세요.
커넥터 ID는 다음 형식이어야 합니다.	커넥터 ID의 형식이 잘못되었습니다.	ID가 다음 형식 중 하나인지 확인합니다. `organizations/{org_id}/locations/global/connectors/{connector_id}` . `projects/{project_number}/locations/{location}/connectors/{connector_id}`
커넥터 ID ... 가 존재하지 않습니다	지정된 커넥터 ID가 존재하지 않습니다.	커넥터가 있는지 확인하거나 목록에서 삭제합니다.
GAR 저장소 이름 패턴은 다음을 충족해야 합니다.	레지스트리 범위에 잘못된 저장소 패턴이 제공되었습니다.	패턴이 유효한 Google Cloud Artifact Registry 저장소 형식과 일치하는지 확인합니다.
프로젝트 ID는 유효한 GCP 프로젝트 ID여야 합니다...	레지스트리 또는 런타임 범위에 잘못된 프로젝트 ID가 제공되었습니다.	유효한 Google Cloud 프로젝트 ID를 제공합니다.
시정 조치를 지정해야 합니다	`enforcementAction`이 파이프라인 또는 런타임 범위에 누락되었습니다.	강제 조치 (예: `AUDIT_ONLY, BLOCK_BUILD` (파이프라인만 해당) 또는 `BLOCK_DEPLOYMENT`(런타임만 해당))를 설정합니다.
조직당 정책 수가 한도를 초과합니다...	조직의 정책 수가 최대 한도 (1,000개)에 도달했습니다.	새 정책을 만들기 전에 사용하지 않는 정책을 삭제하세요.
취약점 정책 수가 한도를 초과합니다.	취약점 정책의 최대 수(500개)에 도달했습니다.	새 취약점 정책을 만들기 전에 사용하지 않는 취약점 정책을 삭제하세요.
파이프라인당 정책 수가 한도를 초과했습니다...	커넥터가 100개가 넘는 정책과 연결되어 있습니다.	커넥터와 연결된 정책 수를 줄입니다.
정책 수정 횟수가 한도를 초과합니다.	7일 동안 정책을 100회 이상 업데이트했습니다.	기다리거나 업데이트 빈도를 줄입니다.

일반적인 운영 문제

정책 콘텐츠 유효성 검사 실패 외에도 기본Google Cloud 컨트롤 플레인에 문제가 발생할 수 있습니다. 이러한 문제는 API 요청, 장기 실행 작업, 리소스 상태에 영향을 줄 수 있으며 일반적으로 특정 오류 코드 또는 비정상적인 동작으로 표시됩니다.

문제	증상	문제 해결 방법
동시 수정	`UpdatePolicy` 또는 `DeletePolicy`이 `ABORTED` 오류 코드 및 `"Provided etag is out of date"` 메시지와 함께 실패합니다.	문제 해결: 이 문제는 요청의 `etag`이 정책의 현재 서버 버전과 일치하지 않아 다른 요청에 의해 수정되었음을 나타낼 때 발생합니다. 해결 방법: 정책을 다시 읽어 최신 etag를 가져온 다음 새 etag로 요청을 다시 시도합니다.
요청이 검증되었지만 실행되지 않음	`CreatePolicy`, `UpdatePolicy` 또는 `DeletePolicy` 요청이 성공적으로 반환되지만 리소스에 변경사항이 표시되지 않습니다.	문제 해결: 일반적으로 요청에 `validate_only: true`이 설정된 경우에 발생합니다. 이 플래그는 변경사항을 커밋하지 않고 모든 유효성 검사를 실행하도록 서비스에 지시합니다. 해결 방법: `validate_only`을 `false`로 설정하거나 요청에서 필드를 생략합니다.
업데이트 시 새 정책 생성	`UpdatePolicy` 요청은 정책이 존재하지 않을 때 '찾을 수 없음' 오류를 반환하는 대신 정책을 만듭니다.	문제 해결: 이는 `allow_missing: true`이 `UpdatePolicyRequest`에 포함될 때 의도된 동작입니다. 해결 방법: 기존 정책만 업데이트하려면 `allow_missing`을 `false`로 설정하거나 필드를 생략하세요.
권한 거부됨 또는 API가 사용 설정되지 않음	`PERMISSION_DENIED` 또는 `"Artifact Guard API has not been used in the project before or it is disabled."`과 같은 오류 메시지와 함께 요청이 실패합니다.	문제 해결: API가 사용 중지되었거나 호출자에게 충분한 권한이 없을 수 있습니다. 해결 방법: Google Cloud 프로젝트에서 Artifact Guard API (`artifactscanguard.googleapis.com`)를 사용 설정합니다. 작업을 실행하는 사용자 또는 서비스 계정에 필요한 IAM 역할이 있는지 확인합니다.
작업 제한 시간	장기 실행 작업 (LRO)을 반환하는 요청이 완료되는 데 너무 오래 걸리거나 `DEADLINE_EXCEEDED` 오류와 함께 실패합니다.	문제 해결: 백엔드 서비스의 일시적인 속도 저하 또는 문제가 있을 수 있습니다. 해결 방법: LRO 상태를 폴링합니다. 실패하거나 시간 초과되면 잠시 후 작업을 다시 시도하세요. 문제가 지속되면 Google Cloud 상태 대시보드에서 진행 중인 인시던트를 확인하거나 Google Cloud 지원팀에 문의하세요.