Beiträge zu Community-Antwortintegrationen

Unterstützt in:

In diesem Dokument werden die Richtlinien für das Einreichen von Antwort Integrationen bei Google SecOps über Community Beiträge beschrieben. Alle eingereichten Integrationen werden vom offiziellen Google SecOps-Team geprüft. Dabei liegt der Fokus auf den in diesem Dokument hervorgehobenen Anforderungen.

Metadaten der Antwortintegration

Name

Der Name sollte dem Produktnamen entsprechen, mit dem die Integration verknüpft werden soll, und darf keine Sonderzeichen enthalten.

Der Anzeigename sollte Leerzeichen enthalten, z. B. Vertex AI und nicht VertexAI.

Integrations-ID

Die Integrations-ID ist eine eindeutige Kennung der Integration. Nachdem die Integration erstellt wurde, kann dieser Wert nicht mehr geändert werden. Die ID sollte denselben Wert wie Name haben, aber ohne Leerzeichen.

Die ID ist an den meisten Stellen auf der Plattform verfügbar.

Beschreibung

Die Beschreibung sollte eine allgemeine Übersicht über das Produkt geben, mit dem die Integration erstellt wurde, und darf nicht mehr als 500 Zeichen umfassen. Sie muss die folgenden Informationen enthalten:

This integration is owned by the "{vendor name}". Support Contact: {email}.

URLs sollten nicht in die Beschreibung aufgenommen werden.

Logos

Für jede Integration sollte ein SVG-Symbol bereitgestellt werden. Dieses Symbol sollte sich an die Designs auf der Plattform anpassen. Symbole sollten das Design von der Plattform übernehmen.

Sie sollten das Logo auf den folgenden Seiten prüfen:

Hier ein Beispiel für ein SVG-Logo, das unserem Styleguide entspricht:

        <?xml version="1.0" encoding="UTF-8"?><svg id="Layer_1" data-name="Layer 1" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 21 23"> <defs> <style> .cls-1 { stroke-width: 0px; } </style> </defs> <path class="cls-1" d="M15.51,4.79H5.49c-.4,0-.72.32-.72.72v5.75c0,2.3,1.71,4.15,3.69,5.38.54.34,1.1.62,1.66.86l.09.04c.06.02.12.05.18.06.03,0,.07,0,.1,0,.1,0,.19-.03.28-.07l.09-.04c.76-.33,2.22-1.03,3.46-2.24,1.24-1.22,1.89-2.6,1.89-4v-5.75c0-.4-.32-.72-.72-.72ZM14.32,11.26c0,.88-.44,1.77-1.32,2.63-.65.64-1.55,1.22-2.5,1.68-.95-.46-1.84-1.04-2.5-1.68-.88-.86-1.32-1.75-1.32-2.63v-4.55h7.64v4.55ZM20.28,0H.72c-.4,0-.72.32-.72.72v10.77c0,2.56,1.18,4.99,3.51,7.21,2.29,2.18,5.12,3.56,6.61,4.2l.09.04s.1.04.15.05c.04,0,.09.01.13.01.1,0,.19-.02.28-.06l.09-.04c.53-.23,1.23-.55,2.02-.97,1.42-.75,3.11-1.82,4.59-3.23,2.33-2.22,3.51-4.64,3.51-7.21V.72c0-.4-.32-.72-.72-.72ZM16.17,17.31c-1.9,1.81-4.24,3.04-5.67,3.69-1.43-.65-3.77-1.88-5.67-3.69-1.94-1.84-2.92-3.8-2.92-5.82V1.92h17.18v9.57c0,2.02-.98,3.98-2.92,5.82Z"/></svg>

Codieren Sie das SVG, bevor Sie es der Datei mit der Integrationsdefinition hinzufügen. Beispiele finden Sie in anderen Integrationen im Content Hub.

Als Teil der Integration können Sie einen Link hinzufügen, der Nutzer zu der Dokumentation weiterleitet. Diese Dokumentation muss von Ihnen gehostet werden.

Nutzer können über den Bereich Parameter im Dialogfeld Instanz konfigurieren auf den Dokumentationslink zugreifen.

Konfigurationsparameter

Alle Integrationen sollten Konfigurationsparameter (API-Root + Authentifizierungsparameter) enthalten, es sei denn, für die zugrunde liegende API ist keine Authentifizierung erforderlich und der API-Root kann fest codiert werden. Für alle Integrationen, bei denen eine Authentifizierung erforderlich ist, sollte ein Verify SSL Parameter vorhanden sein.

Alle Parameter sollten eine Beschreibung haben. Die Beschreibung sollte Nutzern helfen, die Integration auf der Plattform zu konfigurieren. URLs sollten nicht in die Beschreibung von Parametern aufgenommen werden.

Ping-Aktion

Die Ping-Aktion ist eine spezielle Aktion, die von der Plattform verwendet wird, um die API-Verbindung zu prüfen. Diese Aktion ist obligatorisch, auch wenn Ihre Integration keine anderen Aktionen enthält. Wenn der Nutzer in der Integrationskonfiguration auf die Schaltfläche Testen klickt, sollte ein genauer Status der Verbindung angezeigt werden.

Versionshinweise

Die allgemeine Struktur für die Versionshinweise sollte dem folgenden Format entsprechen:

  • {integration item} - {update}
    • Beispiel: Get Case Details - Added ability to fetch information about affected IOCs

Je nach Situation gibt es spezielle Versionshinweise für bestimmte Szenarien:

  • Wenn es sich um eine neue Integration handelt: New Integration Added - {integration name}
  • Wenn eine neue Aktion hinzugefügt wird: New Action Added - {action name}
  • Wenn ein neuer Connector hinzugefügt wird: New Connector Added - {connector name}
  • Wenn ein neuer Job hinzugefügt wird: New Job Added - {job name}
  • Wenn einer Aktion ein vordefiniertes Widget hinzugefügt wird: {action name} - Added Predefined Widget.
  • Wenn ein vordefiniertes Widget aktualisiert wird: {action name} - Updated Predefined Widget.
  • Bei Änderungen, die sich auf alle Integrationselemente auswirken: Integration - {Update}
  • Bei Änderungen, die sich auf alle Aktionen auswirken: Integration's Actions - {Update}
  • Bei Änderungen, die sich auf alle Connectors auswirken: Integration's Connectors - {Update}
  • Bei Änderungen, die sich auf alle Jobs auswirken: Integration's Jobs - {Update}

Wenn die Version eine regressive Änderung enthält, müssen Sie in den Versionshinweisen müssen Sie angeben REGRESSIVE!. Beispiel: Google Chronicle - Chronicle Alerts Connector - REGRESSIVE! Updated mapping.

Versionshinweise sind im seitlichen Bereich Integrationsdetails verfügbar, der angezeigt wird, wenn Sie in der Integration auf die Schaltfläche Details klicken.

Versionsverwaltung

Auf jede Aktualisierung der Integration sollte eine Aktualisierung der Integrationsversion um +1 folgen. Versionen sollten als Ganzzahl dargestellt werden. Nebenversionen wie 11.1.3 oder 11.1 sind nicht zulässig.

Tags

Optional können Sie Ihrer Integration Tags hinzufügen. Erstellen Sie keine neuen Tag-Typen, sondern verwenden Sie die, die bereits auf der Plattform vorhanden sind. Wenn Sie kein passendes Tag finden, wenden Sie sich an das Prüfungsteam.

Allgemeine Hinweise

  • Testen Sie alle Inhalte der Integration vor dem Einreichen.
  • Prüfen Sie alle Inhalte der Integration auf potenzielle Sicherheitslücken und anfällige Abhängigkeiten.
  • Verwenden Sie bei der Entwicklung immer die neueste unterstützte Version von Python (Python 3.11).

Aktionen

Name

Der Name der Aktion sollte auf die ausgeführte Aktivität verweisen, z. B. Get Case Details, List Entity Events oder Execute Search.

Wenn die Aktion hauptsächlich mit Entitäten verwendet werden soll, ist es besser, Entity in den Namen aufzunehmen, z. B. Enrich Entities.

Aktionsnamen sollten aus zwei bis drei Wörtern bestehen.

Beschreibung

In der Beschreibung der Aktion sollte für den Nutzer hervorgehoben werden, was das Ergebnis der Ausführung der Aktion sein wird.

Wenn die Aktion mit Entitäten funktioniert, müssen Sie Informationen dazu hinzufügen, welche Arten von Entitäten unterstützt werden. Beispiel:

Add a vote to entities in VirusTotal. Supported entities: File Hash, URL, Hostname, Domain, IP Address. Note: only MD5, SHA-1 and SHA-256 Hash types are supported.

Wenn die Aktion im Async -Modus ausgeführt wird, müssen Sie in der Beschreibung den folgenden Hinweis angeben:

Note: Action is running as async, adjust script timeout value in Google SecOps IDE for action, as needed.

Die Beschreibung sollte nicht mehr als 500 Zeichen umfassen.

Aktionsparameter

Konfigurationsparameter für Aktionen sollten einen intuitiven Namen haben. Verwenden Sie keine Sonderzeichen und beschränken Sie den Namen des Aktionsparameters auf zwei bis vier Wörter.

In der Beschreibung des Parameters sollte erläutert werden, welche Auswirkungen dieser Parameter auf die Ausführung der Aktion hat. Wenn der Parameter eine bestimmte Anzahl unterstützter Werte unterstützt, geben Sie in der Beschreibung den folgenden Abschnitt an: Possible Values: {value 1}, {value 2}

Aktionsausgabe (Skriptergebnis)

Das Skriptergebnis sollte ein einfaches Ergebnis der Aktion darstellen. In den meisten Fällen sollte es nur auf eine Variable namens is_success verweisen, die die Werte true oder false annehmen kann.

Wenn die Aktion abgeschlossen wurde und ein Vorgang ausgeführt wurde, sollte is_success im Allgemeinen true sein.

Aktionsausgabe (JSON-Ergebnis)

Das JSON-Ergebnis ist die wichtigste Ausgabe der Aktion. Alle im JSON-Ergebnis verfügbaren Daten sind während der Playbook- Ausführung zugänglich. Prüfen Sie, ob ein gültiges JSON-Objekt an die Ausgabe gesendet wird.

JSON-Ergebnisse sind auf 15 MB begrenzt.

Achten Sie beim Erstellen eines JSON-Ergebnisses darauf, dass keine Schlüssel vorhanden sind, die während der Ausführung eindeutig sind. Das folgende JSON-Objekt stellt beispielsweise eine schlechte Struktur dar, da es in Playbooks nicht verwendet werden kann:


{
   "10.10.10.10": {
      "is_malicious": "false"
   }
}

Formatieren Sie es stattdessen so:


[
   {
      "is_malicious": "false",
      "ip": "10.10.10.10"
   }
]

Wenn Sie Entitäten in der Aktion verwenden und Ergebnisse pro Entität zurückgeben, ist es am besten, das JSON-Ergebnis so zu strukturieren:


[
   {
       "Entity": "10.10.10.10",
       "EntityResult": {
           "is_malicious": "false",
       }
   }
]

Überlegen Sie immer, wie die Ausgabe der Aktion in der Automatisierung verwendet werden kann.

Achten Sie darauf, dass für Ihre Aktion ein JSON-Beispiel vorhanden ist.

Das JSON-Beispiel wird von der Plattform im Ausdruckseditor während der Playbook-Erstellung verwendet. Ein genaues JSON-Beispiel verbessert die Playbook-Erstellung erheblich. Entfernen Sie alle personenbezogenen Daten aus JSON-Beispielen.

Aktionsausgaben (Entitätenanreicherung)

Wenn Aktionen für Entitäten ausgeführt werden, können Sie während der Ausführung der Aktion zusätzliche Metadaten anhängen. Die Struktur dieser Metadaten sollte diesem Format entsprechen: {integration identifier}_{key}. Zum Beispiel: WebRisk_is_malicious.

Die hinzugefügten Metadaten finden Sie auf der Detailseite der Entitäten.

Aktionsausgaben (Ausgabemeldung)

Die Ausgabemeldung sollte dem Nutzer auf beschreibendere Weise erklären, wie die Ausführung der Aktion verlaufen ist. Sie sollte den Nutzer auf das Ergebnis der Ausführung der Aktion hinweisen.

Wenn einige Entitäten erfolgreich angereichert wurden, andere jedoch nicht, ist es am besten, in der Meldung Statusinformationen für jede bereitgestellte Entität anzugeben.

Wenn Sie der Meinung sind, dass während der Ausführung der Aktion ein kritischer Fehler aufgetreten ist, muss eine ausführliche Meldung für diese Situation vorhanden sein und die Aktion muss fehlschlagen. Wenn die Aktion fehlschlägt, wird die Ausführung des entsprechenden Playbooks beendet, bis der Fehler behoben oder manuell übersprungen wird.

Einige Beispiele für Ausgabemeldungen:

  • Successfully enriched the following entities using information from VirusTotal: {entity.identifier}
  • Action wasn't able to find any information for the following entities using VirusTotal: {entity.identifier}
  • None of the provided entities were found in VirusTotal.
  • Successfully executed query "{query}" in Google SecOps.

Wenn die Aktion fehlschlagen und die Ausführung des Playbooks beenden soll, empfiehlt es sich, die Ausgabemeldung in der folgenden Struktur zu verwenden:

"Error executing action "{action name}". Reason: {error}'

Vermeiden Sie es, den gesamten Traceback für Fehler anzugeben. Versuchen Sie stattdessen, den Nutzer in natürlicher Sprache auf das eigentliche Problem hinzuweisen.

Connectors

Name

Der Name des Connectors sollte den Nutzer auf die Daten hinweisen, die aufgenommen werden. Im Allgemeinen sollte die Struktur des Namens so aussehen: dies:

  • {integration display name} - {data that is being ingested} Connector
    • Beispiel: Crowdstrike - Pull Alerts Connector

Beschreibung

In der Beschreibung des Connectors sollte für den Nutzer hervorgehoben werden, was vom Connector aufgenommen wird, z. B. Pull alerts from Crowdstrike. Außerdem müssen Sie Informationen zur Unterstützung dynamischer Listen angeben; zum Beispiel, Dynamic List works with the display_name parameter.

Die endgültige Beschreibung würde in diesem Fall so aussehen:

Pull alerts from Crowdstrike. Dynamic List works with the display_name parameter.

Die Beschreibung sollte nicht mehr als 500 Zeichen umfassen.

Connector-Parameter

Konfigurationsparameter für Connectors sollten einen intuitiven Namen haben. Verwenden Sie keine Sonderzeichen und beschränken Sie den Namen des Aktionsparameters auf zwei bis vier Wörter.

In der Beschreibung des Parameters sollte erläutert werden, welche Auswirkungen dieser Parameter auf die Ausführung des Connectors hat.

Wenn der Parameter eine bestimmte Anzahl unterstützter Werte unterstützt, geben Sie in der Beschreibung den folgenden Abschnitt an: Possible Values: {value 1}, {value 2}. sollte die folgenden Parameter haben:

  • Max. abzurufende Benachrichtigungen: Gibt an, wie viele {object} während einer Connector-Iteration verarbeitet werden sollen.
  • Max. {Stunden/Tage} zurück: Gibt die Startzeit für die erste Iteration des Connectors an. Wenn Max. Stunden zurück auf 1 festgelegt ist, ruft der Connector Daten ab, die eine Stunde zurückliegen.
  • SSL prüfen: Prüft die Verbindung zur API/Instanz.

Ontologiezuordnung

Für jeden erstellten Connector empfiehlt es sich, eine Ontologie Zuordnung bereitzustellen, um sicherzustellen, dass gemeinsame Kunden die bestmögliche Erfahrung machen.

Die Ontologiezuordnung wird verwendet, um automatisch Entitäten (IOCs und Assets) zu erstellen. Außerdem werden dort wichtige Metadaten von Systemfeldern wie Startzeit und Endzeit definiert.

Dynamische Liste

Die dynamische Liste ist eine optionale Funktion, mit der Sie einen erweiterten Filter für die Aufnahme erstellen können. Sie können damit beliebige benutzerdefinierte Logik erstellen und gleichzeitig eine einzigartige Benutzeroberfläche nutzen. Der häufigste Anwendungsfall ist das Definieren einer Zulassungsliste oder einer Sperrliste für die Aufnahme.

Wenn Sie benutzerdefinierte Logik für die dynamische Liste erstellen, muss diese in der Beschreibung des Connectors angegeben werden. Außerdem empfiehlt es sich, einen Parameter Dynamische Liste als Sperrliste verwenden zu verwenden, damit auch die umgekehrte Logik unterstützt wird.

Jobs

Name

Der Name des Jobs sollte dem Nutzer erklären, was dieser Job ausführt. Im Allgemeinen sollte die Struktur des Namens so aussehen:

  • {integration display name} - {process} Job
    • Beispiel: ServiceNow - Sync Incidents Job

Beschreibung

In der Beschreibung des Jobs sollte für den Nutzer hervorgehoben werden, was der Job während der Iterationen tut, z. B. This job will synchronize Security Command Center based cases created by the Urgent Posture Findings connector.

Die Beschreibung sollte nicht mehr als 500 Zeichen umfassen.

Jobparameter

Konfigurationsparameter für Jobs sollten einen intuitiven Namen haben. Vermeiden Sie die Verwendung von Sonderzeichen und versuchen Sie, den Namen des Aktionsparameters auf 2-4 Wörter zu beschränken.

In der Beschreibung des Parameters sollte erläutert werden, welche Auswirkungen dieser Parameter auf die Ausführung des Jobs hat.

Wenn der Parameter eine bestimmte Anzahl unterstützter Werte unterstützt, geben Sie in der Beschreibung den folgenden Abschnitt an:

Possible Values: {value 1}, {value 2}.

Neben den Authentifizierungsparametern sollten alle Jobs die folgenden Parameter haben:

  • Max. {Stunden/Tage} zurück: Gibt die Startzeit für die erste Iteration des Jobs an.
  • SSL prüfen: Prüft die Verbindung zur API/Instanz.

Benötigen Sie weitere Hilfe? Erhalten Sie Antworten von Community-Mitgliedern und Google SecOps-Experten.