README.txt (15729B)
1 USFX - Ultimate Subdomain Finder X
2 ===================================
3
4 A standalone Python CLI tool for discovering subdomains on internal
5 networks using custom DNS servers. Designed for air-gapped environments
6 without internet connectivity.
7
8
9 FEATURES
10 --------
11
12 - Custom DNS Server Support: Specify internal DNS servers
13 - Offline-Only Modules: All techniques work without internet
14 - 12 Enumeration Modules:
15 * DNS Brute Force
16 * Zone Transfer (AXFR)
17 * DNSSEC Walking (NSEC/NSEC3)
18 * DNS Record Mining (MX, NS, TXT, SRV, SOA, CAA)
19 * Reverse DNS Sweep
20 * CNAME Chain Analysis
21 * Subdomain Permutation
22 * Recursive Sub-subdomain Enumeration
23 * Virtual Host Discovery
24 * TLS Certificate SAN Extraction
25 * Subdomain Takeover Detection
26 * Web Technology Detection (Wappalyzer)
27 - Pipeline Modes: Output formats for tool chaining (subs, web, ips, json)
28 - Multiple Output Formats: JSON, CSV, TXT
29 - Bundled Wordlists: Small (~500), Medium (~3500), Large (~18000)
30 - Progress Tracking: Real-time progress with Rich terminal UI
31
32
33 INSTALLATION
34 ------------
35
36 From PyPI (Recommended):
37
38 pip install usfx
39
40 # With Wappalyzer support for web technology detection
41 pip install usfx[webtech]
42
43 From GitHub Releases:
44
45 # Download wheel from:
46 # https://github.com/sqzer-x/usfx/releases/latest
47 pip install usfx-1.2.0-py3-none-any.whl
48
49 From Source (Development):
50
51 git clone https://github.com/sqzer-x/usfx.git
52 cd usfx
53 pip install -e .
54
55
56 QUICK START
57 -----------
58
59 Basic Usage:
60
61 usfx corp.local # System DNS
62 usfx corp.local -d 192.168.1.1 # Internal DNS
63 usfx corp.local -d 192.168.1.1 -d 10.0.0.1 # Multiple DNS
64
65 Wordlist Options:
66
67 usfx corp.local -d 10.0.0.1 -s small # ~500 words
68 usfx corp.local -d 10.0.0.1 -s medium # ~3500 words (default)
69 usfx corp.local -d 10.0.0.1 -s large # ~18000 words
70 usfx corp.local -d 10.0.0.1 -w /path/to/custom.txt
71
72 Output Options:
73
74 usfx corp.local -d 10.0.0.1 -o results.json
75 usfx corp.local -d 10.0.0.1 -o results.csv -f csv
76 usfx corp.local -d 10.0.0.1 -o results.txt -f txt
77
78 Module Selection:
79
80 usfx corp.local -d 10.0.0.1 -m bruteforce,zone,records
81
82 Available modules:
83 bruteforce - DNS brute force with wordlist
84 zone - Zone transfer (AXFR)
85 dnssec - DNSSEC zone walking
86 records - DNS record mining
87 reverse - Reverse DNS sweep
88 cname - CNAME chain analysis
89 permutation - Subdomain permutation
90 recursive - Recursive sub-subdomain enumeration
91 vhost - Virtual host discovery
92 tls - TLS certificate analysis
93 takeover - Subdomain takeover detection
94 webtech - Web technology detection
95
96 Extended Scanning:
97
98 # Subdomain takeover vulnerability detection
99 usfx corp.local -d 10.0.0.1 --takeover
100
101 # Web technology detection (optional: python-Wappalyzer)
102 usfx corp.local -d 10.0.0.1 --web-tech
103
104 # Custom web ports for tech detection
105 usfx corp.local -d 10.0.0.1 --web-tech --web-ports 80,443,8080,8443
106
107 Pipeline Modes:
108
109 # Output only subdomains (one per line) - pipe to other tools
110 usfx corp.local -d 10.0.0.1 --pipe-subs | httpx
111
112 # Output only web URLs
113 usfx corp.local -d 10.0.0.1 --web-tech --pipe-web
114
115 # Output only IP addresses
116 usfx corp.local -d 10.0.0.1 --pipe-ips | nmap -iL -
117
118 # JSON output to stdout (for jq processing)
119 usfx corp.local -d 10.0.0.1 --pipe-json | jq '.subdomains'
120
121 Advanced Options:
122
123 usfx corp.local -d 10.0.0.1 -t 50 --timeout 5.0
124 usfx corp.local -d 10.0.0.1 --reverse-range 192.168.0.0/24
125 usfx corp.local -d 10.0.0.1 --vhost-ip 192.168.1.100
126 usfx corp.local -d 10.0.0.1 -v # Verbose
127 usfx corp.local -d 10.0.0.1 -q # Quiet
128
129
130 CLI REFERENCE
131 -------------
132
133 Usage: usfx [OPTIONS] DOMAIN
134
135 Options:
136 -d, --dns-server TEXT DNS server IP (can be repeated)
137 -w, --wordlist PATH Custom wordlist file
138 -s, --wordlist-size TEXT Wordlist size: small|medium|large
139 -o, --output PATH Output file path
140 -f, --format TEXT Output format: json|csv|txt
141 -t, --threads INTEGER Parallel threads (default: 30, max: 100)
142 --timeout FLOAT DNS timeout in seconds (default: 3.0)
143 -m, --modules TEXT Comma-separated module list
144 --reverse-range TEXT CIDR range for reverse DNS
145 --vhost-ip TEXT IP for vhost scanning
146 --takeover Enable subdomain takeover detection
147 --web-tech Enable web technology detection
148 --web-ports TEXT Ports for web tech scanning (default: 80,443,8080,8443)
149 --pipe-subs Pipeline: output subdomains only
150 --pipe-web Pipeline: output web URLs only
151 --pipe-ips Pipeline: output IPs only
152 --pipe-json Pipeline: JSON to stdout
153 -v, --verbose Verbose output
154 -q, --quiet Suppress non-essential output
155 --no-color Disable colored output
156 --version Show version
157 --help Show help message
158
159
160 PYTHON API
161 ----------
162
163 from usfx import ScanConfig, SubdomainEngine
164 from usfx.config import WordlistSize
165
166 config = ScanConfig(
167 domain='corp.internal',
168 dns_servers=['10.0.0.1', '10.0.0.2'],
169 wordlist_size=WordlistSize.MEDIUM,
170 threads=50,
171 timeout=3.0,
172 takeover=True,
173 web_tech=True,
174 )
175
176 engine = SubdomainEngine()
177 result = engine.scan(config)
178
179 print(f"Found {result.total_found} subdomains")
180 for sub in result.subdomains:
181 print(f" {sub.subdomain} -> {sub.ip}")
182
183 # Takeover vulnerabilities
184 for vuln in result.takeover_results:
185 print(f" VULN: {vuln.subdomain} -> {vuln.service}")
186
187 # Web technologies
188 for web in result.web_tech_results:
189 print(f" WEB: {web.url} - {', '.join(web.technologies)}")
190
191
192 MODULE DESCRIPTIONS
193 -------------------
194
195 dns_bruteforce Wordlist-based DNS queries Medium
196 zone_transfer AXFR zone transfer attempts Fast
197 dnssec_walker NSEC/NSEC3 zone walking Fast
198 dns_records MX/NS/TXT/SRV/SOA/CAA mining Fast
199 reverse_dns PTR lookups on IP ranges Slow
200 cname_chaser CNAME chain tracking Fast
201 permutation Subdomain variation generation Medium
202 recursive_enum Sub-subdomain discovery Medium
203 vhost_scanner Host header brute force Slow
204 tls_analyzer TLS certificate SAN extraction Medium
205 takeover Subdomain takeover detection Fast
206 web_tech Web technology detection Medium
207
208
209 REQUIREMENTS
210 ------------
211
212 - Python 3.10+
213 - dnspython >= 2.4.0
214 - click >= 8.1.0
215 - requests >= 2.28.0
216 - cryptography >= 41.0.0
217 - rich >= 13.0.0
218
219 Optional:
220 - python-Wappalyzer >= 0.3.1 (for web technology detection)
221
222
223 USE CASES
224 ---------
225
226 Internal Network Penetration Testing:
227 usfx corp.internal -d 10.0.0.53 -s large --takeover -o findings.json
228
229 Active Directory Reconnaissance:
230 usfx ad.corp.local -d 192.168.1.1 -m records,reverse,zone
231
232 IT Asset Discovery:
233 usfx internal.company -d 172.16.0.1 --reverse-range 172.16.0.0/16
234
235 Web Application Mapping:
236 usfx corp.local -d 10.0.0.1 --web-tech --pipe-web | httpx -silent
237
238 Tool Integration:
239 usfx corp.local --pipe-subs | nuclei -t takeovers/
240
241
242 LICENSE
243 -------
244
245 MIT License - See LICENSE file for details.
246
247
248 ================================================================================
249 한국어 (KOREAN)
250 ================================================================================
251
252
253 USFX - Ultimate Subdomain Finder X
254 ===================================
255
256 내부 네트워크에서 커스텀 DNS 서버를 사용하여 서브도메인을 탐지하는
257 독립 실행형 Python CLI 도구입니다. 인터넷 연결이 없는 에어갭(Air-gapped)
258 환경에서 사용할 수 있도록 설계되었습니다.
259
260
261 기능
262 ----
263
264 - 커스텀 DNS 서버 지원: 내부 DNS 서버 지정 가능
265 - 오프라인 전용 모듈: 모든 기법이 인터넷 없이 작동
266 - 12개 열거 모듈:
267 * DNS 브루트포스
268 * Zone Transfer (AXFR)
269 * DNSSEC 워킹 (NSEC/NSEC3)
270 * DNS 레코드 마이닝 (MX, NS, TXT, SRV, SOA, CAA)
271 * 역방향 DNS 스윕
272 * CNAME 체인 분석
273 * 서브도메인 순열 생성
274 * 재귀적 서브-서브도메인 열거
275 * 가상 호스트 탐지
276 * TLS 인증서 SAN 추출
277 * 서브도메인 Takeover 탐지
278 * 웹 기술 탐지 (Wappalyzer)
279 - 파이프라인 모드: 다른 도구와 연동을 위한 출력 포맷 (subs, web, ips, json)
280 - 다중 출력 포맷: JSON, CSV, TXT
281 - 번들 워드리스트: Small (~500), Medium (~3500), Large (~18000)
282 - 진행 상황 추적: Rich 터미널 UI로 실시간 진행 표시
283
284
285 설치
286 ----
287
288 PyPI에서 설치 (권장):
289
290 pip install usfx
291
292 # Wappalyzer 웹 기술 탐지 지원 포함
293 pip install usfx[webtech]
294
295 GitHub Releases에서 설치:
296
297 # 다운로드:
298 # https://github.com/sqzer-x/usfx/releases/latest
299 pip install usfx-1.2.0-py3-none-any.whl
300
301 소스에서 설치 (개발용):
302
303 git clone https://github.com/sqzer-x/usfx.git
304 cd usfx
305 pip install -e .
306
307
308 빠른 시작
309 ---------
310
311 기본 사용법:
312
313 usfx corp.local # 시스템 DNS 사용
314 usfx corp.local -d 192.168.1.1 # 내부 DNS 지정
315 usfx corp.local -d 192.168.1.1 -d 10.0.0.1 # 다중 DNS 지정
316
317 워드리스트 옵션:
318
319 usfx corp.local -d 10.0.0.1 -s small # ~500 단어
320 usfx corp.local -d 10.0.0.1 -s medium # ~3500 단어 (기본값)
321 usfx corp.local -d 10.0.0.1 -s large # ~18000 단어
322 usfx corp.local -d 10.0.0.1 -w /path/to/custom.txt
323
324 출력 옵션:
325
326 usfx corp.local -d 10.0.0.1 -o results.json
327 usfx corp.local -d 10.0.0.1 -o results.csv -f csv
328 usfx corp.local -d 10.0.0.1 -o results.txt -f txt
329
330 모듈 선택:
331
332 usfx corp.local -d 10.0.0.1 -m bruteforce,zone,records
333
334 사용 가능한 모듈:
335 bruteforce - 워드리스트 기반 DNS 브루트포스
336 zone - Zone Transfer (AXFR)
337 dnssec - DNSSEC 존 워킹
338 records - DNS 레코드 마이닝
339 reverse - 역방향 DNS 스윕
340 cname - CNAME 체인 분석
341 permutation - 서브도메인 순열 생성
342 recursive - 재귀적 서브-서브도메인 열거
343 vhost - 가상 호스트 탐지
344 tls - TLS 인증서 분석
345 takeover - 서브도메인 Takeover 탐지
346 webtech - 웹 기술 탐지
347
348 확장 스캐닝:
349
350 # 서브도메인 Takeover 취약점 탐지
351 usfx corp.local -d 10.0.0.1 --takeover
352
353 # 웹 기술 탐지 (선택사항: python-Wappalyzer)
354 usfx corp.local -d 10.0.0.1 --web-tech
355
356 # 웹 기술 탐지 포트 지정
357 usfx corp.local -d 10.0.0.1 --web-tech --web-ports 80,443,8080,8443
358
359 파이프라인 모드:
360
361 # 서브도메인만 출력 (한 줄에 하나) - 다른 도구로 파이프
362 usfx corp.local -d 10.0.0.1 --pipe-subs | httpx
363
364 # 웹 URL만 출력
365 usfx corp.local -d 10.0.0.1 --web-tech --pipe-web
366
367 # IP 주소만 출력
368 usfx corp.local -d 10.0.0.1 --pipe-ips | nmap -iL -
369
370 # JSON으로 stdout 출력 (jq 처리용)
371 usfx corp.local -d 10.0.0.1 --pipe-json | jq '.subdomains'
372
373 고급 옵션:
374
375 usfx corp.local -d 10.0.0.1 -t 50 --timeout 5.0
376 usfx corp.local -d 10.0.0.1 --reverse-range 192.168.0.0/24
377 usfx corp.local -d 10.0.0.1 --vhost-ip 192.168.1.100
378 usfx corp.local -d 10.0.0.1 -v # 상세 출력
379 usfx corp.local -d 10.0.0.1 -q # 조용한 모드
380
381
382 CLI 레퍼런스
383 ------------
384
385 사용법: usfx [옵션] 도메인
386
387 옵션:
388 -d, --dns-server TEXT DNS 서버 IP (여러 번 지정 가능)
389 -w, --wordlist PATH 커스텀 워드리스트 파일
390 -s, --wordlist-size TEXT 워드리스트 크기: small|medium|large
391 -o, --output PATH 출력 파일 경로
392 -f, --format TEXT 출력 포맷: json|csv|txt
393 -t, --threads INTEGER 병렬 스레드 수 (기본: 30, 최대: 100)
394 --timeout FLOAT DNS 타임아웃 (초, 기본: 3.0)
395 -m, --modules TEXT 쉼표로 구분된 모듈 목록
396 --reverse-range TEXT 역방향 DNS용 CIDR 범위
397 --vhost-ip TEXT 가상 호스트 스캐닝용 IP
398 --takeover 서브도메인 Takeover 탐지 활성화
399 --web-tech 웹 기술 탐지 활성화
400 --web-ports TEXT 웹 기술 스캐닝 포트 (기본: 80,443,8080,8443)
401 --pipe-subs 파이프라인: 서브도메인만 출력
402 --pipe-web 파이프라인: 웹 URL만 출력
403 --pipe-ips 파이프라인: IP만 출력
404 --pipe-json 파이프라인: JSON으로 stdout 출력
405 -v, --verbose 상세 출력
406 -q, --quiet 불필요한 출력 숨김
407 --no-color 색상 출력 비활성화
408 --version 버전 표시
409 --help 도움말 표시
410
411
412 Python API
413 ----------
414
415 from usfx import ScanConfig, SubdomainEngine
416 from usfx.config import WordlistSize
417
418 config = ScanConfig(
419 domain='corp.internal',
420 dns_servers=['10.0.0.1', '10.0.0.2'],
421 wordlist_size=WordlistSize.MEDIUM,
422 threads=50,
423 timeout=3.0,
424 takeover=True, # Takeover 탐지 활성화
425 web_tech=True, # 웹 기술 탐지 활성화
426 )
427
428 engine = SubdomainEngine()
429 result = engine.scan(config)
430
431 print(f"{result.total_found}개 서브도메인 발견")
432 for sub in result.subdomains:
433 print(f" {sub.subdomain} -> {sub.ip}")
434
435 # Takeover 취약점
436 for vuln in result.takeover_results:
437 print(f" 취약: {vuln.subdomain} -> {vuln.service}")
438
439 # 웹 기술
440 for web in result.web_tech_results:
441 print(f" 웹: {web.url} - {', '.join(web.technologies)}")
442
443
444 모듈 설명
445 ---------
446
447 dns_bruteforce - 워드리스트 기반 DNS 쿼리 (보통)
448 zone_transfer - AXFR 존 전송 시도 (빠름)
449 dnssec_walker - NSEC/NSEC3 존 워킹 (빠름)
450 dns_records - MX/NS/TXT/SRV/SOA/CAA 마이닝 (빠름)
451 reverse_dns - IP 범위 PTR 룩업 (느림)
452 cname_chaser - CNAME 체인 추적 (빠름)
453 permutation - 서브도메인 변형 생성 (보통)
454 recursive_enum - 서브-서브도메인 탐지 (보통)
455 vhost_scanner - Host 헤더 브루트포스 (느림)
456 tls_analyzer - TLS 인증서 SAN 추출 (보통)
457 takeover - 서브도메인 Takeover 탐지 (빠름)
458 web_tech - 웹 기술 탐지 (보통)
459
460
461 요구 사항
462 ---------
463
464 - Python 3.10+
465 - dnspython >= 2.4.0
466 - click >= 8.1.0
467 - requests >= 2.28.0
468 - cryptography >= 41.0.0
469 - rich >= 13.0.0
470
471 선택사항:
472 - python-Wappalyzer >= 0.3.1 (웹 기술 탐지용)
473
474
475 사용 사례
476 ---------
477
478 내부 네트워크 침투 테스트:
479 usfx corp.internal -d 10.0.0.53 -s large --takeover -o findings.json
480
481 Active Directory 정찰:
482 usfx ad.corp.local -d 192.168.1.1 -m records,reverse,zone
483
484 IT 자산 탐지:
485 usfx internal.company -d 172.16.0.1 --reverse-range 172.16.0.0/16
486
487 웹 애플리케이션 매핑:
488 usfx corp.local -d 10.0.0.1 --web-tech --pipe-web | httpx -silent
489
490 도구 연동:
491 usfx corp.local --pipe-subs | nuclei -t takeovers/
492
493
494 라이선스
495 --------
496
497 MIT License - 자세한 내용은 LICENSE 파일을 참조하세요.