Community-Richtlinien für Antwortintegrationen

Unterstützt in:

Google SecOps SOAR

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 für die 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 Kennzeichnung sollte denselben Wert wie Name haben, jedoch 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:

• Antwort > Einrichtung der Integration
• Antwort > Playbooks > Playbook Designer
• Fälle > Benachrichtigung > Playbook-Ansicht für Benachrichtigungen

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 Integrationsdefinitionsdatei hinzufügen. Beispiele finden Sie in anderen Integrationen auf dem Marketplace.

Dokumentationslink

Im Rahmen der Integration können Sie einen Link hinzufügen, der Nutzer zur Dokumentation weiterleitet. Diese Dokumentation muss von Ihnen gehostet werden.

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

Alle Parameter sollten eine Beschreibung haben. Die Beschreibung sollte Nutzern helfen, die Integration über die Plattform zu konfigurieren. Vermeiden Sie es, URLs in die Beschreibung von Parametern einzufügen.

Ping-Aktion

Die Ping-Aktion ist eine spezielle Aktion, die von der Plattform verwendet wird, um die API-Verbindung zu validieren. 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 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.
• Für Änderungen, die sich auf alle Integrationselemente auswirken: Integration - {Update}
• Änderungen, die sich auf alle Aktionen auswirken: Integration's Actions - {Update}
• Änderungen, die sich auf alle Connectors auswirken: Integration's Connectors - {Update}
• Änderungen, die sich auf alle Jobs auswirken: Integration's Jobs - {Update}

Wenn der Release eine regressive Änderung enthält, müssen Sie in den Versionshinweisen 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 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. Minor-Versionen wie 11.1.3 oder 11.1 sind nicht zulässig.

Tags

Optional können Sie Ihrer Integration Tags hinzufügen. Vermeiden Sie es, neue Arten von Tags zu erstellen. Verwenden Sie die Tags, die bereits auf der Plattform vorhanden sind. Wenn Sie kein passendes Tag finden, wenden Sie sich an das Team für die Überprüfung.

Allgemeine Hinweise

• Testen Sie alle Inhalte der Integration vor dem Einreichen.
• Überprü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 funktioniert, 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 dem Nutzer erläutert werden, was das Ergebnis der Ausführung der Aktion sein wird.

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

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

Aktionsparameter

Die Parameter für die Aktionskonfiguration 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 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 darstellen. In den meisten Fällen sollte sie einfach auf eine Variable namens is_success verweisen, die die Werte true oder false annehmen kann.

Wenn die Ausführung der Aktion abgeschlossen ist 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 Daten, die im JSON-Ergebnis verfügbar sind, 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 in 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",
       }
   }
]
    

Ü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 Ausdrucksgenerator während der Erstellung des Playbooks verwendet. Ein genaues JSON-Beispiel macht die Erstellung von Playbooks deutlich einfacher. Entfernen Sie alle personenbezogenen Daten 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 diesem Format entsprechen: {integration identifier}_{key}. Beispiel: WebRisk_is_malicious.

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

Aktionsausgaben (Ausgabemeldung)

Die Ausgabemeldung sollte dem Nutzer genauer erklären, wie die Ausführung der Aktion verlaufen ist. Sie sollte den Nutzer über das Ergebnis der Ausführung der Aktion informieren.

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 für diese Situation eine ausführliche Meldung vorhanden ist, 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. Weisen Sie den Nutzer stattdessen in natürlicher Sprache auf das eigentliche Problem hin.

Connectors

Name

Der Name des Connectors sollte den Nutzer auf die Daten verweisen, die aufgenommen werden. 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, was vom Connector aufgenommen wird, 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 würde in diesem Fall so aussehen:

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.

Die Beschreibung des Parameters sollte dem Nutzer erläutern, welche Auswirkungen der 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. abzurufende Benachrichtigungen: Gibt an, wie viele {object} während einer Connector-Iteration verarbeitet werden sollen.
• Max. {Stunden/Tage} rückwärts: Legt die Startzeit für die erste Iteration des Connectors fest. Wenn Max. Stunden rückwärts beispielsweise auf 1 festgelegt ist, werden Daten ab einer Stunde zuvor abgerufen.
• SSL prüfen: Prüft die Verbindung zur API/Instanz.

Ontologiezuordnung

Für jeden erstellten Connector wird empfohlen, eine Ontologiezuordnung anzugeben, um sicherzustellen, dass gemeinsame Kunden die bestmögliche Erfahrung machen.

Mit der Ontologiezuordnung 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 das Definieren 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 Blockierliste 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 macht. Im Allgemeinen sollte der Name so strukturiert sein:

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

Beschreibung

In der Beschreibung des Jobs sollte 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 länger als 500 Zeichen sein.

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

Neben den Authentifizierungsparametern sollten alle Jobs die folgenden Parameter haben:

• Max. {Stunden/Tage} rückwärts: Legt die Startzeit für die erste Iteration des Jobs fest.
• SSL prüfen: Prüft die Verbindung zur API/Instanz.

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