ApiCatcher 빠른 시작
ApiCatcher는 기기에서 앱의 HTTP/HTTPS, WebSocket 트래픽을 캡처하고 살펴보고 분석합니다.
이 문서는 인증서, 트래픽 필터, 요청 기록, 내보내기, API 문서처럼 일상적인 캡처 작업을 다룹니다. 재작성, 스크립트, 콤보 재생 같은 고급 기능은 아래 문서를 보세요.
관련 문서:
목차
- 준비: 인증서와 디버그 권한
- 트래픽 필터
- 캡처 Session과 기록 검색
- Cookie 찾기
- 내보내기: HAR, 파일, 단일 요청
- API 문서 자동 생성
- 품질·성능: API Scan
1. 준비: 인증서와 디버그 권한
1.1 CA 인증서 설치와 신뢰 (HTTPS에 필요)
요즘 앱 통신은 대부분 HTTPS입니다. 기본값으로는 HTTPS를 캡처하지 않습니다. 인증서가 없으면 복호화할 수 없어 평문을 볼 수 없습니다. HTTPS를 보려면 먼저 CA를 설치하고 완전히 신뢰하세요.
인증서는 두 가지로 넣을 수 있습니다.
- ApiCatcher가 만드는 CA (대부분의 경우 이쪽): 아래 순서를 따릅니다.
- 직접 가져온 인증서 (기업 인증서): 사내 CA를 쓸 거면 1.2로 가세요.
기본 CA:
- 앱에서 「인증서 설치」를 누르면 브라우저가 구성 프로파일을 받습니다.
- 설정 → 일반 → VPN 및 기기 관리에서 방금 받은 ApiCatcher 프로파일을 설치합니다.
- 꼭 할 일: 설정 → 일반 → 정보 → 인증서 신뢰 설정에서
ApiCatcher CA로 시작하는 인증서를 찾아 전체 신뢰를 켭니다.
안 될 때
- 디버깅 중 타임아웃이나 이상한 상태 코드: 대개 3번에서 신뢰를 안 켠 경우입니다.
- 앱을 지우고 다시 설치했다면 예전 프로파일은 무효입니다. 설정에서 지운 뒤 처음부터 다시 하세요.
1.2 기업 인증서 (사내망)
일부 사내 앱은 회사 CA만 믿습니다.
- 용도: 회사에서 준
.pem또는.p12를 넣고 내부 호스트(예:*.corp.internal)에 묶어, 로컬 TLS 핸드셰이크가 되게 합니다. - 주의: 캡처를 끈 상태에서 넣거나 고친 뒤, 다시 시작해야 적용됩니다.
1.3 자체 서명 인증서
기업 인증서가 없고 ApiCatcher가 만든 것도 쓰기 싫다면, 같은 기업 인증서 흐름으로 직접 넣은 인증서를 쓸 수 있습니다. 자세한 내용은 커스텀 인증서.
2. 트래픽 필터
시스템과 백그라운드 앱 트래픽이 많으니, 지금 보는 프로젝트만 남기도록 필터를 두는 편이 좋습니다.
- 차단 목록: 일치하는 호스트는 기록하지 않습니다. 허용 목록이 비어 있으면 차단 목록 이외는 모두 기록합니다.
- 허용 목록: 규칙이 하나라도 있으면 맞는 요청만 기록합니다.
- 작성 팁:
*를 쓸 수 있습니다.*.example-api.com이면 그 호스트 아래 테스트 서브도메인이 맞습니다.
안 될 때
- 대상 앱 요청이 안 보임: 허용 목록을 켜 놓고 호스트를 빠뜨렸거나, 차단 목록에 들어 있는 경우입니다.
- 문법:
*.api.com처럼 별표만 쓰면 됩니다. 여기는 정규식이 아닙니다.
3. 캡처 Session과 기록 검색
차단/허용은 무엇을 저장할지 정합니다. 저장된 뒤에는 기록 화면의 Session과 검색으로 이미 잡은 요청을 좁힙니다.
3.1 캡처 Session
Session은 VPN 캡처 한 주기입니다. 화면에는 시작 시각(yyyy-MM-dd HH:mm:ss)으로 보이며, 이름을 바꿀 수 없습니다.
VPN 캡처를 성공적으로 시작하면 Session이 하나 생깁니다. 끄면 종료 시각과 요청 수를 쓰고, 요청이 하나도 없으면 그 Session은 지워집니다. 진행 중이면 종료 시각이 「캡처 중」입니다.
기록 화면 Session 필터로 한 번만 보거나 「전체」를 고를 수 있습니다. 선택기에는 시간 범위, 캡처 시간, 요청 수, 이번에 본 Host(최대 5개)가 나옵니다. Session을 지우면 그 주기의 요청도 같이 사라집니다.
3.2 필터 조건
기록 화면에 필터 막대가 있습니다. 「필터 구성」에서 보여줄 조건을 고르고, 「필터 초기화」로 비울 수 있습니다.
| 조건 | 맞추는 방식 |
|---|---|
| Session | 특정 한 번, 또는 전체 |
| Host | 호스트 정확 일치 |
| 앱 (UA) | User-Agent에서 뽑은 앱 이름 정확 일치 |
| 메서드 | GET / POST / PUT / DELETE / PATCH / OPTIONS / HEAD |
| 스킴 | HTTP / HTTPS / WS / WSS |
| 유형 | 전체, HTML, JSON, XML, 이미지, 동영상, 오디오, Protobuf (Content-Type) |
| 상태 코드 | 1xx–5xx, 그리고 「응답 없음」 |
| 시간 | 최근 15분, 최근 1시간, 오늘, 최근 7일, 최근 30일, 직접 지정 |
3.3 키워드 검색
검색창 기본 대상은 URL(자리 표시: 「Search url...」)입니다. 대소문자를 가리지 않는 부분 일치이며, 정규식과 AND / OR는 없습니다.
기록 화면 「…」→「검색 대상 전환」으로 범위를 바꿉니다.
| 대상 | 범위 |
|---|---|
| URL | 요청 URL |
| 요청 헤더 | 헤더 이름 또는 값 |
| 응답 헤더 | 헤더 이름 또는 값 |
| 요청 Body | 요청 본문 텍스트 |
| 응답 Body | 응답 본문 텍스트 |
Body 검색은 텍스트 Content-Type(HTML / XML / JSON / 일반 텍스트 / form-urlencoded / form-data)만 봅니다. 이미지, 동영상 같은 바이너리 Body는 읽지 않습니다.
4. Cookie 찾기
「Cookie 찾기」는 어떤 Host의 가장 최근 요청에 실린 Cookie를 꺼냅니다. 요청 헤더 Cookie만 보고, Set-Cookie는 보지 않으며, 여러 요청을 합치지 않습니다.
- 기록을 엽니다.
- 오른쪽 위 「…」→「Cookie 찾기」.
- Host를 입력합니다(필수. 이미 잡은 목록에서 고르거나 직접 입력).
- Session은 선택. 비우면 모든 Session에서 찾습니다.
- 「Cookie 검색」을 누릅니다.
있으면 「최근 Cookie」와 키/값이 나오고, 없으면 「Cookie가 있는 요청을 찾지 못했습니다」입니다.
5. 내보내기: HAR, 파일, 단일 요청
5.1 HAR로 내보내기
HAR 1.2 JSON이며 Charles, Fiddler, Burp 등에서 열 수 있습니다. 파일 이름은 apicatcher-export-yyyyMMddHHmmss.har 형태입니다.
| 진입점 | 범위 | 현재 필터를 따를까 |
|---|---|---|
| 기록 화면 「HAR로 내보내기」 | 현재 필터 결과의 전체 요청(지금 페이지만이 아님) | 따름 (Session, Host, 시간, 메서드, 유형, 상태, 검색어가 목록과 같음) |
| 기록에서 여러 개 고른 뒤 공유/내보내기 | 고른 요청만 | 따르지 않음 |
| 요청 즐겨찾기 폴더에서 HAR | 그 폴더 안 요청 | 따르지 않음 |
화면에 「내보낼 요청은 모두 N개입니다. 필터를 바꿔 대상을 줄일 수 있습니다.」라고 나옵니다. 내보내는 동안 화면을 닫지 마세요.
5.2 이미지 / 동영상 / 오디오
진입점: 기록 화면의 파일 관리(폴더 아이콘).
- 이미지, 동영상, 오디오 세 분류.
- Session, Host로 범위를 줄일 수 있습니다.
Range/Content-Range조각은 합친 뒤 내보냅니다.- 파일 하나만, 또는 Host별 하위 폴더를 ZIP으로 묶어 일괄 내보내기.
요청 상세의 본문에서도 「파일 내보내기」를 할 수 있고, Content-Type에 맞춰 임시 파일로 저장한 뒤 공유합니다.
5.3 단일 요청
요청 상세에서 「요청 내보내기」:
- Raw: 원본 HTTP 요청 + 응답 (
.txt) - cURL: 터미널에서 다시 보낼 수 있는 명령 (
.sh) - Markdown: Markdown 미리보기 (
.md)
6. API 문서 자동 생성
조건에 맞는 HTTP/HTTPS를 잡으면 앱이 기기에서 API 문서를 만들거나 고치고, Host로 묶습니다. 같은 API를 여러 번 봐도 아직 없는 필드만 더하고, 이미 있는 파라미터 이름은 덮지 않습니다.
6.1 대상과 병합 규칙
응답이 있고 상태 코드가 301–308이 아닌 HTTP/HTTPS만 봅니다. 요청 Content-Type이 JSON / XML / multipart/form-data / x-www-form-urlencoded이거나, 응답이 JSON / XML일 때만 문서를 만듭니다. 이미지, 동영상, HTML, 일반 텍스트는 건너뜁니다.
재작성 규칙이나 스크립트가 손댄 요청은 문서에 넣지 않습니다. 고유 키는 메서드 + Host + Path(예: GET + api.example.com + /v1/user)입니다.
병합:
- Query, Header, Body: 없는 이름만 추가.
- Body 예시: 이번 응답이 200일 때만 갱신.
- Cookie, User-Agent 같은 흔한 표준 헤더는 파라미터에 넣지 않습니다. Authorization, Content-Type, 커스텀 헤더는 남깁니다.
6.2 Postman / Apifox / Bruno로 내보내기
진입점:
- Host API 목록 오른쪽 위(그 Host의 모든 엔드포인트).
- 개별 API 상세(그 하나만).
- 설정 → API 즐겨찾기 → 내보내기(즐겨찾기만).
| 대상 | 방법 |
|---|---|
| Postman으로 내보내기 | Postman API Key를 넣고 Workspace를 불러온 뒤, Collection을 만들거나 기존 것을 고릅니다 |
| Apifox로 내보내기 | Apifox API Key와 프로젝트 ID. 폴더 ID는 선택(비우면 루트) |
| Bruno로 내보내기 | bruno.json과 .bru가 든 ZIP. Bruno에서 Open Collection |
단계별 화면:
7. 품질·성능: API Scan
기기에 남은 트래픽으로 API 품질, 유출, 지연을 비침습적으로 봅니다. 분석은 기기 안에서만 이뤄집니다.
7.1 내장 엔진
- 민감 정보: 평문으로 나간 전화번호, 주민번호, 이메일, 클라우드 자격 증명(AWS Key, OpenAI API Key 등).
- 스택 유출: 응답에 섞인 Java, Python, SQL 오류 스택.
- 잦은 호출: 평균 간격이 설정한 임계값보다 짧으면 루프나 잘못된 재시도를 의심합니다.
- 소요 시간: 엔드포인트별 p95, p99.
7.2 직접 검사 (Custom Scan)
업무 규칙은 JS로 쓸 수 있습니다.
- 괜찮으면
null. 문제면 짧은 설명(200자 이하)을 반환하면 보고서에 들어갑니다.
안 될 때
- 결과가 없음: 스캔 범위(Host/Session)에 JSON/API가 있는지 확인하세요. 정적 파일만 있으면 비어 있습니다. 한 번에 볼 수 있는 건수에도 상한이 있습니다.