subsurfer 0.1.8__tar.gz

subsurfer-0.1.8/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 arrester
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

subsurfer-0.1.8/MANIFEST.in

@@ -0,0 +1,4 @@
+include README.md
+include subsurfer/core/config/config.yaml
+recursive-include subsurfer *
+recursive-include tests * 

subsurfer-0.1.8/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.2
+Name: subsurfer
+Version: 0.1.8
+Summary: Red Teaming and Web Bug Bounty Fast Asset Identification Tool
+Home-page: https://github.com/arrester/subsurfer
+Author: arrester
+Author-email: arresterloyal@gmail.com
+Project-URL: Bug Reports, https://github.com/arrester/subsurfer/issues
+Project-URL: Source, https://github.com/arrester/subsurfer
+Project-URL: Documentation, https://github.com/arrester/subsurfer#readme
+Keywords: security,subdomain enumeration,bug bounty,red team,web security
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: Topic :: Security
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: rich>=13.7.0
+Requires-Dist: aiohttp>=3.9.1
+Requires-Dist: beautifulsoup4>=4.12.2
+Requires-Dist: dnspython>=2.4.2
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: asyncio>=3.4.3
+Requires-Dist: pytest>=7.4.3
+Requires-Dist: pytest-asyncio>=0.23.2
+Requires-Dist: python-Wappalyzer>=0.3.1
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# 🏄‍♂️ SubSurfer
+
+![Python Version](https://img.shields.io/badge/python-3.13%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Version](https://img.shields.io/badge/version-0.1-orange)
+
+SubSurfer는 빠르고 효율적인 서브도메인 열거 및 웹 자산 식별 도구입니다.
+
+<br>
+
+## 🌟 특징
+- **레드팀/버그바운티 지원**: 레드팀 작전과 웹 버그바운티 프로젝트 모두에서 활용 가능
+- **고성능 스캔**: 비동기 및 병렬 처리를 통한 빠른 서브도메인 수집
+- **포트 스캔**: 사용자 정의 포트 범위로 자산 스캔 범위 확장
+- **웹 서비스 식별**: 웹 서버, 기술 스택 등 환경 정보 수집
+- **파이프라인 지원**: `-pipeweb`, `-pipesub` 옵션으로 다른 도구와의 연계 가능
+- **모듈형 설계**: Python 모듈로 import하여 사용 가능
+- **지속적 업데이트**: 새로운 passive/active 모듈 지속 추가 예정
+
+<br>
+
+## 🚀 설치
+<b>bash</b>
+```bash
+git clone https://github.com/arrester/subsurfer.git
+cd subsurfer
+```
+
+or <br>
+
+<b>Python</b>
+```bash
+pip install -r requirements.txt
+```
+
+<br>
+
+## 📖 사용법
+### CLI 모드
+<b>기본 스캔</b><br>
+`subsurfer -t vulnweb.com`
+
+<b>액티브 스캔 활성화</b><br>
+`subsurfer -t vulnweb.com -a`
+
+<b>포트 스캔 포함</b><br>
+`subsurfer -t vulnweb.com -dp` # 기본 포트 <br>
+`subsurfer -t vulnweb.com -p 80,443,8080-8090` # 사용자 정의 포트
+
+<b>파이프라인 출력</b><br>
+`subsurfer -t vulnweb.com -pipeweb` # 웹 서버 결과만 출력 <br>
+`subsurfer -t vulnweb.com -pipesub` # 서브도메인 결과만 출력
+
+### Python 모듈로 사용
+<b>Subdomain Scan</b><br>
+```python
+from subsurfer.core.controller.controller import SubSurferController
+import asyncio
+
+async def main():
+    controller = SubSurferController(
+        target="vulnweb.com",
+        verbose=1,
+        active=False            # Active Scan Option
+    )
+    
+    # 서브도메인 수집
+    subdomains = await controller.collect_subdomains()
+    
+    # 결과 출력
+    print(f"발견된 서브도메인: {len(subdomains)}개")
+    for subdomain in sorted(subdomains):
+        print(subdomain)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+<br>
+
+<b>Port Scan</b><br>
+```python
+from subsurfer.core.controller.controller import SubSurferController
+import asyncio
+
+async def main():
+    controller = SubSurferController(
+        target="vulnweb.com",
+        verbose=1
+    )
+    
+    # 서브도메인 수집
+    subdomains = await controller.collect_subdomains()
+    
+    # 기본 80, 443 스캔 설정
+    ports = None
+
+    # 포트 스캔 설정
+    # ports = controller.parse_ports()  # 기본 포트
+    # 또는 사용자 지정 포트
+    # ports = controller.parse_ports("80,443,8080-8090")
+    
+    # 웹 서비스 스캔
+    web_services = await controller.scan_web_services(subdomains, ports)
+    
+    # 웹 서버 출력
+    print("\n웹 서버:")
+    for server in sorted(web_services['web_servers']):
+        print(f"https://{server}")
+    
+    # 활성화된 서비스 출력    
+    print("\n활성화된 서비스:")
+    for service in sorted(web_services['enabled_services']):
+        print(service)
+        
+    # URL과 포트 정보 출력
+    print("\n발견된 URL:")
+    for subdomain, urls in web_services['all_urls'].items():
+        for url, port in urls:
+            print(f"{url}:{port}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+<br>
+
+<b>Result Save</b><br>
+```python
+from subsurfer.core.controller.controller import SubSurferController
+import asyncio
+
+async def main():
+    controller = SubSurferController("vulnweb.com")
+    
+    # 서브도메인 수집 및 웹 서비스 스캔
+    subdomains = await controller.collect_subdomains()
+    web_services = await controller.scan_web_services(subdomains)
+    
+    # 결과 저장
+    results_dict = {
+        'subdomains': subdomains,
+        'web_services': web_services.get('web_services', {}),
+        'web_servers': web_services.get('web_servers', set()),
+        'enabled_services': web_services.get('enabled_services', set()),
+        'all_urls': web_services.get('all_urls', {})  # URL과 포트 정보 포함
+    }
+    
+    # 기본 결과 파일 경로 생성 (results 디렉토리에 저장)
+    output_path = controller.get_output_path()
+    controller.save_results(results_dict, output_path)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+<br>
+
+## 🧪 테스트
+### 패시브 핸들러 테스트
+`pytest tests/handlers/test_passive_handler.py -v`
+
+<br>
+
+### 액티브 핸들러 테스트
+`pytest tests/handlers/test_active_handler.py -v`
+
+<br>
+
+## 🗺️ ToDo
+### 0.2 버전
+- 새로운 패시브 모듈 추가
+
+### 0.3 버전
+- JSON 결과 출력 옵션 추가
+- 새로운 패시브 모듈 추가
+- 기타 기능 업데이트
+
+### 0.4 버전
+- 새로운 패시브 모듈 추가
+- 서브도메인 탈취 검사 기능
+
+### 0.5 버전
+- 새로운 패시브 모듈 추가
+- 새로운 액티브 모듈 추가
+
+## 📋 요구사항
+
+- Python 3.13.0 이상 권장
+- aiohttp
+- rich
+- pytest (테스트용)
+
+## 📝 라이선스
+MIT License
+
+## 🤝 기여
+Bug Report, Feature Suggestions, Pull Request

subsurfer-0.1.8/README.md

@@ -0,0 +1,198 @@
+# 🏄‍♂️ SubSurfer
+
+![Python Version](https://img.shields.io/badge/python-3.13%2B-blue)
+![License](https://img.shields.io/badge/license-MIT-green)
+![Version](https://img.shields.io/badge/version-0.1-orange)
+
+SubSurfer는 빠르고 효율적인 서브도메인 열거 및 웹 자산 식별 도구입니다.
+
+<br>
+
+## 🌟 특징
+- **레드팀/버그바운티 지원**: 레드팀 작전과 웹 버그바운티 프로젝트 모두에서 활용 가능
+- **고성능 스캔**: 비동기 및 병렬 처리를 통한 빠른 서브도메인 수집
+- **포트 스캔**: 사용자 정의 포트 범위로 자산 스캔 범위 확장
+- **웹 서비스 식별**: 웹 서버, 기술 스택 등 환경 정보 수집
+- **파이프라인 지원**: `-pipeweb`, `-pipesub` 옵션으로 다른 도구와의 연계 가능
+- **모듈형 설계**: Python 모듈로 import하여 사용 가능
+- **지속적 업데이트**: 새로운 passive/active 모듈 지속 추가 예정
+
+<br>
+
+## 🚀 설치
+<b>bash</b>
+```bash
+git clone https://github.com/arrester/subsurfer.git
+cd subsurfer
+```
+
+or <br>
+
+<b>Python</b>
+```bash
+pip install -r requirements.txt
+```
+
+<br>
+
+## 📖 사용법
+### CLI 모드
+<b>기본 스캔</b><br>
+`subsurfer -t vulnweb.com`
+
+<b>액티브 스캔 활성화</b><br>
+`subsurfer -t vulnweb.com -a`
+
+<b>포트 스캔 포함</b><br>
+`subsurfer -t vulnweb.com -dp` # 기본 포트 <br>
+`subsurfer -t vulnweb.com -p 80,443,8080-8090` # 사용자 정의 포트
+
+<b>파이프라인 출력</b><br>
+`subsurfer -t vulnweb.com -pipeweb` # 웹 서버 결과만 출력 <br>
+`subsurfer -t vulnweb.com -pipesub` # 서브도메인 결과만 출력
+
+### Python 모듈로 사용
+<b>Subdomain Scan</b><br>
+```python
+from subsurfer.core.controller.controller import SubSurferController
+import asyncio
+
+async def main():
+    controller = SubSurferController(
+        target="vulnweb.com",
+        verbose=1,
+        active=False            # Active Scan Option
+    )
+    
+    # 서브도메인 수집
+    subdomains = await controller.collect_subdomains()
+    
+    # 결과 출력
+    print(f"발견된 서브도메인: {len(subdomains)}개")
+    for subdomain in sorted(subdomains):
+        print(subdomain)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+<br>
+
+<b>Port Scan</b><br>
+```python
+from subsurfer.core.controller.controller import SubSurferController
+import asyncio
+
+async def main():
+    controller = SubSurferController(
+        target="vulnweb.com",
+        verbose=1
+    )
+    
+    # 서브도메인 수집
+    subdomains = await controller.collect_subdomains()
+    
+    # 기본 80, 443 스캔 설정
+    ports = None
+
+    # 포트 스캔 설정
+    # ports = controller.parse_ports()  # 기본 포트
+    # 또는 사용자 지정 포트
+    # ports = controller.parse_ports("80,443,8080-8090")
+    
+    # 웹 서비스 스캔
+    web_services = await controller.scan_web_services(subdomains, ports)
+    
+    # 웹 서버 출력
+    print("\n웹 서버:")
+    for server in sorted(web_services['web_servers']):
+        print(f"https://{server}")
+    
+    # 활성화된 서비스 출력    
+    print("\n활성화된 서비스:")
+    for service in sorted(web_services['enabled_services']):
+        print(service)
+        
+    # URL과 포트 정보 출력
+    print("\n발견된 URL:")
+    for subdomain, urls in web_services['all_urls'].items():
+        for url, port in urls:
+            print(f"{url}:{port}")
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+<br>
+
+<b>Result Save</b><br>
+```python
+from subsurfer.core.controller.controller import SubSurferController
+import asyncio
+
+async def main():
+    controller = SubSurferController("vulnweb.com")
+    
+    # 서브도메인 수집 및 웹 서비스 스캔
+    subdomains = await controller.collect_subdomains()
+    web_services = await controller.scan_web_services(subdomains)
+    
+    # 결과 저장
+    results_dict = {
+        'subdomains': subdomains,
+        'web_services': web_services.get('web_services', {}),
+        'web_servers': web_services.get('web_servers', set()),
+        'enabled_services': web_services.get('enabled_services', set()),
+        'all_urls': web_services.get('all_urls', {})  # URL과 포트 정보 포함
+    }
+    
+    # 기본 결과 파일 경로 생성 (results 디렉토리에 저장)
+    output_path = controller.get_output_path()
+    controller.save_results(results_dict, output_path)
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+<br>
+
+## 🧪 테스트
+### 패시브 핸들러 테스트
+`pytest tests/handlers/test_passive_handler.py -v`
+
+<br>
+
+### 액티브 핸들러 테스트
+`pytest tests/handlers/test_active_handler.py -v`
+
+<br>
+
+## 🗺️ ToDo
+### 0.2 버전
+- 새로운 패시브 모듈 추가
+
+### 0.3 버전
+- JSON 결과 출력 옵션 추가
+- 새로운 패시브 모듈 추가
+- 기타 기능 업데이트
+
+### 0.4 버전
+- 새로운 패시브 모듈 추가
+- 서브도메인 탈취 검사 기능
+
+### 0.5 버전
+- 새로운 패시브 모듈 추가
+- 새로운 액티브 모듈 추가
+
+## 📋 요구사항
+
+- Python 3.13.0 이상 권장
+- aiohttp
+- rich
+- pytest (테스트용)
+
+## 📝 라이선스
+MIT License
+
+## 🤝 기여
+Bug Report, Feature Suggestions, Pull Request

subsurfer-0.1.8/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

subsurfer-0.1.8/setup.py

@@ -0,0 +1,51 @@
+from setuptools import setup, find_namespace_packages
+
+setup(
+    name="subsurfer",
+    version="0.1.8",
+    description="Red Teaming and Web Bug Bounty Fast Asset Identification Tool",
+    long_description=open('README.md').read(),
+    long_description_content_type="text/markdown",
+    author="arrester",
+    author_email="arresterloyal@gmail.com",
+    url="https://github.com/arrester/subsurfer",
+    packages=find_namespace_packages(include=['subsurfer*']),
+    package_data={
+        'subsurfer': ['core/config/*.yaml'],
+    },
+    include_package_data=True,
+    install_requires=[
+        'rich>=13.7.0',
+        'aiohttp>=3.9.1',
+        'beautifulsoup4>=4.12.2',
+        'dnspython>=2.4.2',
+        'pyyaml>=6.0.1',
+        'asyncio>=3.4.3',
+        'pytest>=7.4.3',
+        'pytest-asyncio>=0.23.2',
+        'python-Wappalyzer>=0.3.1'
+    ],
+    entry_points={
+        'console_scripts': [
+            'subsurfer=subsurfer.__main__:run_main',
+        ],
+    },
+    python_requires='>=3.9',
+    classifiers=[
+        'Development Status :: 3 - Alpha',
+        'Intended Audience :: Information Technology',
+        'Intended Audience :: System Administrators',
+        'Topic :: Security',
+        'Topic :: Internet :: WWW/HTTP',
+        'License :: OSI Approved :: MIT License',
+        'Programming Language :: Python :: 3',
+        'Programming Language :: Python :: 3.13',
+        'Operating System :: OS Independent',
+    ],
+    keywords='security, subdomain enumeration, bug bounty, red team, web security',
+    project_urls={
+        'Bug Reports': 'https://github.com/arrester/subsurfer/issues',
+        'Source': 'https://github.com/arrester/subsurfer',
+        'Documentation': 'https://github.com/arrester/subsurfer#readme',
+    },
+) 

subsurfer-0.1.8/subsurfer/__init__.py

@@ -0,0 +1,5 @@
+"""
+SubSurfer - Red Teaming and Web Bug Bounty Fast Asset Identification Tool
+"""
+
+__version__ = "0.1.8"

subsurfer-0.1.8/subsurfer/__main__.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+SubSurfer main entry point
+"""
+
+from subsurfer.subsurfer import main
+import asyncio
+
+def run_main():
+    """Wrapper function to run the async main"""
+    asyncio.run(main())
+
+if __name__ == "__main__":
+    run_main() 

subsurfer-0.1.8/subsurfer/core/__init__.py

@@ -0,0 +1 @@
+# Empty file to make the directory a Python package

subsurfer-0.1.8/subsurfer/core/cli/__init__.py

@@ -0,0 +1 @@
+# Empty file to make the directory a Python package

subsurfer-0.1.8/subsurfer/core/cli/cli.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+
+"""
+CLI utilities module
+"""
+
+import sys
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+from rich.box import ROUNDED
+
+console = Console()
+
+def is_cli_mode():
+    """Check if running in CLI mode"""
+    return sys.stdin.isatty()
+
+def print_banner(force=False):
+    """Print banner only in CLI mode unless forced"""
+    if not is_cli_mode() and not force:
+        return
+        
+    banner = r"""
+    🏄‍♂️  SubSurfer  🌊 
+    ----------------------
+     _____         _      _____                __             
+    /  ___|       | |    /  ___|              / _|            
+    \ `--.  _   _ | |__  \ `--.  _   _  _ __ | |_   ___  _ __ 
+     `--. \| | | || '_ \  `--. \| | | || '__||  _| / _ \| '__|
+    /\__/ /| |_| || |_) |/\__/ /| |_| || |   | |  |  __/| |   
+    \____/  \__,_||_.__/ \____/  \__,_||_|   |_|   \___||_|   v0.1
+    """
+    
+    # 배너 패널 생성
+    banner_panel = Panel(
+        banner,
+        title="[bold cyan]Red Teaming and Web Bug Bounty Fast Asset Identification Tool[/]",
+        subtitle="[bold blue]by. arrester (https://github.com/arrester/subsurfer)[/]",
+        style="bold blue",
+        box=ROUNDED
+    )
+    console.print(banner_panel)
+
+def print_usage():
+    """Print usage information"""
+    usage_table = Table(
+        title="[bold cyan]SubSurfer Usage Guide[/]",
+        box=ROUNDED,
+        show_header=True,
+        header_style="bold magenta"
+    )
+    
+    # 테이블 컬럼 설정
+    usage_table.add_column("Command", style="cyan", justify="left")
+    usage_table.add_column("Description", style="white", justify="left")
+    usage_table.add_column("Example", style="green", justify="left")
+    
+    # 사용법 추가
+    usage_table.add_row(
+        "subsurfer -t <domain>",
+        "Scan single domain",
+        "subsurfer -t vulnweb.com"
+    )
+    usage_table.add_row(
+        "subsurfer -t <domain> -o <file>",
+        "Save results to file",
+        "subsurfer -t vulnweb.com -o results.txt"
+    )
+    usage_table.add_row(
+        "subsurfer -t <domain> -a",
+        "Enable active scanning",
+        "subsurfer -t vulnweb.com -a"
+    )
+    usage_table.add_row(
+        "subsurfer -t <domain> -v",
+        "Increase output verbosity",
+        "subsurfer -t vulnweb.com -v"
+    )
+    
+    # 옵션 테이블 생성
+    options_table = Table(
+        title="[bold cyan]Available Options[/]",
+        box=ROUNDED,
+        show_header=True,
+        header_style="bold magenta"
+    )
+    
+    # 옵션 테이블 컬럼 설정
+    options_table.add_column("Option", style="cyan", justify="left")
+    options_table.add_column("Description", style="white", justify="left")
+    
+    # 옵션 추가 (현재 구현된 옵션들만)
+    options_table.add_row("-h, --help", "Show this help message")
+    options_table.add_row("-t, --target", "Target domain (e.g. vulnweb.com)")
+    options_table.add_row("-o, --output", "Output file to save results")
+    options_table.add_row("-v, --verbose", "Increase output verbosity (-v, -vv, -vvv)")
+    options_table.add_row("-a, --active", "Enable active scanning (default: passive only)")
+    options_table.add_row("-dp, --default-ports", "Scan default ports")
+    options_table.add_row("-p, --port", "Custom port range (e.g. 1-65535)")
+    options_table.add_row("-pipeweb", "Output web server results for pipeline")
+    options_table.add_row("-pipesub", "Output subdomain results for pipeline")
+    options_table.add_row("-to, --takeover", "[Coming Soon] Subdomain takeover detection")
+    
+    # 출력
+    console.print("\n[bold cyan]Description:[/]")
+    console.print("SubSurfer is a fast subdomain enumeration tool that combines both passive and active scanning techniques to discover subdomains of a target domain.\n")
+    
+    console.print(usage_table)
+    console.print("\n")
+    console.print(options_table)
+    console.print("\n[bold cyan]Note:[/] Some scanners may require API keys. Configure them in config.yaml")
+    console.print("[bold yellow]Coming Soon:[/] Subdomain takeover detection will be available in the next version!\n")
+
+def print_status(message, status="info", cli_only=True):
+    """Print status messages with color coding"""
+    if cli_only and not is_cli_mode():
+        return
+        
+    colors = {
+        "info": "blue",
+        "success": "green",
+        "warning": "yellow", 
+        "error": "red"
+    }
+    
+    # 상태 아이콘 추가
+    icons = {
+        "info": "ℹ️",
+        "success": "✅",
+        "warning": "⚠️",
+        "error": "❌"
+    }
+    
+    console.print(f"[bold {colors[status]}]{icons[status]} {message}[/]")
+
+def main():
+    """Main entry point for CLI"""
+    if len(sys.argv) == 1:
+        print_banner(force=True)
+        print_usage()
+        sys.exit(0)
+
+if __name__ == "__main__":
+    main()