Referenční dokumentace frontendového SDK pluginů

Frontendový kód pluginu běží v izolovaném iframe. Tento dokument je nízkoúrovňová referenční dokumentace. Obecnější úvod najdete v README.md.

---

Bezpečnostní model

Vlastnost	Hodnota
Sandbox iframe	Pouze allow-scripts (bez allow-same-origin)
CSP script-src	Načtení skriptu vyžaduje platné nonce; načítá se pouze skript vstupního bodu
CSP connect-src	'self' – plugin může odesílat POST na /plugins/{id}/api/* a pravidelně získávat události z /plugins/{id}/events/poll
CSP default-src	'none'
Přístup k nadřazenému DOM	Blokován (bez allow-same-origin)
Cookies relace Ogma	Pro plugin nepřístupné
Komunikace mezi pluginy	Není dostupná

Volání datového můstku se autorizují na straně serveru při každém požadavku; zobrazování a navigaci zajišťuje rozhraní hostitelské aplikace. Mezipaměť oprávnění zobrazená na kartě Oprávnění slouží pouze k zobrazení; nevynucuje oprávnění k přístupu k datům.

---

Protokol můstku

JavaScript pluginu komunikuje s hostitelskou aplikací Ogma prostřednictvím postMessage. Hostitelská část se nachází v PluginsView.vue a zpracovává zprávy bridge_request.

Obálka požadavku

interface BridgeRequest {
  type: 'bridge_request'
  sessionId: string     // nonce assigned when the bridge is set up; prevents stale messages
  requestId: string     // caller-generated correlation id (max 128 chars)
  command: string       // e.g. "ogma.requests.get"
  payload?: unknown     // command-specific input
}

Maximální celková velikost zprávy: 65 536 bajtů.

Obálka odpovědi

interface BridgeResponse {
  type: 'bridge_response'
  requestId: string
  ok: boolean
  result?: unknown
  error?: string
  code?: string
}

Použití SDK (doporučeno)

Neposílejte ručně přímé požadavky můstku přes postMessage. Používejte globální objekt ogmaSDK:

ogmaSDK.ready(function(sdk) {
  sdk.meta.get().then(function(meta) {
    sdk.log.info("running as " + meta.pluginId);
  });
});

SDK zastřešuje veškerou komunikaci můstku a zajišťuje párování požadavků s odpověďmi, správu sessionId a vyřešení objektů Promise.

---

Referenční dokumentace příkazů

ogma.meta.get

Nevyžaduje vstupní data.

Vrací { pluginId, packageId, name, version, ogmaVersion }.

ogma.requests.get

Vstupní data: { id: string }

Vrací projekci záznamu HTTP. Pole: id, method, host, port, path, query, req_len, resp_status, resp_len, roundtrip_ms, created_at. Tato projekce nezahrnuje hlavičky ani bajty těla.

Vyžaduje: read_http_history (udělováno automaticky).

ogma.requests.getRaw

Vstupní data: { id: string }. Volejte prostřednictvím sdk.requests.getRaw(id).

Vrací requestBodyBase64, responseBodyBase64, jejich délky po dekódování (requestBodyLength, responseBodyLength), requestBodyTruncated, responseBodyTruncated a maxBodyBytes. Navzdory názvu tato operace vrací bajty těla, nikoli celou nezpracovanou zprávu HTTP. Podporovaná kódování obsahu se dekódují před projekcí. Každé tělo je omezeno na 256 KiB; před zpracováním celého prostředku zkontrolujte příznaky zkrácení.

Vyžaduje: read_http_history (udělováno automaticky).

ogma.requests.search

Vstupní data: { limit?: number, offset?: number, query?: string }

query podporuje filtrovací výrazy HTTPQL. Maximální limit: 20. Vrací { items: [...], total: number, limit: number, offset: number }.

Vyžaduje: read_http_history (udělováno automaticky).

ogma.findings.list

Vstupní data: { limit?: number, offset?: number }

Vrací { items: [...], total: number, limit: number, offset: number }, nejvýše 20 nálezů na stránku. Položky jsou souhrny; pole zahrnují id, title, severity, status, reporter, tags a created_at.

Vyžaduje: read_findings (udělováno automaticky).

ogma.scope.getActive

Bez vstupních dat. Vrací aktivní předvolbu rozsahu testování nebo null.

Vyžaduje: read_scope (udělováno automaticky).

ogma.projects.getCurrent

Bez vstupních dat. Vrací { id, name, status } nebo null.

Vyžaduje: read_projects (udělováno automaticky).

ogma.log

Vstupní data: { message: string }

Zapisuje do vyrovnávací paměti protokolů pluginu.

ogma.ui.resize

Vstupní data: { height: number } (maximum 2000)

Požádá hostitelskou aplikaci o nastavení výšky iframe.

ogma.ui.sidebar.registerItem

Vstupní data: { name: string, path: string } (název maximálně 64 znaků, cesta maximálně 256 znaků)

Registruje navigaci v panelu pluginu. Maximálně 20 položek na plugin. Odpovídající obsah stránek zaregistrujte pomocí sdk.navigation.addPage(path, { title, body }); výběrem položky se daná stránka zobrazí uvnitř iframe, nevytváří se nová trasa na nejvyšší úrovni pracovního prostoru Ogma.

ogma.backend.call

Vstupní data: { method: string, args: unknown[] }

Volá backendovou obslužnou funkci RPC zaregistrovanou pomocí sdk.api.register(method, fn). Maximální délka názvu metody je 64 znaků.

Vrací vše, co vrátila backendová obslužná funkce, serializované do JSON.

ogma.backend.onEvent

Vstupní data: nejsou vyžadována.

Pouze potvrzuje přijetí. Pro skutečné získávání událostí použijte ogma.events.poll.

ogma.events.poll

Vstupní data: { since: number } (index z posledního dotazu; začněte na 0)

Vrací { events: [{ event: string, args: unknown[] }], next_since: number }.

ogma.navigation.addPage

Vstupní data: { path: string, title?: string }

Můstek potvrzuje přijetí cesty stránky. Vložené SDK navíc přijímá { body: HTMLElement } jako volbu pro sdk.navigation.addPage(path, options), připojí obsah uvnitř iframe a přepíná viditelnost stránky, když hostitelská aplikace vybere odpovídající položku postranního panelu. Uzel DOM zůstává místní; přes můstek se neserializuje.

ogma.window.showToast

Vstupní data: { message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }

Zobrazuje krátké oznámení v panelu pluginu. Doba zobrazení je v ms (maximum 10000, výchozí hodnota 3000).

ogma.commands.register

Vstupní data: { id: string, name: string }

Registruje příkaz pluginu v úložišti příkazů hostitelské aplikace. Při spuštění v hostitelské aplikaci se zpět do iframe odešle zpráva plugin_command obsahující commandId a kontext; plugin musí poskytnout odpovídající obslužnou funkci. Samotná registrace příkaz nespouští.

ogma.menu.registerItem

Vstupní data: { type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }

Registruje položku kontextové nabídky propojenou s příkazem pluginu. Nejdříve zaregistrujte příkaz. Popiskem je ve výchozím nastavení registrovaný název příkazu, a pokud není k dispozici, jeho ID; vynechaný type má výchozí hodnotu Request. Hostitelský můstek nepoužívá leadingIcon.

Pomocné funkce pro vzhled

Vložené SDK poskytuje také sdk.theme.get() a sdk.theme.onChange(callback). Tyto funkce čtou vzhled iframe a přihlašují se k aktualizacím vzhledu hostitelské aplikace bez samostatného příkazu datového můstku. Používejte je, aby rozhraní pluginu odpovídalo světlému či tmavému vzhledu Ogma.

---

Chybové kódy

Kód	Význam
PERMISSION_DENIED	Plugin nemá požadované oprávnění.
PLUGIN_DISABLED	Plugin momentálně není zapnutý.
UNKNOWN_COMMAND	Příkaz není v seznamu podporovaných příkazů.
INVALID_PAYLOAD	Povinné pole vstupních dat chybí nebo má nesprávný typ.
NOT_FOUND	Požadovaný zdroj neexistuje.
LIMIT_EXCEEDED	Byl dosažen limit počtu pro daný plugin (například položek postranního panelu).
SERVER_ERROR	Interní chyba. Zkontrolujte protokoly pluginu.

---

Seznam podporovaných příkazů

ogma.meta.get, ogma.log, ogma.ui.resize, ogma.ui.sidebar.registerItem, ogma.requests.get, ogma.requests.getRaw, ogma.requests.search, ogma.findings.list, ogma.scope.getActive, ogma.projects.getCurrent, ogma.backend.call, ogma.backend.onEvent, ogma.events.poll, ogma.navigation.addPage, ogma.window.showToast, ogma.commands.register, ogma.menu.registerItem.