Benutzerdefiniertes Modul für Security Health Analytics programmieren

Auf dieser Seite wird erläutert, wie Sie eine benutzerdefinierte Moduldefinition mithilfe der Common Expression Language (CEL) und der YAML-Datei codieren.

Verwenden Sie die Google Cloud CLI, um Ihre benutzerdefinierten Moduldefinitionen in Security Health Analytics hochzuladen.

In der YAML-Datei besteht eine benutzerdefinierte Moduldefinition aus einem strukturierten Satz von Attributen, mit denen Sie die folgenden Elemente eines benutzerdefinierten Security Health Analytics-Moduls definieren:

Die zu scannenden Ressourcen.
Die zu verwendende Erkennungslogik.
Die Informationen, die Sie Ihren Sicherheitsteams zur Verfügung stellen, damit sie das erkannte Problem schnell verstehen, beurteilen und beheben können.

Die spezifischen erforderlichen und optionalen Attribute, aus denen eine YAML-Definition besteht, werden unter Coding-Schritte beschrieben.

Erstellen redundanter Detektoren vermeiden

Damit Sie das Ergebnisvolumen steuern können, sollten Sie keine Module mit redundanter Funktionalität erstellen und ausführen.

Wenn Sie beispielsweise ein benutzerdefiniertes Modul erstellen, das auf Verschlüsselungsschlüssel prüft, die nach 30 Tagen nicht rotiert wurden, sollten Sie den integrierten Security Health Analytics-Detektor KMS_KEY_NOT_ROTATED deaktivieren, da seine Prüfung mit einem Wert von 90 Tagen überflüssig wäre.

Weitere Informationen zum Deaktivieren von Detektoren finden Sie unter Detektoren aktivieren und deaktivieren.

Programmierschritte

Die Definition eines benutzerdefinierten Moduls für Security Health Analytics codieren Sie als eine Reihe von YAML-Attributen, von denen einige CEL-Ausdrücke enthalten.

So codieren Sie ein Modul mit benutzerdefinierten Definitionen:

Erstellen Sie eine Textdatei mit der Dateiendung yaml.
Erstellen Sie in der Textdatei das Attribut resource_selector und geben Sie bis zu fünf Ressourcentypen für das benutzerdefinierte Modul an, das gescannt werden soll. Ein Ressourcentyp kann in einer benutzerdefinierten Moduldefinition nur einmal angegeben werden. Beispiel:
```
resource_selector:
 resource_types:
 ‐ cloudkms.googleapis.com/CryptoKey
```
Die von Ihnen angegebenen Ressourcentypen müssen von Security Command Center unterstützt werden. Eine Liste der unterstützten Ressourcentypen finden Sie unter Unterstützte Ressourcentypen.
Erstellen Sie ein predicate-Attribut und geben Sie einen oder mehrere CEL-Ausdrücke an, die die Attribute der zu scannenden Ressourcentypen prüfen. Alle Attribute, auf die Sie in den CEL-Ausdrücken verweisen, müssen in der Google Cloud API-Definition jedes Ressourcentyps vorhanden sein, den Sie unter resource_selector angeben. Zum Auslösen eines Ergebnisses muss der Ausdruck in TRUE aufgelöst werden. Im folgenden Ausdruck lösen beispielsweise nur rotationPeriod-Werte größer als 2592000s ein Ergebnis aus.
```
predicate:
 expression: resource.rotationPeriod > duration("2592000s")
```
Hilfe zum Schreiben von CEL-Ausdrücken finden Sie in den folgenden Ressourcen:
- Unterstützte Ressourcentypen. Klicken Sie auf die einzelnen Ressourcen, um die Attribute zu sehen, die Sie in Ihren CEL-Ausdrücken verwenden können.
- CEL-Ausdrücke schreiben.
- Verweisen auf Ressourcen- und Richtlinienattribute in benutzerdefinierten Modulen
Erstellen Sie ein description-Attribut, das die Sicherheitslücke oder Fehlkonfiguration erläutert, die vom benutzerdefinierten Modul erkannt wird. Diese Erklärung wird in jeder Ergebnisinstanz angezeigt, damit Prüfer das erkannte Problem besser nachvollziehen können. Der Text muss in Anführungszeichen gesetzt werden. Beispiel:
```
description: "The rotation period of
 the identified cryptokey resource exceeds 30 days, the
 maximum rotation period that our security guidelines allow."
```
Erstellen Sie eine recommendation-Property, die erläutert, wie das erkannte Problem behoben wird. Die gcloud CLI erfordert ein Escape-Zeichen vor bestimmten Zeichen, z. B. Anführungszeichen. Das folgende Beispiel zeigt die Verwendung des umgekehrten Schrägstrichs als Escapezeichen für jeden Satz Anführungszeichen:
```
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."
```
Wenn Sie ein benutzerdefiniertes Modul über die Google Cloud Console erstellen oder aktualisieren, sind keine Escapezeichen erforderlich.
Erstellen Sie ein severity-Attribut und geben Sie den Standardschweregrad für die von diesem Modul erstellten Ergebnisse an. Häufig verwendete Werte für das Attribut severity sind LOW, MEDIUM, HIGH und CRITICAL. Beispiel:
```
severity: MEDIUM
```
Optional können Sie ein custom_output-Attribut erstellen und zusätzliche Informationen angeben, die bei jedem Ergebnis zurückgegeben werden sollen. Geben Sie die Informationen an, die als ein oder mehrere Name/Wert-Paare zurückgegeben werden sollen. Sie können entweder den Wert eines Attributs der gescannten Ressource oder einen Literalstring zurückgeben. Attribute müssen als resource.PROPERTY_NAME angegeben werden. Literalstrings müssen in Anführungszeichen gesetzt werden. Das folgende Beispiel zeigt eine custom_output-Definition, die sowohl einen Attributwert, den Wert von rotationPeriod in der gescannten CryptoKey-Ressource als auch den Textstring "Excessive rotation period for CryptoKey" zurückgibt:
```
 custom_output:
   properties:
     - name: duration
       value_expression:
         expression: resource.rotationPeriod
     - name: note
       value_expression:
         expression: "Excessive rotation period for CryptoKey"
```
Speichern Sie die Datei an einem Speicherort, auf den die gcloud CLI zugreifen kann.
Laden Sie die Definition mit dem folgenden Befehl in Security Health Analytics hoch:
```
 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
```
Ersetzen Sie die folgenden Werte:
- ORGANIZATION_ID durch die ID der übergeordneten Organisation des benutzerdefinierten Moduls oder ersetzen Sie das Flag --organization durch --folders oder --project und geben Sie die ID des übergeordneten Ordners oder Projekts an.
- MODULE_DISPLAY_NAME durch einen Namen, der als Ergebniskategorie angezeigt wird, wenn das benutzerdefinierte Modul Ergebnisse zurückgibt. Der Name muss zwischen 1 und 128 Zeichen lang sein, mit einem Kleinbuchstaben beginnen und darf nur alphanumerische Zeichen oder Unterstriche enthalten.
- DEFINITION_FILE_NAME durch den Pfad und den Dateinamen der YAML-Datei, die die Definition des benutzerdefinierten Moduls enthält.
Weitere Informationen zur Verwendung von benutzerdefinierten Security Health Analytics-Modulen finden Sie unter Benutzerdefinierte Module für Security Health Analytics verwenden.

Scanlatenzen für neue benutzerdefinierte Module

Durch das Erstellen eines benutzerdefinierten Moduls wird kein neuer Scan ausgelöst.

Security Health Analytics beginnt erst dann mit der Verwendung eines neuen benutzerdefinierten Moduls, wenn einer der folgenden Punkte zutrifft:

Der erste Batchscan nach dem Erstellen des benutzerdefinierten Moduls. Je nachdem, wann Sie ein benutzerdefiniertes Modul in Ihrem Batchscanzeitplan erstellen, müssen Sie möglicherweise bis zu 24 Stunden warten, bevor Security Health Analytics das benutzerdefinierte Modul verwendet.
Eine Änderung an einer Zielressource löst einen Echtzeitscan aus.

Beispiel für die Definition eines benutzerdefinierten Moduls

Das folgende Beispiel zeigt eine vollständige benutzerdefinierte Moduldefinition,die ein Ergebnis auslöst,wenn der Wert des Attributs rotationPeriod einer cloudkms.googleapis.com/CryptoKey-Ressource größer als 2.592.000 Sekunden (30 Tage) ist. In diesem Beispiel werden im Abschnitt custom_output zwei optionale Werte zurückgegeben: der Wert von resource.rotationPeriod und ein Hinweis als Textstring.

Achten Sie in diesem Beispiel auf die folgenden Elemente:

Der Typ des zu prüfenden Assets oder der zu prüfenden Ressource ist im Abschnitt resource_selector unter resource_types aufgeführt.
Die Prüfung, ob das Modul für die Ressourcen, also seine Erkennungslogik, ausführt, wird im Abschnitt predicate mit vorangestelltem expression definiert.
Im Abschnitt custom_output sind zwei benutzerdefinierte Quell-Properties, duration und violation, definiert.
Die Erklärung des erkannten Problems finden Sie im Attribut description.
Eine Anleitung zur Behebung des erkannten Problems finden Sie im Attribut recommendation. Da Anführungszeichen in der Anleitung vorkommen, muss vor jedem Anführungszeichen ein umgekehrter Schrägstrich (Escape-Zeichen) stehen.

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"

In benutzerdefinierten Modulen auf Ressourcen- und Richtlinienattribute verweisen

Unabhängig von der Methode, mit der Sie ein benutzerdefiniertes Modul erstellen – mithilfe der Google Cloud Console oder indem Sie die Definition selbst schreiben – müssen Sie die Attribute finden können, die Sie im benutzerdefinierten Modul auswerten können. Außerdem müssen Sie wissen, wie Sie in einer benutzerdefinierten Moduldefinition auf diese Attribute verweisen.

Attribute einer Ressource oder Richtlinie suchen

Die Attribute einer Google Cloud-Ressource werden in der API-Definition der Ressource definiert. Um die Definition zu sehen, klicken Sie unter Unterstützte Ressourcentypen auf den Ressourcennamen.

Die Attribute einer Richtlinie finden Sie in der Referenzdokumentation zur IAM API. Die Attribute einer Richtlinie finden Sie unter Richtlinie.

In einer benutzerdefinierten Moduldefinition auf ein Ressourcenattribut verweisen

Wenn Sie ein benutzerdefiniertes Modul erstellen, müssen alle direkten Verweise auf das Attribut einer gescannten Ressource mit resource beginnen, gefolgt von allen übergeordneten Attributen und schließlich dem Zielattribut. Die Attribute werden in Form eines Punktnotation im JSON-Stil durch einen Punkt getrennt.

Im Folgenden finden Sie Beispiele für Ressourcenattribute und wie sie abgerufen werden können:

resourceName: Speichert den vollständigen Namen einer Ressource in Cloud Asset Inventory, z. B. //cloudresourcemanager.googleapis.com/projects/296605646631.
resource.rotationPeriod: wobei rotationPeriod eine Property von resource ist.
resource.metadata.name: Dabei ist name eine untergeordnete Property von metadata, die wiederum eine untergeordnete Property von resource ist.

Referenzattribute der IAM-Richtlinie

Sie können CEL-Ausdrücke erstellen, die die IAM-Richtlinie einer Ressource bewerten, indem Sie auf deren IAM-Richtlinienattribute verweisen. Die einzigen verfügbaren Attribute sind Bindungen und Rollen innerhalb von Bindungen.

Beim Verweis auf IAM-Richtlinienattribute ist policy das Attribut der obersten Ebene.

Im Folgenden finden Sie Beispiele für IAM-Richtlinienattribute und deren Abruf:

policy.bindings, wobei bindings eine Property von policy ist.
policy.version, wobei version eine Property von policy ist.

Weitere Beispiele finden Sie unter Beispiele für CEL-Ausdrücke.

Informationen zu den Attributen einer Richtlinie finden Sie unter Richtlinie.

CEL-Ausdrücke schreiben

Wenn Sie ein benutzerdefiniertes Modul erstellen, verwenden Sie CEL-Ausdrücke, um die Attribute der gescannten Ressource auszuwerten. Optional können Sie auch CEL-Ausdrücke verwenden, um benutzerdefinierte name-value-Paare zu definieren, die zusätzliche Informationen mit Ihren Ergebnissen zurückgeben.

Unabhängig davon, ob Sie ein benutzerdefiniertes Modul in der Google Cloud Console erstellen oder Ihre benutzerdefinierte Moduldefinition selbst in eine YAML-Datei schreiben, sind die von Ihnen definierten CEL-Ausdrücke identisch.

CEL-Ausdrücke für die Erkennungslogik

Sie codieren die Erkennungslogik eines benutzerdefinierten Moduls mithilfe von CEL-Ausdrücken mit CEL-Standardoperatoren, um die Attribute der gescannten Ressourcen auszuwerten.

Die Ausdrücke können einfache Prüfungen eines einzelnen Werts oder komplexere zusammengesetzte Ausdrücke sein, die mehrere Werte oder Bedingungen prüfen. In beiden Fällen muss der Ausdruck in einen booleschen true-Wert aufgelöst werden, damit ein Ergebnis ausgelöst wird.

Wenn Sie ein benutzerdefiniertes Modul in der Google Cloud Console erstellen, schreiben Sie diese Ausdrücke auf der Seite Modul konfigurieren im Ausdruckseditor.

Wenn Sie ein benutzerdefiniertes Modul in einer YAML-Datei codieren, fügen Sie diese Ausdrücke unter dem Attribut predicate hinzu.

Unabhängig davon, ob Sie die Google Cloud Console oder eine YAML-Datei verwenden, müssen CEL-Ausdrücke zur Auswertung von Ressourcenattributen den folgenden Regeln entsprechen:

Die Attribute, die Sie in einem CEL-Ausdruck angeben, müssen Attribute der gescannten Ressource sein, wie in der API-Definition des Ressourcentyps definiert.
Wenn ein benutzerdefiniertes Modul mehrere Ressourcentypen auswertet, müssen die Attribute, die Sie in den CEL-Ausdrücken angeben, jedem Ressourcentyp des benutzerdefinierten Moduls gemeinsam sein.

Wenn Sie beispielsweise ein benutzerdefiniertes Modul namens invalid_cryptokey definieren, das zwei Ressourcentypen prüft: cloudkms.googleapis.com/CryptoKey und cloudkms.googleapis.com/CryptoKeyVersion, können Sie den folgenden Ausdruck schreiben, da die Ressourcentypen CryptoKey und CryptoKeyVersion das Attribut name enthalten:
```
predicate:
resource.name.matches("projects/project1/locations/us-central1/keyRings/keyring1/cryptoKeys/.*")
```
Sie können den folgenden Ausdruck jedoch nicht im benutzerdefinierten Modul invalid_cryptokey angeben, da die vom Ausdruck ausgewerteten Attribute importTime und rotationPeriod nicht von beiden Ressourcentypen gemeinsam genutzt werden:
```
predicate:
resource.importTime >= timestamp("2022-10-02T15:01:23Z") || resource.rotationPeriod > duration("2592000s")
```
Alle Enums in einem CEL-Ausdruck müssen als Strings dargestellt werden. Im Folgenden finden Sie beispielsweise einen gültigen Ausdruck für den Ressourcentyp cloudkms.googleapis.com/CryptoKeyVersion:
```
resource.state = "PENDING_GENERATION"
```
Das Ergebnis der CEL-Ausdrücke, die Sie im Attribut predicate definieren, muss ein boolescher Wert sein. Ein Ergebnis wird nur ausgelöst, wenn das Ergebnis true ist.

Weitere Informationen zu CEL finden Sie hier:

Beispiel-CEL-Ausdrücke

In der folgenden Tabelle sind einige CEL-Ausdrücke aufgeführt, die zum Bewerten von Ressourcenattributen verwendet werden können. Sie können diese sowohl in der Google Cloud Console als auch in benutzerdefinierten YAML-Moduldefinitionen verwenden.

Ressourcentyp	Erläuterung	CEL-Ausdruck
Jede Ressource mit einer IAM-Richtlinie	IAM-Richtlinienprüfung zur Identifizierung von Mitgliedern außerhalb der Domain	`!policy.bindings.all(binding, binding.members.all(m ,!m.endsWith('@gmail.com')))`
`cloudkms.googleapis.com/CryptoKey`	Prüfung des Cloud KMS-Schlüsselrotationszeitraums	`has(resource.rotationPeriod) && resource.rotationPeriod > duration('60h')`
Mehrere Ressourcentypen mit einer einzigen Richtlinie	Prüfen Sie je nach Ressourcentyp, ob der Ressourcenname mit `dev` oder `devAccess` beginnt	`(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`	Peering-Regel für die Virtual Private Cloud zum Abgleich von Netzwerk-Peers	`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`	Nur internen eingehenden Traffic für Cloud Function zulassen	`has(resource.ingressSettings) && resource.ingressSettings.matches('ALLOW_INTERNAL_ONLY')`
`compute.googleapis.com/Instance`	Ressourcenname stimmt mit Muster überein	`resource.name.matches('^gcp-vm-(linux\|windows)-v\\d+$')`
`serviceusage.googleapis.com/Service`	Nur speicherbezogene APIs aktivieren	`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`	Nur öffentliche IP-Adressen auf der Zulassungsliste sind zulässig	`(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`	Prüfen, ob Projekt-IDs in einem Dataproc-Cluster die Teilstrings für Tests oder Entwicklung enthalten	`has(resource.projectId) && resource.projectId.contains('testing') \|\| resource.projectId.contains('development')`

CEL-Ausdrücke für benutzerdefinierte Ergebnisattribute

Wenn Sie zusätzliche Informationen zu jedem Ergebnis zurückgeben möchten, das für Ergebnisabfragen verwendet werden kann, können Sie optional bis zu zehn benutzerdefinierte Attribute definieren, die mit den von Ihren benutzerdefinierten Modulen generierten Ergebnissen zurückgegeben werden sollen.

Die benutzerdefinierten Eigenschaften werden in den Quellattributen des Ergebnisses im JSON-Format und in der Google Cloud Console auf dem Tab Quelleigenschaften der Ergebnisdetails angezeigt.

Benutzerdefinierte Eigenschaften werden als name-value-Paare definiert.

Wenn Sie ein benutzerdefiniertes Modul in der Google Cloud Console erstellen, definieren Sie die name-value-Paare im Abschnitt Benutzerdefinierte Ergebnisattribute auf der Seite Ergebnisdetails definieren.

Wenn Sie ein benutzerdefiniertes Modul in einer YAML-Datei codieren, listen Sie die name-value-Paare als properties im Attribut custom_output auf.

Unabhängig davon, ob Sie die Google Cloud Console oder eine YAML-Datei verwenden, gelten die folgenden Regeln:

Geben Sie name als Textstring ohne Anführungszeichen an.
Geben Sie value auf einen der folgenden Werte an:
- Wenn Sie den Wert einer Eigenschaft zurückgeben möchten, geben Sie die Eigenschaft im folgenden Format an:
  
  RESOURCE_TYPE.PROPERTY.PROPERTY_TO_RETURN
Im Beispiel gilt Folgendes:
- RESOURCE_TYPE kann entweder resource oder policy sein.
- PROPERTY ist ein oder mehrere übergeordnete Attribute der Eigenschaft, die den zurückzugebenden Wert enthält.
- PROPERTY_TO_RETURN ist die Property, die den zurückzugebenden Wert enthält.
- Um eine Textzeichenfolge zurückzugeben, setzen Sie sie in Anführungszeichen.

Das folgende Beispiel zeigt zwei name-value-Paare, die in einer YAML-Datei ordnungsgemäß unter custom_output definiert sind:

custom_output:
  properties:
    - name: duration
      value_expression:
        expression: resource.name
    - name: property_with_text
      value_expression:
        expression: "Note content"

Nächste Schritte

Informationen zum Testen, Einreichen, Aufrufen und Aktualisieren benutzerdefinierter Module finden Sie auf den folgenden Seiten:

Informationen zum Testen benutzerdefinierter Module finden Sie unter Benutzerdefinierte Module für Security Health Analytics testen.
Informationen zum Hochladen, Ansehen und Aktualisieren benutzerdefinierter Module finden Sie unter Benutzerdefinierte Module für Security Health Analytics erstellen und verwalten.