**작동 방식:**

1. **Claude Code**가 `CLAUDE.md`를 읽어 전체 침투 테스트 방법론을 파악하고 7단계 워크플로우를 조율합니다.
2. **역할 특화 하위 에이전트**(Scout, Analyzer, Exploiter, Reporter)는 전용 프롬프트 템플릿, 도구 가이드 및 안티패턴을 사용하여 집중된 작업을 수행합니다.
3. **WSTG MCP 서버**(68개 이상의 도구)는 OWASP 테스트 절차, 31개의 PortSwigger 기술 가이드, 계층형 작업 트리, 지식 그래프, WAF 우회, 엔드포인트 우선순위 지정, 결과 검증, 컨텍스트 압축, 품질 게이트 및 보고서 생성을 제공합니다.
4. **Docker 컨테이너**는 27개의 보안 도구를 모두 실행합니다. 트래픽은 선택적으로 Burp Suite를 통해 라우팅되어 수동 모니터링이 가능합니다.
5. **Playwright MCP**는 브라우저 기반 테스트(DOM XSS, 클릭재킹, JS 렌더링 로그인 페이지)를 처리합니다.

---

## 기능

### 포괄적인 OWASP 적용 범위
- 12개 카테고리에 걸친 **109개의 WSTG 테스트 케이스** — 정보 수집부터 API 테스트까지
- 각 테스트에는 단계별 CLI 절차, 컨텍스트별 페이로드, 탐지 기준 및 심각도 평가 기준이 포함됩니다.
- 테스트는 우선순위가 지정되어(MUST/SHOULD) 조건부 트리거와 함께 제공되므로 관련 항목이 누락되지 않습니다.

### 31개의 PortSwigger 공격 기술 가이드
- [PortSwigger Web Security Academy](https://portswigger.net/web-security)에서 제공 — 탐지 방법, 익스플로잇 기술, 페이로드, 치트 시트 및 WAF 우회 패턴
- 취약점 클래스별(SQLi, XSS, SSRF, JWT, OAuth 등)로 구성되어 테스트 중 직접 사용 가능
- 모든 테스트 단계에 통합됨 — 에이전트는 각 취약점 클래스를 테스트하기 전에 관련 기술 가이드를 자동으로 로드합니다.
- 데이터베이스/플랫폼별 페이로드 테이블(SQLi의 경우 Oracle vs MySQL vs PostgreSQL vs MSSQL, SSTI의 경우 Jinja2 vs Twig vs Freemarker 등)
- 우회 수준(기본 → 중급 → 고급)별로 구성된 WAF 우회 패턴

### 27개의 사전 구성된 보안 도구
- 모든 도구는 단일 Docker 이미지에 사전 설치됨 — `make setup`만으로 준비 완료
- 단계별로 구성된 도구: 검색, 인젝션 테스트, 인증, 암호화, API 테스트
- 수동 트래픽 모니터링을 위한 자동 Burp Suite 프록시 통합

### 구조화된 7단계 워크플로우
- **0단계:** 애플리케이션 검색 및 매핑
- **1단계:** 정보 수집 및 정찰
- **2단계:** 구성 및 배포 테스트
- **3단계:** ID, 인증, 권한 부여 및 세션 관리
- **4단계:** 입력 유효성 검사 테스트(파이프라인화된 XSS/SQLi/SSRF 파이프라인)
- **5단계:** 오류 처리, 암호화, 비즈니스 로직, 클라이언트 측 및 API 테스트
- **6단계:** 적용 범위 확인 및 보고
- **7단계:** 최종 심사자 검토 및 수정

### 품질 보증 시스템
- **자동화된 단계 게이트** — 각 단계는 진행 전 품질 검사를 통과해야 함
- 모든 단계 전환 시 **품질 검토자** 하위 에이전트가 격차를 식별하고 개선 사항을 제안
- **최종 심사자** — 외부 QA 검토자처럼 콜드 스타트로 전체 작업을 검토하는 제로 컨텍스트 에이전트
- **소진 게이트** — "취약하지 않음"을 주장하려면 충분한 테스트 노력(최소 기술 및 우회 시도)에 대한 증거가 필요

### 증거 기반 발견 사항
- 모든 발견 사항은 재현 가능한 curl 명령어와 전체 요청/응답 증거를 요구
- **3단계 분류:** EXPLOITED(입증된 영향), POTENTIAL(제어로 차단됨), FALSE_POSITIVE(제어 유지)
- **환각 방지 프레임워크** — 모든 수준에서 "익스플로잇 없음 = 발견 없음" 적용
- 발견 사항이 기록되기 전에 취약점 클래스별 증거 체크리스트 확인

### 역할 특화 하위 에이전트
- 집중된 프롬프트 템플릿, 도구 가이드 및 안티패턴을 갖춘 **4개의 전담 역할**:
  - **Scout** — 정찰 전용, 페이로드를 보내지 않고 공격 표면 매핑(0-1단계)
  - **Analyzer** — 카나리/증인 페이로드로 잠재적 싱크 식별, 익스플로잇 큐 구축(2-5단계 분석)
  - **Exploiter** — Analyzer 출력 소비, 증거로 익스플로잇 입증, 확인된 발견 사항 기록(4단계 익스플로잇)
  - **Reporter** — 품질 검토 및 최종 심사자, 요청을 보내지 않고 데이터 검토(QA + 사후 보고)
- 분석과 익스플로잇 사이의 검증 체크포인트로 불필요한 작업 방지
- 각 역할은 명시적으로 허용/제한된 도구 목록과 입력/출력 계약을 가짐

### 파이프라인화된 익스플로잇 (4단계)
- 3개의 독립적인 **2단계 파이프라인**이 병렬로 실행: XSS, 인젝션(SQLi/CMDi), SSRF/SSTI
- 각 파이프라인: Analyzer(발견 → 분석 → 큐) → 검증 체크포인트 → Exploiter(익스플로잇 → 기록)
- 각 파이프라인은 탐지 방법, 치트 시트 및 WAF 우회 패턴을 위해 PortSwigger 기술 가이드를 로드합니다.
- WAF 정보는 모든 파이프라인에서 공유됩니다.
- 13가지 싱크 유형에 대한 컨텍스트 인식 증인 페이로드

### 적응형 WAF 우회
- 응답 헤더, 본문 및 상태 코드를 통한 **자동 WAF 핑거프린팅** — 12개 WAF 벤더 식별(Cloudflare, AWS WAF, Akamai, Imperva, ModSecurity, F5, FortiWeb, Sucuri, Barracuda, Wordfence, NAXSI, Citrix)
- 복잡성 수준(기본 → 중급 → 고급)별로 구성된 **벤더별 우회 페이로드**
- 전달 가능 시스템을 통해 모든 에이전트가 WAF 정보 공유
- 에이전트는 첫 번째 차단 응답 시 WAF를 자동으로 식별하고 맞춤형 우회 페이로드로 전환

### 단계 간 지식 그래프
- **엔터티-관계 그래프**는 엔드포인트, 매개변수, 기술, 발견 사항, 쿠키, 도메인 및 사용자 역할을 추적합니다.
- BFS 경로 찾기를 통한 **자동화된 취약점 체이닝** 및 7개의 사전 정의된 체인 패턴:
  - XSS + CSP 누락, XSS + 약한 쿠키(HttpOnly 없음), 오픈 리다이렉트 + OAuth 콜백
  - IDOR + 관리자 역할, SSRF + 클라우드 메타데이터, 잠금 없음 + MFA 없음, CORS + 민감한 엔드포인트
- 체이닝이 실질적으로 영향을 증가시킬 때 심각도 업그레이드
- 테스트 전반에 걸쳐 채워지고, 체인 발견을 위해 4단계 후에 쿼리됨

### 계층형 작업 트리
- 지속적인 트리 구조(단계 = 가지, 테스트 = 잎)는 LLM의 깊이 우선 편향과 컨텍스트 손실을 방지
- 메인 에이전트는 전략적 매크로 뷰를 유지하고, 하위 에이전트는 할당된 잎 노드만 업데이트
- 자동 전파: 모든 자식이 완료되면 부모가 자동 완료
- 정보에 기반한 의사 결정을 위한 단계별 완료 백분율

### 엔드포인트 위험 우선순위 지정
- 우선 테스트를 위해 위험도에 따라 엔드포인트 점수 및 정렬 — 가장 높은 위험부터 테스트
- 점수 요소: 매개변수 수, 기술 위험 지표, 오염 체인 신뢰도, 도구 수렴, 인증 요구 사항, 인젝션 가능한 매개변수 이름
- 0단계 엔드포인트 맵 생성에 통합

### 도구 출력 파싱
- 일반 CLI 도구(nmap, nuclei, sqlmap, ffuf, httpx, whatweb, testssl, nikto, dalfox, katana, gau, wapiti, commix)를 위한 **13개의 내장 파서**
- 주요 발견 사항, 엔드포인트 및 오류를 유지하면서 원시 도구 출력을 3-5배 압축
- 구성 가능한 상세 수준: 요약(~15줄), 상세(~50줄), 전체(완전 파싱된 출력)

### CLI 도구 결과 검증
- CLI 도구 출력 품질 자동 검증 — 빈 출력, 프록시 오류, 권한 문제 및 의심스러운 결과 감지
- 수정된 명령 제안과 함께 **도구당 10개의 검증기**(nmap, nuclei, sqlmap, ffuf, feroxbuster, testssl, dalfox, wapiti, katana, httpx)
- 도구가 빈 출력이나 의심스러운 출력을 생성하면 검증기가 수정 사항을 제안합니다(예: nmap에 `-Pn` 추가, 프록시 환경 변수 제거, 다른 플래그 시도)
- 도구 실행 워크플로우에 통합 — 에이전트는 모든 CLI 도구 실행 후 `verify_tool_result()`를 호출

### 점진적 컨텍스트 압축
- **단계 요약**(~500-800 단어)은 단계 게이트 통과 시 자동 생성 — 발견 사항, 적용 범위, 도구 결과 및 공격 표면을 압축된 형태로 캡처
- 장기 실행 작업에서 원시 기록 데이터를 구조화된 요약으로 대체하여 컨텍스트 저하 방지
- `get_engagement_summary()`는 모든 단계 요약을 하나의 개요로 결합하여 새 하위 에이전트 프롬프트에 주입
- 요약은 전달 가능 항목으로 저장 — 전체 작업 기록 없이 다운스트림 에이전트가 액세스 가능

### 반사실 분석 (2차 발견)
- Analyzer가 취약점을 발견하여 완료된 후, "해당 취약점이 패치되었다고 가정"하라는 지침과 함께 **두 번째 Analyzer**가 생성됨
- 반사실 Analyzer는 **추가** 취약점을 검색: 다른 엔드포인트, 다른 매개변수, 다른 인젝션 컨텍스트, 로직 결함
- 결과는 기존 익스플로잇 큐에 추가됨(엔드포인트+매개변수별 중복 제거 및 자동 증가 ID로 자동 병합)
- 반사실 프롬프팅이 취약점 적용 범위를 +71% 증가시킨 PenHeal 제거 연구 기반

### 다중 도메인 지원
- 자동 SSO/OAuth/OIDC/SAML 감지 및 처리
- 도메인별 범위 등록, 크롤링 및 테스트
- 교차 도메인 세션 지속성을 위한 쿠키 저장소 관리
- 6단계 인증 실패 에스컬레이션(대체 승인 → PKCE → 헤드리스 브라우저 → 토큰 추출 → 사용자 프로비저닝 → 인증되지 않음)

### 충돌 방지 작업 관리
- 추가 전용 `findings.md` 및 `progress.log`는 충돌에도 유지
- 롤백 기능이 있는 Git 작업 공간 체크포인트
- **중단 시 자동 재개** — 모든 체크포인트에서 `resume-prompt.md`가 전체 컨텍스트(대상, 자격 증명, 현재 단계, 남은 테스트, 범위)와 함께 자동 생성됩니다. 새 세션에 붙여넣어 중단한 지점에서 계속 진행
- 단계 중간 체크포인트 세분성 — 단계 수준 상태뿐만 아니라 단계 내에서 완료된 테스트를 추적
- 타임스탬프가 있는 모든 MCP 도구 호출에 대한 전체 감사 추적

### 전문 보고
- 경영진 요약, 심각도별 발견 사항, 테스트 적용 범위 매트릭스 및 도구 적용 범위가 포함된 마크다운 보고서
- 카테고리별 적용 범위 백분율 및 격차 분석
- 취약점 체이닝 분석 문서화
- 최종 심사자 관찰 및 품질 노트 포함

---

## 에이전트 역할 시스템

AutoPentest는 일반 하위 에이전트 대신 4개의 특화된 에이전트 역할을 사용합니다. 각 역할은 집중된 도구 가이드, 입력/출력 계약 및 안티패턴이 포함된 전용 프롬프트 템플릿을 가지고 있습니다.

| 역할 | 템플릿 | 목적 | 단계 |
|------|----------|---------|--------|
| **Scout** | `templates/agent-roles/scout.md` | 정찰 및 공격 표면 매핑 | 0-1단계, 소스 코드 발견 |
| **Analyzer** | `templates/agent-roles/analyzer.md` | 카나리/증인 페이로드를 사용한 취약점 발견 | 2-5단계 분석 |
| **Exploiter** | `templates/agent-roles/exploiter.md` | 증거를 통한 익스플로잇 증명 | 4단계 익스플로잇 |
| **Reporter** | `templates/agent-roles/reporter.md` | 품질 검토 및 최종 심사자 | 단계 전환, 사후 보고 |

### 파이프라인 작동 방식

4단계(가장 영향력이 큰 테스트)는 취약점 클래스별로 2단계 파이프라인을 사용합니다:```
┌──────────────────────────────────────────────────────────────┐
│                    Pipeline 1: XSS                           │
│                                                              │
│  Analyzer (75 turns)          Exploiter (75 turns)           │
│  ┌─────────────────────┐      ┌─────────────────────┐        │
│  │ Discover endpoints  │      │ Load Analyzer queue │        │
│  │ Send canary payloads│─────▶│ Attempt exploitation│        │
│  │ Build exploit queue │ gate │ Prove impact        │        │
│  │ Save deliverable    │      │ Log findings        │        │
│  └─────────────────────┘      └─────────────────────┘        │
│                          ▲                                   │
│               validate_exploitation_queue()                  │
└──────────────────────────────────────────────────────────────┘

이것으로 끝입니다. 이제 27개의 모든 보안 도구가 Docker 컨테이너 내에 설치되어 준비되었습니다.

### 설치 확인```bash
# Check all tools are installed
make verify-tools

# Expected output:
# [+] nuclei: installed
# [+] httpx: installed
# [+] katana: installed
# ... (27 tools total)

그런 다음 Claude에게 테스트할 내용을 알려주세요:```
Run a full WSTG assessment against https://target.example.com

Claude는 누락된 정보(예: 자격 증명)를 요청하고 7단계 워크플로를 시작합니다.

### 옵션 B: 구성 기반 모드 (권장)

반복적이고 일관된 평가를 위해 YAML 구성 파일을 생성하세요:```yaml
# configs/my-target.yaml
target:
  url: https://app.example.com
  scope:
    - app.example.com
    - api.example.com
  exclude:
    - cdn.example.com

authentication:
  login_type: form
  login_url: https://app.example.com/login
  credentials:
    username: [email protected]
    password: secret123
  login_flow:
    - "Type $username into the email field"
    - "Type $password into the password field"
    - "Click the 'Sign In' button"
  success_condition:
    type: url_contains
    value: "/dashboard"

rules:
  avoid:
    - description: "Do not test logout"
      type: path
      url_path: "/logout"
  focus:
    - description: "Prioritize API endpoints"
      type: path
      url_path: "/api"

reporting:
  tester_name: "Security Team"

### 옵션 C: 대상 테스트

특정 WSTG 테스트를 특정 엔드포인트에 대해 실행합니다:```
Run WSTG-INPV-05 (SQL Injection) against https://app.example.com/search?q=

Please provide the Markdown content to translate.```
Run all authentication tests (WSTG-ATHN) against https://app.example.com

---

## 테스트 단계

### 단계 0: 애플리케이션 발견 및 매핑

중요한 기반 단계. Claude가 자율적으로 수행:

1. **사전 점검** — 대상 접근 가능성 확인, 리디렉트 및 크로스도메인 인증 감지
2. **10개 이상의 백그라운드 도구 동시 실행** (katana, ffuf, nuclei, whatweb, gau, nmap, feroxbuster, wapiti, httpx)
3. **재귀적 크롤링** — 링크를 깊이 2~3까지 따라가며 HTML/JS에서 엔드포인트 파싱
4. **디렉터리 무차별 대입** — 일반 경로 + 기술별 워드리스트
5. **도구 결과 수집** — 모든 백그라운드 도구 출력을 읽고 통합 엔드포인트 맵으로 병합
6. **구조화된 엔드포인트 인벤토리 구축** — 매개변수, 인증 요구 사항, 우선순위 등급 포함

**출력:** 도메인별로 정리된 완전한 엔드포인트 맵, 체계적인 테스트 준비 완료.

### 단계 1-2: 정찰 및 구성

- 서버 지문 채취, 기술 탐지, 메타데이터 검토
- 보안 헤더 분석 (HSTS, CSP, CORS, X-Frame-Options)
- TLS 구성 테스트, 관리자 인터페이스 발견
- HTTP 메서드 테스트, 파일 확장자 처리

### 단계 3: 인증, 권한 부여 및 세션 관리

- **역할/권한 체계** 테스트 전에 구축 (가드, 미들웨어, 우회 테스트 매핑)
- 엔드포인트당 여러 대체 ID를 사용한 IDOR 테스트
- 모든 상태 변경 엔드포인트에서 CSRF 테스트
- 세션 고정, 하이재킹 및 토큰 분석
- JWT 취약점 테스트 (해당 시)
- OAuth/OIDC 취약점 테스트 (해당 시)

### 단계 4: 입력 검증 (가장 높은 영향)

세 개의 독립적인 2단계 파이프라인이 병렬로 실행되며, 각각 Analyzer→Exploiter 역할 분할을 사용:

| 파이프라인 | 취약점 클래스 | 도구 | 기술 가이드 |
|-----------|-------------|------|-----------|
| XSS 파이프라인 | 반사형 XSS, 저장형 XSS, DOM XSS | dalfox, Playwright | XSS, DOM |
| 인젝션 파이프라인 | SQL 인젝션, 명령어 인젝션, NoSQL 인젝션 | sqlmap, commix, nosqli | SQLI, CMDI, NOSQLI |
| SSRF/SSTI 파이프라인 | SSRF, SSTI, 경로 순회 | sstimap, ssrfmap | SSRF, SSTI, PTRAV |

각 파이프라인: **Analyzer** (발견 → 분석 → 익스플로잇 큐 구축) → 검증 체크포인트 → **Exploiter** (익스플로잇 시도 → 영향 증명 → 결과 기록). WAF 우회 인텔리전스는 모든 파이프라인 간에 공유됩니다.

### 단계 5: 오류 처리, 암호화, 비즈니스 로직, 클라이언트 측 및 API

- 스택 트레이스 및 오류 메시지 노출
- testssl.sh를 통한 TLS/SSL 테스트
- 비즈니스 로직 우회 (워크플로우 우회, 요청 위조)
- 클라이언트 측 테스트 (클릭재킹, 오픈 리디렉트, DOM 조작)
- GraphQL 및 REST API 테스트
- 모든 발견 사항에 걸친 취약점 체이닝 분석

### 단계 6: 보고

- 커버리지 검증 (테스트 커버리지 + 도구 커버리지)
- 발견 사항 중복 제거 및 심각도 보정
- Markdown 보고서 생성 (경영진 요약, 발견 사항, 커버리지 매트릭스 포함)

### 단계 7: 최종 심판 검토

컨텍스트가 없는 에이전트가 전체 엔게이지먼트를 냉정하게 검토 — 테스트 결정이나 어려움에 대한 사전 정보 없음. 다음과 같은 사항을 조사합니다:

- **커버리지 무결성** — 형식적인 테스트, 누락된 엔드포인트
- **N/A 연쇄 감지** — "해당 없음" 표시가 과도하게 많은 카테고리
- **발견 사항 품질** — 증거 완전성, 심각도 일관성, 체이닝 기회
- **도구 활용** — 실행했지만 출력을 검토하지 않은 도구, 게으른 건너뛰기 사유
- **누락된 공격 표면** — 테스트되지 않은 엔드포인트, 매개변수, 도메인

평결 (PASS/CONDITIONAL_PASS/FAIL)은 보고서 전달 전에 특정 수정 조치를 트리거합니다.

---

## 보안 도구

### 발견 및 정찰 (단계 0)

| 도구 | 목적 | 주요 플래그 |
|------|------|-----------|
| **katana** | JS 렌더링 웹 크롤러 | `-jc` JavaScript 크롤링 |
| **httpx** | HTTP 프로빙, 기술 탐지 | `-tech-detect -status-code -title` |
| **ffuf** | 디렉터리/매개변수 퍼징 | `-w wordlist -mc all -fc 404` |
| **feroxbuster** | 재귀적 디렉터리 열거 | `--smart --auto-tune` |
| **nuclei** | 템플릿 기반 취약점 스캐너 | `-t cves/ -t misconfigurations/` |
| **nikto** | 웹 서버 잘못된 구성 | `-Tuning 1234567890` |
| **whatweb** | 기술 지문 채취 | `--aggression 3` |
| **nmap** | 포트 및 서비스 스캔 | `-sV -sC --top-ports 1000` |
| **gau** | 과거 URL 발견 | `--blacklist png,jpg,gif` |
| **subfinder** | 서브도메인 열거 | `-silent -all` |

### 인젝션 테스트 (단계 4)

| 도구 | 목적 | 주요 플래그 |
|------|------|-----------|
| **sqlmap** | SQL 인젝션 (모든 기법) | `--batch --risk 3 --level 5` |
| **dalfox** | XSS 스캔 및 익스플로잇 | `--skip-bav --deep-domxss` |
| **commix** | 명령어 인젝션 | `--batch --all` |
| **sstimap** | 서버 사이드 템플릿 인젝션 | `-u <url>` |
| **ssrfmap** | SSRF 익스플로잇 | `-r request.txt` |
| **nosqli** | NoSQL 인젝션 | `-u <url>` |
| **crlfuzz** | CRLF 인젝션 / HTTP 분할 | `-u <url>` |
| **smuggler** | HTTP 요청 스머글링 | `-u <url>` |

### 인증 및 세션 (단계 3)

| 도구 | 목적 | 주요 플래그 |
|------|------|-----------|
| **hydra** | 자격 증명 무차별 대입 | `-L users.txt -P pass.txt` |
| **jwt_tool** | JWT 토큰 분석 및 익스플로잇 | `-t <token> -M at` |

### 암호화 및 API (단계 5)

| 도구 | 목적 | 주요 플래그 |
|------|------|-----------|
| **testssl.sh** | TLS/SSL 구성 테스트 | `--severity HIGH --sneaky` |
| **graphql-cop** | GraphQL 보안 테스트 | `-t <url>` |
| **websocat** | WebSocket 테스트 | `ws://<url>` |

### 인프라 (단계 2)

| 도구 | 목적 |
|------|------|
| **corscanner** | CORS 잘못된 구성 스캔 |
| **dnsreaper** | 서브도메인 탈취 감지 |

### 브라우저 자동화

| 도구 | 목적 |
|------|------|
| **Playwright** | DOM XSS 증명, 클릭재킹, JS 렌더링 로그인, 클라이언트 측 저장소 검사 |

---

## WSTG 지식 기반

12개의 OWASP 카테고리에 걸쳐 109개의 테스트 케이스, 각각 CLI 관련 절차 포함:

| 코드 | 카테고리 | 테스트 수 | 예시 |
|------|---------|:--------:|------|
| **INFO** | 정보 수집 | 10 | 검색 엔진 발견, 서버 지문 채취, 메타데이터 검토 |
| **CONF** | 구성 및 배포 | 14 | 보안 헤더, CORS, CSP, HSTS, 관리자 인터페이스 |
| **IDNT** | 신원 관리 | 5 | 역할 정의, 등록, 계정 열거 |
| **ATHN** | 인증 | 11 | 기본 자격 증명, 잠금, 인증 우회, MFA, 비밀번호 정책 |
| **ATHZ** | 권한 부여 | 5 | 디렉터리 순회, 인증 우회, 권한 상승, IDOR |
| **SESS** | 세션 관리 | 11 | 쿠키 속성, CSRF, 세션 고정/하이재킹, JWT |
| **INPV** | 입력 검증 | 20 | XSS, SQLi, CMDi, SSTI, SSRF, 경로 순회, XXE, LDAP |
| **ERRH** | 오류 처리 | 2 | 오류 메시지, 스택 트레이스 |
| **CRYP** | 암호화 | 4 | TLS 구성, 패딩 오라클, 약한 암호화 |
| **BUSL** | 비즈니스 로직 | 10 | 워크플로우 우회, 요청 위조, 파일 업로드, 속도 제한 |
| **CLNT** | 클라이언트 측 | 14 | DOM XSS, 클릭재킹, 오픈 리디렉트, WebSocket, 저장소 |
| **APIT** | API 테스트 | 3 | GraphQL, REST, SOAP |

각 테스트 파일 포함:
- 단계별 CLI 절차 (curl 명령, 도구 호출)
- 우회 수준별 페이로드 (기본, 중급, 고급)
- 심각도 평가 루브릭이 포함된 탐지 기준
- 참조가 포함된 수정 지침

---

## PortSwigger 기술 가이드

[PortSwigger Web Security Academy](https://portswigger.net/web-security)에서 가져온 31개의 공격 기술 참조 가이드, 취약점 클래스별로 구성되어 실제 침투 테스트 엔게이지먼트 중 직접 사용 가능.

### 포함 내용

| 코드 | 카테고리 | WSTG 매핑 | 주요 내용 |
|------|---------|-----------|----------|
| **SQLI** | SQL 인젝션 | INPV-05 | UNION/블라인드/에러/시간 기반/OOB 기법, 데이터베이스별 치트 시트 (Oracle, MySQL, PostgreSQL, MSSQL), WAF 우회 |
| **XSS** | 크로스 사이트 스크립팅 | INPV-01, INPV-02, CLNT-01 | 반사형/저장형/DOM 컨텍스트, 태그 및 이벤트 핸들러 페이로드, CSP 우회, 필터 회피 |
| **CMDI** | OS 명령어 인젝션 | INPV-12 | 구분 문자, 블라인드 기법 (시간 지연, OOB), OS별 페이로드 |
| **SSTI** | 서버 사이드 템플릿 인젝션 | INPV-18 | Jinja2/Twig/Freemarker/Velocity/ERB 탐지 및 익스플로잇, 샌드박스 이스케이프 |
| **SSRF** | 서버 사이드 요청 위조 | INPV-19 | URL 스킴 트릭, IP 난독화, DNS 리바인딩, 클라우드 메타데이터, 필터 우회 |
| **PTRAV** | 경로 순회 | INPV-04 | 인코딩 변형, 널 바이트 인젝션, 래퍼 우회 |
| **XXE** | XML 외부 엔티티 | INPV-07 | 파일 검색, XXE를 통한 SSRF, OOB를 통한 블라인드 XXE, 파라미터 엔티티 |
| **AUTHN** | 인증 | ATHN-01 ~ ATHN-07 | 무차별 대입, 2FA 우회, 비밀번호 재설정 중독, 자격 증명 스터핑 |
| **AUTHZ** | 접근 제어 | ATHZ-01 ~ ATHZ-04 | IDOR, 권한 상승, 수평/수직 우회, 리퍼러 기반 제어 |
| **JWT** | JSON 웹 토큰 | SESS-10 | 알고리즘 혼동 (none/HS256→RS256), kid 인젝션, JWK/JKU 익스플로잇 |
| **OAUTH** | OAuth 2.0 | ATHZ-05 | 인증 코드 탈취, 오픈 리디렉트, 범위 업그레이드, OAuth 흐름의 CSRF |
| **CSRF** | 크로스 사이트 요청 위조 | SESS-05 | 토큰 우회, SameSite 우회, 리퍼러 검증 우회 |
| **SMUGGLE** | HTTP 요청 스머글링 | INPV-15 | CL.TE, TE.CL, TE.TE, HTTP/2 다운그레이드, 요청 터널링 |
| **DOM** | DOM 기반 취약점 | CLNT-01 | 소스/싱크, DOM 클로버링, 프로토타입 폴루션 가젯 |
| **CORS** | 교차 출처 리소스 공유 | CONF-13, CLNT-07 | 출처 반영, null 출처, 서브도메인 신뢰 익스플로잇 |
| **NOSQLI** | NoSQL 인젝션 | INPV-05 | MongoDB 연산자 인젝션, JavaScript 인젝션, 블라인드 추출 |
| **GRAPHQL** | GraphQL | APIT-01 | 인트로스펙션, 필드 제안, 배칭 공격, 인증 우회 |
| **RACE** | 경쟁 조건 | BUSL-04 | 한도 초과, TOCTOU, 단일 엔드포인트 경쟁, 마지막 프레임 동기화 |
| **UPLOAD** | 파일 업로드 | BUSL-08, BUSL-09 | 확장자 우회, 콘텐츠 타입 조작, 웹 셸, 폴리글롯 파일 |
| **HOST** | 호스트 헤더 인젝션 | INPV-17 | 비밀번호 재설정 중독, 캐시 중독, 라우팅 기반 SSRF |

추가 11개: CLICK, WS, CACHEPOIS, CACHEDEC, DESER, INFO, BUSL, PROTO, API, LLM, SKILLS.

### 사용 방법

기술 가이드는 `get_technique_guide()` MCP 도구를 통해 모든 테스트 단계에 통합됩니다:```
Phase 2 → CORS guide for CONF-13 testing
Phase 3 → AUTHN, AUTHZ, CSRF, JWT, OAUTH guides for auth/session testing
Phase 4 → SQLI, XSS, CMDI, SSTI, SSRF, PTRAV, XXE guides for input validation
Phase 5 → DOM, CLICK, GRAPHQL, RACE, UPLOAD guides for client-side & business logic

솔버에는 두 가지 모드가 있습니다:
- **autopentest** (기본값): 프로젝트 루트에서 Claude Code를 실행하며, `.mcp.json`(68개 이상의 도구를 갖춘 MCP 서버)과 `CLAUDE.md`(침투 테스트 방법론)를 로드합니다. AutoPentest의 전체 기능을 측정합니다.
- **raw** (`RAW=1`): MCP 서버나 방법론 없이 기본 Claude Code를 실행합니다. 원시 LLM 기능 대비 AutoPentest의 부가 가치를 측정하기 위한 기준선입니다.

각 챌린지는 빌드 시 플래그가 삽입된 Docker Compose 앱입니다. Claude의 출력에서 플래그를 추출하여 통과/실패를 결정합니다. 결과는 챌린지별, 태그별, 난이도별로 점수가 매겨집니다.

### CTF 모드

CTF 챌린지 및 소규모 앱의 경우, 품질 게이트를 완화하는 CTF 모드를 활성화하세요:```yaml
mode: ctf
target:
  url: https://target.com

### 샘플 발견 (SQL Injection)

보고서에서 — 완전한 익스플로잇 증거를 포함한 치명적인 SQL Injection 발견:```
FINDING-017: SQL Injection in /catalog category parameter — Full Data Extraction

Severity: Critical
WSTG Reference: WSTG-INPV-05

The category parameter is vulnerable to UNION-based SQL injection.
The attacker can:
  1. Inject a single quote to cause a 500 error (confirming injection)
  2. Use UNION SELECT with 8 columns to extract arbitrary data
  3. Enumerate tables: PRODUCTS, TRACKING, USERS
  4. Extract credentials from the USERS table

Evidence (reproducible curl command):
  curl -sk "https://ginandjuice.shop/catalog?category='+UNION+SELECT+1,USERNAME,PASSWORD,
  1,1,USERNAME,1,USERNAME+FROM+USERS+LIMIT+10--"

### MCP 서버 설정

`.mcp.json` 파일은 두 개의 MCP 서버를 등록합니다.```json
{
  "mcpServers": {
    "wstg-pentest": {
      "command": "uv",
      "args": ["--directory", "./server", "run", "server.py"]
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

모든 도메인은 해당 유형(app, auth_provider, api, cdn)과 함께 자동으로 범위에 등록됩니다.

### 도메인별 테스트

모든 WSTG 테스트는 기본 도메인뿐만 아니라 **모든** 도메인에 대해 평가됩니다:

- 탐지 도구(katana, ffuf, nuclei)는 **모든** 도메인에 대해 실행됩니다
- 입력 검증 도구(sqlmap, dalfox)는 서버 측 처리가 있는 **모든** 도메인의 엔드포인트를 대상으로 합니다
- 테스트가 "해당 없음"인 경우는 **어떤** 도메인도 테스트된 기능을 가지고 있지 않을 때만입니다

### 교차 도메인 인증

지원되는 SSO 프로토콜:
- **OAuth 2.0 / OIDC** (Authorization Code, PKCE, Password Grant, Client Credentials)
- **SAML** (SP-initiated flow)
- **Keycloak**, **Auth0**, **Okta**, **Azure AD**
- **Custom SSO** (리디렉션 체인을 추적하는 쿠키 저장소)

인증 에스컬레이션 절차(6단계)는 복잡한 인증 흐름에서도 테스트를 진행할 수 있도록 보장합니다.

---

## 충돌 복구

AutoPentest는 중단 상황을 견딜 수 있도록 설계되었습니다:

### 자동 체크포인트
- 단계 게이트는 PASS 시 체크포인트를 자동 저장합니다
- `git_checkpoint()`는 침투 작업 공간의 git 스냅샷을 생성합니다
- 추가 전용 로그(`findings.md`, `progress.log`)는 충돌에도 유지됩니다

### resume-prompt.md를 통한 자동 재개 (권장)

모든 체크포인트와 단계 게이트는 자동으로 `engagements/<eid>/resume-prompt.md`를 생성합니다. 이는 새로운 세션에서 필요한 모든 것을 포함한 완전하고 자체 포함된 프롬프트입니다:

- 대상 URL, 인증 자격 증명 및 범위 도메인
- 현재 단계와 남아 있는 특정 테스트 (단계 중간 정밀도)
- 쿠키 저장소 상태 및 재인증 지침
- 회피/집중 규칙 및 엔드포인트 맵 참조

**중단 후 재개하려면:**
1. 새 Claude Code 세션을 엽니다
2. `engagements/<eid>/resume-prompt.md`의 내용을 붙여넣습니다
3. Claude는 정확히 중단된 지점부터 이어서 진행합니다 — 수동 컨텍스트가 필요하지 않습니다

### 체크포인트에서 재개 (대안)```
Resume engagement pentest-2026-02-11-myapp

### 실패 시 롤백

단계에서 잘못된 결과가 나오면 이전 체크포인트로 롤백하십시오:```
Roll back the engagement to the last checkpoint

---

## 요구 사항

| 요구 사항 | 버전 | 비고 |
|-------------|---------|-------|
| Docker | 20.10+ | macOS/Windows용 Docker Desktop |
| Claude Code | 최신 | `npm install -g @anthropic-ai/claude-code` |
| uv | 0.1+ | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
| Node.js | 18+ | Playwright MCP 서버용 |
| Python | 3.10+ | uv로 관리됨 (수동 설치 불필요) |
| Burp Suite Pro | 최신 | **선택 사항** — 수동 트래픽 모니터링용 |

**지원 플랫폼:** macOS (Apple Silicon 및 Intel), Linux (x86_64 및 ARM64)

---

## FAQ

**Q: 이것이 인간 침투 테스터를 대체합니까?**

아니요. AutoPentest는 침투 테스트의 체계적이고 방법론 기반 부분을 자동화합니다. 이 도구는 범위(놓치는 항목이 없도록 보장)와 일관성(모든 테스트가 동일한 절차를 따름)에서 탁월합니다. 그러나 복잡한 비즈니스 로직, 창의적인 익스플로잇 체인, 상황에 따른 위험 평가는 여전히 인간의 전문성이 필요합니다. 역량 강화 도구로 생각하십시오.

**Q: 전체 평가는 얼마나 걸립니까?**

애플리케이션의 규모와 복잡성에 따라 다릅니다. 일반적인 중간 규모 웹 앱(50-100개 엔드포인트)은 몇 시간이 걸립니다. SSO가 있는 다중 도메인 애플리케이션은 더 오래 걸립니다. 파이프라인 방식의 4단계 아키텍처는 가장 시간이 많이 소요되는 테스트를 병렬화합니다.

**Q: Burp Suite 없이 실행할 수 있습니까?**

예. Burp Suite는 선택 사항이며 수동 트래픽 모니터링에만 사용됩니다. 모든 HTTP 요청은 `docker exec curl`을 통해 전송되고 모든 보안 도구는 Docker 컨테이너 내에서 실행됩니다. Burp 없이도 Burp의 프록시 기록에서 트래픽을 검토하는 기능은 잃게 되지만 모든 테스트 기능은 정상 작동합니다.

**Q: PortSwigger 기술 가이드란 무엇입니까?**

탐지, 익스플로잇 기법, 페이로드, 치트 시트 및 WAF 우회 패턴을 다루는 31개의 공격 참조 가이드입니다. PortSwigger 웹 보안 아카데미에서 제공됩니다. 테스트 중에 에이전트는 관련 가이드를 자동으로 로드합니다(예: SQL 인젝션 테스트 시 SQLi 가이드). 포괄적인 기법 및 페이로드 참조를 제공합니다. 자신만의 가이드를 추가하려면 [`docs/adding-knowledge-base-resources.md`](https://github.com/bhavsec/autopentest-ai/blob/HEAD/docs/adding-knowledge-base-resources.md)를 참조하십시오.

**Q: 맞춤형 워드리스트 또는 페이로드를 어떻게 추가합니까?**

워드리스트를 `templates/wordlists/`에 배치하면 볼륨 마운트를 통해 Docker 컨테이너 내에서 사용할 수 있습니다. `knowledge-base/`의 WSTG 테스트 파일에 추가 페이로드를 사용자 정의할 수도 있습니다. 새로운 공격 기법 가이드를 추가하려면 [`docs/adding-knowledge-base-resources.md`](https://github.com/bhavsec/autopentest-ai/blob/HEAD/docs/adding-knowledge-base-resources.md)의 지침을 따르십시오.

**Q: VPN 뒤에 있는 애플리케이션을 테스트할 수 있습니까?**

예. Docker 컨테이너는 호스트의 네트워크를 상속받거나(Linux에서 `--network host` 사용 시) macOS/Windows에서 `host.docker.internal`을 통해 호스트에 도달합니다. 호스트에서 VPN이 실행 중이면 컨테이너가 VPN으로 보호된 대상에 도달할 수 있습니다.

**Q: 침투 테스트가 중단되면(충돌, 사용량 제한, 시간 초과) 어떻게 됩니까?**

AutoPentest는 모든 체크포인트에서 계속하는 데 필요한 모든 정보가 포함된 `resume-prompt.md` 파일을 자동으로 생성합니다. 새 Claude Code 세션을 열고 `engagements/<eid>/resume-prompt.md`의 내용을 붙여넣으면 테스트가 중단된 지점에서 정확히 재개됩니다(단계 중간 진행 상황, 자격 증명, 범위 및 남은 테스트 포함).

**Q: 속도 제한은 어떻게 처리됩니까?**

AutoPentest는 세 가지 계층의 오류 분류(일시적/속도 제한/영구적)와 자동 백오프를 포함합니다. 대상이 요청 속도를 제한하면 도구가 자동으로 속도를 늦춥니다. 구성에서 특정 엔드포인트를 건너뛰도록 회피 규칙을 설정할 수도 있습니다.

**Q: 에이전트 역할은 무엇입니까?**

AutoPentest는 일반 서브에이전트 대신 4개의 특수 역할(정찰, 분석, 익스플로잇, 보고)을 사용합니다. 각 역할에는 집중된 도구 지침, 제한된 도구 목록 및 안티패턴이 포함된 전용 프롬프트 템플릿이 있습니다. 이는 에이전트가 정찰, 분석, 익스플로잇 및 보고를 혼동하는 것을 방지하여 집중도와 오류 격리를 개선합니다. 전체 역할 인덱스는 [`templates/agent-roles/README.md`](https://github.com/bhavsec/autopentest-ai/blob/HEAD/templates/agent-roles/README.md)를 참조하십시오.

**Q: WAF 우회는 어떻게 작동합니까?**

페이로드가 차단(403, 차단 페이지)되면 AutoPentest는 응답 특성에서 WAF 공급업체를 자동으로 식별한 다음 복잡성 수준별로 구성된 공급업체별 우회 페이로드를 로드합니다. 12개 WAF 공급업체(Cloudflare, AWS WAF, Akamai, Imperva, ModSecurity, F5 등)가 지원됩니다. WAF 인텔리전스는 전달 시스템을 통해 모든 에이전트 간에 공유됩니다.

**Q: 반사실적 분석이란 무엇입니까?**

첫 번째 분석 패스에서 취약점을 발견한 후 AutoPentest는 알려진 모든 취약점이 패치되었다고 가정하는 두 번째 분석가를 생성할 수 있습니다. 이는 에이전트가 다른 엔드포인트, 매개변수, 인젝션 컨텍스트 및 로직 결함과 같은 다른 공격 벡터를 찾도록 강제합니다. 결과는 자동 중복 제거와 함께 기존 익스플로잇 큐에 병합됩니다. 이 기술은 +71% 취약점 범위 개선을 보여주는 학술 연구(PenHeal ablation study)를 기반으로 합니다.

**Q: 결과 검증은 어떻게 작동합니까?**

CLI 도구(nmap, nuclei, sqlmap 등)가 비어 있거나 의심스러운 출력을 생성하면 `verify_tool_result()` 도구가 일반적인 문제(프록시 오류, 권한 거부, 잘못된 플래그)를 감지하고 수정된 명령을 제안합니다. 이는 에이전트가 자동화된 침투 테스트에서 흔히 발생하는 실패 모드인 손상된 도구 실행을 "완료"로 조용히 계산하는 것을 방지합니다.

**Q: 취약점 체이닝은 어떻게 작동합니까?**

지식 그래프는 테스트 중에 발견된 엔터티(엔드포인트, 매개변수, 발견 사항, 쿠키, 도메인)와 관계를 추적합니다. 4단계 후에 `find_chains()`는 BFS를 사용하여 다중 홉 공격 경로를 발견하고 7개의 사전 정의된 체인 패턴(예: XSS + CSP 누락, SSRF + 클라우드 메타데이터, IDOR + 관리자 역할)을 확인합니다. 영향을 증가시키는 체인은 자동으로 심각도 업그레이드를 트리거합니다.

---

## 면책 조항

**이 도구는 승인된 보안 테스트용으로만 사용됩니다.** 명시적 허가를 받은 애플리케이션에 대해서만 AutoPentest를 사용하십시오. 컴퓨터 시스템에 대한 무단 접근은 불법입니다. 저자는 이 도구의 오용에 대해 책임을 지지 않습니다.

항상 다음 사항을 확인하십시오:
- 애플리케이션 소유자의 서면 승인
- 테스트 가능 및 불가능 항목이 명확히 정의된 범위
- 테스트 환경(프로덕션 vs 스테이징)에 대한 이해
- 파괴적이거나 민감한 엔드포인트에 대한 적절한 회피 규칙 구성

---

<p align="center">
  <a href="https://modelcontextprotocol.io">Model Context Protocol</a>로 제작됨
</p>