README.md (6259B)
1 # UAF — Ultimate AP Finder
2
3 A Linux-based wireless AP detection and analysis tool for PCI-DSS security auditing.
4
5 > **[한국어 (Korean)](#uaf--ultimate-ap-finder-1)**
6
7 ## Why UAF?
8
9 In enterprise environments, PCI-DSS (Payment Card Industry Data Security Standard) compliance requires **wireless AP vulnerability assessments**. You need to identify authorized vs. rogue APs, and detect open networks or APs using weak encryption.
10
11 Existing tools either stop at basic scanning, lack active reconnaissance capabilities, or don't provide output formats ready for enterprise audit reports.
12
13 **UAF** was built to solve this:
14
15 - Real-time collection of all nearby APs with automatic security classification (encryption/authentication/WPS)
16 - Visual highlighting of open (OPN) APs for immediate identification
17 - Active connection to suspicious APs to map network structure (DHCP, gateway, clients)
18 - Export results to CSV/JSON for direct use in audit reports
19
20 ---
21
22 ## Features
23
24 ### Passive Scanning
25 - Real-time AP detection across 2.4GHz / 5GHz / 6GHz bands
26 - Security classification: WEP, WPA, WPA2, WPA3, OPN
27 - 802.11 a/b/g/n/ac/ax standard detection
28 - Channel width detection (20/40/80/160 MHz)
29 - Hidden SSID detection and recovery
30 - MAC vendor lookup
31 - Band/sort filtering
32
33 ### Active Scanning
34 - Interactive UI with arrow key AP selection
35 - Active reconnaissance after connecting to open (OPN) APs
36 - DHCP information gathering, ARP scan for connected client detection
37 - Gateway port scan (22, 53, 80, 443, 8080, 8443)
38 - Instant results via overlay panel
39
40 ### Export
41 - CSV / JSON export (including active scan results)
42 - Configuration file support
43
44 ---
45
46 ## Requirements
47
48 - Python 3.10+
49 - Linux (`iw`, `ip` commands)
50 - Root privileges
51 - WiFi adapter with monitor mode support
52
53 ## Installation
54
55 ### From PyPI
56
57 ```bash
58 pip install uaf
59 ```
60
61 ### From source
62
63 ```bash
64 git clone https://github.com/sqzer-x/uaf.git
65 cd uaf
66 pip install -e .
67 ```
68
69 ## Usage
70
71 ```bash
72 # Basic scan (auto-detect interface)
73 sudo uaf
74
75 # Specify interface
76 sudo uaf -i wlan0
77
78 # Scan specific channels only
79 sudo uaf -c 1,6,11
80
81 # Band filter
82 sudo uaf -b 2.4
83
84 # Change sort order
85 sudo uaf --sort channel
86
87 # Save to CSV
88 sudo uaf -w output.csv
89
90 # Use config file
91 sudo uaf --config /path/to/config.ini
92 ```
93
94 ## Keybindings
95
96 ### Normal Mode
97 | Key | Action |
98 |-----|--------|
99 | `q` | Quit |
100 | `w` | Write CSV |
101 | `j` | Write JSON |
102 | `b` | Cycle band filter (All / 2.4GHz / 5GHz / 6GHz) |
103 | `s` | Cycle sort mode (RSSI / Channel / ESSID / ENC) |
104 | `Enter` | Enter AP selection mode |
105
106 ### Selection Mode
107 | Key | Action |
108 |-----|--------|
109 | `↑` / `↓` | Navigate through AP list |
110 | `Enter` | Run active scan on selected open AP |
111 | `Esc` | Exit selection mode |
112
113 ## Configuration
114
115 Default config path: `~/.config/ap-scanner/config.ini`
116
117 ```ini
118 [scanner]
119 interface = wlan0
120 band = all
121 sort = rssi
122 no_color = false
123 verbose = false
124 ```
125
126 ## Development
127
128 ```bash
129 pip install -e ".[dev]"
130 pytest tests/ -v
131 ```
132
133 ## License
134
135 GPL-2.0-or-later. See [LICENSE](LICENSE) for details.
136
137 ---
138
139 # UAF — Ultimate AP Finder
140
141 PCI-DSS 무선 보안 감사 대응을 위한 Linux 기반 AP 탐지 및 분석 도구.
142
143 ## Why UAF?
144
145 기업 환경에서 PCI-DSS(Payment Card Industry Data Security Standard) 인증을 대응하다 보면 **무선 AP 취약점 점검** 항목을 마주하게 됩니다. 인가된 AP와 비인가(Rogue) AP를 식별하고, 오픈 네트워크나 취약한 암호화를 사용하는 AP를 탐지해야 합니다.
146
147 기존 도구들은 단순 스캔에 그치거나, 능동적 정찰이 불가능하거나, 기업 감사 보고서에 바로 활용할 수 있는 출력 포맷을 제공하지 않았습니다.
148
149 **UAF**는 이 문제를 해결하기 위해 만들어졌습니다:
150
151 - 주변 전체 AP를 실시간으로 수집하고, 보안 설정(암호화/인증/WPS)을 자동 분류
152 - 오픈(OPN) AP를 시각적으로 강조하여 즉시 식별
153 - 의심스러운 AP에 직접 접속해 네트워크 구조(DHCP, 게이트웨이, 클라이언트)까지 파악
154 - 결과를 CSV/JSON으로 내보내 감사 보고서에 바로 활용
155
156 ---
157
158 ## 기능
159
160 ### 수동 스캔 (Passive Scanning)
161 - 2.4GHz / 5GHz / 6GHz 전 대역 실시간 AP 탐지
162 - 보안 분류: WEP, WPA, WPA2, WPA3, OPN
163 - 802.11 a/b/g/n/ac/ax 표준 탐지
164 - 채널 폭 탐지 (20/40/80/160 MHz)
165 - Hidden SSID 탐지 및 복원
166 - MAC 벤더 조회
167 - 대역/정렬 필터링
168
169 ### 능동 스캔 (Active Scanning)
170 - 화살표 키로 AP 선택하는 인터랙티브 UI
171 - 오픈(OPN) AP 접속 후 능동 정찰
172 - DHCP 정보 수집, ARP 스캔으로 연결 클라이언트 탐지
173 - 게이트웨이 포트 스캔 (22, 53, 80, 443, 8080, 8443)
174 - 결과 오버레이 패널로 즉시 확인
175
176 ### 내보내기 (Export)
177 - CSV / JSON 내보내기 (능동 스캔 결과 포함)
178 - 설정 파일 지원
179
180 ---
181
182 ## 요구 사항
183
184 - Python 3.10+
185 - Linux (`iw`, `ip` 명령어)
186 - Root 권한
187 - Monitor 모드 지원 WiFi 어댑터
188
189 ## 설치
190
191 ### PyPI에서 설치
192
193 ```bash
194 pip install uaf
195 ```
196
197 ### 소스에서 설치
198
199 ```bash
200 git clone https://github.com/sqzer-x/uaf.git
201 cd uaf
202 pip install -e .
203 ```
204
205 ## 사용법
206
207 ```bash
208 # 기본 스캔 (인터페이스 자동 탐지)
209 sudo uaf
210
211 # 인터페이스 지정
212 sudo uaf -i wlan0
213
214 # 특정 채널만 스캔
215 sudo uaf -c 1,6,11
216
217 # 대역 필터
218 sudo uaf -b 2.4
219
220 # 정렬 기준 변경
221 sudo uaf --sort channel
222
223 # CSV로 저장
224 sudo uaf -w output.csv
225
226 # 설정 파일 사용
227 sudo uaf --config /path/to/config.ini
228 ```
229
230 ## 키 바인딩
231
232 ### 일반 모드
233 | 키 | 동작 |
234 |----|------|
235 | `q` | 종료 |
236 | `w` | CSV 저장 |
237 | `j` | JSON 저장 |
238 | `b` | 대역 필터 순환 (All / 2.4GHz / 5GHz / 6GHz) |
239 | `s` | 정렬 모드 순환 (RSSI / Channel / ESSID / ENC) |
240 | `Enter` | AP 선택 모드 진입 |
241
242 ### 선택 모드
243 | 키 | 동작 |
244 |----|------|
245 | `↑` / `↓` | AP 목록 탐색 |
246 | `Enter` | 선택한 오픈 AP에 능동 스캔 실행 |
247 | `Esc` | 선택 모드 종료 |
248
249 ## 설정
250
251 기본 설정 파일 경로: `~/.config/ap-scanner/config.ini`
252
253 ```ini
254 [scanner]
255 interface = wlan0
256 band = all
257 sort = rssi
258 no_color = false
259 verbose = false
260 ```
261
262 ## 개발
263
264 ```bash
265 pip install -e ".[dev]"
266 pytest tests/ -v
267 ```
268
269 ## 라이선스
270
271 GPL-2.0-or-later. 자세한 내용은 [LICENSE](LICENSE)를 참조하세요.