Community-Antwortintegrationen beitragen

Unterstützt in:

In diesem Dokument werden die Richtlinien für das Einreichen von Antwortintegrationen in Google SecOps über Community-Beiträge beschrieben. Alle eingereichten Integrationen werden vom offiziellen Google SecOps-Team geprüft. Dabei liegt der Schwerpunkt 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, 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, mit dem 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 URLs in der Beschreibung.

Logos

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

Sie sollten das Logo auf den folgenden Seiten validieren:

Hier ist 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 die SVG-Datei, bevor Sie sie der Integrationsdefinitionsdatei hinzufügen, wie es auch bei anderen Integrationen im Content Hub der Fall ist.

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 im Dialogfeld Instanz konfigurieren im Abschnitt Parameter auf den Dokumentationslink zugreifen.

Konfigurationsparameter

Alle Integrationen sollten Konfigurationsparameter (API-Stamm + Authentifizierungsparameter) enthalten, es sei denn, die zugrunde liegende API erfordert keine Authentifizierung und der API-Stamm kann hartcodiert 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 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 auch dann obligatorisch, wenn Ihre Integration keine anderen Aktionen hat. Wenn der Nutzer in der Integrationskonfiguration auf den Button Testen klickt, sollte der genaue 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}
  • Für Ä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 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 den Button Details klicken.

Versionsverwaltung

Nach jeder Aktualisierung der Integration sollte die Integrationsversion um 1 erhöht werden. 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. Falldetails abrufen, Entitätsereignisse auflisten oder 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 aus 2–3 Wörtern bestehen.

Beschreibung

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

Wenn die Aktion mit Entitäten funktioniert, müssen Sie Informationen darüber 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

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

In der Beschreibung des Parameters sollte dem Nutzer erklärt werden, welche Auswirkungen dieser Parameter auf die Ausführung der Aktion hat. Wenn der Parameter eine vordefinierte Anzahl von unterstützten Werten 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 sie einfach auf eine Variable namens is_success verweisen, die die Werte true oder false annehmen kann.

Wenn die Aktion ausgeführt 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 eine Größe von 15 MB beschränkt.

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

Verwenden Sie stattdessen dieses Format:


[
   {
      "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 Expression Builder 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 Aktionsausführung zusätzliche Metadaten an sie 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 Ausgabenachricht sollte dem Nutzer ausführlicher erklärt werden, wie die Aktion ausgeführt wurde. Sie sollte den Nutzer auf das Ergebnis der Aktionsausführung 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 kritischer Fehler aufgetreten ist, achten Sie darauf, 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 gestoppt, bis der Fehler behoben oder manuell übersprungen wird.

Hier einige 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 fehlschlägt und die Ausführung des Playbooks beendet wird, sollte die Ausgabenachricht die folgende Struktur haben:

"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 verweisen, die aufgenommen werden sollen. Im Allgemeinen sollte die Struktur des Namens so aussehen:

  • {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.

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

Connector-Parameter

Die Konfigurationsparameter des Connectors sollten einen intuitiven Namen haben. Vermeiden Sie Sonderzeichen und beschränken Sie den Namen des Aktionsparameters auf 2–4 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 vordefinierte Anzahl von unterstützten Werten unterstützt, geben Sie in der Beschreibung den folgenden Abschnitt an: Possible Values: {value 1}, {value 2}. sollte die folgenden Parameter haben:

  • Max Alerts To Fetch: Gibt an, wie viele {object} während einer Connector-Iteration verarbeitet werden sollen.
  • Max. {Stunden/Tage} zurück: Bestimmt die Startzeit bei der ersten Iteration des Connectors. Wenn Max. Stunden rückwärts beispielsweise auf 1 festgelegt ist, beginnt der Connector, Daten von einer Stunde zuvor abzurufen.
  • SSL überprüfen: Überprüft die Verbindung zur API/Instanz.

Ontologiezuordnung

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

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 jede benutzerdefinierte Logik erstellen und gleichzeitig eine einzigartige UX nutzen. Der häufigste Anwendungsfall ist die Definition einer Zulassungs- oder Sperrliste für die Aufnahme.

Wenn Sie eine benutzerdefinierte Logik für Dynamische Liste erstellen, muss diese in der Beschreibung des Connectors angegeben werden. Außerdem wird empfohlen, den 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 tut. 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..

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

Jobparameter

Jobkonfigurationsparameter 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 Jobausführung hat.

Wenn der Parameter eine vordefinierte Anzahl von unterstützten Werten unterstützt, geben Sie in der Beschreibung den folgenden Abschnitt an:

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

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

  • Max. {Stunden/Tage} rückwärts: Gibt die Startzeit für die erste Iteration des Jobs an.
  • SSL überprüfen: Überprüft die Verbindung zur API/Instanz.

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