Integrationen für Community-Antworten beitragen

Unterstützt in:

In diesem Dokument werden die Richtlinien für das Einreichen von Response-Integrationen für 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 zur Antwortintegration

Name

Der Name sollte dem Produktnamen entsprechen, mit dem die Integration integriert wird, und darf keine Sonderzeichen enthalten.

Der Anzeigename sollte mit Leerzeichen geschrieben werden, 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 Kennung sollte denselben Wert wie Name haben, aber ohne Leerzeichen.

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

Beschreibung

Die Beschreibung sollte einen allgemeinen Überblick über das Produkt geben, für das die Integration erstellt wird, und darf nicht länger als 500 Zeichen sein. Folgende Angaben sind erforderlich:

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

Vermeiden Sie es, URLs in die Beschreibung einzufügen.

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 nur von der Plattform übernehmen.

Sie sollten das Logo auf den folgenden Seiten validieren:

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.

Im Rahmen der Integration kannst du einen Link hinzufügen, der Nutzer zur Dokumentation weiterleitet. Diese Dokumentation muss von Ihnen gehostet werden.

Nutzer können über den Bereich Parameter im Dialogfeld Instanz konfigurieren auf den Dokumentlink 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 es einen Verify SSL-Parameter geben.

Alle Parameter sollten eine Beschreibung haben. Die Beschreibung sollte Nutzern helfen, die Integration innerhalb der Plattform zu konfigurieren. Vermeiden Sie URLs in der Beschreibung von Parametern.

Ping-Aktion

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

Versionshinweise

Die allgemeine Struktur der 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 für bestimmte Szenarien eigene Versionshinweise:

  • 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.
  • Für Änderungen, die alle Integrationselemente betreffen: Integration - {Update}
  • Änderungen, die sich auf alle Aktionen auswirken: Integration's Actions - {Update}
  • Änderungen, die alle Connectors betreffen: Integration's Connectors - {Update}
  • Für Änderungen, die sich auf alle Jobs auswirken: Integration's Jobs - {Update}

Wenn der Release eine regressive Änderung enthielt, müssen Sie in der Versionsinformation REGRESSIVE! angeben. Beispiel: Google Chronicle - Chronicle Alerts Connector - REGRESSIVE! Updated mapping.

Versionshinweise sind in der Seitenleiste Integrationsdetails verfügbar, die angezeigt wird, wenn Sie in der Integration auf den Button 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 bereits auf der Plattform vorhandenen. Wenn Sie kein passendes Tag finden, wenden Sie sich an das Prüfteam.

Allgemeine Hinweise

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

Aktionen

Name

Der Name der Aktion sollte auf die Aktivität verweisen, die ausgeführt wird, z. B. Get Case Details (Fallinformationen abrufen), List Entity Events (Entität-Ereignisse auflisten) oder Execute Search (Suche ausführen).

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

Aktionsnamen sollten in zwei bis drei Wörtern angegeben werden.

Beschreibung

In der Beschreibung der Aktion sollte für den Nutzer hervorgehoben werden, was das Ergebnis der Aktionsausführung ist.

Wenn die Aktion mit Entitäten funktioniert, müssen Sie Informationen dazu anhängen, 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 asynchronen Modus funktioniert, 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.

Versuchen Sie, die Beschreibung auf 500 Zeichen zu beschränken.

Aktionsparameter

Die Parameter der Aktionskonfiguration sollten einen intuitiven Namen haben. Vermeiden Sie Sonderzeichen und beschränken Sie den Namen des Aktionsparameters auf 2–4 Wörter.

Die Beschreibung des Parameters sollte dem Nutzer erläutern, welche Auswirkungen der Parameter auf die Ausführung der Aktion hat. Wenn der Parameter eine bestimmte Anzahl unterstützter Werte unterstützt, fügen Sie in die Beschreibung den folgenden Abschnitt ein: Possible Values: {value 1}, {value 2}

Aktionsausgabe (Skriptergebnis)

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

Wenn die Aktion abgeschlossen ist und ein Vorgang ausgeführt wurde, sollte is_success in der Regel 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 in die Ausgabe übertragen wird.

JSON-Ergebnisse dürfen maximal 15 MB groß sein.

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 innerhalb der Aktion verwenden und Ergebnisse pro Entität zurückgeben, sollten Sie das JSON-Ergebnis so strukturieren:


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

Überlege 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 Ausdrucksgenerator während der Erstellung des Playbooks verwendet. Ein genaues JSON-Beispiel verbessert die Erstellung von Playbooks erheblich. Entfernen Sie alle personenidentifizierbaren Informationen aus JSON-Beispielen.

Aktionsausgaben (Entitätsanreicherung)

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 folgendes Format haben: {integration identifier}_{key}. Beispiel: WebRisk_is_malicious.

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

Aktionsausgaben (Ausgabenachricht)

In der Ausgabemeldung sollte dem Nutzer genauer erklärt werden, 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, sollten Sie in der Nachricht Statusinformationen für jede bereitgestellte Entität angeben.

Wenn Sie der Meinung sind, dass während der Ausführung der Aktion ein schwerwiegender Fehler aufgetreten ist, sorgen Sie dafür, dass es eine ausführliche Meldung für diese Situation gibt, und lassen Sie die Aktion fehlschlagen. Wenn die Aktion fehlschlägt, wird die Ausführung des entsprechenden Playbooks angehalten, bis der Fehler behoben oder manuell übersprungen wird.

Beispiele für Ausgabenachrichten:

  • 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 beendet werden soll, empfiehlt es sich, die Ausgabemeldung in der folgenden Struktur zu formatieren:

"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 tatsächliche Problem hinzuweisen.

Connectors

Name

Der Name des Connectors sollte den Nutzer auf die Daten hinweisen, die aufgenommen werden sollen. Im Allgemeinen sollte der Name so strukturiert sein:

  • {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, welche Daten vom Connector aufgenommen werden, z. B. Pull alerts from Crowdstrike. Außerdem müssen Sie Informationen zur Unterstützung dynamischer Listen angeben, z. B. Dynamic List works with the display_name parameter..

Die endgültige Beschreibung sieht in diesem Fall so aus:

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

Die Beschreibung sollte nicht länger als 500 Zeichen sein.

Connector-Parameter

Die Parameter für die Connector-Konfiguration sollten einen intuitiven Namen haben. Vermeiden Sie Sonderzeichen und beschränken Sie den Namen des Aktionsparameters auf zwei bis vier Wörter.

In der Beschreibung des Parameters sollte dem Nutzer erklärt werden, welche Auswirkungen dieser Parameter auf die Ausführung des Connectors hat.

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

  • Max Alerts To Fetch (Maximale Anzahl abzurufender Benachrichtigungen): Gibt an, wie viele {object} während einer Connector-Iteration verarbeitet werden sollen.
  • Max. {Stunden/Tage} rückwärts: Gibt die Startzeit für die erste Iteration des Connectors an. Wenn Max. Stunden rückwärts beispielsweise auf 1 festgelegt ist, werden Daten ab einer Stunde zuvor abgerufen.
  • SSL überprüfen: Überprüft die Verbindung zur API/Instanz.

Ontologiezuordnung

Für jeden erstellten Connector wird empfohlen, eine Ontologiezuordnung anzugeben, damit gemeinsame Kunden die bestmögliche Nutzung erhalten.

Mit Ontology Mapping werden automatisch Entitäten (IOCs und Assets) erstellt. 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 die Definition einer Zulassungs- oder Sperrliste für die Aufnahme.

Wenn Sie benutzerdefinierte Logik für Dynamic List erstellen, muss sie in der Beschreibung des Connectors angegeben werden. Außerdem wird empfohlen, einen Parameter Use Dynamic List as a blocklist (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 der Name so aufgebaut sein:

  • {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 macht, z. B. This job will synchronize Security Command Center based cases created by the Urgent Posture Findings connector..

Versuchen Sie, die Beschreibung auf 500 Zeichen zu beschränken.

Jobparameter

Parameter für die Jobkonfiguration sollten einen intuitiven Namen haben. Vermeiden Sie Sonderzeichen und beschränken Sie den Namen des Aktionsparameters auf zwei bis vier Wörter.

Die Beschreibung des Parameters sollte dem Nutzer erläutern, welche Auswirkungen der Parameter auf die Ausführung des Jobs hat.

Wenn der Parameter eine bestimmte Anzahl unterstützter Werte unterstützt, fügen Sie in die Beschreibung den folgenden Abschnitt ein:

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

Zusätzlich zu den Authentifizierungsparametern sollten alle Jobs die folgenden Parameter haben:

  • Max. {Hours/Days} Backwards (Max. {Stunden/Tage} rückwärts): Legt die Startzeit für die erste Iteration des Jobs fest.
  • SSL überprüfen: Überprüft die Verbindung zur API/Instanz.

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