Benutzerdefiniertes Modul für Security Health Analytics programmieren

Auf dieser Seite wird erklärt, wie Sie eine benutzerdefinierte Moduldefinition mit der Common Expression Language (CEL) und YAMLcodieren.

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

In der YAML-Datei besteht eine benutzerdefinierte Moduldefinition aus einer strukturierten Gruppe 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, priorisieren und beheben können.

Die spezifischen erforderlichen und optionalen Attribute, aus denen eine YAML-Definition besteht werden unter Codierungsschritte behandelt.

Redundante Detektoren vermeiden

Um das Ergebnisvolumen 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 die 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.

Codierungsschritte

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

So codieren Sie ein benutzerdefiniertes Modul:

  1. Erstellen Sie eine Textdatei mit der Dateinamenerweiterung yaml.

  2. Erstellen Sie in der Textdatei ein resource_selector-Attribut und geben Sie ein bis fünf Ressourcentypen an, die vom benutzerdefinierten Modul gescannt werden sollen. 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.

  3. 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_selectorangeben. Damit ein Ergebnis ausgelöst wird, muss der Ausdruck in TRUE aufgelöst werden. Im folgenden Ausdruck lösen beispielsweise nur rotationPeriod-Werte, die größer als 2592000s sind, ein Ergebnis aus.

    predicate:
 expression: resource.rotationPeriod > duration("2592000s")

    Hilfe beim Schreiben von CEL-Ausdrücken finden Sie in den folgenden Ressourcen:

  4. Erstellen Sie ein description-Attribut, in dem die Sicherheitslücke oder Fehlkonfiguration erläutert wird, die vom benutzerdefinierten Modul erkannt wird. Diese Erklärung wird in jeder Ergebnisinstanz angezeigt, damit Prüfer das erkannte Problem verstehen 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 ein recommendation-Attribut, in dem erklärt wird, wie das erkannte Problem behoben werden kann. Die gcloud CLI erfordert ein Escapezeichen vor bestimmten Zeichen wie Anführungszeichen. Im folgenden Beispiel wird der umgekehrte Schrägstrich verwendet, um jedes Paar von Anführungszeichen zu maskieren:

    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.

  6. Erstellen Sie ein severity-Attribut und geben Sie den Standard-Schweregrad für die Ergebnisse an, die von diesem Modul erstellt werden. Häufig verwendete Werte für das severity-Attribut sind LOW, MEDIUM, HIGH und CRITICAL. Beispiel:

    severity: MEDIUM

  7. Optional können Sie ein custom_output-Attribut erstellen und zusätzliche Informationen angeben, die mit jedem Ergebnis zurückgegeben werden sollen. Geben Sie die zurückzugebenden Informationen als ein oder mehrere Name-Wert-Paare an. 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 einen Textstring zurückgibt: "Excessive rotation period for CryptoKey":

     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 Ihre 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 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 werden soll, wenn das benutzerdefinierte Modul Ergebnisse zurückgibt. Der Name muss zwischen 1 und 128 Zeichen lang sein, mit einem Kleinbuchstaben beginnen und 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 benutzerdefinierter Module von Security Health Analytics 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 verwendet ein neues benutzerdefiniertes Modul erst, wenn eine der folgenden Bedingungen erfüllt ist:

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

Beispiel für eine benutzerdefinierte Moduldefinition

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

Beachten Sie im Beispiel 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, die das Modul für die Ressourcen ausführt, die Erkennungslogik, wird im Abschnitt predicate definiert, dem expression vorangestellt ist.
  • Im Abschnitt custom_output sind zwei benutzerdefinierte Quellattribute definiert: duration und violation.
  • Die Erklärung des erkannten Problems wird im Attribut description angegeben.
  • Die Anleitung zur Behebung des erkannten Problems wird im Attribut recommendation angegeben. Da in der Anleitung Anführungszeichen vorkommen, ist vor jedem Anführungszeichen ein umgekehrter Schrägstrich als Escapezeichen 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'"

Auf Ressourcen- und Richtlinienattribute in benutzerdefinierten Modulen verweisen

Unabhängig davon, mit welcher Methode Sie ein benutzerdefiniertes Modul erstellen – über die Google Cloud Console oder durch Schreiben der Definition – müssen Sie die Attribute nachschlagen 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 finden

Die Attribute einer Google Cloud Ressource sind in der API Definition der Ressource definiert. Sie finden diese Definition, indem Sie auf der SeiteUnterstützte Ressourcentypenauf den Ressourcennamen klicken.

Die Attribute einer Richtlinie finden Sie in der IAM API-Referenzdokumentation. Informationen zu den Attributen 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 durch einen Punkt getrennt, wobei die JSON-Punktnotation verwendet wird.

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 ein Attribut von resource ist.
  • resource.metadata.name: wobei name ein Unterattribut von metadata ist, das ein Unterattribut von resource ist.

Auf IAM-Richtlinienattribute verweisen

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 Attribute sind Bindungen und Rollen innerhalb von Bindungen.

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

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

  • 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 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 Konsole erstellen oder Ihre benutzerdefinierte Moduldefinition selbst in einer 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 mit CEL-Ausdrücken und Standard-CEL-Operatoren, um die Attribute der gescannten Ressourcen auszuwerten.

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 ein Ergebnis auszulösen.

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, die Ressourcenattribute auswerten, die folgenden Regeln erfüllen:

  • Die in einem CEL-Ausdruck angegebenen Attribute 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 in den CEL-Ausdrücken angegebenen Attribute für jeden Ressourcentyp, den das benutzerdefinierte Modul auswertet, gleich sein.

    Wenn Sie beispielsweise ein benutzerdefiniertes Modul mit dem Namen 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 CryptoKey als auch der CryptoKeyVersion Ressourcentyp das Attribut name enthalten:

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

    Sie können jedoch den folgenden Ausdruck nicht im benutzerdefinierten Modul invalid_cryptokey angeben, da die Attribute importTime und rotationPeriod, die der Ausdruck auswertet, nicht von beiden Ressourcentypen gemeinsam verwendet 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. 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 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 unter:

Beispiel-CEL-Ausdrücke

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

Ressourcentyp Erklärung 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 Rotationszeitraums für Cloud KMS-Schlüssel 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 VPC-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 Cloud Run-Funktion zulassen has(resource.ingressSettings) && resource.ingressSettings.matches('ALLOW_INTERNAL_ONLY')
compute.googleapis.com/Instance Der Ressourcenname entspricht dem Muster resource.name.matches('^gcp-vm-(linux|windows)-v\\d+$')
serviceusage.googleapis.com/Service Nur die Aktivierung von speicherbezogenen 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 Managed Service for Apache Spark-Cluster die Teilstrings „testing“ oder „development“ enthalten has(resource.projectId) && resource.projectId.contains('testing') || resource.projectId.contains('development')

CEL-Ausdrücke für benutzerdefinierte Ergebniseigenschaften

Optional können Sie bis zu zehn benutzerdefinierte Attribute definieren, die mit den Ergebnissen zurückgegeben werden sollen, die von Ihren benutzerdefinierten Modulen generiert werden. Diese Attribute können in Ergebnisabfragen verwendet werden.

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

Sie definieren benutzerdefinierte Attribute als name-value-Paare.

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

Wenn Sie ein benutzerdefiniertes Modul in einer YAML-Datei codieren, listen Sie die name-value-Paare als properties unter dem 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 als einen der folgenden Werte 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 ist ein oder mehrere übergeordnete Attribute des Attributs, das den zurückzugebenden Wert enthält.

    • PROPERTY_TO_RETURN ist das Attribut, das den zurückzugebenden Wert enthält.

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

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