### 추가 하드웨어

- **이더넷 연결**: 인터넷 패스스루에 필요 (물리적 또는 USB-이더넷 어댑터 가능)
- **충분한 USB 전원**: 일부 고전력 어댑터는 전원 공급 USB 허브가 필요할 수 있음
- **컴퓨터**: Linux를 실행하는 모든 노트북 또는 데스크탑 (권장: Kali Linux)

---

## 💻 소프트웨어 요구사항

### 운영 체제

- **권장**: Kali Linux (2020.1 이상)
- **또한 지원**:
  - Debian 10+
  - Ubuntu 18.04+
  - Fedora 30+
  - Arch Linux
  - ParrotOS
  - BlackArch

### 필수 패키지

이들은 `install_dependencies.sh`에 의해 자동으로 설치됩니다:

- `hostapd` - 액세스 포인트 생성
- `dnsmasq` - DHCP 및 DNS 서비스 제공
- `iptables` - NAT 및 방화벽 규칙 구성
- `iproute2` - 네트워크 인터페이스 구성
- `wireless-tools` - 무선 관리 유틸리티
- `net-tools` - 네트워크 진단 도구
- `iw` - 무선 구성 유틸리티
- `tcpdump` - 패킷 캡처 유틸리티

### 권한

- 모든 작업에 루트/sudo 액세스 필요

---

## 📦 설치

### 빠른 시작```bash
# Clone the repository
git clone https://github.com/yourusername/evil-twin-ap.git
cd evil-twin-ap

# Install dependencies
sudo ./install_dependencies.sh

# Detect your wireless interfaces
sudo ./detect_interface.sh

# Configure your settings (update interface if needed)
nano hostapd.conf  # Change SSID, channel, interface
nano dnsmasq.conf  # Adjust DHCP settings, interface

# Start the evil twin
sudo ./start_evil_twin.sh

#### 2단계: 종속성 설치

설치 스크립트는 자동으로 사용 중인 Linux 배포판을 감지하고 필요한 패키지를 설치합니다:```bash
sudo ./install_dependencies.sh

이 스크립트는 모든 무선 인터페이스를 분석하고 최적의 것을 추천합니다.

**예제 출력:**```
==========================================
   Wireless Interface Detection
==========================================

[INFO] Scanning for wireless interfaces...

[✓] Found 2 wireless interface(s)

═══════════════════════════════════════════
Interface: wlan1
═══════════════════════════════════════════
State: DORMANT
MAC Address: 1a:60:c6:85:87:53
Driver: rtl88XXau

[INFO] Checking capabilities for wlan1...
[✓] Supports AP mode (Access Point) ✓
[✓] Supports Monitor mode ✓
Current Mode: managed

═══════════════════════════════════════════
Interface: wlan0
═══════════════════════════════════════════
State: DOWN
MAC Address: b2:72:bf:bc:31:bd
Driver: iwlwifi

[INFO] Checking capabilities for wlan0...
[✓] Supports AP mode (Access Point) ✓
[✓] Supports Monitor mode ✓
Current Mode: managed
[!] Power management is ON (may cause issues)

==========================================
   Summary & Recommendations
==========================================

[✓] Found 2 AP-capable interfaces:
  - wlan1
  - wlan0

[INFO] Recommendation: Use wlan1 (likely external USB adapter)

[!] wlan0 is usually built-in WiFi - use external adapter if available

[INFO] To update configuration files, run:
  sed -i 's/^interface=.*/interface=wlan1/' hostapd.conf
  sed -i 's/^interface=.*/interface=wlan1/' dnsmasq.conf

Current Configuration:
  hostapd.conf: interface=wlan1
  dnsmasq.conf: interface=wlan1

[INFO] After updating, verify with: iw list | grep -A 10 'Supported interface modes'

---

## ⚙️ 설정

### hostapd.conf - 액세스 포인트 설정

`hostapd.conf`를 편집하여 악성 트윈을 사용자 지정하세요:```bash
nano hostapd.conf

### dnsmasq.conf - DHCP/DNS 설정

`dnsmasq.conf`를 편집하여 네트워크 설정을 사용자 지정하세요:```bash
nano dnsmasq.conf

### 네트워크 구성

**기본 설정:**
- **AP IP**: 192.168.99.1
- **서브넷**: 192.168.99.0/24
- **DHCP 범위**: 192.168.99.10 - 192.168.99.250
- **채널**: 6 (2.4GHz)
- **비밀번호**: letitrain2
- **인터페이스**: wlan1 (외부 어댑터)

---

## 🚀 사용법

### Evil Twin 시작하기```bash
sudo ./start_evil_twin.sh

### Evil Twin 중지하기```bash
sudo ./stop_evil_twin.sh

---

## 📸 트래픽 캡처

### 네트워크 트래픽 캡처

이 도구 키트에는 패킷 데이터를 분석을 위해 PCAP 파일로 저장하는 포괄적인 트래픽 캡처 스크립트가 포함되어 있습니다:```bash
# Basic capture (continuous until Ctrl+C)
sudo ./capture_traffic.sh

# Capture for specific duration (60 seconds)
sudo ./capture_traffic.sh -d 60

# Capture with verbose output and live statistics
sudo ./capture_traffic.sh -v

# Capture only HTTP/HTTPS traffic
sudo ./capture_traffic.sh -f "tcp port 80 or tcp port 443"

# Capture with custom filename
sudo ./capture_traffic.sh -n my_test_capture

# Capture on specific interface
sudo ./capture_traffic.sh -i wlan1

# Capture with file rotation (50MB files, max 20 files)
sudo ./capture_traffic.sh -s 50 -m 20

### 캡처 기능

- ✅ 트래픽을 표준 PCAP 형식으로 저장
- ✅ 대용량 파일 방지를 위한 자동 파일 로테이션
- ✅ 자세한 모드에서 실시간 패킷 통계
- ✅ BPF 필터링 지원 (버클리 패킷 필터)
- ✅ 시간 설정 캡처 또는 연속 작동
- ✅ Ctrl+C 입력 시 안전한 정리
- ✅ 출력이 `output/` 디렉토리에 저장됨

### 출력 위치

모든 캡처는 타임스탬프 기반 파일명으로 `output/`에 저장됩니다:
- 형식: `capture_YYYYMMDD_HHMMSS.pcap`
- 사용자 정의: `yourname_YYYYMMDD_HHMMSS.pcap`

### 캡처된 트래픽 분석```bash
# Open in Wireshark (GUI)
wireshark output/capture_20251018_143215.pcap

# Analyze with tcpdump
tcpdump -r output/capture_20251018_143215.pcap -n

# Filter for specific protocols
tcpdump -r output/capture_20251018_143215.pcap 'tcp port 80'

# Extract HTTP requests
tcpdump -r output/capture_20251018_143215.pcap -A 'tcp port 80'

# Get capture statistics
capinfos output/capture_20251018_143215.pcap

# Use tshark for advanced analysis
tshark -r output/capture_20251018_143215.pcap -Y "http.request"

---

## 📊 모니터링

### 실시간 연결 모니터링

이 툴킷은 연결된 클라이언트를 모니터링하는 여러 방법을 제공합니다:

#### 1. 연결 로그

5초마다 자동으로 업데이트됩니다:```bash
tail -f logs/connections.log

#### 2. DHCP 할당

DHCP 임대를 실시간으로 확인하세요:```bash
tail -f logs/dnsmasq.log

#### 3. 액세스 포인트 상태

hostapd 로그 모니터링:```bash
tail -f logs/hostapd.log

---

## 🔧 문제 해결

### 일반적인 문제 및 해결 방법

#### 1. "무선 인터페이스를 찾을 수 없습니다"

**문제:** 무선 어댑터가 감지되지 않습니다.

**해결 방법:**```bash
# Check if adapter is connected
lsusb | grep -i wireless

# Check interface name
ip link show

# Try replugging USB adapter

# Check kernel messages
dmesg | tail -20

# Run the detection script
sudo ./detect_interface.sh

#### 3. "hostapd failed to start"

**문제:** hostapd가 액세스 포인트를 시작할 수 없습니다.

**해결 방법:**```bash
# Check if interface is busy
sudo airmon-ng check kill

# Verify interface is up
sudo ip link set wlan1 up

# Check hostapd config syntax
sudo hostapd -d hostapd.conf

# View detailed logs
cat logs/hostapd.log

# Make sure you're using the right interface
grep "^interface=" hostapd.conf

#### 5. "클라이언트가 연결되지만 인터넷에 접속할 수 없음"

**문제:** NAT/라우팅이 올바르게 구성되지 않았습니다.

**해결 방법:**```bash
# Verify IP forwarding
cat /proc/sys/net/ipv4/ip_forward
# Should output: 1

# Check NAT rules
sudo iptables -t nat -L -v

# Verify internet interface
ip route show default

# Test internet on host
ping -c 3 8.8.8.8

# Check if eth0 has internet
ping -I eth0 -c 3 8.8.8.8

#### 7. "채널 X를 사용할 수 없습니다"

**문제:** 무선 규정으로 인해 특정 채널이 제한됩니다.

**해결 방법:**```bash
# Check available channels for your country
iw list | grep -A 20 "Frequencies:"

# Edit hostapd.conf and change to available channel
nano hostapd.conf
# Common safe channels: 1, 6, 11 (2.4GHz)

#### 9. "잘못된 인터페이스 사용"

**문제:** 스크립트가 wlan0 대신 wlan1을 사용하고 있습니다(또는 그 반대).

**해결 방법:**```bash
# Run interface detection
sudo ./detect_interface.sh

# Update config files to use correct interface
sed -i 's/^interface=.*/interface=wlan1/' hostapd.conf
sed -i 's/^interface=.*/interface=wlan1/' dnsmasq.conf

# Verify changes
grep "^interface=" hostapd.conf dnsmasq.conf

### 파일 설명

| 파일 | 목적 | 수정? |
|------|---------|---------|
| `hostapd.conf` | AP 설정 (SSID, 채널, 비밀번호, 인터페이스) | ✅ 예 - 테스트에 맞게 사용자 지정 |
| `dnsmasq.conf` | DHCP/DNS 구성 (인터페이스, IP 범위) | ✅ 예 - 네트워크 설정 조정 |
| `install_dependencies.sh` | 필요한 패키지 설치 | ❌ 아니오 - 그대로 실행 |
| `detect_interface.sh` | 무선 인터페이스 및 AP 모드 지원 감지 | ❌ 아니오 - 그대로 실행 |
| `start_evil_twin.sh` | 이블 트윈 AP 시작 | ⚠️ 드물게 - 고급 사용자 지정에만 |
| `stop_evil_twin.sh` | 중지 및 정리 | ❌ 아니오 - 그대로 실행 |
| `capture_traffic.sh` | 트래픽을 PCAP 파일로 캡처 | ⚠️ 대신 CLI 옵션 사용 |
| `logs/*.log` | 실행 로그 | 📖 읽기 전용 - 모니터링용 |
| `output/*.pcap` | 캡처된 패킷 데이터 | 📖 읽기 전용 - 분석용 |

---

## 🔒 보안 고려사항

### 윤리적 사용 가이드라인

1. **승인**: 테스트 전에 항상 서면 허가를 받으세요.
2. **범위**: 합의된 테스트 범위 내에서 유지하세요.
3. **문서화**: 모든 활동에 대한 상세 로그를 보관하세요.
4. **공개**: 네트워크 소유자에게 책임 있게 결과를 보고하세요.
5. **데이터 처리**: 캡처된 데이터를 가로채거나 저장하거나 오용하지 마세요.

### 법적 고려사항

- 승인 없이 불량 액세스 포인트를 생성하는 것은 대부분의 국가에서 **불법**입니다.
- 처벌에는 벌금, 징역, 전과 기록이 포함될 수 있습니다.
- '무해한' 테스트라도 승인되지 않으면 기소될 수 있습니다.
- 기업 환경: IT 부서의 서면 승인을 받으세요.
- 공공 장소: 공용 네트워크에서 절대 테스트하지 마세요.

### 기술적 보안

**이 도구 키트는 설계상 다음과 같습니다:**
- ✅ 액세스 포인트 생성 및 모니터링에 초점
- ✅ 승인된 분석만을 위한 트래픽 캡처 포함
- ✅ 책임 추적을 위한 포괄적인 로깅 제공
- ⚠️ 자격 증명 수집을 포함하지 않음
- ⚠️ SSL 스트리핑 또는 능동적 MITM 공격을 포함하지 않음
- ⚠️ 캡티브 포털 피싱을 포함하지 않음

**테스트 보안 강화를 위해:**
- 격리된 네트워크 세그먼트 사용
- 테스트 네트워크 식별 구현 (고유 SSID)
- 특정 시간대에 테스트 제한
- 모든 활동 모니터링 및 로깅
- 신호 누출 방지를 위해 패러데이 케이지 또는 RF 차폐실에서만 사용

### 방어 조치

조직은 다음과 같은 방법으로 이블 트윈 공격으로부터 보호할 수 있습니다:

- **802.1X 인증** 구현 (WPA2/WPA3 Enterprise)
- 네트워크 인증에 **인증서 검증** 사용
- **무선 침입 탐지 시스템(WIDS)** 배포
- **보호 관리 프레임(PMF/802.11w)** 활성화
- 사용자 교육으로 네트워크 신뢰성 확인
- 민감한 통신에 VPN 사용
- 불량 액세스 포인트 모니터링

---

## 🤝 기여

기여를 환영합니다! 다음 지침을 따라주세요:

### 기여 방법

1. **저장소 포크**
2. **기능 브랜치 생성**: `git checkout -b feature/your-feature`
3. 명확한 커밋 메시지와 함께 **변경**
4. 가능한 경우 여러 시스템에서 **철저히 테스트**
5. 기능 변경 시 **문서 업데이트**
6. 상세 설명과 함께 **풀 리퀘스트 제출**

### 기여 지침

- 모듈식 구조 유지
- 새 기능에 대한 상세 로깅 추가
- 엣지 케이스에 대한 오류 처리 포함
- 새 기능 추가 시 README 업데이트
- 기존 코드 스타일 준수 (bash 모범 사례)
- 복잡한 로직에 주석 추가
- 최소 하나의 Debian 기반 배포판에서 테스트

### 코드 스타일```bash
# Use descriptive function names
configure_network_interface() {
    # Clear comments
    # Error handling
    # Verbose output
}

# Consistent formatting
print_info "Starting process..."
command || print_error "Failed to execute command"

---

## 🙏 감사의 말

- 뛰어난 무선 보안 도구를 제공하는 Kali Linux 팀
- hostapd 및 dnsmasq 프로젝트
- 무선 보안 연구 커뮤니티
- 기여자 및 테스터 여러분

---

## 📚 추가 자료

### 학습 자료

- [OWASP 무선 보안 테스트 가이드](https://owasp.org/www-project-web-security-testing-guide/)
- [WiFi 침투 테스트 방법론](https://www.sans.org/white-papers/)
- [Kali Linux에서의 무선 보안](https://www.kali.org/docs/wireless/)

### 관련 도구

- **Aircrack-ng**: 무선 감사 제품군
- **Wireshark**: 네트워크 프로토콜 분석기
- **Bettercap**: 네트워크 공격 및 모니터링
- **Wifiphisher**: WiFi 자동화 피싱 공격

### 문서

- [hostapd 문서](https://w1.fi/hostapd/)
- [dnsmasq 매뉴얼](http://www.thekelleys.org.uk/dnsmasq/doc.html)
- [Linux 무선 위키](https://wireless.wiki.kernel.org/)
- [tcpdump 매뉴얼](https://www.tcpdump.org/manpages/tcpdump.1.html)

---

## 📞 지원

- **이슈**: [GitHub Issues](https://github.com/yourusername/evil-twin-ap/issues)
- **토론**: [GitHub Discussions](https://github.com/yourusername/evil-twin-ap/discussions)
- **보안**: 취약점은 이메일로 보고해 주세요 (공개 이슈 사용 금지)

---

## ⚖️ 최종 경고```
┌─────────────────────────────────────────────────────────────┐
│                                                             │
│  This tool is provided for EDUCATIONAL PURPOSES ONLY        │
│                                                             │
│  Unauthorized access to computer networks is ILLEGAL        │
│                                                             │
│  Always obtain written permission before testing            │
│                                                             │
│  You are responsible for your actions                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘