外掛後端 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 權杖或私有流量。
• 讓外掛行為明確，且容易讓使用者理解。