Referenz des Plugin-Backend-SDKs

Backend-Plugin-Code läuft in Ogmas JavaScript-Sandbox und erhält von der Host-Anwendung ein sdk-Objekt.

Informationen zum vollständigen Plugin-Paketformat, zu Manifest-Feldern, Berechtigungen und Beispielen finden Sie zunächst in der Anleitung zum Plugin-System.

Einstiegspunkt

Backend-Plugins stellen eine init-Funktion bereit:

async function init(sdk) {
  sdk.console.log("plugin started");
}

Ogma ruft init(sdk) auf, wenn das Plugin aktiviert wird.

Zentrale Namensräume

Namensraum	Zweck
sdk.console	Nachrichten in den Protokollpuffer des Plugins schreiben.
sdk.meta	Plugin-Metadaten und Datenpfade lesen.
sdk.events	Callbacks für Ogma-Ereignisse registrieren.
sdk.requests	HTTP-Verlauf und Anfragedaten abfragen.
sdk.findings	Befunde abfragen oder erstellen, sofern die Berechtigungen dies zulassen.
sdk.scope	Informationen zum aktiven Scope lesen.
sdk.storage	Plugin-Zustand als Schlüssel-Wert-Paare dauerhaft speichern.
sdk.fs	Dateioperationen im privaten Datenverzeichnis des Plugins.
sdk.path	Hilfsfunktionen zum Zusammensetzen von Pfaden im Datenverzeichnis des Plugins.
sdk.api	Backend-Handler für das Plugin-Frontend bereitstellen.

Protokollierung

sdk.console.log("message")
sdk.console.warn("warning")
sdk.console.error("error")

Nachrichten sind in der Oberfläche für Plugin-Protokolle sichtbar. Halten Sie Protokolle knapp und vermeiden Sie das Protokollieren von Geheimnissen.

Metadaten

sdk.meta.id()
sdk.meta.packageId()
sdk.meta.version()
sdk.meta.path()

Verwenden Sie sdk.meta.path() für Plugin-spezifische Daten. Gehen Sie bei Plugin-Code in der Sandbox nicht davon aus, dass beliebige Dateisystempfade zugänglich sind.

sdk.storage.set("key", "value")
sdk.storage.get("key")
sdk.storage.keys()
sdk.storage.delete("key")
sdk.storage.clear()

sdk.fs.readFile("relative/file.txt")
sdk.fs.writeFile("relative/file.txt", "text")
sdk.fs.appendFile("relative/file.txt", "more")
sdk.fs.exists("relative/file.txt")
sdk.fs.existsSync("relative/file.txt")
sdk.fs.mkdir("relative/dir")
sdk.path.join("a", "b", "c")

Ereignisse

sdk.events.onInterceptRequest(function(req) {
  return req
})

sdk.events.onInterceptResponse(function(req, res) {
  sdk.console.log(res.getCode())
})

sdk.events.onProjectChange(function() {
  sdk.console.log("project changed")
})

Callbacks sollten schnell ausgeführt werden. Länger dauernde Arbeiten sollten durch ausdrückliche Benutzeraktionen oder Backend-API-Handler angestoßen werden.

Handler der Frontend-Bridge

Backend-Plugins können Handler für Frontend-Plugin-Panels bereitstellen:

sdk.api.register("ping", async function(input) {
  return { ok: true, input: input };
});

Das Frontend ruft den Handler über das Ogma-Frontend-SDK auf. Siehe die Frontend-SDK-Referenz.

Sicherheitsanforderungen

• Behandeln Sie HTTP-Verkehr, Befunde, Protokolle und Exporte als sensible Daten.
• Fordern Sie nur die Berechtigungen an, die Ihr Plugin benötigt.
• Protokollieren Sie standardmäßig niemals Zugangsdaten, Cookies, Bearer-Tokens oder privaten Verkehr.
• Machen Sie das Verhalten des Plugins für den Nutzer klar erkennbar und verständlich.