F --> G1[Passive scanners]
F --> G2[Active scanners]

I[template-tool] --> H[CVE templates]
H --> G2

G1 --> J[Findings]
G2 --> J
J --> K[Reporter]
K --> L[Auto Reports]
K --> M[CI/CD Controls]

## ApiHunter를 선택해야 하는 이유는?

### 핵심 장점

- **API 우선 아키텍처**: 웹 앱 스캐너를 개조한 것이 아니라 REST/GraphQL API 전용으로 설계됨
- **지능형 오탐(False Positive) 감소**:
  - 카나리 프로빙을 통한 SPA catch-all 감지
  - 컨텍스트 인식 시크릿 검증(프런트엔드 vs 백엔드)
  - 본문 콘텐츠 검증 및 referer 확인
  - 중복 발견 항목을 건너뛰기 위한 응답 핑거프린팅
- **설계상 프로덕션 안전**:
  - 오류 발생 시 백오프하는 적응형 동시성(AIMD)
  - 구성 가능한 지연 시간을 갖춘 호스트별 속도 제한
  - 정중함 제어(재시도, 타임아웃, WAF 우회)
  - 활성 검사를 위한 드라이런 모드
- **스텔스 및 회피**:
  - 큐레이션된 풀(assets/user_agents.txt)에서 런타임 User-Agent 로테이션
  - 지터가 포함된 무작위 요청 지연
  - 호스트별 지연 강제(버스트 패턴 방지)
  - 지수 백오프가 포함된 재시도 로직
  - 정상 트래픽과 혼합되기 위한 사용자 정의 헤더 주입
  - 서버 응답에 따른 적응형 타이밍
  - 기본 모드에서 하드코딩된 스캐너 핑거프린트 없음

### 스텔스 기법 심층 분석

ApiHunter는 WAF(웹 애플리케이션 방화벽) 및 봇 보호 시스템의 탐지를 피하기 위해 여러 스텔스 기법을 사용합니다:

#### 1. User-Agent 로테이션
**기능:** 파일(`assets/user_agents.txt`)에서 100개 이상의 실제 브라우저 User-Agent 문자열을 무작위로 순환합니다.

**효과가 있는 이유:** 봇은 일반적으로 동일한 User-Agent(예: `curl/7.68.0`)를 사용합니다. Chrome, Firefox, Safari 등으로 위장하면 정상 트래픽에 섞여들 수 있습니다.

**쉬운 비유:** 항상 같은 제복을 입는 대신 여러 가지 변장을 하는 것과 같습니다.

#### 2. 무작위 타이밍 및 지터
**기능:** 요청 사이에 지터(작은 무작위 변동)와 함께 무작위 지연을 추가합니다(`--delay-ms`로 제어).

**효과가 있는 이유:** 봇은 완벽한 간격(정확히 100ms 간격)으로 요청을 보냅니다. 인간은 예측할 수 없습니다. 무작위 타이밍은 트래픽을 자연스럽게 보이게 만듭니다.

**쉬운 비유:** 로봇처럼 행진하는 대신 불규칙한 보폭으로 걷는 것과 같습니다.

#### 3. 호스트별 지연 강제
**기능:** 전역이 아닌 각 도메인에 대해 지연을 별도로 추적합니다.

**효과가 있는 이유:** 한 호스트에 50번을 순식간에 때리는 버스트 패턴을 방지합니다. 각 호스트는 정중하고 간격을 둔 요청을 보게 됩니다.

**쉬운 비유:** 한 사람에게 반복적으로 소리치는 대신 여러 대화에 번갈아 참여하는 것과 같습니다.

#### 4. 적응형 동시성(AIMD)
**기능:** 429(속도 제한) 또는 503(서버 사용 중) 오류가 발생하면 자동으로 속도를 늦추고, 성공하면 속도를 높입니다.

**효과가 있는 이유:** 적발되면 물러나고 브라우저가 재시도하는 방식을 모방합니다. WAF는 "이 클라이언트는 우리의 제한을 존중한다"고 봅니다.

**쉬운 비유:** 교통이 혼잡하면 속도를 줄이고, 열린 도로에서는 속도를 높이는 것과 같습니다.

#### 5. 지수 백오프 재시도
**기능:** 요청이 실패하면 재시도 전에 1초, 그다음 2초, 그다음 4초를 기다립니다.

**효과가 있는 이유:** 정당한 클라이언트는 정상적으로 재시도합니다. 봇은 종종 즉시 두들기거나 포기합니다.

**쉬운 비유:** 문을 두드릴 때 계속 두드리는 대신 매번 더 오래 기다리는 것과 같습니다.

#### 6. 스캐너 핑거프린트 없음
**기능:** `X-Scanner: ApiHunter` 같은 헤더나 예측 가능한 패턴을 보내지 않습니다.

**효과가 있는 이유:** 많은 도구가 시그니처(Nuclei 템플릿, sqlmap 패턴)를 남깁니다. ApiHunter는 명백한 표식을 피합니다.

**쉬운 비유:** "보안 테스터"라는 이름표를 달지 않는 것과 같습니다.

#### 7. 연결 재사용 및 풀링
**기능:** 호스트별 HTTP 클라이언트 풀을 사용하고 연결을 유지합니다.

**효과가 있는 이유:** 브라우저는 연결을 재사용합니다. 모든 요청에 대해 열고 닫는 것은 의심스러워 보입니다.

**쉬운 비유:** 문을 계속 닫아 버리고 다시 벨을 누르는 대신 문을 열어 두는 것과 같습니다.

#### 8. 사용자 정의 헤더 주입
**기능:** `Referer`, `X-Forwarded-For`, 사용자 정의 쿠키 같은 헤더를 추가할 수 있습니다.

**효과가 있는 이유:** 요청이 정상적인 애플리케이션 흐름(링크 클릭, 세션 쿠키 보유)에서 온 것처럼 보이게 만듭니다.

**쉬운 비유:** 울타리를 넘는 대신 입장 시 티켓 스텁을 보여주는 것과 같습니다.

#### 탐지 비교

| 기법 | 회피 없음 | 회피 적용 |
|-----------|----------------|-------------|
| **User-Agent** | `python-requests/2.28.0`(명백한 봇) | `Mozilla/5.0 (Windows NT 10.0; Win64; x64)...`(Chrome처럼 보임) |
| **타이밍** | 완벽한 100ms 간격 → WAF 차단 | 120ms, 95ms, 180ms → 인간처럼 보임 |
| **재시도** | 즉시 재시도 → 차단 | 1초→2초→4초 대기 → "인내심 있는 클라이언트" |
| **동시성** | 100개 병렬 히트 → 경보 | 응답에 따라 적응형 5→10→3 → "정중한 브라우저" |

#### `--waf-evasion` 사용 시점

- Cloudflare/Akamai/AWS WAF가 있는 프로덕션 API 테스트
- 대규모 스캔 중 IP 차단 방지
- 레이더에 잡히지 않아야 하는 침투 테스트

- **CI/CD 네이티브**:
  - 베이스라인 비교(새로운 발견 항목만 보고)
  - 실시간 모니터링을 위한 스트리밍 NDJSON 출력
  - GitHub/GitLab 코드 스캐닝용 SARIF 2.1.0
  - 파이프라인 제어를 위한 종료 코드 비트마스크
  - 심각도 기반 필터링 및 실패 임계값
- **대규모 성능**:
  - 제로 비용 추상화를 갖춘 Rust 비동기 런타임(tokio)
  - 세마포어로 제한된 병렬 처리를 통한 동시 스캔
  - 연결 병목을 피하기 위한 호스트별 HTTP 클라이언트 풀
  - 효율적인 메모리 사용(GC 일시 중지 없음)
- **포괄적인 인증 지원**:
  - 쿠키/헤더 추출이 포함된 JSON 기반 인증 흐름
  - 이중 신원 IDOR/BOLA 테스트
  - 세션 파일 가져오기(Excalibur 통합)
  - Bearer, Basic 및 사용자 정의 헤더 인증
  - 권한 상승 검사를 위한 자동 비인증 클라이언트

## 스캐너 모듈

ApiHunter에는 13개의 내장 스캐너 모듈이 포함되어 있습니다. 자세한 탐지 로직은 [docs/scanners.md](https://github.com/teycir/apihunter/blob/HEAD/docs/scanners.md)를 참조하세요.

| 스캐너 | 유형 | 탐지 대상 |
|---------|------|----------------|
| **CORS** | 패시브 | 와일드카드 오리진, 자격 증명과 함께 반사된 오리진, null 오리진 허용, 정규식 우회 취약점(접미사/접두사 공격), Vary: Origin 누락, 안전하지 않은 preflight 메서드 |
| **CSP** | 패시브 | Content-Security-Policy 누락, unsafe-inline/unsafe-eval 지시문, 와일드카드 소스, 우회 가능한 CDN 호스트(JSONP 가젯), frame-ancestors 누락 |
| **GraphQL** | 패시브 | 인트로스펙션 활성화, 민감한 스키마 필드(user/password/token 유형), 필드 제안(스키마 유출), 쿼리 배칭, 별칭 증폭(DoS), GraphiQL/Playground 노출 |
| **JWT** | 패시브 | alg=none 토큰, 취약한 HS256 시크릿(단어 목록 기반), 만료 누락/과도한 만료, 페이로드의 민감한 클레임, 알고리즘 혼동 취약점 |
| **OpenAPI** | 패시브 | 보안 스키마 누락, 인증 요구 사항이 없는 작업, 파일 업로드 엔드포인트, 여전히 존재하는 더 이상 사용되지 않는 작업, 보안되지 않은 민감한 엔드포인트 |
| **API 버저닝** | 패시브 | 버전 헤더 노출, 동시 사용 중인 레거시/신규 API 버전, deprecation 헤더, 일반 쿼리/버전 변형에 걸친 응답 드리프트(`--response-diff-deep`로 딥 모드 지원) |
| **gRPC/Protobuf** | 패시브 + 액티브 | gRPC 전송/콘텐츠 유형 신호, protobuf 표면 힌트, 선택적 reflection/health 프로브 신호 |
| **API 보안** | 패시브 + 액티브 | 보안 헤더 누락(X-Content-Type-Options, X-Frame-Options), 서버 버전 노출, 민감한 경로에 대한 인증되지 않은 접근, HTTP 메서드 열거, 디버그 엔드포인트, 시크릿 노출 패턴, 액티브 IDOR/BOLA 검사(본문 + 선택된 헤더 비교), 블라인드 SSRF 콜백 프로브, 게이트웨이/우회 프로브 신호 |
| **Mass Assignment** | 액티브 | 반사된 민감한 필드(is_admin, role, permissions), 지속된 상태 변경, 필드 주입을 통한 권한 상승 |
| **OAuth/OIDC** | 액티브 | 리다이렉트 URI 검증 우회, state 매개변수 누락, PKCE 지원 문제(S256 누락, plain 허용), 암시적 흐름 활성화, password grant 활성화 |
| **Rate Limit** | 액티브 | 속도 제한 누락(버스트 프로브), Retry-After 헤더 누락, IP 헤더 스푸핑 우회(X-Forwarded-For) |
| **WebSocket** | 액티브 | 일반적인 경로에서 WebSocket 업그레이드 수락, 오리진 검증 누락, 인증되지 않은 WebSocket 연결 |
| **CVE 템플릿** | 액티브 | `assets/cve_templates/*.toml`의 템플릿 기반 CVE 탐지(현재 168개 템플릿), 베이스라인 vs 우회 차등 매칭 |

**패시브 스캐너**는 기본적으로 실행되며 제작된 요청을 보내지 않고 응답을 분석합니다.  
**액티브 스캐너/검사**는 `--active-checks`가 필요하며 잠재적으로 침습적인 프로브(IDOR/BOLA, 변형, 우회 테스트)를 보냅니다.  
IDOR/BOLA는 `API 보안` 스캐너에 속합니다(전용 `--no-idor` 플래그는 없으며, 비활성화하려면 `--no-api-security`를 사용하세요).

### 모듈 출력 및 신호 참고 사항

이 노트는 발견 항목이 어떻게 출력되는지와 일반적으로 노이즈를 유발하는 원인을 요약합니다:

| 모듈 | 발견 접두사 / 형태 | 일반적인 오탐 | 일반적인 미탐 |
|---------|-------------------------|-------------------------|-------------------------|
| CORS | origin/evidence 필드가 있는 `cors/*` | 민감하지 않은 경로에서의 반사 | 인증된 경로에만 적용되는 오리진 검사 |
| CSP | 지시문 evidence가 있는 `csp/*` | 마이그레이션 중 의도적으로 적용된 레거시 CSP | 프로덕션 CDN 엣지 경로에서만 제공되는 CSP |
| GraphQL | 엔드포인트 + 기능 신호가 있는 `graphql/*` | 내부/테스트 테넌트용으로 의도된 공용 playground | 인증 후에만 활성화되는 스키마 제어 |
| JWT | 토큰 클레임/헤더 evidence가 있는 `jwt/*` | 합성 응답의 테스트/데모 토큰 | 스캔된 응답에 토큰이 전혀 나타나지 않음 |
| OpenAPI | operation/security 컨텍스트가 있는 `openapi/*` | 스펙에 의도적으로 포함된 더 이상 사용되지 않지만 차단된 엔드포인트 | 스펙을 사용할 수 없거나 비공개 문서에 분할되어 있음 |
| API 버저닝 | `api_versioning/*` + `response_diff/*` | 통제된 마이그레이션 중 여러 지원 버전 | 현재 시드 세트에서 버저닝된 경로를 찾을 수 없음 |
| gRPC/Protobuf | transport/reflection evidence가 있는 `grpc_protobuf/*` | 노출된 RPC 표면 없이 엣지 프록시의 gRPC 유사 메타데이터 | 시드 세트에서 도달하지 못한 별도 호스트/경로 뒤의 gRPC 엔드포인트 |
| API 보안 | header/path/method evidence가 있는 `api_security/*` | 비프로덕션 환경에서 의도적으로 노출된 디버그/테스트 엔드포인트 | 인증/세션 컨텍스트 뒤에서 적용되는 제어 |
| Mass Assignment | 반사/지속 델타가 있는 `mass_assignment/*` | 백엔드 상태를 지속하지 않는 에코 동작 | 숨겨진 검증 규칙에 의해 거부되는 변형 |
| OAuth/OIDC | redirect/metadata evidence가 있는 `oauth/*` | 완화된 정책이 있는 비프로덕션 IdP 구성 | 메타데이터에 표시되지 않는 동적 정책 적용 |
| Rate Limit | burst/429 동작이 있는 `rate_limit/*` | 전역 트래픽 셰이핑이 앱 수준 리미터 동작을 가림 | 짧은 프로브 창에 의해 트리거되지 않는 장기 창 리미터 |
| WebSocket | upgrade/origin 검사가 있는 `websocket/*` | 의도적으로 익명인 공용 WS 엔드포인트 | 프로브에 제공되지 않은 핸드셰이크 헤더를 통한 인증 요구 |
| CVE 템플릿 | 템플릿 evidence가 있는 `cve/<id>/<check>` | 일반 엔드포인트에 대한 핑거프린트 충돌 | 시드 URL에서 도달하지 못한 취약한 경로/컨텍스트 |

검사별 세부 정보 및 수정 지침은 [docs/scanners.md](https://github.com/teycir/apihunter/blob/HEAD/docs/scanners.md) 및 [docs/findings.md](https://github.com/teycir/apihunter/blob/HEAD/docs/findings.md)를 참조하세요.
스캐너 문서에는 이제 소스 정렬된 [모듈 검사 카탈로그](https://github.com/teycir/apihunter/blob/HEAD/docs/scanners.md#module-check-catalog) 및 [오탐 기대 모델](https://github.com/teycir/apihunter/blob/HEAD/docs/scanners.md#false-positive-expectation-model)이 포함되어 있습니다.

## 기능

### 패시브 보안 분석
- **CORS 잘못된 구성 탐지**:
  - 대상 도메인 기반 동적 오리진 생성
  - 정규식 우회 테스트(접미사/접두사 공격)
  - 자격 증명 인식 심각도 점수
  - 와일드카드 및 null 오리진 탐지
- **CSP 정책 분석**:
  - 누락/취약한 Content Security Policy 탐지
  - unsafe inline/eval 지시문
  - 와일드카드 소스 탐지
  - 정책 우회 패턴
- **GraphQL 보안**:
  - 인트로스펙션 쿼리 탐지
  - 민감한 유형/필드 이름 분석
  - 쿼리 배칭 지원 탐지
  - 별칭 증폭(DoS) 프로빙
  - 액티브 변형 퍼징(`--active-checks`, `--dry-run` 지원)
  - GraphiQL/Playground 노출
- **JWT 토큰 분석**:
  - 알고리즘 혼동(alg=none, HS256→RS256)
  - 취약한 시크릿 탐지(큐레이션 단어 목록)
  - 장기 토큰 탐지(exp 누락/과도)
  - 민감한 클레임 노출
  - 헤더 및 쿠키에서 토큰 추출
- **OpenAPI/Swagger 분석**:
  - 보안 스키마 검증
  - 파일 업로드 엔드포인트 탐지
  - 더 이상 사용되지 않는 작업 플래그 지정
  - 보안 정의 누락
  - 성능을 위한 스펙 캐싱
- **gRPC/Protobuf 적용 범위**:
  - gRPC 응답 메타데이터/콘텐츠 유형 탐지
  - 엔드포인트 메타데이터/경로 형태에서 protobuf 표면 힌트 탐지
  - 알려진 gRPC 경로에 대한 선택적 reflection/health 액티브 프로브 신호
- **시크릿 노출 탐지**:
  - AWS 키(AKIA*, 시크릿 키)
  - Google API 키(AIza*)
  - GitHub 토큰(ghp_*, github_pat_*)
  - Slack 토큰(xox*)
  - Stripe 키(sk_live_*, pk_live_*)
  - 데이터베이스 URL, 개인 키, bearer 토큰
  - 컨텍스트 인식 검증(오탐 감소)
- **API 보안 검사**:
  - HTTP 메서드 열거
  - 디버그 엔드포인트 탐지
  - 디렉터리 목록 노출
  - security.txt 존재 여부
  - 응답 헤더 분석(HSTS, X-Frame-Options 등)
  - 오류 메시지 노출

### 액티브 보안 테스트(--active-checks)
- **API 보안 IDOR/BOLA 검사**(3단계 접근):
  - 인증되지 않은 접근 테스트
  - 본문 핑거프린트 및 안정적인 헤더 스냅샷을 통한 응답 비교
  - ID 열거(±2 범위 이동)
  - 교차 사용자 권한 부여 우회(이중 신원)
  - 콜백 스타일 쿼리 매개변수를 통한 블라인드 SSRF 콜백 프로빙(`APIHUNTER_OAST_BASE`, `--dry-run` 지원)
  - 게이트웨이 핑거프린트 및 우회 프로빙(`api_security/gateway-*`)
- **Mass Assignment 취약점**:
  - 반사된 민감한 필드 주입
  - 지속된 상태 변경 탐지
  - 베이스라인→변형→확인 검증
  - 필드 주입을 통한 권한 상승
- **OAuth/OIDC 보안**:
  - 리다이렉트 URI 검증 우회
  - state 매개변수 처리
  - PKCE 지원 탐지
  - 메타데이터 구성 강화
  - 암시적 흐름 및 password grant 탐지
- **속도 제한**:
  - 버스트 요청 프로빙
  - 속도 제한 누락 탐지
  - Retry-After 헤더 검증
  - IP 헤더 스푸핑 우회 테스트
- **WebSocket 보안**:
  - 일반적인 경로에서 업그레이드 수락
  - 오리진 검증 테스트
  - 인증 누락 검사
- **CVE 템플릿 엔진**:
  - TOML 기반 템플릿 카탈로그
  - Nuclei YAML 가져오기 지원
  - 베이스라인 vs 우회 차등 매칭
  - 호스트+템플릿 중복 제거
  - 로더 품질 게이트가 잘못되었거나 안전하지 않은 요청 템플릿을 건너뜀(예: 확인되지 않은 요청 플레이스홀더)
  - 세그먼트 인식 컨텍스트 매칭으로 광범위한 경로 하위 문자열 과다 트리거 감소
  - 현재 로컬 카탈로그: 168개 템플릿(CVE-2022-22947, CVE-2021-29442, CVE-2021-29441, CVE-2020-13945, CVE-2021-45232, CVE-2022-24288과 같은 큐레이션된 강화 검사 포함)

### 발견 및 열거
- **엔드포인트 발견**:
  - robots.txt 파싱
  - sitemap.xml 파싱
  - OpenAPI/Swagger 스펙 가져오기
  - HAR 파일 가져오기(Excalibur 통합)
  - Postman/Insomnia 컬렉션 가져오기(`--collection`)
  - JavaScript 엔드포인트 추출
  - 동일 호스트 필터링
- **URL 접근성 사전 필터링**:
  - 죽은 엔드포인트를 건너뛰기 위한 빠른 사전 검사
  - 구성 가능한 타임아웃
  - --no-filter로 선택적 우회

### 성능 및 안정성
- **적응형 동시성(AIMD)**:
  - 오류에 따른 자동 속도 조정
  - 가산 증가(5초마다)
  - 429/503/타임아웃 시 승법 감소
- **스텔스 및 WAF 우회**:
  - 런타임 풀에서 User-Agent 로테이션(100개 이상의 실제 UA가 있는 assets/user_agents.txt)
  - 파일을 사용할 수 없는 경우 내장 폴백 UA
  - 탐지 패턴을 피하기 위한 무작위 지연 지터
  - 호스트별 타이밍 강제(전역 아님)
  - 지수 백오프가 포함된 재시도 로직
  - 사용자 정의 헤더 주입(X-Forwarded-For, Referer 등)
  - 429/503 응답에 따른 적응형 타이밍
  - 협력적 테스트를 위한 정중함 모드
  - 기본적으로 User-Agent 또는 헤더에 스캐너 핑거프린트 없음
- **리소스 관리**:
  - 세마포어로 제한된 병렬 처리
  - 호스트별 HTTP 클라이언트 풀
  - 연결 재사용 및 풀링
  - 구성 가능한 타임아웃 및 재시도
- **오류 처리**:
  - JoinSet을 통한 패닉 복구
  - 포착된 오류를 별도로 보고
  - 스캐너 실패 시 원활한 성능 저하

### 출력 및 보고
- **다중 출력 형식**:
  - Pretty JSON(사람이 읽을 수 있음)
  - NDJSON(스트리밍, 파싱 가능)
  - SARIF 2.1.0(GitHub/GitLab 코드 스캐닝)
- **베이스라인 비교**:
  - 베이스라인 스냅샷 생성
  - 새로운 발견 항목만 보고하도록 스캔 비교
  - 회귀 테스트에 적합
- **자동 저장 보고서**(기본 활성화, `--no-auto-report`로 비활성화):
  - ~/Documents/ApiHunterReports/<timestamp>/에 저장됨
  - findings.json(구조화된 발견 항목)
  - summary.md(마크다운 보고서)
  - scan.log(실행 로그)
- **실시간 스트리밍**:
  - 발견되는 대로 발견 항목 스트리밍
  - 실시간 파싱을 위한 NDJSON 형식
  - 진행 상황 추적
- **심각도 필터링**:
  - 최소 심각도로 필터링(info/low/medium/high/critical)
  - CI/CD용 실패 임계값
  - 종료 코드 비트마스크(0x01 발견, 0x02 오류)

### 통합 및 확장성
- **플러그형 스캐너 아키텍처**:
  - 모듈을 추가하려면 Scanner 트레이트 구현
  - 비동기 우선 설계
  - 독립적인 스캐너 실행
  - 스캐너별 패닉 격리
- **TOML 기반 확장성**:
  - assets/cve_templates/*.toml의 CVE 템플릿 카탈로그
  - 새 검사를 추가하는 데 코드 변경 불필요
  - 템플릿 기반 취약점 탐지
  - 커뮤니티 공유 가능한 템플릿 형식
- **Nuclei 템플릿 가져오기**:
  - YAML → TOML 변환용 template-tool 바이너리
  - 자동 매처 변환(status, word, regex, dsl)
  - 안전한 사전 점검 요청 체인 추출
  - 업스트림 템플릿의 탐지 로직 보존
- **이중 확장 모델**:
  - **코드 기반**: 복잡한 로직을 위해 Scanner 트레이트를 구현하는 Rust 스캐너 작성
  - **템플릿 기반**: 시그니처 기반 검사(CVE, 잘못된 구성)를 위한 TOML 템플릿 작성
  - 최상의 조합: 성능 + 유연성
- **보완 도구**:
  - Excalibur 브라우저 확장 프로그램(HAR 캡처)
  - BurpAPIsecuritysuite(수동 테스트)
  - 워크플로: 캡처 → 자동화 → 심층 테스트

### 구성 및 제어
- **유연한 입력**:
  - 파일 기반 URL 목록
  - stdin(다른 도구에서 파이프)
  - HAR 파일 가져오기
  - Postman/Insomnia 컬렉션 가져오기
  - OpenAPI 스펙 가져오기
- **세부 스캐너 제어**:
  - 개별 스캐너 활성화/비활성화
  - 액티브 vs 패시브 모드
  - 액티브 검사용 드라이런
  - 스캐너별 구성
- **네트워크 구성**:
  - HTTP/HTTPS 프록시 지원
  - TLS 인증서 검증 제어
  - 사용자 정의 헤더 및 쿠키
  - 구성 가능한 타임아웃 및 재시도
- **스캔 프로필**:
  - quickscan.sh(빠름, 저영향)
  - deepscan.sh(포괄적, 액티브 검사)
  - inaccessiblescan.sh(더 느린 설정으로 이전에 접근할 수 없었던 대상 재확인)
  - baselinescan.sh(베이스라인 생성)
  - diffscan.sh(베이스라인과 비교)
  - authscan.sh(인증된 스캔)
  - sarifscan.sh(CI/CD 통합)
  - scan-and-report.sh(스캔 실행 + 최신 보고서 경로 출력)
  - split-by-host.sh(호스트별로 대상을 분할하고 선택적으로 스캔 팬아웃)

## 다른 도구와의 비교| Feature | ApiHunter | Nuclei | ZAP | Burp Suite | ffuf |
|---------|-----------|--------|-----|------------|------|
| **언어** | Rust | Go | Java | Java | Go |
| **성능** | ⚡⚡⚡ 비동기, 적응형 동시성 | ⚡⚡ 빠른 병렬 처리 | ⚡ 보통 | ⚡ 보통 | ⚡⚡⚡ 매우 빠름 |
| **API 우선 설계** | ✅ API용으로 설계 | ❌ 일반 웹 | ⚠️ 하이브리드 | ⚠️ 하이브리드 | ❌ 퍼징 중심 |
| **오탐 필터링** | ✅ SPA 탐지, 본문 검증, referer 확인 | ⚠️ 템플릿 의존적 | ⚠️ 오탐 많음 | ✅ 좋음 | N/A |
| **CORS/CSP 분석** | ✅ 심층 정책 파싱 | ⚠️ 기본 템플릿 | ✅ 좋음 | ✅ 좋음 | ❌ |
| **GraphQL 인트로스펙션** | ✅ 스키마 노출 + 민감 필드 점검 | ⚠️ 기본 탐지 | ⚠️ 제한적 | ✅ 확장 프로그램을 통해 | ❌ |
| **OpenAPI/Swagger** | ✅ 보안 스킴 분석 | ❌ | ✅ 가져오기만 지원 | ✅ 가져오기 + 스캔 | ❌ |
| **JWT 분석** | ✅ alg=none, 취약한 시크릿, 만료 | ⚠️ 템플릿을 통해 | ⚠️ 제한적 | ✅ 확장 프로그램을 통해 | ❌ |
| **IDOR/BOLA 탐지** | ✅ 3계층 (비인증/범위/교차 사용자) | ⚠️ 수동 템플릿 | ⚠️ 제한적 | ✅ 수동 테스트 | ❌ |
| **비밀 정보 탐지** | ✅ 컨텍스트 인식 (프론트엔드 vs 백엔드) | ⚠️ 정규식 기반 | ⚠️ 기본 | ⚠️ 기본 | ❌ |
| **능동 점검** | ✅ 옵트인 (IDOR, mass-assignment, OAuth/OIDC, websocket, rate-limit, CVE 템플릿) | ✅ 템플릿 기반 | ✅ 능동 스캔 | ✅ 능동 스캔 | ✅ 퍼징 |
| **WAF 우회** | ✅ UA 회전, 지연, 재시도, 적응형 타이밍 | ⚠️ 기본 | ⚠️ 제한적 | ✅ 좋음 | ⚠️ 기본 |
| **CI/CD 통합** | ✅ NDJSON, SARIF, 종료 코드 | ✅ JSON, SARIF | ⚠️ XML 리포트 | ⚠️ XML/JSON | ✅ JSON |
| **기준선 차이 비교** | ✅ 내장 | ❌ 외부 도구 | ❌ | ❌ | ❌ |
| **인증 흐름** | ✅ JSON 기반 사전 스캔 로그인 | ⚠️ 헤더 주입 | ✅ 세션 관리 | ✅ 세션 관리 | ⚠️ 헤더 주입 |
| **스트리밍 출력** | ✅ 실시간 NDJSON | ❌ 배치 전용 | ❌ | ❌ | ✅ |
| **리소스 사용량** | 🟢 낮음 (Rust) | 🟢 낮음 (Go) | 🟡 높음 (Java) | 🟡 높음 (Java) | 🟢 낮음 (Go) |
| **학습 곡선** | 🟢 간단한 CLI | 🟢 템플릿 문법 | 🟡 GUI 복잡성 | 🔴 가파름 | 🟢 간단함 |
| **확장성** | ✅ Rust 트레이트 시스템 | ✅ YAML 템플릿 | ✅ 애드온 | ✅ 확장 프로그램 | ⚠️ 제한적 |
| **라이선스** | MIT (무료) | MIT (무료) | Apache 2.0 (무료) | 상용 | MIT (무료) |
| **적합한 용도** | CI/CD에서의 API 보안, 회귀 테스트, CORS/GraphQL/JWT 분석 | 일반 취약점 스캔, CVE 탐지 | 전체 웹 애플리케이션 침투 테스트 | 수동 침투 테스트, 복잡한 워크플로 | 디렉터리/파라미터 퍼징 |

### 주요 차별점

**ApiHunter:** API 우선 설계, SPA 탐지, 기준선 차이 비교, 3계층 IDOR/BOLA, 컨텍스트 인식 시크릿, AIMD 동시성, **스텔스/WAF 우회 (UA 회전, 지터, 적응형 타이밍)**, **이중 확장성 (TOML 템플릿 + Rust 모듈)**  
**Nuclei:** 더 넓은 CVE 커버리지, YAML 템플릿 전용, 기본적인 우회  
**ZAP/Burp:** 수동 테스트, 프록시 워크플로, GUI 기반 확장, 제한된 스텔스  
**ffuf:** 순수 퍼징, 콘텐츠 발견, 제한된 확장성, 기본적인 우회

## 빠른 시작```bash
cargo build --release

# Scan URLs from a file (newline-delimited)
./target/release/apihunter --urls ./targets/cve-regression-real-public.txt --format ndjson --output ./results.ndjson

# Or scan URLs from stdin
cat ./targets/cve-regression-real-public.txt | ./target/release/apihunter --stdin --min-severity medium

데스크톱 스캔 입력은 다음을 지원합니다:
- 수동 다중 대상 입력(줄당 하나의 URL 또는 쉼표로 구분)
- `Load CSV`를 통한 CSV 가져오기(최대 307,200바이트 / 300KiB)
- 안내 스캔 사전 설정: `Quick Passive` 및 `Deep Active`
- 하드 제한: 실행당 최대 3,000개 대상(중복 제거 및 절대 `http/https` URL로 검증됨)
- 범위 제어: 검색 켜기/끄기, 접근성 필터링 + 시간 제한, 사이트당 최대 엔드포인트 수
- API 버전 관리 제어: 선택적 심층 응답 차이 탐지 토글
- 고급 제어: 프록시, 헤더, 쿠키, Bearer/기본 인증, TLS 잘못된 인증서 허용 토글
- 활성 검사를 위한 블라인드 SSRF 콜백 상관관계 입력(`OAST callback base`)
- 성능 제어: 호스트별 클라이언트, 적응형 동시성, 사용자 지정 user-agent 풀을 사용한 WAF 우회
- `API Versioning` 및 `gRPC/Protobuf`를 포함한 전체 스캐너 토글 범위
- 오른쪽 정렬 캐럿이 있는 접을 수 있는 스캔 섹션; `Safety and Scan Behavior`, `Runtime Limits`, `Scanner toggles`는 기본적으로 접혀 있음
- 대상별 완료/탐지 결과 스냅샷이 있는 병렬 실행 진행 카드
- 결과 분석 대시보드: 심각도 히트맵, 최악 대상 카드, 스캔 효율성, 스캐너 적용 범위, 주요 취약 경로, 검사 심각도 분석
- 세션 지속성: 다음 실행 시 마지막 스캔 결과 자동 복원
- Enrich Mode 패널: 탐지 결과 NDJSON 로드, 위협 인텔리전스 강화 실행, 높은 점수의 호스트를 Deep Active 사전 설정으로 Full Scan에 직접 승격
- 내보내기 UX: 크기 라벨 + `Save All Reports` + 실행별 타임스탬프 파일 이름; 내보내기에는 대상별 JSON 번들, NDJSON, SARIF, Insomnia 컬렉션 및 Insomnia Runner 데이터가 포함됩니다.

자세한 사용법은 [HOWTO.md](https://github.com/teycir/apihunter/blob/HEAD/HOWTO.md), Vulhub 기반 CVE 검증 랩은 [docs/lab-setup.md](https://github.com/teycir/apihunter/blob/HEAD/docs/lab-setup.md), 내부 구조는 [docs/](https://github.com/teycir/apihunter/blob/HEAD/docs/)를 참조하세요.

릴리스 데스크톱 바이너리를 원한다면:```bash
cd apps/desktop
npm run tauri build
./src-tauri/target/release/apihunter-desktop

참고: 데스크톱 개발 시작 시 이제 빌드된 프런트엔드 자산을 직접 사용하며 별도의 `localhost:1420` 서버가 필요하지 않습니다.

자세한 사용법은 [HOWTO.md](https://github.com/teycir/apihunter/blob/HEAD/HOWTO.md), Vulhub 기반 CVE 검증 랩은 [docs/lab-setup.md](https://github.com/teycir/apihunter/blob/HEAD/docs/lab-setup.md), 내부 구조는 [docs/](https://github.com/teycir/apihunter/blob/HEAD/docs/)를 참조하세요.

### NDJSON 탐지 결과 예시```json
{
  "url": "https://api.example.com/graphql",
  "check": "graphql/introspection-enabled",
  "title": "GraphQL introspection is enabled",
  "severity": "MEDIUM",
  "detail": "Introspection query returned schema metadata from a public endpoint.",
  "evidence": "POST /graphql -> HTTP 200 with __schema fields in response body",
  "scanner": "graphql",
  "timestamp": "2026-03-19T14:02:11.824Z"
}

**흐름:** CLI args → Config → Runner가 Discovery + Scanners를 조정 → HTTP Client (Auth/WAF 포함) → Reports

## 템플릿 도구

ApiHunter는 **이중 확장성**을 지원합니다: **TOML 템플릿**(코드 없음) 또는 **Rust 모듈**(완전한 제어)를 통해 검사를 추가할 수 있습니다.

### TOML 템플릿 형식
`assets/cve_templates/*.toml`에서 사용자 정의 검사를 생성하세요:```toml
id = "custom-api-check"
name = "Custom API Vulnerability"
severity = "high"

[[requests]]
method = "GET"
path = "/api/vulnerable"

[[requests.matchers]]
type = "status"
values = [200]

[[requests.matchers]]
type = "word"
part = "body"
words = ["sensitive_data", "exposed"]

### 사용자 정의 Rust 스캐너 추가하기
복잡한 로직을 위해 `Scanner` 트레이트를 구현하세요:```rust
#[async_trait]
impl Scanner for MyCustomScanner {
    async fn scan(
        &self,
        url: &str,
        client: &HttpClient,
        config: &Config,
    ) -> (Vec<Finding>, Vec<CapturedError>) {
        // Your custom scanning logic
    }
}

`split-by-host.sh`를 제외한 모든 래퍼 스크립트는 `--stdin` 및 후행 ApiHunter 플래그를 지원합니다.

## 테스트 전략

ApiHunter 테스트는 목적에 따라 분류됩니다:

- **단위 테스트** (`tests/*_scanner.rs`, 파서/설정 테스트): 스캐너 로직 및 엣지 케이스.
- **통합 테스트** (`tests/integration_runner.rs`, 시작/CLI 동작): 오케스트레이션 및 런타임 연결.
- **Fixture 회귀 테스트** (`tests/cve_templates_real_data.rs`, `tests/cve_templates_upstream_parity.rs`): 실제 페이로드를 재생하고 고정된 업스트림 템플릿과 비교합니다.
- **Mock-server 테스트** (여러 스캐너 스위트): 인터넷 대상에 의존하지 않고 결정적 동작 검사를 수행합니다.
- **Live-target 검사**: 선택 사항/수동으로만 수행 (기본 `cargo test`에는 포함되지 않음).

전체 테스트 매트릭스와 커버리지 맵은 전용 [Testing Guide](https://github.com/teycir/apihunter/blob/HEAD/docs/testing.md)를 참조하세요.

포커스된 스위트 실행:```bash
cargo test --test cors_scanner
cargo test --test graphql_scanner
cargo test --test cve_templates_runtime_ext
cargo test --test integration_runner

실제 데이터 통합 게이트 실행(픽스처 + 라이브 무시 스위트):```bash
# Fixture-backed real payload regression suites
cargo test --test cve_templates_real_data --test cve_templates_upstream_parity --test cve_templates_runtime_ext

# Manual live internet integration suites (ignored by default)
cargo test --test live_vulnerable_apis --test live_real_world_targets -- --ignored

### 사전 빌드된 릴리스 아티팩트

태그된 릴리스(`v*`)는 다음 플랫폼용으로 사전 빌드된 `apihunter` 바이너리를 게시합니다:

- Linux (`x86_64-unknown-linux-gnu`, `aarch64-unknown-linux-gnu`)
- macOS (`x86_64-apple-darwin`)
- Windows (`x86_64-pc-windows-msvc`)

각 릴리스는 또한 공급망 아티팩트를 게시합니다:

- SHA256 체크섬 파일 (`*.sha256`)
- Sigstore 키리스 서명 자료 (`*.sig`, `*.pem`, `*.sigstore.json`)
- SPDX JSON SBOM (`apihunter-release-assets-sbom.spdx.json`)
- GitHub 아티팩트 증명 (provenance 및 SBOM 증명 메타데이터)

[GitHub Releases](https://github.com/Teycir/ApiHunter/releases)에서 다운로드하세요.

### 데스크톱 설치 (Tauri + React)

데스크톱 앱 소스는 `apps/desktop`에 있습니다.

프로덕션 데스크톱 바이너리를 빌드하고 실행하세요:```bash
cd apps/desktop
npm install
npm run tauri build
./src-tauri/target/release/apihunter-desktop

클릭 가능한 Linux 런처 아이콘을 설치합니다:```bash
cd apps/desktop
npm run desktop:install-icon

현재 디렉터리의 파일에서 스캔을 실행하십시오:```bash
docker run --rm -v "$PWD:/work" apihunter:local \
  --urls /work/targets/cve-regression-real-public.txt \
  --format ndjson \
  --output /work/results.ndjson

**Q: 기준선 diffing?**```bash
./target/release/apihunter --urls targets/cve-regression-real-public.txt --format ndjson --output baseline.ndjson
./target/release/apihunter --urls targets/cve-regression-real-public.txt --baseline baseline.ndjson --format ndjson