AgentBridge (한국어)

§1 개요

AgentBridge란?

IDE 에이전트(예: GitHub Copilot, Cursor, Claude Code)가 API 호출을 수행하면 업스트림 AI 제공자(OpenAI, Anthropic 등)에 직접 연결됩니다. AgentBridge는 에이전트 구성을 변경할 필요 없이 TLS 수준에서 해당 연결을 투명하게 가로채고, 요청이 OmniRoute를 통하도록 재작성합니다.

이를 통해 다음과 같은 작업을 수행할 수 있습니다.

모든 에이전트를 모든 제공자로 다시 라우팅: Copilot이 OpenAI와 통신하고 있나요? 이를 Anthropic Claude, Gemini 또는 OmniRoute의 352개 제공자 중 어디로든 리디렉션할 수 있습니다.
모델 매핑 적용: 핸들러 수준에서 gemini-3-flash → claude-sonnet-4.7로 투명하게 매핑할 수 있습니다.
모든 에이전트 트래픽 관찰: 가로챈 모든 요청이 Traffic Inspector에 게시됩니다.
OmniRoute 복원력 적용: 콤보 라우팅, 회로 차단기, 폴백 및 비용 추적 기능이 IDE 에이전트 트래픽에도 적용됩니다.

시장 대비 포지셔닝

기능	9router	anti-api	llm-interceptor	OmniRoute AgentBridge
Antigravity	✓	✓	—	✓
GitHub Copilot	✓	✓	—	✓
Kiro (AWS)	✓	✓	—	✓
OpenAI Codex	—	✓	—	✓
Cursor IDE	✓	✓	—	✓
Zed Industries	—	✓	—	✓
Claude Code	—	—	✓	✓
Open Code	—	—	✓	✓
Trae	—	—	—	🔍 조사 중
대시보드 UI	✓	✗	✗	✓
트래픽 검사기	✗	✗	✓	✓
OmniRoute 라우팅	✗	✗	✗	✓
모델 매핑 UI	✗	✗	✗	✓
우회 목록	✗	✗	✓	✓
업스트림 CA 인증서	✗	✗	✓	✓

§2 아키텍처

2.1 구성 요소 개요

IDE 에이전트 (VS Code / Cursor / 기타)
    │  HTTPS (포트 443)
    ▼
/etc/hosts — 127.0.0.1 api.githubcopilot.com   ← DNS 리디렉션
    │
    ▼
src/mitm/server.cjs  (포트 443, CJS 자식 프로세스)
    │  Host 헤더 SNI를 기준으로 대상 확인
    │  AgentBridge CA로 서명된 SNI별 TLS 인증서 생성
    ├── 우회 목록과 일치? → TCP 패스스루 (복호화 없음)
    ├── 대상과 일치? → fetch → OmniRoute 라우터 (포트 20128)
    │       └── handler.intercept() — TypeScript
    │               ├── 요청 본문/헤더에 maskSecrets() 적용
    │               ├── TrafficBuffer.push() — 트래픽 검사기에 게시
    │               └── fetchRouter() → /v1/chat/completions
    └── 일치 항목 없음? → TCP 패스스루 (복호화 없음)

2.2 MITM 서버 (`src/mitm/server.cjs`)

핵심 MITM 서버는 Node.js CJS 자식 프로세스로 실행됩니다(기존 CJS 코드베이스를 다시 작성하지 않기 위함). 이 서버는 다음을 수행합니다.

포트 443에서 수신 대기(권한 또는 authbind/setcap 필요)
OS로부터 CONNECT 터널 수신(/etc/hosts DNS 리디렉션을 통해)
AgentBridge CA(DATA_DIR/mitm/ca.crt)로 서명된 SNI별 TLS 인증서 생성
targets/index.ts 레지스트리를 통해 Host 헤더를 기준으로 대상 에이전트 확인
HTTP를 통해 http://127.0.0.1:20128의 TypeScript 핸들러 계층으로 디스패치

TARGET_HOSTS는 부팅 시 targets/index.ts가 작성하는 DATA_DIR/mitm/targets.json에서 로드되므로 CJS 서버를 다시 시작하지 않고도 동적으로 업데이트할 수 있습니다.

루트 CA 모델(#6684). 위에서 설명한 SNI별 인증서를 CA로 서명하는 방식은 #6684에서 추가된 영구 루트 CA 모델입니다(src/mitm/cert/rootCa.ts + src/mitm/_internal/rootCaShim.cjs, src/mitm/tproxy/dynamicCert.ts에서 TPROXY용으로 이미 검증된 CA/리프 암호화 구현 재사용). 이 모델은 디스크에 단순히 server.crt/server.key 쌍이 있을 때 나타나는 이전의 단일 정적 자체 서명 리프 (src/mitm/cert/generate.ts, 여전히 antigravity 호스트로만 범위가 제한됨)를 대체합니다. 마이그레이션 동작: 새로 설치한 경우(기존 server.crt 없음)에는 루트 CA 모델이 자동으로 적용됩니다. 기존 정적 리프를 이미 신뢰하는 설치 환경에서는 운영자가 MITM_ROOT_CA_ENABLED=true를 설정하고 브리지를 다시 시작할 때까지 해당 리프를 계속 사용합니다(src/mitm/cert/migration.ts는 순수 결정 함수입니다. 모든 호스트의 리프에 서명할 수 있는 신뢰된 MITM CA는 기존의 고정 SAN 리프보다 실질적으로 더 강력하므로 이미 신뢰가 설정된 설치 환경에서는 절대로 조용히 전환되지 않습니다). CA 인증서는 기존 리프가 사용하던 것과 동일한 omniroute-mitm.crt 신뢰 저장소 슬롯에 설치되므로 (cert/install.ts::installCaCert) 이중 신뢰 정리는 필요하지 않습니다.

2.3 핸들러 기반 클래스 (`src/mitm/handlers/base.ts`)

모든 에이전트 핸들러는 MitmHandlerBase를 확장합니다.

export abstract class MitmHandlerBase {
  abstract readonly agentId: AgentId;

  abstract intercept(
    req: IncomingMessage,
    res: ServerResponse,
    body: Buffer,
    mappedModel: string
  ): Promise&lt;void&gt;;

  // 보호된 헬퍼: fetchRouter, pipeSSE, hookBufferStart, hookBufferUpdate
}

각 핸들러는 프록시하기 전에 hookBufferStart()를 호출하고 완료 시 hookBufferUpdate()를 호출합니다. 이 함수들은 InterceptedRequest 항목을 globalTrafficBuffer에 푸시합니다(트래픽 검사기 §4 참조).

2.4 대상 레지스트리 (`src/mitm/targets/`)

각 에이전트에는 선언적 대상 파일이 있습니다.

export const COPILOT_TARGET: MitmTarget = {
  id: "copilot",
  name: "GitHub Copilot",
  hosts: ["api.githubcopilot.com", "copilot-proxy.githubusercontent.com"],
  port: 443,
  endpointPatterns: ["/chat/completions", "/v1/chat/completions"],
  defaultModels: [{ id: "gpt-4o", name: "GPT-4o", alias: "gpt-4o" }],
  handler: () => import("../handlers/copilot"),
  riskNoticeKey: "providers.riskNotice.oauth",
};

레지스트리(targets/index.ts)는 ALL_TARGETS를 내보내고 부팅 시 DATA_DIR/mitm/targets.json을 생성합니다.

2.5 패스스루 및 우회 목록 (`src/mitm/passthrough.ts`)

우회 목록(가장 먼저 검사되며 대상 일치보다 우선함):

기본 패턴: 은행 호스트, .gov., OAuth/SSO 공급자(Okta, Auth0) 등
사용자 패턴: DB 테이블 agent_bridge_bypass에 저장
우회되는 호스트에는 투명한 TCP 터널이 제공되며 TLS는 절대로 복호화되지 않음

기본 패스스루(대상과 일치하지 않고 우회 목록에도 없는 경우):

마찬가지로 TCP 터널이 제공되며 연결은 절대로 중단되지 않음
AgentBridge가 일반적인 시스템 HTTPS 트래픽을 방해하지 않도록 방지

라우팅 우선순위:

우회 목록 → 대상 일치 → 패스스루

2.6 업스트림 CA 인증서 (`src/mitm/upstreamTrust.ts`)

사용자 지정 CA가 있는 기업 네트워크 환경에서는 다음을 사용합니다.

AGENTBRIDGE_UPSTREAM_CA_CERT=/path/to/corporate-ca.pem

설정하면 추가 CA 인증서를 사용하도록 undici의 전역 디스패처를 구성하여 AgentBridge가 기업 TLS 종단 프록시를 통해 업스트림 공급자에 연결할 수 있게 합니다.

2.7 비밀 정보 마스킹 (`src/mitm/maskSecrets.ts`)

독립적인 클린룸 스캐너는 요청 본문과 자격 증명 헤더가 트래픽 검사기 버퍼 또는 로그에 들어가기 전에 적용됩니다. 이 스캐너는 한 번의 선형 패스로 다음을 처리합니다.

sk- / ak- / pk- 접두사가 붙은 토큰(OpenAI/Anthropic 형식)
RFC 6750 Authorization: Bearer <token> 자격 증명(전체 토큰 우선)
점 및 패딩 형식을 포함한 일반적인 긴 불투명 토큰(40자 이상)

sanitizeHeaders()는 유지되는 이름을 소문자로 변환하고, 배열 값을 결정론적으로 결합하며, 프록시 인증을 포함한 공통 홉 간/프레이밍 거부 목록을 제거하고, cookie 및 set-cookie를 완전히 수정 처리한 후 자격 증명 값을 스캐너에 위임합니다.

§3 설정

3.1 MITM 서버 시작/중지

/dashboard/tools/agent-bridge에서 AgentBridge 서버 카드를 사용합니다.

작업	설명
서버 시작	포트 443에서 `src/mitm/server.cjs`를 실행합니다
서버 중지	자식 프로세스를 정상적으로 종료합니다
서버 재시작	중지 후 시작합니다(대상 변경 사항이 적용됨)
인증서 신뢰	`DATA_DIR/mitm/ca.crt`를 OS 신뢰 저장소에 설치합니다
인증서 다운로드	수동 설치를 위해 `ca.crt`를 다운로드합니다
인증서 재생성	새 CA 키 쌍을 생성합니다(기존의 모든 에이전트별 인증서가 무효화됨)

3.2 인증서 신뢰 설정

IDE가 MITM 연결을 허용하려면 먼저 OS에서 AgentBridge CA 인증서를 신뢰해야 합니다.

Linux (NSS — Chrome/Firefox):

certutil -A -d sql:$HOME/.pki/nssdb -n "OmniRoute AgentBridge" -t CT,, -i ~/.omniroute/mitm/ca.crt

macOS (키체인):

sudo security add-trusted-cert -d -r trustRoot \
  -k /Library/Keychains/System.keychain ~/.omniroute/mitm/ca.crt

Windows (certmgr):

certutil -addstore -f Root $env:USERPROFILE\.omniroute\mitm\ca.crt

또는 대시보드의 “인증서 신뢰” 버튼을 사용합니다(OS에 적합한 명령을 실행하며, 필요한 경우 sudo를 요청함).

Electron 기반 IDE는 OS 신뢰 저장소를 무시함(`NODE_EXTRA_CA_CERTS`)

일부 IDE, 특히 Antigravity IDE와 기타 Electron / VS Code 파생 앱은 아웃바운드 fetch/HTTPS에 대해 OS 신뢰 저장소를 참조하지 않는 자체 Node.js 런타임을 포함합니다. OS/NSS 수준에서 CA를 신뢰하도록 설정하면 IDE의 네이티브 백엔드(예: OS CA 번들을 사용하는 Go 언어 서버)에는 충분하지만, Electron 프런트엔드에서는 여전히 TLS가 실패합니다. MITM 로그에 백엔드의 부트스트랩 호출이 200을 반환하는 것으로 표시되더라도 앱에서는 로그아웃된 상태이거나 _“연결 오류”_가 표시됩니다. 다음 두 단계가 필요하며, 둘 다 중요합니다.

런타임에서 CA를 명시적으로 지정합니다.
터미널 창
```
export NODE_EXTRA_CA_CERTS=/path/to/omniroute-agentbridge-ca.crt
```
해당 셸에서 IDE를 실행합니다. 데스크톱 아이콘 / Dock / 시작 메뉴에서 실행하면 셸의 export 설정을 상속하지 않으며, ~/.config/environment.d/*.conf는 새로운 그래픽 로그인 이후에만 적용됩니다. 먼저 IDE를 완전히 종료해야 합니다. Electron의 싱글턴 잠금으로 인해 두 번째 실행은 기존 프로세스에 포커스만 주며 새 환경은 무시됩니다.

위의 OS 신뢰 + NSS 단계도 여전히 필요합니다. 일부 인증 흐름에서 사용하는 Chromium 네트워크 스택은 사용자별 NSS 저장소를 읽으며, *.googleapis.com에 자체 정적 핀을 적용하지만 로컬에서 신뢰하는 CA가 이를 재정의합니다. NODE_EXTRA_CA_CERTS는 여기에 더해 Node fetch 경로를 처리합니다.

3.3 DNS 라우팅

가로채려는 각 에이전트의 API 호스트가 127.0.0.1로 확인되어야 합니다. 설정 마법사에서 에이전트의 DNS를 전환하면 AgentBridge가 /etc/hosts 항목을 자동으로 관리합니다.

GitHub Copilot의 /etc/hosts 항목 예시:

127.0.0.1 api.githubcopilot.com
127.0.0.1 copilot-proxy.githubusercontent.com

3.4 모델 매핑

각 에이전트 카드의 모델 매핑 테이블을 사용하여 소스 → 대상 매핑을 정의합니다.

소스 모델(에이전트 네이티브)	대상 모델(OmniRoute)
`gpt-4o`	`claude-sonnet-4.7`
`*` (와일드카드)	`claude-haiku-4.7`

와일드카드 *는 인식되지 않는 모든 모델을 지정된 대상으로 매핑합니다. 매핑은 agent_bridge_mappings 테이블에 영구 저장됩니다.

팁 — 에이전트의 실제 모델 ID 확인하기. IDE는 UI 레이블과 다른 모델 이름을 전송할 수 있으며, 이러한 이름은 메이저 버전 간에 변경될 수 있습니다. 예를 들어 Antigravity 2는 이전 문서에 표시된 gemini-2.5-pro가 아니라 gemini-3.1-pro-low, gemini-pro-agent, gemini-3.1-flash-lite를 실제 통신에서 전송합니다. 일치하는 매핑이 없는 상태에서 채팅을 한 번 보내면 MITM이 정확한 수신 model:을 기록하고 요청을 그대로 전달합니다. 해당 리터럴 값을 매핑하면 다음 요청부터 가로채 대상 모델로 라우팅합니다.

3.5 위험 고지

AgentBridge는 IDE가 업스트림 공급자 인증에 사용하는 자격 증명(OAuth 토큰, API 키)을 가로챕니다. 이러한 정보는 로깅 전에 마스킹되지만(§2.7 참조) OmniRoute의 MITM 계층에서는 볼 수 있습니다. 각 에이전트를 처음 활성화하면 닫을 수 있는 위험 고지 모달이 표시됩니다.

3.6 유지보수 및 진단

대시보드는 이전에는 UI가 없었던 운영용 MITM 경로를 제공하는 유지보수 및 진단 카드(AgentBridgeMaintenanceCard, src/app/(dashboard)/dashboard/tools/agent-bridge/components/에 위치)를 제공합니다. 부제는 _“캡처 파이프라인을 자체 테스트하고, 남아 있는 시스템 상태를 되돌리며, 머신 간에 설정을 이전하세요.”_입니다. 카드 클라이언트 헬퍼는 src/lib/inspector/agentBridgeMaintenanceApi.ts에 있습니다.

버튼	경로	기능
진단	`GET /api/tools/agent-bridge/diagnose`	캡처 파이프라인 자체 테스트를 실행하고 검사별 보고서(✓/✗ + 해결 방법 힌트)를 표시합니다.
복구	`POST /api/tools/agent-bridge/repair`	충돌 또는 SIGKILL로 인해 남겨진 고립된 MITM 시스템 상태(DNS 스푸핑 항목, 루트 CA, 시스템 프록시)를 되돌립니다. 멱등성을 가지며, 상태가 정상인 경우 “복구할 항목이 없습니다”라고 보고합니다.
CA 제거	`DELETE /api/tools/agent-bridge/cert`	OS 신뢰 저장소에서 MITM 루트 CA의 신뢰를 해제하고 제거합니다(명시적이며 멱등성을 가짐). 현재 CA가 신뢰된 경우에만 표시되며, 인라인 “CA를 제거하시겠습니까?” 확인이 필요합니다.
구성 내보내기	`GET /api/tools/agent-bridge/config`	이식 가능한 구성 JSON을 다운로드합니다(§3.7 참조).
구성 가져오기	`POST /api/tools/agent-bridge/config`	이전에 내보낸 구성 JSON을 업로드합니다(§3.7 참조).

진단 검사(src/mitm/inspector/diagnostics.ts의 summarizeDiagnostics()). 경로는 각 항목에 대해 부수 효과가 있는 프로브를 실행하고, 불리언 값을 순수 요약 함수에 전달합니다. 단일 healthy 판정과 실패 항목별 힌트가 반환됩니다.

검사 이름	확인하는 내용	실패 시 힌트
`server-running`	MITM 서버 프로세스가 실행 중인지 확인	“MITM 서버가 실행 중이 아닙니다. AgentBridge 탭에서 시작하세요.”
`server-reachable`	MITM 서버가 해당 포트에서 연결을 수락하는지 확인(TCP 프로브)	“MITM 서버가 해당 포트에서 연결을 수락하지 않습니다. 포트를 사용할 수 있는지, 그리고 포트에 바인딩할 권한이 있는지 확인하세요.”
`cert-exists`	MITM 인증서가 디스크에 생성되었는지 확인	“아직 MITM 인증서가 생성되지 않았습니다. AgentBridge 탭에서 인증서를 생성하세요.”
`cert-trusted`	MITM 루트 CA가 OS 신뢰 저장소에 있는지 확인	“MITM 루트 CA가 OS 저장소에서 신뢰되지 않으므로 TLS 가로채기가 실패합니다. AgentBridge 탭에서 인증서를 신뢰하도록 설정하세요.”
`dns-configured`	대상 호스트 이름이 `/etc/hosts`에서 스푸핑되는지 확인	“대상 호스트 이름이 /etc/hosts에서 스푸핑되지 않아 트래픽이 프록시에 도달하지 않습니다. 캡처하려는 에이전트의 DNS를 활성화하세요.”

고립된 상태 배너: 페이지가 충돌로 인해 남겨진 상태(DNS 스푸핑 / CA / 시스템 프록시)를 감지하면 카드에 황색 배너—“이전 세션에서 시스템 상태(DNS 스푸핑, CA 또는 시스템 프록시)가 남았습니다. 복구를 실행하여 정리하세요.”—가 표시되고 복구 버튼이 강조됩니다. Repair는 애플리케이션 계층에서 ProxyBridge의 --cleanup 플래그에 대응하는 기능입니다(src/mitm/manager.ts의 repairMitm()에 위임).

MITM 루트 CA는 sudo 프롬프트가 반복해서 표시되는 것을 방지하기 위해 중지/시작 후에도 설치된 상태로 유지됩니다(mitmproxy/Charles와 동일한 동작). 따라서 중지 시 자동으로 제거되는 대신 명시적인 CA 제거 작업을 통해 제거해야 합니다.

3.7 이식 가능한 구성 가져오기/내보내기

AgentBridge는 운영자가 조정할 수 있는 상태를 버전이 지정된 JSON 블롭으로 직렬화하여 여러 머신에서 설정을 복제할 수 있습니다. 직렬화 도구는 src/lib/inspector/configPortability.ts의 exportConfig() / importConfig()이며, AgentBridgeConfigSchema로 검증됩니다.

내보내기에는 정확히 세 가지 항목이 포함됩니다(기본 제공 기본값은 의도적으로 내보내지 않으므로, 가져올 때 기본값이 중복되거나 충돌하지 않습니다).

필드	소스	참고
`bypassPatterns`	사용자 정의 우회 패턴(`agent_bridge_bypass`)	기본 bank/gov/okta 패턴은 제외됨
`customHosts`	Traffic Inspector 사용자 정의 호스트(`inspector_custom_hosts`)	각 항목: `{ host, kind: "llm"\|"app"\|"custom", label? }`
`agentMappings`	에이전트별 모델 매핑(`agent_bridge_mappings`)	매핑이 있는 모든 에이전트에 대한 `{ [agentId]: [{ source, target }] }`

// GET /api/tools/agent-bridge/config
{
  "version": 1,
  "bypassPatterns": ["*.internal.example.com"],
  "customHosts": [{ "host": "api.example.com", "kind": "llm", "label": null }],
  "agentMappings": {
    "copilot": [{ "source": "gpt-4o", "target": "claude-sonnet-4.7" }],
  },
}

가져오기 동작(POST /api/tools/agent-bridge/config): 우회 패턴과 에이전트별 매핑은 전체가 대체되며, 사용자 정의 호스트는 멱등적으로 추가됩니다(INSERT OR IGNORE). 응답에는 각 항목이 몇 개씩 적용되었는지가 보고됩니다.

{ "ok": true, "bypassPatterns": 1, "customHosts": 1, "agents": 1 }

구성에 포함되지 않는 항목: 서버 실행 상태, 인증서 경로, 에이전트별 DNS 상태, 업스트림 CA 경로, TPROXY 설정 — 이러한 항목은 이식 가능한 기본 설정이 아니라 호스트/런타임 상태입니다.

§4 에이전트별 참조

#	에이전트	상태	가로채는 호스트	인증 유형
1	Antigravity	✅ 지원됨	`daily-cloudcode-pa.googleapis.com`, `cloudcode-pa.googleapis.com`	Firebase OAuth
2	Kiro (AWS)	✅ 지원됨	`prod.kiro.aws`, `dev.kiro.aws`	AWS SigV4
3	GitHub Copilot	✅ 지원됨	`api.githubcopilot.com`, `copilot-proxy.githubusercontent.com`	GitHub OAuth
4	OpenAI Codex	✅ 지원됨	`api.openai.com` (Codex 경로), `chatgpt.com`	OpenAI 키
5	Cursor IDE	✅ 지원됨	`api2.cursor.sh`, `api.cursor.sh`	Cursor OAuth
6	Zed Industries	✅ 지원됨	`api.zed.dev`, `llm.zed.dev`	Zed OAuth
7	Claude Code	✅ 지원됨	`api.anthropic.com` (옵트인)	Anthropic 키
8	Open Code	✅ 지원됨	`openrouter.ai`, `api.openai.com` (zen 경로)	API 키
9	Trae	🔍 조사 중	미정 — §8 참조	미정

설정 마법사 단계(에이전트별)

각 에이전트 카드에는 3단계 설정 마법사가 있습니다.

필수 조건 확인 — 서버가 실행 중인가요? 인증서를 신뢰하나요? IDE가 설치되어 있나요(자동 감지)?
DNS 활성화 — /etc/hosts 항목을 추가합니다(sudo 필요). 추가될 줄을 정확히 표시합니다.
모델 매핑 — 선택적 모델 매핑 테이블입니다. 와일드카드를 사용할 수 있습니다.

에이전트 감지

에이전트 1–8에 대해 AgentBridge는 IDE 설치를 자동으로 감지하려고 시도합니다.

export async function detectAgent(agentId: AgentId): Promise<DetectionResult>;
// 반환값: { installed: boolean, version?: string, path?: string }

감지에는 OS별 경로와 바이너리 검사가 사용됩니다(예: Copilot의 경우 code --list-extensions | grep github.copilot, Antigravity의 경우 ~/.config/antigravity/).

§5 보안

적용된 엄격한 규칙

규칙	적용 방식
#12 `sanitizeErrorMessage`	모든 핸들러 오류는 응답 또는 버퍼 항목에 들어가기 전에 정제됩니다
#13 셸 환경 전달	`/etc/hosts` 편집에는 `env` 옵션을 사용하며 경로의 문자열 보간은 사용하지 않습니다
#15 + #17 `isLocalOnlyPath()`	`/api/tools/agent-bridge/`는 LOCAL_ONLY + SPAWN_CAPABLE이며 인증 전에 루프백을 강제합니다

민감한 호스트용 우회 목록

우회 목록은 금융 기관, OAuth/SSO 제공업체 및 기타 민감한 호스트가 절대로 복호화되지 않도록 보장합니다. 해당 TLS 트래픽은 투명한 TCP 터널을 통해 전달되므로 OmniRoute는 평문을 절대 볼 수 없습니다.

기본 우회 패턴에는 다음이 포함됩니다.

*.bank.*, *.gov.* (금융/정부)
*.okta.com, *.auth0.com, *.microsoft.com (SSO/ID 관리)
*.apple.com, *.icloud.com (Apple 시스템 서비스)

사용자가 추가한 우회 패턴은 agent_bridge_bypass 테이블에 저장되며 다른 모든 설정보다 우선합니다.

비밀 정보 마스킹

src/mitm/maskSecrets.ts의 maskSecrets()가 다음과 같이 적용됩니다.

TrafficBuffer.push() 전에 모든 요청 본문에 적용
로깅 또는 브로드캐스팅 전에 모든 헤더에 적용

패턴: sk-/ak-/pk- 접두사 토큰, Bearer 토큰 및 40자 이상의 일반 토큰.

업스트림 CA 인증서

AGENTBRIDGE_UPSTREAM_CA_CERT가 설정되면 시작 시 해당 파일을 읽습니다. 경로는 존재하지만 파일을 읽을 수 없는 경우 AgentBridge는 명확한 오류를 기록하고 시작을 거부합니다(기업 환경에서 조용한 TLS 실패가 발생하는 것을 방지).

알려진 제한 사항

포트 443에는 권한이 필요함: Linux에서 AgentBridge를 사용하려면 Node 바이너리에 setcap 'cap_net_bind_service=+ep'를 적용하거나 authbind를 통해 실행해야 합니다. 설정 마법사는 OS별 지침을 표시합니다.
IDE를 다시 시작해야 함: DNS 리디렉션 후 새로운 호스트 확인을 적용하려면 IDE를 다시 시작해야 합니다.
하드코딩된 OAuth 토큰: 일부 에이전트(Kiro, Antigravity)는 OAuth 새로 고침 토큰을 로컬에 저장합니다. 이 토큰은 AgentBridge에 투명하게 전달됩니다. AgentBridge는 각 요청에서 Bearer 토큰을 확인하며, 해당 토큰은 로깅 전에 마스킹됩니다.
Electron 프런트엔드에는 NODE_EXTRA_CA_CERTS가 필요함: 번들 Node/Electron 런타임에서 프런트엔드가 실행되는 IDE는 OS/NSS 신뢰 저장소를 무시하므로 NODE_EXTRA_CA_CERTS가 설정된 셸에서 실행해야 합니다(§3.2 참조). 누락 시 증상: IDE 백엔드는 인증되지만(MITM에 200 응답 표시) UI는 로그아웃 상태로 유지됩니다.
동일한 IDE의 여러 설치는 서로 독립적임: 시스템 설치(예: /usr/share/antigravity/antigravity)와 사용자 로컬 “Full” 설치(예: ~/AntigravityIDE_Full/antigravity-ide)는 자체 런타임을 사용하는 별도의 프로세스이므로, 각각 CA가 주입된 상태로 다시 실행해야 합니다. 다시 실행하기 전에 바이너리 경로를 통해 어떤 설치가 실행 중인지 확인하세요.
ID는 라우팅된 모델이 아니라 에이전트의 시스템 프롬프트에 의해 설정됨: 에이전트의 모델을 다른 제공업체에 다시 매핑해도 IDE가 해당 정보를 시스템 프롬프트에 삽입하므로, 응답은 여전히 에이전트의 기본 ID를 주장합니다(예: Antigravity가 “I am powered by Gemini”라고 답함). 모델에게 정체성을 묻는 대신 call_logs / proxy_logs의 provider, model, target_format을 확인하여 실제 백엔드를 검증하세요.

§6 문제 해결

포트 443 충돌

다른 프로세스(웹 서버, VPN 등)가 이미 포트 443에서 수신 중인 경우:

lsof -i :443          # 프로세스 찾기
sudo fuser -k 443/tcp  # 강제 종료(주의해서 사용)

또는 AgentBridge 설정에서 비특권 포트를 구성하고 iptables / pf 리디렉션 규칙을 설정하세요.

인증서를 신뢰하지 않음

AgentBridge를 시작한 후 IDE에 TLS 오류가 표시되는 경우:

인증서가 설치되었는지 확인합니다: security find-certificate -c "OmniRoute AgentBridge" (macOS) 또는 certutil -L -d sql:$HOME/.pki/nssdb (Linux/NSS)
일부 앱은 자체 신뢰 저장소를 유지합니다(Firefox, Linux의 Chrome). “Trust Cert”를 다시 실행하고 NSS/Firefox 전용 인증서 저장소를 확인하세요.
신뢰 설정 후 IDE를 다시 시작하세요. 진행 중인 TLS 세션은 이전 신뢰 상태를 사용합니다.

신뢰할 수 있는 CA가 있는데도 IDE에서 로그아웃됨 / “connection error”

증상: DNS를 리디렉션하고 CA를 신뢰하도록 설정한 후 Electron 기반 IDE(예: Antigravity)를 열면 로그아웃된 상태이거나 인증/연결 오류가 표시되지만, MITM 로그에는 부트스트랩 호출(loadCodeAssist, fetchAvailableModels, …)이 200을 반환하는 것으로 나타납니다.

원인: IDE에 번들로 포함된 Node/Electron 런타임이 OS 신뢰 저장소를 무시합니다. 네이티브 백엔드(Go 언어 서버)는 OS CA를 신뢰하여 인증되지만 Electron 프런트엔드는 그렇지 않으므로 UI는 오프라인 상태라고 판단합니다.

해결 방법(두 단계 모두 필요): NODE_EXTRA_CA_CERTS=<ca.crt>를 내보내고 데스크톱 아이콘이 아닌 해당 셸에서 IDE를 다시 실행하세요. 먼저 IDE를 완전히 종료해야 합니다. Electron의 싱글턴 잠금으로 인해 두 번째 실행은 기존 프로세스에 포커스만 맞추며 새 환경은 무시됩니다. §3.2를 참조하세요. 이는 독립 실행형 에이전트는 MITM을 통해 작동하지만 동일한 설정에서 IDE 버전은 실패한다는 공개된 업스트림 보고와 같은 현상입니다.

DNS가 전파되지 않음

/etc/hosts가 업데이트되었는지 확인합니다:

grep "omniroute\|127.0.0.1.*github\|127.0.0.1.*cursor" /etc/hosts

DNS 캐시를 플러시합니다:

# macOS
sudo dscacheutil -flushcache && sudo killall -HUP mDNSResponder
# Linux (systemd-resolved)
sudo systemctl restart systemd-resolved
# Windows
ipconfig /flushdns

IDE가 감지되지 않음

자동 감지는 일반적인 설치 경로를 사용합니다. IDE가 설치되어 있지만 감지되지 않는 경우:

IDE 바이너리가 비표준 위치에 있는지 확인하세요.
Setup Wizard는 계속 작동합니다. 감지 실패는 배지에 설치 경로가 표시되지 않는다는 의미일 뿐입니다.

핸들러 오류(업스트림 가져오기 실패)

AgentBridge가 요청을 가로채지만 모든 요청이 실패하는 경우:

/dashboard/providers에서 하나 이상의 공급자가 연결되어 있는지 확인합니다.
OmniRoute 서버 로그를 확인합니다: .env에서 APP_LOG_LEVEL=debug
OMNIROUTE_BASE_URL이 올바른 라우터 엔드포인트를 가리키는지 확인합니다(기본값: http://127.0.0.1:20128).

§7 API 참조

모든 라우트는 LOCAL_ONLY(루프백 전용이며 인증 전에 적용됨)이자 SPAWN_CAPABLE입니다. src/server/authz/routeGuard.ts를 참조하세요.

기본 경로: /api/tools/agent-bridge/

메서드	경로	설명
GET	`/api/tools/agent-bridge/state`	전역 서버 상태 + 에이전트별 감지/상태
GET	`/api/tools/agent-bridge/agents`	등록된 에이전트 목록(id, 이름, 호스트, 사용 가능 여부, 상태)
GET	`/api/tools/agent-bridge/agents/{id}`	단일 에이전트의 상태(대상 구성 + 감지 + 저장된 상태)
PATCH	`/api/tools/agent-bridge/agents/{id}`	에이전트의 `setup_completed` 업데이트
GET	`/api/tools/agent-bridge/agents/{id}/detect`	에이전트 감지 프로브 실행(`installed`, `version?`, `path?`)
POST	`/api/tools/agent-bridge/agents/{id}/dns`	에이전트의 DNS 활성화/비활성화(`{enabled: boolean}`)
GET	`/api/tools/agent-bridge/agents/{id}/mappings`	에이전트의 모델 매핑
PUT	`/api/tools/agent-bridge/agents/{id}/mappings`	모델 매핑 교체
POST	`/api/tools/agent-bridge/server`	서버 시작/중지/재시작(`action: "start"\|"stop"\|"restart"\|"trust-cert"\|"regenerate-cert"`)
GET	`/api/tools/agent-bridge/cert`	인증서 상태(`exists`, `trusted`, `path`)
POST	`/api/tools/agent-bridge/cert`	MITM 루트 CA 신뢰 설정(설치)
DELETE	`/api/tools/agent-bridge/cert`	MITM 루트 CA 신뢰 해제(제거) — 멱등성 보장(§3.6 참조)
POST	`/api/tools/agent-bridge/cert/regenerate`	자체 서명 MITM 인증서 재생성
GET	`/api/tools/agent-bridge/cert/download`	다운로드용 PEM 인증서 스트리밍
GET	`/api/tools/agent-bridge/bypass`	우회 패턴 목록(`default` + `user`)
POST	`/api/tools/agent-bridge/bypass`	사용자 정의 우회 패턴 전체 교체
DELETE	`/api/tools/agent-bridge/bypass?pattern=...`	단일 사용자 정의 우회 패턴 제거
GET	`/api/tools/agent-bridge/diagnose`	캡처 파이프라인 자체 테스트(§3.6 참조)
POST	`/api/tools/agent-bridge/repair`	고립된 MITM 시스템 상태 되돌리기(§3.6 참조)
GET	`/api/tools/agent-bridge/config`	이식 가능한 구성 JSON 내보내기(§3.7 참조)
POST	`/api/tools/agent-bridge/config`	이식 가능한 구성 JSON 가져오기(§3.7 참조)
GET	`/api/tools/agent-bridge/upstream-ca`	구성된 업스트림 CA 경로 가져오기
POST	`/api/tools/agent-bridge/upstream-ca`	업스트림 CA 경로 검증 + 저장
POST	`/api/tools/agent-bridge/upstream-ca/test`	업스트림 CA 경로 검증만 수행(드라이런) — 저장하지 않음
GET / POST / DELETE	`/api/tools/agent-bridge/tproxy`	TPROXY 투명 복호화 캡처 모드 — `docs/security/MITM-TPROXY-DECRYPT.md` 참조(git에 포함되며 `/docs`에는 컴파일되지 않음)

전체 OpenAPI 스키마: docs/openapi.yaml → 태그 AgentBridge.

§8 로드맵

Trae 조사

Trae는 비교적 새로운 AI 코딩 어시스턴트입니다. 핸들러를 구현하기 전에 다음을 수행해야 합니다.

VS Code / JetBrains 마켓플레이스 또는 독립 실행형 앱에서 바이너리/확장 프로그램 식별
mitmproxy로 트래픽을 캡처하여 API 호스트와 엔드포인트 형식 파악
인증 메커니즘 확인
이용 약관과 API 검색 가능성을 기준으로 진행 여부 평가

조사가 완료될 때까지 대시보드의 Trae 카드에는 “조사 중” 배지와 “실현 가능성 보고” 링크가 표시됩니다. src/mitm/handlers/trae.ts의 핸들러 스텁은 구조화된 아직 구현되지 않음 오류를 발생시킵니다.

백로그 에이전트(MITM 필요 — 사용자 지정 기본 URL 미지원)

다음 도구의 현재 버전은 사용자 지정 기본 URL을 지원하지 않으므로 MITM이 유일한 가로채기 경로입니다. 실현 가능성 평가는 아직 진행되지 않았습니다.

Windsurf (Codeium/Cognition)
Amp (Sourcegraph)
Amazon Q / Kiro CLI (AWS Bedrock — Kiro IDE와 별개)
Cowork (Anthropic 데스크톱)

참고: GitHub Copilot CLI ≥v1.0.19는 COPILOT_PROVIDER_BASE_URL을 지원하므로, 해당 도구에는 MITM 대신 직접 설정을 사용하세요.

OmniRoute 소스 코드 (a58000c7685f)

HagiCode

HagiCode는 구조화된 워크플로, 다중 에이전트 실행, Hero Dungeon 뷰를 갖춘 에이전트 코딩 작업 공간입니다.

더 스마트하고 빠르며 즐거운 에이전트 워크플로로 유용한 소프트웨어를 만드세요.

Smart구조화된 워크플로는 의도를 아이디어부터 배포까지 실행 가능한 경로로 바꿉니다.
Efficient다중 에이전트 워크플로로 조사, 구현, 검토를 병렬로 진행합니다.
FunHero Dungeon은 긴 코딩 세션을 시각적이고 협업적인 경험으로 만듭니다.

HagiCode 방문