Referência do SDK de backend para plugins

O código dos plugins de backend é executado no sandbox de JavaScript do Ogma e recebe um objeto sdk do aplicativo principal.

Para conhecer o formato completo do pacote de plugin, os campos do manifesto, as permissões e os exemplos, comece pelo guia do sistema de plugins.

Ponto de entrada

Os plugins de backend expõem uma função init:

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

O Ogma chama init(sdk) quando o plugin é habilitado.

Namespaces principais

Namespace	Finalidade
sdk.console	Gravar mensagens no buffer de logs do plugin.
sdk.meta	Ler os metadados e os caminhos de dados do plugin.
sdk.events	Registrar callbacks para eventos do Ogma.
sdk.requests	Consultar o histórico HTTP e os dados das requisições.
sdk.findings	Consultar ou criar achados quando as permissões permitem.
sdk.scope	Ler informações do escopo ativo.
sdk.storage	Persistência de chave/valor para o estado do plugin.
sdk.fs	Operações de arquivos no diretório privado de dados do plugin.
sdk.path	Funções auxiliares para compor caminhos no diretório de dados do plugin.
sdk.api	Expor handlers do backend ao frontend do plugin.

Logs

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

As mensagens aparecem na interface de logs do plugin. Mantenha os logs concisos e evite gravar segredos.

Metadados

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

Use sdk.meta.path() para dados específicos do plugin. Não presuma que o código do plugin executado em sandbox pode acessar caminhos arbitrários do sistema de arquivos.

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

Eventos

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

Os callbacks devem ser rápidos. Tarefas demoradas devem ser executadas mediante ações explícitas do usuário ou handlers da API do backend.

Handlers da ponte com o frontend

Os plugins de backend podem expor handlers para os painéis de frontend dos plugins:

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

O frontend chama o handler pelo SDK de frontend do Ogma. Consulte a referência do SDK de frontend.

Requisitos de segurança

• Trate o tráfego HTTP, os achados, os logs e as exportações como dados sensíveis.
• Solicite somente as permissões de que seu plugin precisa.
• Nunca registre credenciais, cookies, tokens de portador ou tráfego privado por padrão.
• Mantenha o comportamento do plugin explícito e compreensível para o usuário.