Referenční dokumentace backendového SDK pluginů

Backendový kód pluginu běží v JavaScriptovém sandboxu Ogma a od hostitelské aplikace dostává objekt sdk.

Úplný formát balíčku pluginu, pole manifestu, oprávnění a příklady najdete v průvodci systémem pluginů.

Vstupní bod

Backendové pluginy poskytují funkci init:

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

Ogma volá init(sdk) při zapnutí pluginu.

Základní jmenné prostory

Jmenný prostor	Účel
sdk.console	Zápis zpráv do vyrovnávací paměti protokolů pluginu.
sdk.meta	Čtení metadat pluginu a cest k datům.
sdk.events	Registrace obslužných funkcí pro události Ogma.
sdk.requests	Dotazování na historii HTTP a data požadavků.
sdk.findings	Dotazování na nálezy nebo jejich vytváření, pokud to oprávnění umožňují.
sdk.scope	Čtení informací o aktivním rozsahu testování.
sdk.storage	Trvalé ukládání stavu pluginu ve formě klíč/hodnota.
sdk.fs	Operace se soubory v soukromém datovém adresáři pluginu.
sdk.path	Pomocné funkce pro sestavování cest v datovém adresáři pluginu.
sdk.api	Zpřístupnění backendových obslužných funkcí frontendu pluginu.

Protokolování

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

Zprávy jsou viditelné v rozhraní protokolů pluginu. Pište stručné protokoly a nezapisujte do nich citlivé údaje.

Metadata

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

Pro data konkrétního pluginu používejte sdk.meta.path(). Nepředpokládejte, že kód pluginu v sandboxu má přístup k libovolným cestám v souborovém systému.

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

Události

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

Obslužné funkce by měly být rychlé. Dlouhotrvající práci spouštějte až na základě explicitní uživatelské akce nebo ji přesuňte do obslužných funkcí backendového API.

Obslužné funkce frontendového můstku

Backendové pluginy mohou zpřístupnit obslužné funkce pro frontendové panely pluginů:

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

Frontend volá obslužnou funkci prostřednictvím frontendového SDK Ogma. Viz referenční dokumentace frontendového SDK.

Bezpečnostní zásady

• Považujte provoz HTTP, nálezy, protokoly a exporty za citlivé údaje.
• Žádejte pouze o oprávnění, která váš plugin potřebuje.
• Ve výchozím nastavení nikdy neprotokolujte přihlašovací údaje, cookies, bearer tokeny ani soukromý provoz.
• Zajistěte, aby chování pluginu bylo zřejmé a pro uživatele srozumitelné.