Referencia del SDK de backend para plugins

El código de los plugins de backend se ejecuta en el sandbox de JavaScript de Ogma y recibe un objeto sdk de la aplicación principal.

Para conocer el formato completo del paquete de plugin, los campos del manifiesto, los permisos y los ejemplos, comienza por la guía del sistema de plugins.

Punto de entrada

Los plugins de backend exponen una función init:

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

Ogma llama a init(sdk) cuando se habilita el plugin.

Espacios de nombres principales

Espacio de nombres	Función
sdk.console	Escribir mensajes en el búfer de registros del plugin.
sdk.meta	Leer los metadatos y las rutas de datos del plugin.
sdk.events	Registrar callbacks para eventos de Ogma.
sdk.requests	Consultar el historial HTTP y los datos de solicitudes.
sdk.findings	Consultar o crear hallazgos cuando los permisos lo permiten.
sdk.scope	Leer la información del alcance activo.
sdk.storage	Persistencia de clave/valor para el estado del plugin.
sdk.fs	Operaciones de archivos en el directorio privado de datos del plugin.
sdk.path	Utilidades para componer rutas en el directorio de datos del plugin.
sdk.api	Exponer manejadores del backend al frontend del plugin.

Registros

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

Los mensajes aparecen en la interfaz de registros del plugin. Mantén los registros concisos y evita escribir secretos.

Metadatos

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

Utiliza sdk.meta.path() para los datos específicos del plugin. No des por supuesto que el código del plugin ejecutado en sandbox puede acceder a rutas arbitrarias del sistema de archivos.

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

Los callbacks deben ser rápidos. Las tareas de larga duración deben ejecutarse mediante acciones explícitas del usuario o manejadores de la API del backend.

Manejadores del puente con el frontend

Los plugins de backend pueden exponer manejadores para los paneles de frontend de los plugins:

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

El frontend llama al manejador mediante el SDK de frontend de Ogma. Consulta la referencia del SDK de frontend.

Requisitos de seguridad

• Trata el tráfico HTTP, los hallazgos, los registros y las exportaciones como datos sensibles.
• Solicita únicamente los permisos que necesita el plugin.
• Nunca registres credenciales, cookies, tokens de portador ni tráfico privado de forma predeterminada.
• Mantén el comportamiento del plugin explícito y comprensible para el usuario.