Ogma

화면 설정

플러그인 프런트엔드 SDK 참조 ​

플러그인 프런트엔드 코드는 샌드박스 iframe 안에서 실행됩니다. 이 문서는 저수준 참조입니다. 개요는 README.md를 확인하세요.

보안 모델 ​

속성값
Iframe 샌드박스allow-scripts만 허용(allow-same-origin 없음)
CSP script-srcnonce로 제한되며 진입점 스크립트만 로드됨
CSP connect-src'self' - 플러그인이 /plugins/{id}/api/*에 POST 요청을 보내고 /plugins/{id}/events/poll을 폴링할 수 있음
CSP default-src'none'
부모 DOM 접근차단됨(allow-same-origin 없음)
Ogma 세션 쿠키플러그인에서 접근 불가
플러그인 간 통신사용 불가

데이터 브리지 호출은 모든 요청에 대해 서버 측에서 권한을 확인하며, 표시 및 탐색 동작은 호스트 UI가 처리합니다. 권한 탭에 표시되는 권한 캐시는 표시용일 뿐, 데이터 접근을 제어하지 않습니다.

브리지 프로토콜 ​

플러그인 JS는 postMessage를 통해 Ogma 호스트와 통신합니다. 호스트는 PluginsView.vue에 있으며 bridge_request 메시지를 처리합니다.

요청 메시지 형식 ​

ts
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
}

전체 메시지 크기 상한: 65 536바이트.

응답 메시지 형식 ​

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

원시 postMessage 브리지 요청을 수동으로 보내지 마세요. 전역 객체 ogmaSDK를 사용하세요.

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

SDK는 모든 브리지 통신을 감싸고 요청과 응답의 대응 관계, sessionId 관리 및 Promise 완료 처리를 담당합니다.

명령 참조 ​

ogma.meta.get ​

페이로드가 필요하지 않습니다.

{ pluginId, packageId, name, version, ogmaVersion }을 반환합니다.

ogma.requests.get ​

페이로드: { id: string }

일부 필드로 구성된 HTTP 항목을 반환합니다. 필드: id, method, host, port, path, query, req_len, resp_status, resp_len, roundtrip_ms, created_at. 이 데이터에는 헤더나 본문 바이트가 포함되지 않습니다.

필요 권한: read_http_history(자동 부여).

ogma.requests.getRaw ​

페이로드: { id: string }. sdk.requests.getRaw(id)를 통해 호출합니다.

requestBodyBase64, responseBodyBase64, 디코딩된 길이(requestBodyLength, responseBodyLength), requestBodyTruncated, responseBodyTruncated, maxBodyBytes를 반환합니다. 이름과 달리 이 작업은 전체 원시 HTTP 메시지가 아닌 본문 바이트를 반환합니다. 지원되는 콘텐츠 인코딩은 반환 데이터를 구성하기 전에 디코딩됩니다. 각 본문은 256 KiB로 제한되므로 전체 에셋을 처리하기 전에 잘림 플래그를 확인하세요.

필요 권한: read_http_history(자동 부여).

페이로드: { limit?: number, offset?: number, query?: string }

query는 HTTPQL 필터 표현식을 지원합니다. limit 상한: 20. { items: [...], total: number, limit: number, offset: number }를 반환합니다.

필요 권한: read_http_history(자동 부여).

ogma.findings.list ​

페이로드: { limit?: number, offset?: number }

{ items: [...], total: number, limit: number, offset: number }를 반환하며, 페이지당 발견 사항은 최대 20개입니다. 항목은 요약 정보이며 id, title, severity, status, reporter, tags, created_at 필드를 포함합니다.

필요 권한: read_findings(자동 부여).

ogma.scope.getActive ​

페이로드가 필요하지 않습니다. 활성 점검 범위 프리셋 또는 null을 반환합니다.

필요 권한: read_scope(자동 부여).

ogma.projects.getCurrent ​

페이로드가 필요하지 않습니다. { id, name, status } 또는 null을 반환합니다.

필요 권한: read_projects(자동 부여).

ogma.log ​

페이로드: { message: string }

플러그인 로그 버퍼에 기록합니다.

ogma.ui.resize ​

페이로드: { height: number }(최대 2000)

호스트에 iframe 높이 설정을 요청합니다.

ogma.ui.sidebar.registerItem ​

페이로드: { name: string, path: string }(이름 최대 64자, 경로 최대 256자)

플러그인 패널 내 탐색 항목을 등록합니다. 플러그인당 최대 20개입니다. sdk.navigation.addPage(path, { title, body })로 해당 페이지 내용을 등록하세요. 항목을 선택하면 새로운 Ogma 최상위 워크스페이스 라우트가 아닌 iframe 내부에 해당 페이지가 표시됩니다.

ogma.backend.call ​

페이로드: { method: string, args: unknown[] }

sdk.api.register(method, fn)으로 등록된 백엔드 RPC 핸들러를 호출합니다. 메서드 이름의 최대 길이는 64자입니다.

백엔드 핸들러가 반환한 값을 JSON으로 직렬화하여 반환합니다.

ogma.backend.onEvent ​

페이로드: 필요 없음.

수신 확인만 합니다. 실제 이벤트 조회에는 ogma.events.poll을 사용하세요.

ogma.events.poll ​

페이로드: { since: number }(마지막 폴링의 인덱스, 시작값은 0)

{ events: [{ event: string, args: unknown[] }], next_since: number }를 반환합니다.

ogma.navigation.addPage ​

페이로드: { path: string, title?: string }

브리지는 페이지 경로의 수신을 확인합니다. 주입된 SDK는 sdk.navigation.addPage(path, options)의 옵션으로 { body: HTMLElement }도 받아 iframe 안에 내용을 붙이고, 호스트에서 해당 사이드바 항목을 선택하면 페이지 표시 여부를 전환합니다. DOM 노드는 로컬에 남으며 브리지를 통해 직렬화되지 않습니다.

ogma.window.showToast ​

페이로드: { message: string, variant?: "info"|"success"|"warning"|"error", duration?: number }

플러그인 패널에 토스트를 표시합니다. 표시 시간은 ms 단위입니다(최대 10000, 기본값 3000).

ogma.commands.register ​

페이로드: { id: string, name: string }

호스트 명령 저장소에 플러그인 명령을 등록합니다. 호스트에서 실행하면 commandId와 컨텍스트가 포함된 plugin_command 메시지를 iframe으로 보내며, 플러그인은 해당 콜백을 제공해야 합니다. 등록만으로 명령이 실행되지는 않습니다.

ogma.menu.registerItem ​

페이로드: { type?: "Request" | "RequestRow" | "Response", commandId: string, label?: string }

플러그인 명령에 연결된 컨텍스트 메뉴 항목을 등록합니다. 먼저 명령을 등록하세요. 레이블은 기본적으로 등록된 명령 이름을 사용하고, 이름이 없으면 ID를 사용합니다. type을 생략하면 기본값은 Request입니다. 호스트 브리지는 leadingIcon을 사용하지 않습니다.

테마 도우미 ​

주입된 SDK는 sdk.theme.get()과 sdk.theme.onChange(callback)도 제공합니다. 별도의 데이터 브리지 명령 없이 iframe 테마를 읽고 호스트의 테마 업데이트를 구독합니다. 플러그인 UI를 Ogma의 라이트/다크 테마와 일관되게 유지하는 데 사용하세요.

오류 코드 ​

코드의미
PERMISSION_DENIED플러그인에 필요한 권한이 없습니다.
PLUGIN_DISABLED플러그인이 현재 활성화되어 있지 않습니다.
UNKNOWN_COMMAND지원 목록에 없는 명령입니다.
INVALID_PAYLOAD필수 페이로드 필드가 없거나 타입이 올바르지 않습니다.
NOT_FOUND요청한 리소스가 존재하지 않습니다.
LIMIT_EXCEEDED플러그인별 개수 제한에 도달했습니다(예: 사이드바 항목).
SERVER_ERROR내부 오류입니다. 플러그인 로그를 확인하세요.

지원 명령 목록 ​

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.

독점 소프트웨어입니다. 모든 권리는 저작권자에게 있습니다.

저작권 © 2024년부터 현재까지 OgmaBox