Traffic Inspector (한국어)

§1 개요

Traffic Inspector만의 차별점

기능	mitmweb	Charles	Fiddler	OmniRoute Traffic Inspector
웹 기반	✓	✗	✗	✓
오픈 소스	✓	✗	부분 지원	✓
에이전트 인식(요청이 Antigravity/Copilot 등에서 전송되었는지 식별)	✗	✗	✗	✓
LLM 인식(OpenAI/Anthropic/Gemini 형식, 토큰, 모델 파싱)	✗	✗	✗	✓
모델 매핑 표시(gemini-3-flash → claude-sonnet-4.7)	✗	✗	✗	✓
프록시/업스트림 지연 시간 분리	부분 지원	✗	✗	✓
OmniRoute의 라우팅, 폴백, 비용과 통합	✗	✗	✗	✓
시스템 전체 프록시 디버깅(머신의 모든 앱)	✓	✓	✓	✓
사용자 지정 호스트 캡처(호스트별 DNS 리디렉션)	✓	✓	✓	✓
HTTP_PROXY 환경 변수 모드	✓	✓	✓	✓
대화 보기(다중 턴 말풍선, tool_use/tool_result)	✗	✗	✗	✓
SSE 스트림 병합기(델타 이벤트로부터 재구성)	✗	✗	✗	✓
세션 기록(이름 지정 가능, .har/.jsonl로 내보내기 가능)	✗	✓	✓	✓

한 단락으로 보는 아키텍처

TrafficBuffer(src/mitm/inspector/buffer.ts)는 공유 인메모리 링 버퍼입니다(기본값 1000개 항목, INSPECTOR_BUFFER_SIZE로 구성 가능). 모든 캡처 소스는 push()를 통해 이 버퍼에 기록합니다. 버퍼는 kindDetector.ts를 사용해 각 항목을 분류하고(LLM 요청인지 판별), contextKey(시스템 프롬프트의 SHA-256 지문)를 계산한 다음 globalTrafficBuffer.subscribe()를 통해 모든 WebSocket 구독자에게 브로드캐스트합니다. 대시보드는 GET /api/tools/traffic-inspector/ws를 통해 연결되며, 연결 시 스냅샷을 수신한 후 new/update/clear 이벤트를 차례로 수신합니다.

---

§2 캡처 모드

Traffic Inspector는 5개의 동시 캡처 소스를 지원합니다. 각 소스는 독립적으로 켜거나 끌 수 있습니다. 모든 InterceptedRequest(src/mitm/inspector/types.ts)의 source 필드는 "agent-bridge", "custom-host", "http-proxy", "system-proxy", "tproxy" 중 하나입니다.

모드 1 — AgentBridge(기본값, 항상 활성화)

소스: AgentBridge 핸들러(src/mitm/handlers/base.ts) 메커니즘: MitmHandlerBase의 모든 intercept() 호출은 전달 전에 hookBufferStart()를 호출하고 완료 시 hookBufferUpdate()를 호출합니다. 추가 설정이 전혀 필요하지 않으며, AgentBridge가 실행되는 즉시 작동합니다. 적용 범위: AgentBridge에 구성된 9개의 IDE 에이전트 참고: InterceptedRequest의 source 필드 = "agent-bridge"

모드 2 — 사용자 지정 호스트(DNS 리디렉션)

소스: 사용자 정의 호스트 목록(inspector_custom_hosts 테이블) 메커니즘: UI를 통해 호스트를 추가하면 /etc/hosts에 127.0.0.1 <host>가 추가됩니다(sudo 필요). 기존 AgentBridge MITM 서버(포트 443)가 새 호스트의 SNI 인증서를 동적으로 생성합니다. 적용 범위: 추가된 호스트를 사용하는 모든 애플리케이션 — 앱 설정을 변경할 필요가 없습니다. 참고: source = "custom-host"

사용 사례 예시:

• Python 스크립트에서 api.openai.com 모니터링
• my-internal-llm.company.com 디버깅
• 동일한 네트워크에 있는 모바일 기기의 트래픽 캡처(ARP 스푸핑 사용 — 고급)

모드 3 — HTTP_PROXY 리스너(포트 8080)

소스: HTTP_PROXY/HTTPS_PROXY 환경 변수를 사용하는 애플리케이션 메커니즘: 표준 명시적 HTTP/HTTPS 프록시로 작동하는 포트 8080의 보조 리스너(src/mitm/inspector/httpProxyServer.ts)입니다. CONNECT 터널(HTTPS)과 직접 HTTP 요청을 수락합니다. 적용 범위: HTTP_PROXY 환경 변수를 준수하는 모든 애플리케이션 — DNS 변경이나 sudo가 필요하지 않습니다. 참고: source = "http-proxy"

# 단일 명령을 빠르게 캡처:
HTTPS_PROXY=http://127.0.0.1:8080 curl https://api.openai.com/v1/models

# 셸 세션에서 지속적으로 캡처:
export HTTP_PROXY=http://127.0.0.1:8080
export HTTPS_PROXY=http://127.0.0.1:8080

TLS 제한 사항: HTTPS CONNECT 터널은 기본적으로 메타데이터(호스트, 포트, 타이밍)만 캡처되며 TLS 본문은 복호화되지 않습니다. 전체 본문을 검사하려면 “프록시 모드에서 HTTPS 복호화” 토글을 활성화하세요(옵트인이며 AgentBridge 인증서를 신뢰해야 함).

포트 충돌: 포트 8080이 사용 중이면 AgentBridge가 구조화된 오류와 함께 409를 반환합니다. INSPECTOR_HTTP_PROXY_PORT 환경 변수를 사용하여 포트를 변경하세요.

모드 4 — 시스템 전체 프록시(고급, 옵트인)

소스: OS 수준 프록시 설정(머신의 모든 앱에 적용) 메커니즘: OS API를 사용하여 모든 HTTP/HTTPS 트래픽을 HTTP_PROXY 리스너를 통해 리디렉션합니다.

• macOS: networksetup -setwebproxy / -setsecurewebproxy
• Linux: gsettings set org.gnome.system.proxy + /etc/environment
• Windows: netsh winhttp set proxy 127.0.0.1:8080 적용 범위: 시스템 프록시 설정을 준수하는 머신의 모든 애플리케이션 참고: source = "system-proxy"

안전 메커니즘:

• 자동 비활성화 타이머(기본값 30분, INSPECTOR_SYSTEM_PROXY_GUARD_MINUTES를 통해 구성 가능)
• 이전 시스템 프록시 상태를 DB에 저장하고 되돌릴 때 복원
• 활성화된 상태에서 사용자가 다른 페이지로 이동하면 대시보드에 “시스템 프록시 되돌리는 중” 메시지 표시
• UI에 ⚠ 고급 배지와 명시적 확인 체크박스 표시

모드 5 — TPROXY 투명 복호화(Linux, root, 옵트인)

소스: 커널 TPROXY + 정책 라우팅(src/mitm/tproxy/) 메커니즘: mangle OUTPUT에서 대상 포트(기본값 443)로 향하는 새로운 로컬 아웃바운드 TCP 연결을 마킹하고, ip rule이 마킹된 패킷을 로컬 전달로 재라우팅하며, mangle PREROUTING의 TPROXY 대상이 이를 투명(IP_TRANSPARENT) 리스너(기본 포트 8443)로 전달합니다. 리스너는 동적 CA가 각 SNI 호스트 이름별로 필요 시 발급한 리프 인증서로 TLS를 종료하고, 복호화된 통신을 캡처한 후 요청을 다시 암호화하여 원래 대상으로 전달합니다. 적용 범위: 대상 포트의 임의 목적지 호스트 — /etc/hosts 스푸핑, HTTP_PROXY 환경 변수 또는 시스템 전체 프록시 변경이 필요하지 않습니다. 가로채기 대상 프로세스의 설정을 변경할 필요는 없지만 동적 CA를 신뢰해야 합니다. 참고: source = "tproxy"

요구 사항: Linux 전용(IP_TRANSPARENT는 Linux에서만 지원), CAP_NET_ADMIN 기능(root), C 도구 체인으로 빌드해야 하는 네이티브 N-API 애드온(npm run build:native:tproxy)이 필요합니다. 사용할 수 없는 경우 대시보드 토글이 비활성화되고 “TPROXY 복호화에는 Linux + root + 네이티브 애드온이 필요합니다”라는 도구 설명이 표시됩니다. 방화벽 규칙은 트랜잭션 방식으로 적용/되돌리며(충돌이 발생해도 mangle 규칙이 남지 않음) 재부팅 시 초기화됩니다. SO_MARK 기반 안티 루프는 프록시 자체에서 다시 암호화하여 전달한 트래픽이 다시 가로채지는 것을 방지합니다.

이 기능은 자체적인 전용 운영자 가이드가 있는 대규모 하위 시스템입니다. 전체 방화벽 구성법, SNI별 동적 CA + 신뢰 저장소 설치 프로그램, 로컬 전용 경로, 안티 루프 세부 정보 및 구성 스키마는 docs/security/MITM-TPROXY-DECRYPT.md(git에 있으며 /docs로 컴파일되지 않음)를 참조하세요. 토글은 GET / POST / DELETE /api/tools/agent-bridge/tproxy로 제어됩니다(참고: 이 경로는 Traffic Inspector 접두사가 아닌 AgentBridge 접두사 아래에 있음).

캡처 모드 비교

모드	설정	Sudo?	적용 범위	참고
1. AgentBridge	자동	1회(cert+hosts)	9개 IDE 에이전트	기본적으로 활성화
2. 사용자 지정 호스트	호스트별 입력	예(hosts 파일)	해당 호스트를 사용하는 모든 앱	DB에 유지됨
3. HTTP_PROXY	export HTTPS_PROXY=...	아니요	환경 변수를 준수하는 앱	포트 8080, 기본적으로 TLS 복호화 안 함
4. 시스템 전체	토글 + 확인	예	머신의 모든 앱	30분 후 자동 비활성화
5. TPROXY 복호화	토글(Linux + 네이티브 애드온)	예(root + CA 설치)	대상 포트의 모든 호스트	임의의 호스트를 복호화함. 기본적으로 비활성화 — docs/security/MITM-TPROXY-DECRYPT.md 참조(git에만 있으며 /docs에는 컴파일되지 않음)

---

§3 UI

3.1 레이아웃

┌─ 트래픽 인스펙터 ────────────────────────────────────────────────────┐
│ ┌─ 캡처 소스 도구 모음 ──────────────────────────────────────────┐   │
│ │ [✓ AgentBridge]  [✓ 사용자 지정 호스트 (3)]  [○ HTTP_PROXY]  [○ 시스템]│   │
│ └─────────────────────────────────────────────────────────────────────┘  │
│ ┌─ 필터/제어 모음 ────────────────────────────────────────────────┐   │
│ │ 프로필: (●) LLM만  (○) 사용자 지정  (○) 전체                    │   │
│ │ [⎉ 일시 중지] [🗑 지우기] [⬇ .har] [● 세션 녹화]    ● 실시간 482/1k│   │
│ └─────────────────────────────────────────────────────────────────────┘  │
├══◀▶══════════════════════════════╬══════════════════════════════════════╤╡
│ 요청 목록 (크기 조절 가능)       ║ 세부 정보 창                        ▲ │
│ ────────────────────────────── │ ║ [대화][헤더][요청]                  │ │
│ ▎ 14:32 POST 200 12k AG openai ║ [응답][타이밍][LLM][통계]           │ │
│ ▎ 14:31 POST 200 8k  CP openai ║                                     ▼ │
│ ▎ 14:31 POST 503 ⚠   KR ...   ║                                       │
│ ▎ 14:30 GET  200 3k  🌐 사용자 지정║                                  │
└══════════════════════════════════╝══════════════════════════════════════╝

3.2 요청 목록(왼쪽 패널)

• 가상화 (useVirtualList + ResizeObserver): 멈춤 현상 없이 1000개 항목 처리
• 검사 중 일시 중지할 수 있는 토글이 포함된 자동 스크롤
• 상태별 색상 구분: 녹색(2xx), 노란색(3xx), 빨간색(4xx/5xx), 회색(진행 중)
• 에이전트 이모지: 🔵 Antigravity, 🟢 Copilot, 🟠 Kiro, 🟣 Codex, 🔷 Cursor, 🟤 Zed, 🟡 Claude Code, ⚫ Open Code, 🌐 사용자 지정 호스트
• 컨텍스트 색상 표시줄: contextKey(시스템 프롬프트의 SHA-256)에 따라 색상이 지정된 1px 왼쪽 테두리 — 관련 대화를 시각적으로 그룹화
• 본문 지연 로딩: 선택한 요청의 본문만 세부 정보 탭에 구체화(1000 × 1MB 본문을 렌더링하는 상황 방지)

3.3 세부 정보 창 — 7개 탭

탭	내용	참고
대화	여러 턴의 채팅 말풍선(system/user/assistant + tool_use/tool_result)	모든 제공자 형식에서 정규화되며, detectedKind === "llm"인 경우에만 표시
헤더	요청 + 응답 헤더 표	민감한 헤더(Authorization, Cookie, api-key)는 기본적으로 마스킹되며, “비밀 정보 표시” 토글 제공
요청	원시 본문, JSON 트리 뷰, 모델 필드 배지	보기 좋게 출력된 JSON 또는 원시 텍스트
응답	원시 본문 또는 SSE 이벤트 목록, “원시 ↔ 병합” 토글	SSE 병합기가 델타 이벤트로부터 최종 메시지를 재구성
타이밍	워터폴: 프록시 오버헤드 및 업스트림 지연 시간	총 시간, TTFB 및 크기
LLM 세부 정보	제공자, 모델, 메시지 수, 입력/출력 토큰, 예상 비용, 매핑된 대상	LLM 요청에만 표시
통계	Recharts: 지연 시간 타임라인, 토큰 막대 차트, 도구 호출 산점도	녹화된 세션을 불러온 경우에만 표시

3.4 도구 모음 컨트롤

컨트롤	동작
⎉ 일시 중지	새 요청 렌더링을 중지하며, “새 요청 X개” 배지가 누적됨
🗑 지우기	UI 목록을 지움(서버 버퍼에는 영향 없음)
⬇ .har 내보내기	현재 필터링된 목록을 HAR 파일로 다운로드
● 세션 녹화	이름이 지정된 녹화 세션을 시작
프로필 선택기	LLM만 / 사용자 지정 호스트 / 전체
호스트 필터	host 필드에 대한 부분 문자열 일치
에이전트 필터	드롭다운: 전체 / 에이전트별
상태 필터	전체 / 2xx / 3xx / 4xx / 5xx / 오류
소스 필터	전체 / agent-bridge / custom-host / http-proxy / system-proxy / tproxy
실시간 필터	진행 중인(열린) 요청만 표시 — liveOnly 토글(§4.6 참조)

3.5 크기 조절 가능 패널

• 목록과 세부 정보 창은 드래그 핸들로 구분
• 목록 너비: 최소 280px, 최대 720px, localStorage에 유지 (inspector.listWidth)
• 48px 레일(아이콘만 표시)로 축소 가능하며, 레일에서 행을 클릭하면 확장됨

---

§4 LLM 인식 기능

4.1 종류 감지기 (src/mitm/inspector/kindDetector.ts)

다음 4가지 신호를 사용하여 각 요청을 "llm", "app" 또는 "unknown"으로 분류합니다.

1. 호스트 레지스트리 — 알려진 LLM API 호스트 이름 약 18개(OpenAI, Anthropic, Gemini, Groq, Mistral, Together, Fireworks, Cohere, Perplexity, Hugging Face, OpenRouter, xAI, Moonshot 등)
2. 경로 패턴 — /v1/chat/completions, /v1/messages, /generateContent, /v1/responses 등
3. 본문 구조 — messages[](OpenAI/Claude), contents[](Gemini), prompt, input 필드를 감지
4. 사용자 에이전트 힌트 — UA 문자열의 codex, claude, gemini, antigravity, kiro, copilot, cursor

모드 2를 통해 추가된 사용자 지정 호스트는 양식 입력에서 kind를 상속합니다(기본값은 "custom").

4.2 SSE 병합기 (src/mitm/inspector/sseMerger.ts)

독립적인 클린룸 구현입니다. 이벤트 파싱은 WHATWG 서버 전송 이벤트 알고리즘을 따르며, 재구성은 공개된 OpenAI, Anthropic 및 Gemini 스트리밍 스키마를 따릅니다.

원시 SSE 델타 이벤트에서 최종 어시스턴트 메시지를 재구성합니다.

• Anthropic: 인덱스별로 content_block_delta를 누적하며 text_delta, input_json_delta(도구 호출), thinking_delta를 처리
• OpenAI: Chat Completions의 선택 항목/도구 호출과 Responses API 출력 항목을 인덱스별로 누적
• Gemini: candidates[i].content.parts를 누적
• 알 수 없음: 원시 이벤트를 그대로 반환

응답 탭에는 “원시 이벤트 ↔ 병합됨” 전환 버튼이 표시됩니다.

4.3 대화 정규화기 (src/mitm/inspector/conversationNormalizer.ts)

독립적인 클린룸 구현입니다. 정규화는 로컬 블랙박스 계약과 공개된 OpenAI, Anthropic 및 Gemini 메시지 스키마에 따라 정의되며, 업스트림 구현 소스는 사용하지 않습니다.

OpenAI, Anthropic 및 Gemini 메시지 형식을 렌더링 전에 단일 NormalizedConversation으로 변환합니다.

interface NormalizedConversation {
  request: NormalizedTurn[]; // 요청 본문의 messages / contents / prompt
  response: NormalizedTurn[]; // 어시스턴트 응답(sseMerger를 통해 병합됨)
  contextKey: string | null; // SHA-256 시스템 프롬프트 지문
}

블록 유형: text, tool_use, tool_result. 대화 탭은 제공업체와 관계없이 이 구조를 사용합니다.

4.4 컨텍스트 키 색상화 (src/mitm/inspector/contextKey.ts)

• 시스템 프롬프트(첫 번째 role:system 메시지, system 필드 또는 Gemini systemInstruction)의 SHA-256을 계산
• 12자의 16진수 접두사를 반환("a3f9c2...")
• 프런트엔드는 왼쪽 테두리 막대에 사용할 결정론적 HSL 색상으로 키를 매핑
• “동일한 컨텍스트” 필터: ctx #a3f 칩을 클릭하면 동일한 지문을 가진 요청만 표시하는 필터가 추가됨

이를 통해 동일한 에이전트 세션에서 실행되는 서로 다른 “페르소나”나 작업을 시각적으로 쉽게 구분할 수 있습니다.

4.5 LLM 메타데이터 추출

LLM 요청의 경우 LLM 세부 정보 탭에서 다음 정보를 추출합니다.

interface LlmMetadata {
  provider: string | null; // "openai" | "anthropic" | "gemini" | ...
  apiKind: string | null; // "chat.completions" | "messages" | "embeddings" | ...
  model: string | null; // 요청 본문 또는 응답에서 가져옴
  messages: number; // 턴 수
  tokensIn: number | null; // usage.prompt_tokens / usage.input_tokens
  tokensOut: number | null; // usage.completion_tokens / usage.output_tokens
  streamed: boolean; // SSE 응답이면 true
  mappedTo: string | null; // x-omniroute-mapped 헤더
  costEstimateUsd: number | null; // OmniRoute 가격을 기반으로 추정한 비용
}

4.6 실시간 진행 중 요청 필터

요청의 status 필드는 number | "in-flight" | "error"입니다. 요청이 시작되는 즉시 항목이 "in-flight" 상태로 추가되고, 응답(또는 오류)이 도착하면 해당 위치에서 업데이트됩니다. 도구 모음의 “실시간” 전환 버튼 (liveOnly, i18n 키 trafficInspector.liveOnly)은 목록을 status === "in-flight"인 항목으로 제한하여 열린 연결을 실시간으로 확인할 수 있게 합니다.

필터는 src/lib/inspector/matchesTrafficFilter.ts에 있는 순수 클라이언트 측 조건자입니다.

if (f.liveOnly && req.status !== "in-flight") return false;

전환 상태는 useTrafficFilters(검사기 대시보드 훅)에 있으며, 다른 필터(프로필, 호스트, 에이전트, 소스, 상태, 컨텍스트)와 함께 적용됩니다.

4.7 프로세스 귀속(Linux)

Linux에서는 가로챈 각 요청을 요청을 시작한 로컬 프로세스에 귀속시킬 수 있습니다. InterceptedRequest에 다음 두 개의 선택적 필드가 추가됩니다.

pid?: number;          // 요청을 시작한 프로세스 ID(Linux 전용)
processName?: string;  // 요청을 시작한 프로세스 이름(Linux 전용)

src/mitm/inspector/processAttribution.ts는 다음 단계에 따라 연결의 클라이언트 임시 포트를 PID와 이름에 매핑합니다.

1. /proc/net/tcp와 /proc/net/tcp6를 읽어 해당 포트의 소켓 inode를 찾습니다(parseProcNetTcpForInode, 픽스처로 테스트할 수 있는 순수 파서).
2. /proc/<pid>/fd/를 스캔하여 socket:[<inode>]를 가리키는 심볼릭 링크를 찾습니다.
3. /proc/<pid>/comm에서 프로세스 이름을 읽습니다.

1초 TTL 캐시는 부하 상황에서 procfs 스캔 비용을 제한합니다. 귀속은 최선형 방식으로 수행됩니다. 오류가 발생하면 null로 처리되며 캡처를 차단하지 않습니다. macOS/Windows에서는 함수가 null을 반환합니다(스텁이며 lsof/GetExtendedTcpTable 지원은 후속 작업입니다).

---

§5 세션

5.1 세션 기록

1. 도구 모음에서 **“● 세션 기록”**을 클릭 → 이름 입력(선택 사항)
2. 실시간 테일은 정상적으로 계속되며, 빨간색으로 깜박이는 표시기에 ◉ REC · <name> · 00:42 · 23개 요청이 표시됩니다.
3. **“⏹ 중지”**를 클릭 → 세션 스냅샷이 inspector_sessions + inspector_session_requests에 저장됩니다.

5.2 기록된 세션 보기

도구 모음의 세션 드롭다운에는 저장된 세션이 표시됩니다. 하나를 선택하면 다음과 같이 동작합니다.

• 세션의 스냅샷을 불러옵니다(고정된 상태).
• 배너에 기록된 세션 "<name>" 보는 중 — [실시간으로 돌아가기]가 표시됩니다.
• Recharts 집계를 제공하는 통계 탭을 사용할 수 있게 됩니다.

5.3 내보내기 형식

각 세션은 다음 형식으로 내보낼 수 있습니다.

형식	용도
HAR (HTTP Archive 1.2)	Chrome DevTools, Charles, Fiddler와 호환 — 오프라인 분석을 위해 가져오기 가능
JSONL	줄마다 하나의 InterceptedRequest — llm-interceptor 형식과 호환

GET /api/tools/traffic-inspector/sessions/{id}/export.har 또는 세션 드롭다운의 ⬇ 버튼을 통해 내보낼 수 있습니다.

---

§6 보안

Traffic Inspector는 인증 헤더와 요청 본문을 포함하여 가로챈 모든 HTTPS 트래픽을 표시합니다. 다음과 같은 제어 기능이 적용됩니다.

제어 기능	세부 정보
LOCAL_ONLY	모든 라우트와 WebSocket 엔드포인트는 루프백에서만 접근할 수 있습니다(인증 전에 routeGuard.ts에서 강제 적용).
비밀 정보 마스킹	선형 maskSecret() 스캐너는 TrafficBuffer.push() 전에 RFC 6750 Bearer 자격 증명, 공급자 접두사가 붙은 키 및 긴 불투명 토큰을 마스킹합니다.
본문 크기 제한	INSPECTOR_MAX_BODY_KB(기본값 1024 KB)를 초과하는 본문은 "(성능을 위해 잘림)" 알림과 함께 잘립니다.
헤더 정리	이름은 소문자로 변환되고, 프레이밍/홉별 및 프록시 인증 헤더는 삭제되며, 쿠키는 완전히 마스킹됩니다. 자격 증명 값은 maskSecret()에 위임됩니다.
CSP	삽입된 응답 본문을 통한 XSS를 방지하기 위해 Traffic Inspector 페이지에 엄격한 Content Security Policy가 적용됩니다.
기본적으로 영속성 없음	TrafficBuffer는 메모리에만 존재하며 서버를 재시작하면 손실됩니다. 세션은 명시적으로 기록한 경우에만 영구 저장됩니다.

적용되는 강제 규칙

규칙	적용 방식
#12 sanitizeErrorMessage	Traffic Inspector 라우트의 모든 HTTP 오류 응답이 정리됩니다.
#15 + #17 isLocalOnlyPath()	/api/tools/traffic-inspector/는 LOCAL_ONLY + SPAWN_CAPABLE입니다(시스템 프록시 명령).

알려진 제한 사항

• 시스템 전체 프록시 모드는 VPN 클라이언트와 SSO를 포함하여 기기의 모든 애플리케이션에 영향을 줍니다. 항상 자동 비활성화 타이머와 함께 사용하십시오. 공유 기기에서는 사용하지 마십시오.
• CONNECT 터널 HTTPS: TLS 가로채기가 활성화되지 않은 경우 모드 3(HTTP_PROXY)은 HTTPS 대상에 대한 터널 메타데이터만 캡처합니다. 이는 의도된 동작입니다. 해당 앱이 AgentBridge 인증서를 신뢰하지 않는 상태에서 투명하게 캡처하면 TLS 검증이 실패하기 때문입니다.
• 일부 컴포넌트에 하드코딩된 문자열: 일부 UI 컴포넌트(F7/F8)에는 아직 i18n 키가 적용되지 않은 소수의 하드코딩된 문자열이 있습니다. 이러한 문자열은 i18n 격차 보고서에 알려진 제한 사항으로 문서화되어 있으며, 후속 작업에서 마이그레이션될 예정입니다. 영향을 받는 문자열은 기능 사용을 위해 번역할 필요가 없는 UI 장식용 레이블입니다.

---

§7 문제 해결

WebSocket 연결 끊김

라이브 테일에 “연결 끊김”이 표시되는 경우:

1. 서버가 계속 실행 중인지 확인합니다: GET /api/tools/traffic-inspector/capture-modes
2. 페이지를 새로고침합니다. WebSocket이 다시 연결되고 새로운 스냅샷을 수신합니다
3. 서버가 재시작된 경우 인메모리 버퍼가 지워집니다. 세션을 기록하지 않았다면 이전 항목은 사라집니다

포트 8080 충돌

HTTP_PROXY 모드가 시작되지 않는 경우:

lsof -i :8080    # 프로세스 찾기

포트를 변경합니다:

.env

INSPECTOR_HTTP_PROXY_PORT=8888

시스템 프록시가 되돌려지지 않음

시스템 전체 프록시 모드가 활성화된 상태에서 OmniRoute가 충돌하는 경우:

macOS:

networksetup -setwebproxystate Wi-Fi off
networksetup -setsecurewebproxystate Wi-Fi off

Linux (GNOME):

gsettings set org.gnome.system.proxy mode 'none'

Windows:

netsh winhttp reset proxy

다음에 대시보드를 불러올 때 DB 상태에서 프록시가 활성화되어 있었던 것으로 감지되면 “시스템 프록시 되돌리기” 옵션도 제공됩니다.

버퍼 가득 참

버퍼가 INSPECTOR_BUFFER_SIZE(기본값 1000)에 도달하면 새 항목이 추가될 때 가장 오래된 항목이 제거됩니다. 중요한 요청이 유실되는 경우:

• INSPECTOR_BUFFER_SIZE를 늘립니다(예: 5000). 메모리 사용량이 늘어나는 대신 보존되는 항목이 많아집니다
• 관련 시간 범위를 DB에 영구 저장하려면 세션을 기록합니다

---

§8 API 참조

모든 라우트는 LOCAL_ONLY(루프백 전용) 및 SPAWN_CAPABLE(시스템 프록시 명령)입니다. src/server/authz/routeGuard.ts를 참조하세요.

기본 경로: /api/tools/traffic-inspector/

요청 관리

메서드	경로	설명
GET	/requests	요청 목록 조회(필터링 가능: ?profile=llm&host=&agent=&status=&source=&sessionId=)
GET	/requests/{id}	단일 요청 세부 정보
DELETE	/requests	인메모리 버퍼 지우기
POST	/requests/{id}/replay	OmniRoute 라우터를 통해 동일한 요청 다시 실행
PUT	/requests/{id}/annotation	요청에 대한 메모 저장 또는 업데이트

WebSocket

메서드	경로	설명
GET	/ws	라이브 WebSocket 스트림. 연결 시 snapshot을 전송한 후 new/update/clear 이벤트를 전송합니다

내보내기

메서드	경로	설명
GET	/export.har	현재 필터링된 목록을 HAR 1.2로 내보내기

사용자 지정 호스트

메서드	경로	설명
GET	/hosts	사용자 지정 호스트 목록 조회
POST	/hosts	호스트 추가(/etc/hosts 자동 편집)
DELETE	/hosts/{host}	호스트 제거
PATCH	/hosts/{host}	enabled 전환

캡처 모드

메서드	경로	설명
GET	/capture-modes	AgentBridge / 사용자 지정 호스트 / HTTP_PROXY / 시스템 프록시 모드의 상태와 tls-intercept 토글
POST	/capture-modes/http-proxy	HTTP_PROXY 리스너 시작/중지({action: "start"|"stop"})
POST	/capture-modes/system-proxy	시스템 전체 프록시 적용/되돌리기({action: "apply"|"revert"})
POST	/capture-modes/tls-intercept	프록시 모드에서 HTTPS 본문 복호화 전환({enabled: boolean})

TPROXY 복호화(캡처 모드 5)는 AgentBridge 접두사 아래의 별도 라우트인 GET / POST / DELETE /api/tools/agent-bridge/tproxy를 통해 제어되며, /api/tools/traffic-inspector/ 아래에 있지 않습니다. docs/security/MITM-TPROXY-DECRYPT.md를 참조하세요(git에 있으며 /docs에는 컴파일되지 않음).

세션

메서드	경로	설명
POST	/sessions	기록 시작({name?: string})
PATCH	/sessions/{id}	중지 또는 이름 변경({action: "stop"|"rename", name?: string})
GET	/sessions	저장된 모든 세션 목록 조회
GET	/sessions/{id}	세션 스냅샷(모든 요청)
DELETE	/sessions/{id}	세션 삭제
GET	/sessions/{id}/export.har	세션을 HAR 1.2로 내보내기

내부 수집(D4 폴백)

메서드	경로	설명
POST	/internal/ingest	server.cjs 패스스루 경로에서 가로챈 요청을 수락하며, INSPECTOR_INTERNAL_INGEST_TOKEN 헤더가 필요합니다

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

---

OmniRoute 소스 코드 (a58000c7685f)