Security Health Analytics용 커스텀 모듈 코딩

이 페이지에서는 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 Run 함수에 내부 인그레스 트래픽만 허용	`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용 커스텀 모듈 만들기 및 관리를 참조하세요.