PacketPirate

Windows 시스템에서 네트워크 트래픽 차단, 분석 및 수정을 위해 설계된 헤드리스(headless), 스크립트 가능한 CLI 기반 MITM 프록시입니다. 업계 표준 GUI 프록시와 유사하게 작동하지만 자동화 환경, 헤드리스 운영 및 개발 워크플로우와의 통합에 최적화되어 있습니다.

참고: Node.js로 구현된 독립형이며 의존성이 없는 도구입니다.

개요

• PacketPirate는 시스템 전체 네트워크 차단 도구입니다. Windows HTTP 프록시 설정을 활용하여 사용자 머신에서 실행 중인 모든 애플리케이션의 트래픽을 캡처할 수 있습니다—웹 브라우저(Chrome, Edge), CLI 도구(curl, git), 데스크톱 애플리케이션(Spotify, VS Code, Discord)을 포함합니다.

• 전역 시스템 차단: 시스템 프록시를 준수하는 모든 프로세스의 HTTP/HTTPS 트래픽을 캡처합니다.

• 프로세스 인식: 어떤 애플리케이션이 정확히 트래픽을 생성하는지 식별합니다.

• 동적 규칙 엔진: JSON을 통해 구성하여 일치하는 트래픽에 대해 특정 작업을 수행합니다(예: 토큰 추출, 요청 로깅).

• 전체 트래픽 로깅: 분석을 위해 전체 요청 및 응답 본문(HTML, JSON, Binary)을 덤프할 수 있습니다.

• 헤드리스 아키텍처: 전적으로 CLI에서 실행되며 백그라운드 서비스 및 자동화된 테스트 파이프라인에 적합합니다.

• 사용자 지정 인증서 관리: HTTPS 복호화를 위한 자체 서명 루트 CA 생성 및 신뢰 유틸리티를 포함합니다.

설치

사전 요구 사항

• Node.js (v14 이상)
• Windows 10/11 (시스템 프록시 자동화 기능에 필요)
• PowerShell (인증서 관리 스크립트용)

설정

저장소를 클론하고 환경을 초기화합니다:

# 1. 로컬 SSL 인증서 생성
npm run setup

# 2. 생성된 루트 CA 신뢰
npm run trust
# 참고: 신뢰할 수 있는 루트 저장소에 인증서를 추가하려면 관리자 승인이 필요합니다.

사용법

프록시 서버를 시작합니다:

npm start

이 명령은 표준 CLI 인터페이스를 실행합니다.

CLI 작동

대화형 메뉴는 다음 컨트롤을 제공합니다:

1. 프로세스 스캔: 활성 네트워크 연결이 있는 프로세스 목록을 표시합니다. 특정 PID로 트래픽을 필터링할 수 있습니다(예: code.exe만 독점 모니터링).
2. 필터 전환: 특정 모니터링 하위 시스템을 활성화/비활성화합니다:
   • API URL 스캔: 요청된 API 엔드포인트를 기록합니다.
   • 헤더 덤프: 전체 요청 헤더를 콘솔에 출력합니다.
   • 토큰 헌트: Authorization 헤더에서 Bearer 토큰을 휴리스틱하게 감지합니다.
   • 전체 트래픽 덤프: 모든 트래픽(헤더 + 전체 본문)을 구조화된 jsonl 로그 파일로 캡처합니다.
3. 프록시 시작: 서버를 사용 가능한 첫 번째 포트(기본값 8080)에 바인딩하고 Windows 시스템 프록시를 구성합니다.
4. 규칙 생성: 새 차단 패턴을 빠르게 만드는 도우미 기능입니다.

구성

차단 로직은 config/rules.json에 정의됩니다. 이 파일은 트래픽 처리의 영구 구성이 가능하게 합니다.

스키마:

{
  "rules": [
    {
      "name": "Description of rule",
      "host": "hostname.match",
      "urlPattern": "regex_pattern",
      "action": "log | save_token",
      "outputFile": "path/to/output.txt",
      "tokenFilter": "regex_filter"
    }
  ]
}

예시:

{
    "rules": [
        {
            "name": "Test API",
            "host": "jsonplaceholder.typicode.com",
            "action": "save_token",
            "outputFile": "test_tokens.txt"
        }
    ]
}

기술적 세부 사항

아키텍처

이 도구는 이중 서버 아키텍처를 사용합니다:

1. 프록시 서버: 초기 CONNECT 터널링 요청을 처리하고 호스트 필터링을 수행합니다.
2. MITM 서버: 동적으로 생성된 CA를 사용하여 HTTPS 트래픽을 복호화하고, 규칙 엔진에 대해 페이로드를 검사한 후 요청을 업스트림으로 전달합니다.

네트워크 처리

• 포트 관리: EADDRINUSE 오류를 자동으로 감지하고 사용 가능한 포트를 찾을 때까지 포트 번호를 증가시킵니다.
• 시스템 프록시: PowerShell을 통한 직접 레지스트리 조작을 사용하여 시스템 전체에 프록시 설정을 적용합니다.
• 정리: SIGINT/SIGTERM 핸들러를 구현하여 종료 시 프록시 설정이 되돌려지도록 보장하여 네트워크 연결 문제를 방지합니다.

인증서 수명 주기 및 보안

이 도구는 HTTPS 차단을 위해 이중 인증서 모델에 의존합니다:

1. 루트 CA 생성: npm run setup은 자체 서명된 루트 CA(PacketPirateRoot)를 생성합니다.
   • 로직: PowerShell의 New-SelfSignedCertificate를 사용하여 5년 동안 유효한 키 쌍을 생성합니다.
   • 내보내기: 키는 비밀번호 "headless"와 함께 src/certs/server.pfx(PKCS#12 형식)로 내보내집니다.
2. 신뢰 설정: npm run trust는 이 루트 CA를 Windows CurrentUser\Root 저장소에 주입합니다.
   • 보안 범위: LocalMachine이 아닌 CurrentUser를 대상으로 하여 신뢰 범위를 사용자 프로필로 제한하여 시스템 전체 위험을 줄입니다.
   • 브라우저 수락: Chrome, Edge 및 IE는 이 신뢰 저장소를 상속합니다. Firefox는 Windows 신뢰 저장소를 존중하려면 별도의 토글(security.enterprise_roots.enabled)이 필요합니다.
3. 제거: npm run untrust는 깨끗한 정리를 제공합니다.
   • 식별: 스크립트는 고유한 FriendlyName("PacketPirateRoot")으로 인증서를 찾아 다른 사용자 인증서를 건드리지 않도록 합니다.
   • 검증: 제거 후 인증서 지문이 레지스트리에 더 이상 없는지 확인합니다.

🎓 교육: 빌드 방법

이 프로젝트는 Node.js를 사용한 시스템 프로그래밍의 실용적인 예입니다. 일반적인 웹 서버를 넘어 운영 체제 및 네트워크 스택과 더 낮은 수준에서 상호 작용합니다.

아키텍처

participant App as Application (VS Code)
participant OS as Windows OS
participant Proxy as Proxy Server
participant MITM as MITM Server
participant Web as Internet

Note over App,Proxy: 1. Plain HTTP Tunneling
App->>Proxy: CONNECT google.com:443
Proxy-->>App: 200 Connection Established

Note over Proxy,MITM: 2. The "Hand-Off" Trick
Proxy->>MITM: Pipe socket data (raw encrypted bytes)

Note over App,MITM: 3. TLS Handshake and Decryption
MITM-->>App: ServerHello (signed by local root CA)
App->>MITM: Encrypted request (GET /)

Note over MITM: 4. Interception Logic
MITM->>MITM: Decrypt → Inspect headers → Log

Note over MITM,Web: 5. Upstream Forwarding
MITM->>Web: New HTTPS request (GET /)
Web-->>MITM: Response
MITM-->>App: Response

핵심 개념

1. "이중 서버" 패턴

Node.js의 표준 http 모듈은 동일한 서버 인스턴스에서 CONNECT 메서드(HTTPS 터널에 사용)와 일반 HTTPS 트래픽을 쉽게 처리할 수 없습니다.

• 서버 A (Net/HTTP): 포트 8080에서 수신 대기합니다. 초기 CONNECT 요청을 처리합니다. 단순한 TCP 파이프 역할을 합니다.
• 서버 B (HTTPS): 메모리에만 존재합니다(또는 임의 포트에 존재). 개인 키를 보유합니다.
• 트릭: 서버 A가 연결을 받으면 소켓을 서버 B로 "emit"합니다. 서버 B는 방금 새 연결을 받은 것으로 간주하고 SSL 핸드셰이크를 시작합니다. 이를 통해 트래픽을 원활하게 복호화할 수 있습니다.

2. 프로세스 귀속 (netstat 핵)

어떤 앱이 트래픽을 보내는지 어떻게 알 수 있을까요? TCP 패킷 자체에는 "프로세스 ID" 스티커가 없습니다.

• 임시 포트: 모든 나가는 연결은 무작위의 높은 번호의 포트(예: 54321)를 사용합니다.
• 상관 관계: netstat -ano를 호출하여 포트 54321을 소유한 PID를 찾습니다.
• 최적화: 모든 패킷에 대해 이 작업을 수행하는 것은 느리므로 결과를 캐시하거나 필요할 때만 확인합니다.

3. 스트림 분기

데이터를 효율적으로 처리하기 위해 Node.js Streams를 사용합니다. 전체 10MB 응답이 다운로드될 때까지 기다리는 대신 스트림을 "분기"합니다:

• 파이프 1: 클라이언트로 전달(앱이 계속 작동하도록).
• 파이프 2: 로거로 전달(디스크에 저장할 수 있도록). 이 작업은 PassThrough 스트림을 사용하여 수행되며 최소한의 추가 지연으로 실시간 모니터링이 가능합니다.

라이선스

GNU GPL v3.0