插件后端 SDK 参考

后端插件代码在 Ogma 的 JavaScript 沙箱中运行，并从宿主应用接收 sdk 对象。

完整插件包格式、清单字段、权限和示例，请先参阅插件系统指南。

入口

后端插件提供 init 函数：

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

插件启用时，Ogma 会调用 init(sdk)。

核心命名空间

命名空间	用途
sdk.console	将消息写入插件日志缓冲区。
sdk.meta	读取插件元数据和数据路径。
sdk.events	为 Ogma 事件注册回调。
sdk.requests	查询 HTTP 历史记录和请求数据。
sdk.findings	在权限允许时查询或创建安全发现。
sdk.scope	读取当前测试范围信息。
sdk.storage	以键值形式持久保存插件状态。
sdk.fs	在插件私有数据目录内执行文件操作。
sdk.path	用于组合插件数据目录内路径的辅助函数。
sdk.api	向插件前端提供后端处理函数。

日志

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

消息可在插件日志 UI 中查看。请保持日志简洁，避免写入秘密信息。

元数据

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

使用 sdk.meta.path() 存储插件专属数据。不要假定沙箱中的插件代码可以访问任意文件系统路径。

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

事件

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

回调应快速执行。耗时较长的操作应由明确的用户操作或后端 API 处理函数触发。

前端桥接处理函数

后端插件可向前端插件面板提供处理函数：

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

前端通过 Ogma 前端 SDK 调用处理函数。参阅前端 SDK 参考。

安全要求

• 将 HTTP 流量、安全发现、日志和导出内容视为敏感数据。
• 仅申请插件所需的权限。
• 默认情况下，绝不记录凭据、Cookie、Bearer 令牌或私有流量。
• 让插件行为明确且易于用户理解。