HTTP Breakout Proxy

Go로 작성된 경량 HTTP/HTTPS 인터셉팅 프록시 및 트래픽 분석 도구로, 캡처된 트래픽을 실시간으로 검사, 필터링, 색상 표시, 주석 처리할 수 있는 웹 기반 UI를 제공합니다.

Web App

개요

HTTP Breakout Proxy는 HTTP 및 HTTPS MITM 프록시이자 실시간 시각화 도구로 동작합니다.
두 소프트웨어 구성 요소 간의 요청과 응답을 캡처하여 개발자가 다음을 수행할 수 있게 해줍니다:

각 요청과 응답에 대한 헤더, 본문, 타이밍 세부 정보를 검사합니다.
캡처된 데이터를 구성, 필터링, 저장합니다.
사용자 정의 컬러 규칙을 기반으로 요청을 강조 표시합니다.
캡처를 동적으로 일시 중지하거나 재개합니다.
요청 타이밍을 간트 차트로 확인하여 성능 단계를 시각화합니다.

이 프록시는 모든 최신 웹 브라우저에서 접근 가능한 완전한 기능의 UI를 내장하여, 외부 도구 없이 즉각적인 실시간 분석이 가능합니다.

기능

🔍 캡처 및 검사

HTTP 및 HTTPS 트래픽을 모두 인터셉트합니다(MITM CA 지원).
모든 요청 및 응답 메타데이터, 헤더, 본문을 표시합니다.
매우 큰 본문에 대한 잘라내기(truncation)를 지원합니다.

💾 영속성(Persistence)

캡처 및 컬러 규칙은 captures.json(또는 지정된 파일)에 저장됩니다.
시작 시 상태를 자동으로 다시 로드하고 주기적으로 디스크에 저장합니다.
기본 컬러 규칙은 최초 실행 시 생성됩니다(기존 규칙이 없는 경우).

🖥️ 웹 UI

반응형 내장 웹 인터페이스(프록시 자체에서 제공).
캡처를 색상 코드 표시기가 포함된 스크롤 가능한 목록으로 표시합니다.
세부 정보 패널에는 다음이 표시됩니다:
- 요청 및 응답 헤더/본문
- 타이밍 분석
- 편집 가능한 메모
- 연결 단계에 대한 간트 스타일 성능 차트

🎨 컬러 규칙

유연한 필터 구문을 사용하여 캡처에 대한 조건부 색상 강조를 정의합니다:
- 예: status:4 status:5 → HTTP 오류 강조
- 예: url:/api/ → API 요청 강조
- 예: /\.css$/ → URL에 대한 정규식 매칭
각 규칙에는 다음이 포함됩니다:
- 이름, 색상, 매칭 표현식, 우선순위, 메모
가장 높은 우선순위의 매칭이 적용됩니다.
실시간 미리보기가 포함된 모달 UI를 통해 대화형으로 관리됩니다.
세션 간에 유지됩니다.

⏸️ 캡처 제어

일시 중지/재개 버튼으로 프록시를 중지하지 않고 새 캡처 수집을 중단할 수 있습니다.
고정된 데이터 세트에 집중하거나 특정 동작을 분리할 때 유용합니다.

📈 성능 시각화

각 캡처에는 상세한 연결 타이밍이 포함됩니다:
- DNS 조회
- TCP 연결
- TLS 핸드셰이크
- 서버 처리
- 응답 읽기
세부 정보 패널에 간트 차트로 표시됩니다.
가독성을 위해 눈금이 가장 가까운 초 단위로 자동 반올림됩니다.

🧭 필터링 및 검색

실시간 필터 상자 지원:
- 필드 기반 필터(method:GET, status:404, header:Content-Type=application/json)
- 정규식 표현식(/login/)
- AND/OR 의미론으로 결합된 용어
대소문자를 구분하지 않으며 부분 일치를 지원합니다.
필터는 캡처 목록과 색상 강조 모두에 적용됩니다.
검색 기록은 브라우저에 로컬로 저장됩니다.

🧹 관리

UI를 통해 개별 캡처를 삭제하거나 모든 캡처를 지울 수 있습니다.
규칙과 메모는 캡처와 함께 유지됩니다.

🧩 내보내기 유틸리티

캡처를 다음 형식으로 복사:
- curl 명령어(터미널용 형식)
- python requests 코드 스니펫(깔끔한 JSON 표현)
UI에서 응답 본문을 직접 다운로드합니다.

명령줄 사용법

httpbreakout  -l 127.0.0.1:8080

빠른 시작

빌드(소스에서)

git clone https://github.com/jbsouthe/http-breakout-proxy.git
cd http-breakout-proxy
go build -o http-breakout-proxy

이렇게 하면 컴파일된 프록시와 내장 UI 에셋이 포함된 단일 실행 파일이 생성됩니다.

실행(기본값)

# 기본값으로 실행 (프록시 + UI)
./http-breakout-proxy

기본적으로 바이너리는 프록시용으로 127.0.0.1:8080에 바인딩됩니다(선택적으로 UI도 — CLI 플래그 참조). 브라우저에서 UI를 열어 캡처를 검사합니다.

예: curl로 프록시 사용해보기

# 프록시를 통해 HTTPS 요청 전송 (프록시는 127.0.0.1:8080에서 수신)
curl -x http://127.0.0.1:8080 https://example.com

캡처된 트래픽이 웹 UI에 표시됩니다.

명령줄 인수

사용 가능한 플래그와 사용법 설명을 보려면 ./http-breakout-proxy -h를 사용하세요.

웹 UI 개요

UI는 조사 워크플로우에 최적화되어 있습니다.

상단 도구 모음: 전역 필터 입력(정규식 및 키 접두사 지원), 캡처 일시 중지/재개, 지우기, 필터 도움말(새 탭에서 열림).
왼쪽 패널: 시간순 캡처 목록(최신 항목이 맨 위). 각 항목은 캡처 이름을 표시합니다. 기본값은 METHOD URL [STATUS]이지만 사용자 지정 이름을 지정할 수 있습니다.
오른쪽 패널: 선택된 캡처의 세부 정보:
- 개요: 메타데이터, 헤더, 본문(해당되는 경우 형식화된 JSON).
- 요청 / 응답 탭: 원시 형식의 본문.
- 원시 탭: 전체 캡처 JSON.
행 작업: curl로 복사, Python requests로 복사, 응답 본문 다운로드, 이름 바꾸기, 삭제.

필터 언어(간단 참조)

일반 토큰: 어디서든 매칭(메서드, URL, 상태, 호스트, 헤더, 본문).
접두사: method:, status:, host:, url:, body:, req.body:, resp.body:, header:, req.header:, resp.header:.
정규식 구문: /pattern/flags (예: /bearer\\s+\\S+/i).
헤더 지정: header:name=value, 여기서 name 또는 value는 정규식일 수 있습니다.

예시:

method:POST status:2 host:api.example.com
/token\\s*[:=]\\s*\\S+/i
req.header:authorization=/bearer/i
body:/\\"success\\"\\s*:\\s*true/i

HTTPS 인터셉션(MITM)

중간자(MITM) 모드가 활성화되면:

프록시는 RSA CA 키 쌍과 루트 인증서를 생성하여 -ca(기본값 ./ca)에 저장합니다.
HTTPS 트래픽을 검사하려면 생성된 CA 인증서(ca.pem 또는 유사한 파일)를 요청을 보내는 클라이언트(또는 시스템)의 신뢰 저장소에 추가해야 합니다. 많은 플랫폼에서 관리자 권한이 필요합니다.
프록시는 클라이언트가 요청한 각 호스트 이름에 대해 로컬 CA가 서명한 리프 인증서를 발급하여 TLS 인터셉션을 수행합니다.

보안 참고: 제어된 환경에서만 CA를 설치하세요. 관련 없는 민감한 트래픽을 읽는 시스템에서는 이 CA를 신뢰하지 마세요.

영속성

영속성이 활성화된 경우(-f 또는 설정된 경로를 통해):

캡처는 주기적으로 디스크에 기록됩니다(예: captures.json).
시작 시 애플리케이션은 영속성 파일에서 이전 캡처를 메모리 내 버퍼로 로드하려고 시도합니다(순서 유지).
이름 바꾸기와 삭제는 저장 작업 시 영속적 저장소에 동기화됩니다. 중요한 작업의 경우 즉시 플러시를 호출하는 것을 고려하세요.

저장 형식

캡처된 항목은 JSON으로 직렬화되며 다음 필드를 포함합니다(전체 목록 아님):

id — 고유 시퀀스 식별자
time — 타임스탬프(ISO 8601)
method, url
request_headers, response_headers
request_body, response_body — 필요한 경우 -max-body로 잘림
response_status, duration_ms
name — 선택적 사용자 레이블
notes, deleted — SSE 이벤트 및 UI 상태를 위한 제어 메타데이터

내보내기 및 재생 헬퍼

cURL로 복사: 헤더와 본문을 포함한 셸 안전 curl 명령을 생성합니다(홉바이홉 헤더 제외).
Python으로 복사: url, headers, 선택적 data가 포함된 작은 requests 스니펫을 생성합니다.
다운로드: 응답 본문을 파일로 저장합니다. 가능한 경우 Content-Type에서 확장자를 유추합니다.

설계 고려 사항:

홉바이홉 헤더(예: Host, Content-Length, Connection)는 생성된 재생 명령에서 제외됩니다.
이진 응답 본문(이미지, PDF)은 이진 블롭으로 다운로드할 수 있습니다. 응답이 Base64로 인코딩되어 저장된 경우 클라이언트는 다운로드 전에 디코딩합니다.

API: REST 엔드포인트(자동화용)

GET /api/captures — 캡처 목록(JSON 배열).
DELETE /api/captures — 모든 캡처 지우기.
GET /api/captures/{id} — 단일 캡처 검색.
DELETE /api/captures/{id} — 특정 캡처 삭제.
PATCH /api/captures/{id} — 캡처 메타데이터 업데이트; 본문 예: { "name": "My label" }.
GET /api/pause — { "paused": true|false } 반환.
POST /api/pause — 일시 중지 상태 설정; 본문 예: { "paused": true }.
GET /events — 실시간 캡처 알림 및 제어 이벤트용 SSE(Server-Sent Events) 스트림.

구현 참고 사항(개발자용)

UI 임베딩: //go:embed ui/*와 fs.Sub를 사용하여 정적 파일을 제공합니다. 이렇게 하면 단일 배포 가능 아티팩트가 생성됩니다.
압축 해제: 캡처 코드는 Content-Encoding을 확인하고 표시 전에 gzip 및 deflate 본문의 압축 해제를 시도합니다. 원본 바이트는 프록시 투명성을 위해 유지됩니다.
동시성: 캡처 저장소는 스레드 안전한 추가/목록/조회/업데이트 작업을 제공하기 위해 내부 잠금을 사용합니다. 가능한 경우 토글 플래그(예: 일시 중지/재개)에 원자적 부울이 사용됩니다.
SSE: 경량 브로커가 연결된 UI 클라이언트에 캡처 추가, 삭제, 이름 변경 및 제어 이벤트를 브로드캐스트합니다.
버퍼링: 캡처 본문은 io.LimitReader를 사용하여 읽혀 잘림을 감지하고 메모리 사용을 보호합니다.

패키징 및 배포

권장 배포 모델:

대상 플랫폼용 정적, 트림된 바이너리를 빌드합니다(CGO_ENABLED=0, -trimpath, -ldflags "-s -w").
아카이브를 생성하고(Unix용 .tar.gz, Windows용 .zip) README.md와 LICENSE를 포함합니다.
SHA-256 체크섬을 제공하고 GitHub Releases에 아티팩트를 첨부합니다.
선택적으로 goreleaser를 사용하여 크로스 플랫폼 빌드 및 릴리스 아티팩트를 자동화합니다.

빌드 명령 예시:

# Linux x86_64
GOOS=linux GOARCH=amd64 CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o dist/http-breakout-proxy-linux-amd64 .

# macOS (arm64)
GOOS=darwin GOARCH=arm64 CGO_ENABLED=0 go build -trimpath -ldflags "-s -w" -o dist/http-breakout-proxy-darwin-arm64 .

서비스로 실행

systemd 유닛(Linux 예시)

[Unit]
Description=HTTP Breakout Proxy
After=network.target

[Service]
ExecStart=/opt/http-breakout-proxy/http-breakout-proxy -l 0.0.0.0:8080
Restart=on-failure
User=proxy
Group=proxy

[Install]
WantedBy=multi-user.target

launchd(macOS 사용자 에이전트)

~/Library/LaunchAgents에 plist를 생성하고 launchctl로 로드합니다.

문제 해결

캡처된 본문이 이진 깨진 텍스트로 표시됨
본문이 압축되어 있습니다(예: gzip). 자동 압축 해제가 포함된 빌드를 실행 중인지 확인하세요. UI는 가능한 경우 압축 해제된 JSON/텍스트를 표시합니다.
HTTPS 트래픽이 표시되지 않음 / 연결 오류
클라이언트가 생성된 CA를 신뢰하지 않습니다. ca/ca.pem을 클라이언트/시스템 신뢰 저장소에 설치하고 TLS 인터셉션용으로 신뢰됨으로 표시하세요.
캡처를 지운 후 UI에 오래된 선택 항목이 표시됨
cleared SSE 이벤트에서 selectedId를 지우는 클라이언트로 업그레이드하거나 GET /api/captures 엔드포인트를 호출하여 상태를 새로 고치세요.
DELETE /api/captures에서 405 발생
서버 핸들러가 /api/captures에 대한 DELETE를 허용하는지, 그리고 후행 슬래시 불일치가 아닌지 확인하세요.

보안 및 개인정보

이 도구는 MITM이 활성화되면 TLS 인터셉션을 수행합니다. 트래픽 검사에 대한 명시적 승인이 있는 제어된 환경에서만 사용하세요. 생성된 CA는 강력합니다: 개인 키를 다른 루트 CA 개인 키와 동일한 수준의 기밀로 취급하세요. 공유 또는 프로덕션 신뢰 저장소에 CA를 설치하지 마세요.

기여

기여를 환영합니다. 버그나 기능 요청은 이슈를 열어 주세요. 코드 기여의 경우:

저장소를 포크합니다.
기능 브랜치를 생성합니다.
해당되는 경우 단위 테스트와 린터를 실행합니다.
변경 사항, 근거 및 이전 버전과의 호환성 문제를 설명하는 풀 리퀘스트를 제출합니다.

라이선스

이 프로젝트는 MIT 라이선스에 따라 배포됩니다. 자세한 내용은 LICENSE를 참조하세요.

저자 및 연락처

저자: John Southerland (GitHub: jbsouthe)
프로젝트: http-breakout-proxy — HTTP 동작에 대한 디버깅, 개발 및 학습을 위해 제작되었습니다.

`-l`	`127.0.0.1:8080`	프록시가 수신할 주소이자 UI 앱 주소.
`-mitm`	`true`	HTTPS 중간자(MITM) 모드 인터셉션 활성화(TLS 인터셉션용 로컬 CA 생성).
`-ca`	`./ca`	MITM이 활성화되고 영속성이 선택된 경우 생성된 CA 인증서와 키가 저장되는 디렉터리.
`-f`	`./captures.json`	캡처를 디스크에 저장하기 위한 선택적 경로 또는 디렉터리(예: `./captures.json`).
`-max-body`	`1048576`	본문별 저장/표시할 최대 바이트 수. 더 큰 본문은 센티널 표시와 함께 잘립니다.
`-buffer-size`	`1000`	메모리 내 캡처용 순환 버퍼 용량.
`-v`	`false`	디버깅용 상세 로깅 활성화.

http-breakout-proxy

인기