이 페이지에서는 Common Expression Language(CEL) 및 YAML을 사용하여 커스텀 모듈 정의를 코딩하는 방법을 설명합니다.
Google Cloud CLI를 사용하여 커스텀 모듈 정의를 Security Health Analytics에 업로드합니다.
YAML 파일에서 커스텀 모듈 정의는 Security Health Analytics 커스텀 모듈의 다음 요소를 정의하기 위해 사용하는 구조화된 속성 집합으로 구성됩니다.
- 스캔할 리소스
- 사용할 감지 논리
- 감지된 문제를 빠르게 이해, 분류, 해결할 수 있도록 보안팀에 제공할 정보
YAML 정의를 구성하는 구체적인 필수 및 선택적인 속성에 대해서는 코딩 단계에서 설명합니다.
중복된 감지기 생성 방지
발견 항목 볼륨을 제어하려면 중복된 기능을 포함하는 모듈을 만들고 실행하지 않도록 합니다.
예를 들어 30일 이후에 순환되지 않는 암호화 키를 검사하는 커스텀 모듈을 만들 경우 기본 제공되는 Security Health Analytics 감지기 KMS_KEY_NOT_ROTATED
는 검사 기간이 90일에 해당되어 너무 과도하므로 사용 중지하는 것이 좋습니다.
감지기 사용 중지에 대한 자세한 내용은 감지기 사용 설정 및 사용 중지를 참조하세요.
코딩 단계
Security Health Analytics용 커스텀 모듈 정의를 일련의 YAML 속성으로 코딩합니다. 이중 일부에는 CEL 표현식이 포함됩니다.
커스텀 정의 모듈을 코딩하려면 다음 단계를 수행합니다.
yaml
파일 이름 확장자로 텍스트 파일을 만듭니다.텍스트 파일에서
resource_selector
속성을 만들고 스캔할 커스텀 모듈의 리소스 유형을 1~5개까지 지정합니다. 리소스 유형은 커스텀 모듈 정의에 1개를 초과해서 지정할 수 없습니다. 예를 들면 다음과 같습니다.resource_selector: resource_types: ‐ cloudkms.googleapis.com/CryptoKey
지정하는 리소스 유형은 Security Command Center에서 지원되어야 합니다. 지원되는 리소스 유형 목록은 지원되는 리소스 유형을 참조하세요.
predicate
속성을 만들고 스캔할 리소스 유형의 속성을 검사하는 CEL 표현식을 하나 이상 지정합니다. CEL 표현식에서 참조하는 속성은resource_selector
아래에 지정하는 각 리소스 유형의 Google Cloud API 정의에 존재해야 합니다. 발견 항목을 트리거하려면 표현식이TRUE
로 확인되어야 합니다. 예를 들어 다음 표현식에서는2592000s
보다 큰rotationPeriod
값만 발견 항목을 트리거합니다.predicate: expression: resource.rotationPeriod > duration("2592000s")
CEL 표현식 작성에 도움이 필요하면 다음 리소스를 참조하세요.
- 지원되는 리소스 유형. CEL 표현식에 사용할 수 있는 속성을 보려면 각 리소스를 클릭합니다.
- CEL 표현식 작성.
- 커스텀 모듈에서 리소스 및 정책 속성 참조
커스텀 모듈이 감지하는 취약점 또는 잘못된 구성을 설명하는
description
속성을 만듭니다. 이 설명은 조사자가 감지된 문제를 이해하는 데 도움이 되도록 각 발견 항목 인스턴스에 표시됩니다. 텍스트는 따옴표로 묶어야 합니다. 예를 들면 다음과 같습니다.description: "The rotation period of the identified cryptokey resource exceeds 30 days, the maximum rotation period that our security guidelines allow."
감지된 문제의 해결 방법을 설명하는
recommendation
속성을 만듭니다. gcloud CLI는 따옴표와 같이 특정 문자 앞에 이스케이프 문자가 필요합니다. 다음 예시는 각 따옴표 쌍을 이스케이프 처리하기 위해 사용되는 백슬래시를 보여줍니다.recommendation: "To fix this issue go to https://console.cloud.google.com/security/kms. Click the key-ring that contains the key. Click the key. Click \"Edit rotation period\". Then set the rotation period to at most 30 days."
Google Cloud 콘솔을 사용하여 커스텀 모듈을 만들거나 업데이트하는 경우 이스케이프 문자가 필요하지 않습니다.
severity
속성을 만들고 이 모듈에서 생성된 발견 항목의 기본 심각도를 지정합니다.severity
속성에 일반적으로 사용되는 값은LOW
,MEDIUM
,HIGH
,CRITICAL
입니다. 예를 들면 다음과 같습니다.severity: MEDIUM
선택적으로
custom_output
속성을 만들고 각 발견 항목에 반환할 추가 정보를 지정합니다. 하나 이상의 이름-값 쌍으로 반환할 정보를 지정합니다. 스캔한 리소스의 속성 값 또는 리터럴 문자열을 반환할 수 있습니다. 속성은resource.PROPERTY_NAME
으로 지정해야 합니다. 리터럴 문자열은 따옴표로 묶어야 합니다. 다음 예시는 스캔된CryptoKey
리소스의rotationPeriod
값인 속성 값과 텍스트 문자열"Excessive rotation period for CryptoKey"
를 모두 반환하는custom_output
정의를 보여줍니다.custom_output: properties: - name: duration value_expression: expression: resource.rotationPeriod - name: note value_expression: expression: "Excessive rotation period for CryptoKey"
gcloud CLI가 액세스할 수 있는 위치에 파일을 저장합니다.
다음 명령어를 사용하여 정의를 Security Health Analytics에 업로드합니다.
gcloud scc custom-modules sha create \ --organization=organizations/ORGANIZATION_ID \ --display-name="MODULE_DISPLAY_NAME" \ --enablement-state="ENABLED" \ --custom-config-from-file=DEFINITION_FILE_NAME.yaml
다음 값을 바꿉니다.
ORGANIZATION_ID
를 커스텀 모듈의 상위 조직 ID로 바꾸거나--organization
플래그를--folders
또는--project
로 바꾸고 상위 폴더 또는 프로젝트의 ID를 지정합니다.MODULE_DISPLAY_NAME
을 커스텀 모듈이 발견 항목을 반환할 때 발견 항목 카테고리로 표시할 이름으로 바꿉니다. 이름은 1~128자(영문 기준)여야 하고 소문자로 시작하며 영숫자 문자 또는 밑줄만 포함해야 합니다.DEFINITION_FILE_NAME
을 커스텀 모듈의 정의가 포함된 YAML 파일의 경로 및 파일 이름으로 바꿉니다.
Security Health Analytics 커스텀 모듈 작업에 대한 자세한 내용은 Security Health Analytics에 커스텀 모듈 사용을 참조하세요.
새 커스텀 모듈의 스캔 지연 시간
커스텀 모듈 만들기는 새 스캔을 트리거하지 않습니다.
Security Health Analytics는 다음 중 하나가 수행될 때까지 새 커스텀 모듈을 사용하지 않습니다.
- 커스텀 모듈을 만든 후 첫 번째 배치 스캔. 배치-스캔 일정으로 커스텀 모듈을 만드는 경우에는 Security Health Analytics에서 커스텀 모듈이 사용되기 전까지 최대 24시간 기다려야 할 수 있습니다.
- 대상 리소스 변경은 실시간 스캔을 트리거합니다.
커스텀 모듈 정의 예시
다음 예시는 cloudkms.googleapis.com/CryptoKey
리소스의 rotationPeriod
속성 값이 2,592,000초(30일)보다 클 경우 발견 항목을 트리거하는 완료된 커스텀 모듈 정의를 보여줍니다. 이 예시는 custom_output
섹션에 두 가지 선택적인 값인 resource.rotationPeriod
값과 텍스트 문자열 메모를 반환합니다.
이 예시에서 다음 요소에 주의하세요.
- 검사할 애셋 또는 리소스 유형은
resource_types
아래의resource_selector
섹션에 나열되어 있습니다. - 모듈이 리소스에 대해 수행하는 검사인 감지 논리는
expression
앞에 오는predicate
섹션에 정의되어 있습니다. - 두 가지 커스텀 소스 속성인
duration
과violation
은custom_output
섹션에 정의되어 있습니다. - 감지된 문제에 대한 설명은
description
속성에 지정됩니다. - 감지된 문제 해결을 위한 안내는
recommendation
속성에 지정됩니다. 따옴표가 가이드에 표시되기 때문에 각 따옴표 앞에 백슬래시 이스케이프 문자가 필요합니다.
severity: HIGH
description: "Regular key rotation helps provide protection against
compromised keys, and limits the number of encrypted messages available
to cryptanalysis for a specific key version."
recommendation: "To fix this issue go to
https://console.cloud.google.com/security/kms. Click the key-ring that
contains the key. Click the key. Click \"Edit rotation period\". Then
set the rotation period to at most 30 days."
resource_selector:
resource_types:
- cloudkms.googleapis.com/CryptoKey
predicate:
expression: resource.rotationPeriod > duration("2592000s")
custom_output:
properties:
- name: duration
value_expression:
expression: resource.rotationPeriod
- name: violation
value_expression:
expression:
"Excessive rotation period for CryptoKey"
커스텀 모듈에서 리소스 및 정책 속성 참조
Google Cloud 콘솔을 사용하거나 정의를 직접 작성하는 등 커스텀 모듈을 만들기 위해 사용하는 방법에 관계없이 커스텀 모듈에서 평가할 수 있는 속성을 조회해야 합니다. 또한 커스텀 모듈 정의에서 이러한 속성을 참조하는 방법을 알아야 합니다.
리소스 또는 정책의 속성 찾기
Google Cloud 리소스의 속성은 리소스의 API 정의에 정의되어 있습니다. 지원되는 리소스 유형에서 리소스 이름을 클릭하여 이 정의를 찾을 수 있습니다.
IAM API 참고 문서에서 정책의 속성을 찾을 수 있습니다. 정책 속성은 정책을 참조하세요.
커스텀 모듈 정의에서 리소스 속성 참조
커스텀 모듈을 만들 때는 스캔된 리소스의 속성에 대한 모든 직접 참조가 resource
로 시작되어야 하고, 그 다음 상위 속성과 마지막으로 대상 속성이 와야 합니다. 속성은 JSON 스타일의 점 표기법을 사용해서 마침표로 구분됩니다.
다음은 리소스 속성과 이를 검색하는 방법에 대한 예시입니다.
resourceName
: Cloud 애셋 인벤토리에 리소스의 전체 이름을 저장합니다. 예를 들면//cloudresourcemanager.googleapis.com/projects/296605646631
입니다.resource.rotationPeriod
: 여기서rotationPeriod
는resource
의 속성입니다.resource.metadata.name
: 여기서name
은resource
의 하위 속성에 해당하는metadata
의 하위 속성입니다.
IAM 정책 속성 참조
리소스의 IAM 정책 속성을 참조하여 리소스의 IAM 정책을 평가하는 CEL 표현식을 만들 수 있습니다. 사용 가능한 유일한 속성은 바인딩과 바인딩 내의 역할입니다.
IAM 정책 속성을 참조할 때는 policy
가 최상위 속성입니다.
다음은 IAM 정책 속성 및 검색 방법에 대한 예시입니다.
policy.bindings
: 여기서bindings
는policy
의 속성입니다.policy.version
: 여기서version
은policy
의 속성입니다.
더 많은 예시는 CEL 표현식 예시를 참조하세요.
정책의 속성에 대한 자세한 내용은 정책을 참조하세요.
CEL 표현식 작성
커스텀 모듈을 만들 때는 CEL 표현식을 사용하여 스캔된 리소스의 속성을 평가합니다. 선택적으로 CEL 표현식을 사용하여 발견 항목과 함께 추가 정보를 반환하는 커스텀 name
-value
쌍을 정의할 수 있습니다.
Google Cloud 콘솔에서 커스텀 모듈을 만들거나 YAML 파일로 커스텀 모듈 정의를 직접 작성하는지에 관계없이 정의하는 CEL 표현식은 동일합니다.
감지 논리를 위한 CEL 표현식
스캔한 리소스의 속성을 평가하기 위해 표준 CEL 연산자와 함께 CEL 표현식을 사용하여 커스텀 모듈의 감지 논리를 코딩합니다.
표현식은 단일 값을 검사하는 간단한 표현식이거나 여러 값 또는 조건을 검사하는 복잡한 복합 표현식일 수 있습니다. 어느 경우든 표현식은 발견 항목을 트리거하기 위해 불리언 true
로 결정되어야 합니다.
Google Cloud 콘솔에서 커스텀 모듈을 만들 때는 모듈 구성 페이지의 표현식 편집기에서 이러한 표현식을 작성합니다.
YAML 파일에서 커스텀 모듈을 코딩하는 경우 predicate
속성 아래에 이러한 표현식을 추가합니다.
Google Cloud 콘솔 또는 YAML 파일 사용에 관계없이 리소스 속성을 평가하는 CEL 표현식은 다음 규칙을 준수해야 합니다.
- CEL 표현식에서 지정하는 속성은 리소스 파일의 API 정의에 정의된 대로 스캔된 리소스의 속성이어야 합니다.
커스텀 모듈이 여러 리소스 유형을 평가하는 경우 CEL 표현식에 지정하는 속성은 커스텀 모듈이 평가하는 각 리소스 유형에 대해 일반적이어야 합니다.
예를 들어
cloudkms.googleapis.com/CryptoKey
및cloudkms.googleapis.com/CryptoKeyVersion
의 두 가지 리소스 유형을 검사하는invalid_cryptokey
라는 커스텀 모듈을 정의하는 경우,CryptoKey
및CryptoKeyVersion
리소스 유형 모두name
속성을 포함하기 때문에 다음 표현식을 작성해야 합니다.predicate: resource.name.matches("projects/project1/locations/us-central1/keyRings/keyring1/cryptoKeys/.*")
그러나 표현식이 평가하는
importTime
및rotationPeriod
속성이 두 리소스 유형 모두에서 공유되지 않기 때문에invalid_cryptokey
커스텀 모듈에 다음 표현식을 지정할 수 없습니다.predicate: resource.importTime >= timestamp("2022-10-02T15:01:23Z") || resource.rotationPeriod > duration("2592000s")
CEL 표현식의 모든 열거형은 문자열로 표시되어야 합니다. 예를 들어 다음은
cloudkms.googleapis.com/CryptoKeyVersion
리소스 유형의 유효한 표현식입니다.resource.state = "PENDING_GENERATION"
predicate
속성에서 정의하는 CEL 표현식의 결과는 불리언이어야 합니다. 결과가true
인 경우에만 발견 항목이 트리거됩니다.
CEL에 대한 자세한 내용은 다음을 참조하세요.
CEL 표현식 예시
다음 표에는 리소스 속성 평가를 위해 사용할 수 있는 일부 CEL 표현식이 나와 있습니다. Google Cloud 콘솔 및 YAML 커스텀 모듈 정의 모두에 사용할 수 있습니다.
리소스 유형 | 설명 | CEL 표현식 |
---|---|---|
IAM 정책을 포함하는 모든 리소스 | 외부 도메인의 멤버를 식별하는 IAM 정책 검사 | !policy.bindings.all(binding, binding.members.all(m ,!m.endsWith('@gmail.com'))) |
cloudkms.googleapis.com/CryptoKey |
Cloud KMS 키 순환 기간 검사 | has(resource.rotationPeriod) && resource.rotationPeriod > duration('60h') |
단일 정책의 여러 리소스 유형 | 리소스 이름이 리소스 유형 기반의 dev 또는 devAccess 로 시작하는지 검사 |
(resource.type == 'compute.googleapis.com/Disk' &&
resource.name.startsWith('projects/PROJECT_ID/regions/
REGION/disks/devAccess')) || (resource.type ==
'compute.googleapis.com/Instance ' &&
resource.name.startsWith('projects/PROJECT_ID/zones/REGION/instances/dev-')) |
compute.googleapis.com/Network |
네트워크 피어 일치를 위한 Virtual Private Cloud 피어링 규칙 | resource.selfLink.matches('https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/default') || resource.peerings.exists(p, p.network.matches('https://www.googleapis.com/compute/v1/projects/PROJECT_ID/global/networks/shared$')) |
cloudfunctions.googleapis.com/CloudFunction |
Cloud 함수에 내부 인그레스 트래픽만 허용 | has(resource.ingressSettings) && resource.ingressSettings.matches('ALLOW_INTERNAL_ONLY') |
compute.googleapis.com/Instance |
리소스 이름 패턴 일치 | resource.name.matches('^gcp-vm-(linux|windows)-v\\d+$') |
serviceusage.googleapis.com/Service |
스토리지 관련 API만 사용 설정 허용 | resource.state == 'ENABLED' && !( resource.name.matches('storage-api.googleapis.com') || resource.name.matches('bigquery-json.googleapis.com') || resource.name.matches('bigquery.googleapis.com') || resource.name.matches('sql-component.googleapis.com') || resource.name.matches('spanner.googleapis.com'))
|
sqladmin.googleapis.com/Instance
|
허용 목록에 포함된 공개 IP만 허용 | (resource.instanceType == 'CLOUD_SQL_INSTANCE' && resource.backendType == 'SECOND_GEN' && resource.settings.ipConfiguration.ipv4Enabled ) && !(resource.ipAddresses.all(ip, ip.type != 'PRIMARY' || ip.ipAddress.matches('IP_ADDRESS'))))
|
dataproc.googleapis.com/Cluster |
Dataproc 클러스터의 프로젝트 ID에 하위 문자열 테스트 또는 개발이 포함되는지 여부 확인 | has(resource.projectId) && resource.projectId.contains('testing') || resource.projectId.contains('development') |
커스텀 발견 항목 속성에 대한 CEL 표현식
선택적으로 발견 항목 쿼리에 사용할 수 있는 각 발견 항목이 포함된 추가 정보를 반환하려면 커스텀 모듈에서 생성된 발견 항목과 함께 반환할 커스텀 속성을 최대 10개까지 정의할 수 있습니다.
커스텀 속성은 JSON의 발견 항목의 소스 속성과 Google Cloud 콘솔의 발견 항목 세부정보의 소스 속성 탭에 표시됩니다.
커스텀 속성을 name
-value
쌍으로 정의합니다.
Google Cloud 콘솔에서 커스텀 모듈을 만드는 경우 발견 항목 세부정보 정의 페이지의 커스텀 발견 항목 속성 섹션에 name
-value
쌍을 정의합니다.
YAML 파일에서 커스텀 모듈을 코딩하는 경우 custom_output
속성 아래에서 name
-value
쌍을 properties
로 나열합니다.
Google Cloud 콘솔 또는 YAML 파일을 사용하는지 여부에 관계없이 다음 규칙이 적용됩니다.
- 따옴표 없이
name
을 텍스트 문자열로 지정합니다. value
를 다음 중 하나로 지정합니다.속성 값을 반환하려면 다음 형식으로 속성을 지정합니다.
RESOURCE_TYPE.PROPERTY.PROPERTY_TO_RETURN
예를 들면 다음과 같습니다.
RESOURCE_TYPE
은resource
또는policy
일 수 있습니다.PROPERTY
는 반환할 값을 포함하는 속성의 하나 이상의 상위 속성입니다.PROPERTY_TO_RETURN
은 반환할 값을 포함하는 속성입니다.텍스트 문자열을 반환하려면 따옴표로 문자열을 묶습니다.
다음 예시는 YAML 파일의 custom_output
아래에 올바르게 정의되는 2개의 name
-value
쌍을 보여줍니다.
custom_output: properties: - name: duration value_expression: expression: resource.name - name: property_with_text value_expression: expression: "Note content"
다음 단계
커스텀 모듈을 테스트, 제출, 확인, 업데이트하려면 다음 페이지를 참조하세요.
- 커스텀 모듈을 테스트하려면 Security Health Analytics용 커스텀 모듈 테스트를 참조하세요.
- 커스텀 모듈을 업로드, 확인, 업데이트하려면 Security Health Analytics용 커스텀 모듈 만들기 및 관리를 참조하세요.