Diese Seite wurde von der Cloud Translation API übersetzt.

Benutzerdefiniertes Modul für Security Health Analytics programmieren

Auf dieser Seite wird erläutert, wie Sie die Definition eines benutzerdefinierten Moduls mithilfe der Methode Common Expression Language (CEL) und YAML.

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

In der YAML-Datei besteht eine Definition für ein benutzerdefiniertes Modul aus einer strukturierten Reihe von Eigenschaften, mit denen Sie die folgenden Elemente eines benutzerdefinierten Security Health Analytics-Moduls definieren:

Die zu scannenden Ressourcen.
Die zu verwendende Erkennungslogik.
Informationen, die Sie Ihren Sicherheitsteams zur Verfügung stellen müssen, damit sie schnell das erkannte Problem zu verstehen, einzuschätzen und zu beheben.

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

Vermeiden Sie redundante Sensoren.

Vermeiden Sie es, Module zu erstellen und auszuführen, die Folgendes enthalten: überflüssige Funktionen.

Wenn Sie beispielsweise ein benutzerdefiniertes Modul erstellen, das nach Verschlüsselungsschlüsseln sucht, 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

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

So codieren Sie ein benutzerdefiniertes Definitionsmodul:

Erstellen Sie eine Textdatei mit der Dateiendung yaml.
Erstellen Sie in der Textdatei eine resource_selector-Property und geben Sie einen bis fünf Ressourcentypen für das zu scannende benutzerdefinierte Modul an. Ein Ressourcentyp kann in einer benutzerdefinierten Moduldefinition nicht mehrmals angegeben werden. Beispiel:
```
resource_selector:
 resource_types:
 ‐ cloudkms.googleapis.com/CryptoKey
```
Die von Ihnen angegebenen Ressourcentypen müssen von Security Command Center. Eine Liste der unterstützten Ressourcentypen finden Sie unter Unterstützte Ressourcentypen.
Erstellen Sie eine predicate-Property und geben Sie einen oder mehrere CEL-Ausdrücke an, mit denen Eigenschaften der zu scannenden Ressourcentypen geprüft werden. Alle Properties, 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. Damit ein Ergebnis ausgelöst wird, muss der Ausdruck auf TRUE verweisen. Im folgenden Ausdruck lösen beispielsweise nur rotationPeriod-Werte, die größer als 2592000s sind, eine Abweichung aus.
```
predicate:
 expression: resource.rotationPeriod > duration("2592000s")
```
Hilfe beim Schreiben von CEL-Ausdrücken finden Sie in den folgenden Ressourcen:
- Unterstützte Ressourcentypen Klicken Sie auf jede Ressource, um die Eigenschaften anzuzeigen, die Sie in Ihrem CEL-Ausdrücke
- CEL-Ausdrücke schreiben
- In benutzerdefinierten Modulen auf Ressourcen- und Richtlinienattribute verweisen
Erstellen Sie eine description-Property, in der die Sicherheitslücke oder Fehlkonfiguration erläutert wird, die vom benutzerdefinierten Modul erkannt wird. Diese Erklärung wird bei jeder gefundenen Instanz 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, in der beschrieben wird, wie das erkannte Problem behoben werden kann. In der gcloud-Befehlszeile ist vor bestimmten Zeichen wie Anführungszeichen ein Escape-Zeichen erforderlich. Im folgenden Beispiel wird gezeigt, wie mit dem umgekehrten Schrägstrich jedes Anführungszeichen-Set entkommentiert wird:
```
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 mithilfe der Methode Google Cloud Console verwenden, sind keine Escape-Zeichen erforderlich.
Erstellen Sie ein severity-Attribut und geben Sie die Standardschwere für die von diesem Modul erstellten Ergebnisse an. Gängige Werte für die Eigenschaft severity sind LOW, MEDIUM, HIGH und CRITICAL. Beispiel:
```
severity: MEDIUM
```
Erstellen Sie optional ein custom_output-Attribut und geben Sie zusätzliche Informationen, die mit jedem Ergebnis zurückgegeben werden können. Geben Sie die Informationen als ein oder mehrere Name/Wert-Paare an. Sie können entweder den Wert eines Attributs der gescannten Ressource zurückgeben oder einen literalen String. Unterkünfte müssen als resource.PROPERTY_NAME angegeben werden. Literalstrings müssen in Anführungszeichen gesetzt. Im folgenden Beispiel wird eine custom_output-Definition gezeigt, die sowohl einen Attributwert, den Wert von rotationPeriod in der gescannten CryptoKey-Ressource, als auch einen 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 Ihre 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 ersetzen oder das Flag --organization durch --folders oder --project ersetzen und die ID des übergeordneten Ordners oder Projekts angeben.
- MODULE_DISPLAY_NAME durch einen Namen, der angezeigt werden soll als Ergebniskategorie verwenden, wenn das benutzerdefinierte Modul Ergebnisse zurückgibt. Der Name muss zwischen 1 und 128 Zeichen lang sein und mit einem Kleinbuchstaben beginnen. Er darf nur alphanumerische Zeichen oder Unterstriche enthalten.
- DEFINITION_FILE_NAME durch den Pfad und den Dateinamen der YAML-Datei ersetzen, die die Definition des benutzerdefinierten Moduls enthält.
Weitere Informationen zur Arbeit mit Security Health Analytics (benutzerdefiniert) finden Sie unter Benutzerdefinierte Module für Security Health Analytics verwenden

Latenzen für neue benutzerdefinierte Module prüfen

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

Ein neues benutzerdefiniertes Modul wird in Security Health Analytics erst dann verwendet, wenn einer der folgenden Punkte zutrifft:

Der erste Batch-Scan nach dem Erstellen des benutzerdefinierten Moduls. Je nach Wenn Sie in Ihrem Zeitplan für den Batch-Scan ein benutzerdefiniertes Modul erstellen, kann es bis zu 24 Stunden dauern, bis Security Health Analytics benutzerdefiniertes Modul.
Eine Änderung an einer Zielressource löst einen Echtzeitscan aus.

Beispiel für die Definition eines benutzerdefinierten Moduls

Das folgende Beispiel zeigt eine fertige Definition eines benutzerdefinierten Moduls, das ein Ergebnis auslöst, wenn der Wert des Attributs rotationPeriod einer cloudkms.googleapis.com/CryptoKey-Ressource mehr als 2.592.000 Sekunden (30 Tage) beträgt. Im Beispiel werden im Feld Abschnitt custom_output: der Wert von resource.rotationPeriod und ein Hinweis als Textzeichenfolge.

Beachten Sie in diesem Beispiel die folgenden Elemente:

Der zu prüfende Asset- oder Ressourcentyp ist in der resource_selector aufgeführt. unter resource_types.
Die Prüfung, die das Modul für die Ressourcen durchführt, seine Erkennungslogik, ist im Abschnitt predicate mit vorangestelltem expression definiert.
Es werden zwei benutzerdefinierte Quell-Properties definiert, duration und violation im Abschnitt custom_output.
Eine Erklärung des erkannten Problems finden Sie in der Property description.
Eine Anleitung zur Behebung des erkannten Problems finden Sie unter recommendation. Da Anführungszeichen müssen Sie vor jedem Schrägstrich ein Escapezeichen setzen. Anführungszeichen.

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 davon, mit welcher Methode Sie ein benutzerdefiniertes Modul erstellen, indem Sie die oder indem Sie die Definition selbst schreiben, müssen Sie die Eigenschaften nachschlagen können, die Sie in der benutzerdefiniertes Modul. Außerdem müssen Sie wissen, wie Sie in einer benutzerdefinierten Moduldefinition auf diese Properties verweisen.

Eigenschaften einer Ressource oder Richtlinie finden

Die Eigenschaften einer Google Cloud-Ressource werden in der API-Definition der Ressource definiert. Sie finden diese Definition, indem Sie unter Unterstützte Ressourcentypen auf den Ressourcennamen klicken.

Die Attribute einer Richtlinie finden Sie in der IAM-Datei API-Referenzdokumentation Informationen zu den Eigenschaften einer Richtlinie finden Sie unter Richtlinie.

Auf eine Ressourceneigenschaft in der Definition eines benutzerdefinierten Moduls verweisen

Wenn Sie ein benutzerdefiniertes Modul erstellen, können alle direkten Verweise auf die Eigenschaft einer gescannten Ressource muss mit resource beginnen, gefolgt von einem beliebigen übergeordneten Element. und schließlich die Zieleigenschaft. Die Eigenschaften werden getrennt durch einen Punkt, unter Verwendung einer Punktnotation im JSON-Stil.

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, für Beispiel: //cloudresourcemanager.googleapis.com/projects/296605646631.
resource.rotationPeriod: Dabei ist rotationPeriod eine Property von resource.
resource.metadata.name: wobei name eine untergeordnete Property von metadata ist, die wiederum eine untergeordnete Property von resource ist.

Referenz-IAM-Richtlinienattribute

Sie können CEL-Ausdrücke erstellen, um die IAM-Richtlinie auszuwerten einer Ressource durch Verweisen auf die IAM-Richtlinienattribute der Ressource. Die einzigen verfügbaren Attribute sind Bindungen und Rollen innerhalb von Bindungen.

Beim Verweisen auf IAM-Richtlinienattribute ist policy der Wert für die Property der obersten Ebene.

Im Folgenden finden Sie Beispiele für IAM-Richtlinienattribute und ihre Vorgehensweise. kann abgerufen werden:

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

Weitere Beispiele finden Sie unter CEL-Beispiele.

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 Eigenschaften der gescannten Ressource zu bewerten. Optional können Sie auch CEL-Ausdrücke verwenden, um benutzerdefinierte name-value-Paare zu definieren, die zusätzliche Informationen zu Ihren Ergebnissen zurückgeben.

Ganz gleich, ob Sie ein benutzerdefiniertes Modul in der Google Cloud Console erstellen oder die Definition des benutzerdefinierten Moduls selbst in einer YAML-Datei schreiben, die von Ihnen definierten CEL-Ausdrücke sind identisch.

CEL-Ausdrücke für die Erkennungslogik

Sie codieren die Erkennungslogik eines benutzerdefinierten Moduls mithilfe von CEL mit Standard-CEL-Operatoren, um die Eigenschaften die gescannten Ressourcen.

Ihre Ausdrücke können einfache oder komplexere Prüfungen eines einzelnen Werts sein zusammengesetzten Ausdrücken, die mehrere Werte oder Bedingungen überprüfen. In beiden Fällen muss der Ausdruck in einen booleschen Wert true aufgelöst werden, um eine Meldung auszulösen.

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

Wenn Sie ein benutzerdefiniertes Modul in einer YAML-Datei codieren, fügen Sie folgende Ausdrücke hinzu: unter der Property predicate.

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

Die in einem CEL-Ausdruck angegebenen Eigenschaften müssen Attribute sein der gescannten Ressource, wie in der API-Definition der Ressource definiert Typ.
Wenn ein benutzerdefiniertes Modul mehrere Ressourcentypen auswertet, die Sie in den CEL-Ausdrücken angeben, müssen für jeden Ressourcentyp gemeinsam sein die das benutzerdefinierte Modul auswertet.

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 sowohl der Ressourcentyp CryptoKey als auch 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 in der invalid_cryptokey, weil die importTime und rotationPeriod-Eigenschaften, die der Ausdruck auswertet, sind nicht gemeinsam genutzt nach beiden Ressourcentypen aufgeschlüsselt werden:
```
predicate:
resource.importTime >= timestamp("2022-10-02T15:01:23Z") || resource.rotationPeriod > duration("2592000s")
```
Alle Enumerationen in einem CEL-Ausdruck müssen als Strings dargestellt werden. Der folgende Ausdruck ist beispielsweise für den Ressourcentyp cloudkms.googleapis.com/CryptoKeyVersion gültig:
```
resource.state = "PENDING_GENERATION"
```
Das Ergebnis der CEL-Ausdrücke, die Sie in der Property predicate definieren, muss ein boolescher Wert sein. Eine Meldung 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, mit denen sich Ressourceneigenschaften bewerten lassen. Sie können beide in der Definitionen von benutzerdefinierten YAML-Modulen in der Google Cloud Console.

Ressourcentyp	Erklärung	CEL-Ausdruck
Alle Ressourcen mit einer IAM-Richtlinie	IAM-Richtlinienprüfung zur Identifizierung von Mitgliedern von 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üsselrotationszeitraum	`has(resource.rotationPeriod) && resource.rotationPeriod > duration('60h')`
Mehrere Ressourcentypen mit einer einzelnen Richtlinie	Prüfen, ob der Ressourcenname je nach Ressourcentyp 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`	Virtual Private Cloud-Peering-Regel zum Abgleichen 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 die Cloud Run-Funktion 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`	Aktivieren nur speicherbezogene APIs zulassen	`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 Folgendes enthalten: Teilstrings „Test“ oder „Development“	`has(resource.projectId) && resource.projectId.contains('testing') \|\| resource.projectId.contains('development')`

CEL-Ausdrücke für benutzerdefinierte Ergebnisattribute

Optional, um zu jedem Ergebnis, das ermittelt werden kann, zusätzliche Informationen zurückzugeben zum Ermitteln von Abfragen können Sie bis zu zehn benutzerdefinierte Eigenschaften um die Ergebnisse zurückzugeben, die von Ihren benutzerdefinierten Modulen generiert wurden.

Die benutzerdefinierten Properties werden in den Quellattributen des Ergebnisses in der JSON-Datei und auf dem Tab Quellattribute der Ergebnisdetails in der Google Cloud Console angezeigt.

Sie definieren benutzerdefinierte Properties als name-value-Paare.

Wenn Sie ein benutzerdefiniertes Modul in der Google Cloud Console erstellen, Sie definieren die name-value-Paare in den benutzerdefinierten Ergebnisattributen. auf der Seite Ergebnisdetails definieren.

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

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

Geben Sie name als Textstring ohne Anführungszeichen an.
Geben Sie value als eine der folgenden Optionen an:
- Wenn Sie den Wert eines Attributs zurückgeben möchten, geben Sie das Attribut im folgenden Format an:
  
  RESOURCE_TYPE.PROPERTY.PROPERTY_TO_RETURN
Im Beispiel gilt Folgendes:
- RESOURCE_TYPE kann entweder resource oder policy sein.
- PROPERTY eine oder mehrere übergeordnete Properties der Property, die den zurückzugebenden Wert enthält.
- PROPERTY_TO_RETURN ist die Property, die Folgendes enthält: den Wert, der zurückgegeben werden soll.
- Wenn Sie einen Textstring zurückgeben möchten, setzen Sie ihn in Anführungszeichen.

Im folgenden Beispiel sind zwei name-value-Paare richtig definiert unter custom_output in einer YAML-Datei:

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, Ansehen und Aktualisieren benutzerdefinierter Module finden Sie auf den folgenden Seiten:

Wie Sie benutzerdefinierte Module testen, erfahren 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.