Benutzerdefiniertes Modul für Security Health Analytics programmieren

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

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 das erkannte Problem schnell verstehen, priorisieren und beheben können.

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

Vermeiden Sie redundante Sensoren.

Um die Anzahl der Ergebnisse zu steuern, sollten Sie keine Module erstellen und ausführen, die redundante Funktionen enthalten.

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:

1. Erstellen Sie eine Textdatei mit der Dateinamenserweiterung yaml.

2. 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 unterstützt werden. Eine Liste der unterstützten Ressourcentypen finden Sie unter Unterstützte Ressourcentypen.

3. 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 die einzelnen Ressourcen, um die Attribute zu sehen, die Sie in Ihren CEL-Ausdrücken verwenden können.
   • CEL-Ausdrücke schreiben
   • Verweise auf Ressourcen- und Richtlinieneigenschaften in benutzerdefinierten Modulen

4. 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."

5. Erstellen Sie eine recommendation-Property, in der beschrieben wird, wie das erkannte Problem behoben werden kann. In der gcloud CLI 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 escapiert 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 mit der Google Cloud Console erstellen oder aktualisieren, sind keine Escape-Zeichen erforderlich.

6. 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

7. Optional können Sie eine custom_output-Property erstellen und zusätzliche Informationen angeben, die mit jeder Feststellung zurückgegeben werden sollen. Geben Sie die Informationen als ein oder mehrere Name/Wert-Paare an. Sie können entweder den Wert einer Property der gescannten Ressource oder einen Literalstring zurückgeben. Unterkünfte müssen als resource.PROPERTY_NAME angegeben werden. Literalstrings müssen in Anführungszeichen gesetzt werden. 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"
   

8. Speichern Sie die Datei an einem Speicherort, auf den die gcloud CLI zugreifen kann.

9. 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 mit einem Namen, der als Ergebniskategorie angezeigt wird, 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 benutzerdefinierten Security Health Analytics-Modulen finden Sie unter Benutzerdefinierte Module für Security Health Analytics verwenden.

Latenzen für neue benutzerdefinierte Module prüfen

Das Erstellen eines benutzerdefinierten Moduls löst keinen neuen Scan aus.

In Security Health Analytics wird ein neues benutzerdefiniertes Modul erst dann verwendet, wenn einer der folgenden Fälle eintritt:

• Beim ersten Batch-Scan nach dem Erstellen des benutzerdefinierten Moduls. Je nachdem, wann Sie ein benutzerdefiniertes Modul in Ihrem Zeitplan für Batch-Scans erstellen, kann es bis zu 24 Stunden dauern, bis es in Security Health Analytics verwendet wird.
• Eine Änderung an einer Zielressource löst einen Echtzeit-Scan aus.

Beispiel für eine benutzerdefinierte Moduldefinition

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 Abschnitt custom_output zwei optionale Werte zurückgegeben: der Wert von resource.rotationPeriod und eine Notiz als Textstring.

Beachten Sie in diesem Beispiel die folgenden Elemente:

• Die Art des zu prüfenden Assets oder der zu prüfenden Ressource ist im Abschnitt resource_selector unter resource_types aufgeführt.
• Die Prüfung, die das Modul an den Ressourcen durchführt, also seine Erkennungslogik, wird im Abschnitt predicate definiert, der von expression vorangestellt wird.
• Im Abschnitt custom_output sind zwei benutzerdefinierte Quelleigenschaften definiert: duration und violation.
• Eine Erklärung des erkannten Problems finden Sie in der Property description.
• Eine Anleitung zur Behebung des erkannten Problems finden Sie in der Property recommendation. Da in der Anleitung Anführungszeichen verwendet werden, ist vor jedem Anführungszeichen ein umgekehrter Schrägstrich als Escape-Zeichen erforderlich.

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"

Ressourcen- und Richtlinieneigenschaften in benutzerdefinierten Modulen referenzieren

Unabhängig davon, welche Methode Sie zum Erstellen eines benutzerdefinierten Moduls verwenden – über die Google Cloud Console oder indem Sie die Definition selbst schreiben –, müssen Sie die Eigenschaften, die Sie im benutzerdefinierten Modul auswerten können, nachschlagen können. 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 Eigenschaften einer Richtlinie finden Sie in der IAM API-Referenzdokumentation. Informationen zu den Eigenschaften einer Richtlinie finden Sie unter Richtlinie.

Auf eine Ressourceneigenschaft in einer benutzerdefinierten Moduldefinition verweisen

Wenn Sie ein benutzerdefiniertes Modul erstellen, müssen alle direkten Verweise auf die Property einer gescannten Ressource mit resource beginnen, gefolgt von allen übergeordneten Properties und schließlich der Ziel-Property. Die Eigenschaften werden durch einen Punkt getrennt, wobei die Punktnotation in JSON-Form verwendet wird.

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

• resourceName: Der vollständige Name einer Ressource wird in Cloud Asset Inventory gespeichert, z. B. //cloudresourcemanager.googleapis.com/projects/296605646631.
• resource.rotationPeriod: wobei rotationPeriod eine Eigenschaft von resource ist.
• resource.metadata.name: wobei name eine untergeordnete Property von metadata ist, die wiederum eine untergeordnete Property von resource ist.

IAM-Richtlinieneigenschaften als Referenz verwenden

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

Bei Verweis auf IAM-Richtlinieneigenschaften ist policy die oberste Property.

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

• policy.bindings, wobei bindings ein Attribut von policy ist.
• policy.version, wobei version ein Attribut von policy ist.

Weitere Beispiele finden Sie unter Beispiel-CEL-Ausdrücke.

Informationen zu den Eigenschaften 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 mit CEL-Ausdrücken mit Standard-CEL-Operatoren, um die Eigenschaften der gescannten Ressourcen zu bewerten.

Ihre 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 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 diese Ausdrücke unter der Eigenschaft predicate hinzu.

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 der gescannten Ressource sein, wie in der API-Definition des Ressourcentyps definiert.

• Wenn in einem benutzerdefinierten Modul mehrere Ressourcentypen ausgewertet werden, müssen die in den CEL-Ausdrücken angegebenen Eigenschaften für jeden Ressourcentyp identisch 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 sowohl der Ressourcentyp CryptoKey als auch CryptoKeyVersion das Attribut name enthalten:

  predicate:
  resource.name.matches("projects/project1/locations/us-central1/keyRings/keyring1/cryptoKeys/.*")

  Der folgende Ausdruck kann jedoch nicht im benutzerdefinierten invalid_cryptokey-Modul angegeben werden, da die Eigenschaften importTime und rotationPeriod, die vom Ausdruck ausgewertet werden, nicht für beide Ressourcentypen gemeinsam sind:

  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:

• CEL-Spezifikation
• CEL-Sprachdefinition

Beispiel-CEL-Ausdrücke

In der folgenden Tabelle sind einige CEL-Ausdrücke aufgeführt, mit denen sich Ressourceneigenschaften bewerten lassen. Sie können sie sowohl in der Google Cloud Console als auch in YAML-Beschreibungen für benutzerdefinierte Module verwenden.

CEL-Ausdrücke für benutzerdefinierte Ergebnisattribute

Optional können Sie bis zu zehn benutzerdefinierte Properties definieren, die mit den Ergebnissen zurückgegeben werden, die in Suchanfragen verwendet werden können.

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, definieren Sie die name-value-Paare auf der Seite Ergebnisdetails definieren im Abschnitt Eigenschaften für benutzerdefinierte Ergebnisse.

Wenn Sie ein benutzerdefiniertes Modul in einer YAML-Datei codieren, listen Sie die name-value-Paare unter der Eigenschaft custom_output als properties 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 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 den zurückzugebenden Wert enthält.

  • Wenn Sie einen Textstring zurückgeben möchten, setzen Sie ihn in Anführungszeichen.

Das folgende Beispiel zeigt zwei name-value-Paare, die in einer YAML-Datei unter custom_output korrekt 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, 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.