一個功能豐富的 Python 網路診斷工具，結合 nmap 強大功能與現代化介面，提供完整的 traceroute 解決方案。
- 🚀 靈活的協定支援: 支援 TCP 和 UDP 協定的 traceroute
- 🔍 多端口掃描: 可同時掃描多個端口，支援端口範圍
- 📊 豐富的輸出格式: 終端顯示、CSV 檔案、HTML 報告
- 📈 美觀的視覺化: 使用 Rich 庫生成美觀的表格和圖表
- 🔄 批量掃描: 支援從檔案讀取多個目標進行批量掃描
- 🔄 即時監測: 持續監控網路狀態，即時顯示路由變化
- 📈 統計分析: 提供成功率、回應時間、跳點穩定性等詳細統計
- ⚡ 高效能設計: 模組化架構，支援並行掃描和非阻塞操作
- 🎛️ 互動式控制: 支援實時控制和狀態查詢
- 📋 增強版報告: 包含趨勢分析、跳點行為分析的詳細報告
- 🔒 輸入驗證: 完整的參數驗證和錯誤處理
- 🚦 防護機制: 自動防止掃描重疊和資源濫用
- 📝 詳細日誌: 完整的操作記錄和除錯資訊
- 🔧 容錯設計: 優雅處理網路異常和系統錯誤
graph TB
A[🎯 CLI Interface<br/>argument_parser.py] --> B[🔧 Core Scanner<br/>traceroute_scanner.py]
A --> C[⏰ Realtime Monitor<br/>realtime_monitor.py]
B --> D[⚙️ nmap Executor<br/>nmap_executor.py]
B --> E[📊 Result Parser<br/>result_parser.py]
B --> F[✅ Validators<br/>validators.py]
B --> G[📋 Models]
G --> G1[🎯 HopData<br/>hop_data.py]
G --> G2[📊 ScanResult<br/>scan_result.py]
B --> H[📤 Output Modules]
H --> H1[📄 CSV Writer<br/>csv_writer.py]
H --> H2[📊 Table Chart<br/>table_chart.py]
I[⚙️ Configuration<br/>default_settings.py] --> A
J[🧪 Tests] --> B
K[📖 Examples] --> B
L[📚 Documentation] --> A
style A fill:#e1f5fe
style B fill:#f3e5f5
style C fill:#fff3e0
style G fill:#e8f5e8
style H fill:#fce4ec
graph LR
A[main.py] --> B[TracerouteScanner]
A --> C[RealtimeMonitor]
A --> D[ArgumentParser]
B --> E[NmapExecutor]
B --> F[ResultParser]
B --> G[Models]
C --> B
C --> H[Statistics]
I[OutputModules] --> J[CSVWriter]
I --> K[TableChart]
B --> I
C --> I
- 核心語言: Python 3.12+
- 網路掃描: nmap
- CLI 介面: Click
- 資料處理: Pandas, Pydantic
- 視覺化: Rich, Tabulate
- 日誌系統: Loguru
- 測試框架: pytest
- Python: 3.12 或更新版本
- nmap: 已安裝並在 PATH 中
- 作業系統: Windows, Linux, macOS
# Windows - 從官方網站下載安裝程式
# https://nmap.org/download.html
# Linux (Ubuntu/Debian)
sudo apt-get update && sudo apt-get install nmap
# Linux (CentOS/RHEL)
sudo yum install nmap
# macOS (使用 Homebrew)
brew install nmap
# macOS (使用 MacPorts)
sudo port install nmap# 使用 uv 安裝 (推薦)
uv add rich click pandas tabulate pydantic loguru
uv sync
# 或使用 pip
pip install rich click pandas tabulate pydantic loguru# 測試 nmap 安裝
uv run python main.py --test-nmap
# 檢查 Python 版本
python --version# 🎯 基本掃描 - 追蹤到目標的路徑
uv run python main.py -t 8.8.8.8 -p 443 --protocol tcp --show-chart
# 🔍 多端口掃描 - 掃描常見服務端口
uv run python main.py -t github.com -p 80,443,22 --save-html
# 📦 批量掃描 - 從檔案讀取目標清單
uv run python main.py -f examples/targets.txt --output-csv batch_results.csv
# 🌐 UDP 掃描 - DNS 服務檢測
uv run python main.py -t 8.8.8.8 -p 53 --protocol udp --timeout 60
# ⏰ 即時監測 - 持續監控網路狀態
uv run python main.py -t cloudflare.com -p 443 --monitor --interval 30Usage: uv run python main.py [OPTIONS]
🎯 目標選項:
-t, --target TEXT 目標主機 (IP 或域名)
-f, --targets-file PATH 批量掃描目標檔案
🔌 網路選項:
-p, --ports TEXT 端口 (單一、多個或範圍: 80,443 或 1-1000, 預設 33434)
--protocol [tcp|udp] 使用的協定 (預設: udp)
--max-hops INTEGER 最大跳點數 (預設: 30)
--timeout INTEGER 超時時間秒數 (預設: 30)
📤 輸出選項:
--output-csv PATH 輸出 CSV 檔案路徑
--output-dir PATH 輸出目錄 (預設: output_data/)
--show-chart 顯示美觀的表格圖表
--save-html 儲存互動式 HTML 報告
⏰ 監測選項:
--monitor 啟用即時監測模式
--interval INTEGER 監測間隔秒數 (預設: 5, 建議 ≥10)
--max-history INTEGER 最大歷史記錄數 (預設: 100)
🔧 其他選項:
--verbose 詳細輸出模式
--quiet 安靜模式 (只輸出結果)
--test-nmap 測試 nmap 安裝狀態
--help 顯示完整說明
# 基本掃描
uv run python main.py -t example.com -p 443
# 詳細輸出
uv run python main.py -t 8.8.8.8 -p 53 --verbose --show-chart# 建立目標檔案 targets.txt
echo "8.8.8.8
1.1.1.1
cloudflare.com
github.com" > targets.txt
# 執行批量掃描
uv run python main.py -f targets.txt -p 443 --output-csv results.csv# 基本監測
uv run python main.py -t github.com -p 443 --monitor
# 自訂監測參數
uv run python main.py -t 8.8.8.8 -p 53 --monitor --interval 60 --max-history 200
# 靜默監測
uv run python main.py -t example.com -p 80 --monitor --quiet --interval 30from core.traceroute_scanner import TracerouteScanner
from output.csv_writer import CSVWriter
from output.table_chart import TableChart
# 🚀 建立掃描器
scanner = TracerouteScanner(
protocol="tcp",
max_hops=30,
timeout=30,
verbose=True
)
# 🎯 單一目標掃描
result = scanner.scan_target("github.com", 443)
print(f"掃描完成: {result.target}:{result.port}")
# 📊 獲取統計資訊
stats = result.get_statistics()
print(f"總跳點: {stats['total_hops']}")
print(f"到達目標: {stats['target_reached']}")
print(f"平均延遲: {stats['avg_rtt']:.2f}ms")# 📦 批量掃描
targets = ["google.com", "github.com", "stackoverflow.com"]
results = scanner.scan_multiple_targets(targets, ports=[80, 443])
for result in results:
stats = result.get_statistics()
status = "✅" if stats['target_reached'] else "❌"
print(f"{status} {result.target} - {stats['total_hops']} 跳點")
# 📄 輸出處理
csv_writer = CSVWriter("output_data/csv")
table_chart = TableChart("output_data/charts")
# 儲存結果
csv_file = csv_writer.write_scan_result(result, "scan_result.csv")
html_file = table_chart.save_html_report(result, "scan_report.html")
# 顯示表格
table_chart.display_scan_result(result)from core.realtime_monitor import RealtimeMonitor
# ⏰ 建立監測器
monitor = RealtimeMonitor(
target="8.8.8.8",
port=53,
protocol="tcp",
interval=10,
max_history=100
)
# 📊 設定回調函數
def on_scan_complete(result):
stats = result.get_statistics()
print(f"掃描完成: {stats['total_hops']} 跳點")
def on_status_change(is_reachable):
status = "✅ 可達" if is_reachable else "❌ 不可達"
print(f"狀態變化: {status}")
monitor.on_scan_complete = on_scan_complete
monitor.on_status_change = on_status_change
# 🚀 開始監測
try:
monitor.start_monitoring(display_live=True)
except KeyboardInterrupt:
monitor.stop_monitoring()
# 📈 獲取最終統計
final_stats = monitor.get_current_stats()
print(f"監測完成 - 成功率: {final_stats.success_rate:.1f}%")# 診斷到重要服務的連線品質
uv run python main.py -t github.com -p 443 --protocol tcp --show-chart --save-html
# 檢查 DNS 解析路徑
uv run python main.py -t 8.8.8.8 -p 53 --protocol udp --verbose預期輸出:
🎯 掃描目標: github.com:443 (TCP)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
┌─────┬─────────────────┬──────────────────────────────┬─────────────┬──────────┐
│ Hop │ IP Address │ Hostname │ RTT (ms) │ Status │
├─────┼─────────────────┼──────────────────────────────┼─────────────┼──────────┤
│ 1 │ 192.168.1.1 │ gateway.local │ 1.234 │ success │
│ 2 │ 10.0.0.1 │ isp-gateway.example.com │ 12.567 │ success │
│ 3 │ 203.69.123.45 │ router.telecom.tw │ 25.891 │ success │
│ ... │ ... │ ... │ ... │ ... │
│ 15 │ 140.82.112.4 │ github.com │ 45.123 │ success │
└─────┴─────────────────┴──────────────────────────────┴─────────────┴──────────┘
📊 統計摘要:
• 總跳點數: 15
• 目標到達: ✅ 是
• 平均延遲: 28.45 ms
• 最大延遲: 67.89 ms
• 掃描時間: 12.3 秒
📄 報告已儲存: output_data/charts/github_com_443_20250603_153045.html
# 監測關鍵服務的可用性
uv run python main.py -t api.example.com -p 443 --monitor --interval 60 --max-history 1440監測功能特色:
- 🔄 持續監控: 24/7 監控服務可用性
- 📊 實時統計: 即時顯示成功率和回應時間
- 📈 趨勢分析: 自動檢測和報告性能趨勢
⚠️ 異常警報: 自動檢測路由變化和連線問題- 💾 數據保存: 自動儲存詳細監測記錄
# 建立目標清單
cat > audit_targets.txt << EOF
production-api.company.com
backup-server.company.com
cdn.company.com
database.company.com
mail.company.com
EOF
# 執行批量審計
uv run python main.py -f audit_targets.txt -p 80,443,22 --output-csv audit_results.csv --save-html#!/usr/bin/env python3
"""多協定比較範例"""
from core.traceroute_scanner import TracerouteScanner
def compare_protocols(target, port):
"""比較 TCP 和 UDP 協定的路由差異"""
protocols = ["tcp", "udp"]
results = {}
for protocol in protocols:
scanner = TracerouteScanner(protocol=protocol, timeout=60)
try:
result = scanner.scan_target(target, port)
results[protocol] = result.get_statistics()
except Exception as e:
print(f"{protocol.upper()} 掃描失敗: {e}")
results[protocol] = None
# 比較結果
print(f"\n🔍 {target}:{port} 協定比較")
print("─" * 50)
for protocol, stats in results.items():
if stats:
print(f"{protocol.upper()}: {stats['total_hops']} 跳點, "
f"平均延遲: {stats['avg_rtt']:.2f}ms")
else:
print(f"{protocol.upper()}: 掃描失敗")
# 使用範例
compare_protocols("8.8.8.8", 53)| 指標 | 數值 | 說明 |
|---|---|---|
| 掃描速度 | 5-15 秒/目標 | 依網路條件和跳點數而定 |
| 記憶體使用 | < 50MB | 基本掃描模式 |
| 並行掃描 | 最多 10 個 | 可設定的並行數量 |
| 歷史記錄 | 無限制 | 受系統記憶體限制 |
| 檔案輸出 | > 1000 筆/秒 | CSV 寫入效能 |
| 特性 | nmapTraceroute | 傳統 traceroute | nmap 純命令 |
|---|---|---|---|
| 協定支援 | ✅ TCP/UDP | ❌ ICMP only | ✅ TCP/UDP |
| 批量掃描 | ✅ 完整支援 | ❌ 無 | ❌ 有限 |
| 即時監測 | ✅ 進階功能 | ❌ 無 | ❌ 無 |
| 視覺化輸出 | ✅ Rich 表格 | ❌ 純文字 | ❌ 純文字 |
| 程式化API | ✅ 完整API | ❌ 無 | ❌ 無 |
| 統計分析 | ✅ 詳細統計 | ❌ 基本 | ❌ 無 |
| 跨平台 | ✅ Windows/Linux/macOS | ✅ 限制性 | ✅ 全平台 |
# 執行效能測試
uv run python examples/benchmark.py
# 典型結果:
# 單目標掃描: 8.2 秒 (15 跳點)
# 批量掃描 (10 目標): 45.6 秒
# 記憶體峰值: 42MB
# CSV 輸出: 1,250 筆/秒# config/custom_settings.py
from config.default_settings import DefaultSettings
class CustomSettings(DefaultSettings):
"""自訂設定類別"""
# 網路設定
DEFAULT_TIMEOUT = 45
MAX_HOPS = 25
RETRY_COUNT = 3
# 輸出設定
CSV_DELIMITER = ";"
HTML_THEME = "dark"
CHART_WIDTH = 1200
# 監測設定
MIN_INTERVAL = 15
MAX_HISTORY = 500
AUTO_SAVE_INTERVAL = 300
# nmap 進階選項
NMAP_EXTRA_ARGS = [
"--source-port", "53",
"--data-length", "32"
]from core.traceroute_scanner import TracerouteScanner
# 建立高級掃描器
scanner = TracerouteScanner(
protocol="tcp",
max_hops=20,
timeout=60,
# 進階選項
extra_nmap_args=[
"--source-port", "53", # 指定來源端口
"--ttl", "255", # 設定 TTL
"--data-length", "64" # 資料包大小
],
# 重試機制
retry_count=3,
retry_delay=5,
# 並行設定
parallel_scans=5,
thread_pool_size=10
)from loguru import logger
import sys
# 自訂日誌格式
logger.remove()
logger.add(
sys.stderr,
format="<green>{time:YYYY-MM-DD HH:mm:ss}</green> | "
"<level>{level: <8}</level> | "
"<cyan>{name}</cyan>:<cyan>{function}</cyan>:<cyan>{line}</cyan> | "
"<level>{message}</level>",
level="INFO"
)
# 檔案日誌
logger.add(
"logs/nmaptraceroute_{time:YYYY-MM-DD}.log",
rotation="1 day",
retention="30 days",
compression="zip",
level="DEBUG"
)# plugins/custom_output.py
from abc import ABC, abstractmethod
class OutputPlugin(ABC):
"""輸出外掛基底類別"""
@abstractmethod
def process_result(self, result):
"""處理掃描結果"""
pass
class SlackNotificationPlugin(OutputPlugin):
"""Slack 通知外掛"""
def __init__(self, webhook_url):
self.webhook_url = webhook_url
def process_result(self, result):
stats = result.get_statistics()
if not stats['target_reached']:
self.send_alert(f"目標 {result.target} 不可達!")
def send_alert(self, message):
# 實作 Slack 通知邏輯
pass
# 使用外掛
scanner = TracerouteScanner()
scanner.add_plugin(SlackNotificationPlugin("webhook_url"))問題: nmap 未安裝或不在 PATH 中
# 解決方案:
# Windows: 確保 nmap.exe 在 PATH 中
set PATH=%PATH%;C:\Program Files\Nmap
# Linux: 安裝 nmap
sudo apt-get install nmap
# macOS: 使用 Homebrew
brew install nmap
# 驗證安裝
nmap --version問題: 權限不足，無法執行原始套接字操作
# Linux/macOS 解決方案:
sudo uv run python main.py -t example.com -p 80
# 或使用 TCP connect 掃描 (無需 root)
uv run python main.py -t example.com -p 80 --protocol tcp問題: 目標不可達或被防火牆封鎖
# 診斷步驟:
# 1. 檢查基本連線
ping 8.8.8.8
# 2. 測試不同協定
uv run python main.py -t 8.8.8.8 -p 53 --protocol udp
uv run python main.py -t 8.8.8.8 -p 53 --protocol tcp
# 3. 增加超時時間
uv run python main.py -t example.com -p 80 --timeout 120
# 4. 詳細除錯
uv run python main.py -t example.com -p 80 --verbose問題: 掃描速度過慢
# 最佳化建議:
scanner = TracerouteScanner(
timeout=30, # 減少超時時間
max_hops=20, # 限制最大跳點
parallel_scans=3 # 啟用並行掃描
)
# 批量掃描最佳化
targets = ["host1", "host2", "host3"]
results = scanner.scan_multiple_targets(
targets,
ports=[80, 443],
batch_size=5, # 批次處理
delay_between_batches=2
)問題: 監測被意外中斷或跳過掃描
# 解決方案:
# 1. 增加監測間隔
uv run python main.py -t example.com -p 80 --monitor --interval 15
# 2. 檢查系統資源
uv run python main.py -t example.com -p 80 --monitor --verbose
# 3. 使用較短的超時時間
uv run python main.py -t example.com -p 80 --monitor --timeout 20# 1. 系統診斷
uv run python main.py --test-nmap
# 2. 詳細日誌
uv run python main.py -t example.com -p 80 --verbose
# 3. 乾執行模式 (不實際掃描)
uv run python main.py -t example.com -p 80 --dry-run
# 4. 效能分析
uv run python main.py -t example.com -p 80 --profile# 生成診斷報告
from utils.diagnostics import SystemDiagnostics
diag = SystemDiagnostics()
report = diag.generate_report()
print("=== 系統診斷報告 ===")
print(f"Python 版本: {report['python_version']}")
print(f"nmap 版本: {report['nmap_version']}")
print(f"可用記憶體: {report['available_memory']}MB")
print(f"網路介面: {report['network_interfaces']}")
print(f"作業系統: {report['os_info']}")# 1. 複製專案
git clone https://github.com/yourusername/nmapTraceroute.git
cd nmapTraceroute
# 2. 安裝開發依賴
uv add --dev pytest pytest-cov black isort mypy
uv add --dev sphinx sphinx-rtd-theme
uv sync
# 3. 安裝 pre-commit hooks
pip install pre-commit
pre-commit install
# 4. 執行測試
uv run pytest tests/ -v --cov=core# 完整測試套件
uv run pytest tests/ -v
# 單元測試
uv run pytest tests/test_traceroute_scanner.py
# 整合測試
uv run pytest tests/test_integration.py
# 效能測試
uv run pytest tests/test_performance.py --benchmark
# 測試涵蓋率
uv run pytest --cov=core --cov-report=html
open htmlcov/index.htmlnmapTraceroute/
├── 📁 core/ # 核心模組
│ ├── traceroute_scanner.py # 主掃描器 (300+ 行)
│ └── realtime_monitor.py # 即時監測 (250+ 行)
│
├── 📁 utils/ # 工具模組
│ ├── nmap_executor.py # nmap 執行 (200+ 行)
│ ├── result_parser.py # 結果解析 (180+ 行)
│ └── validators.py # 輸入驗證 (120+ 行)
│
├── 📁 models/ # 資料模型
│ ├── hop_data.py # 跳點資料結構
│ └── scan_result.py # 掃描結果結構
│
├── 📁 output/ # 輸出模組
│ ├── csv_writer.py # CSV 輸出 (150+ 行)
│ └── table_chart.py # 表格圖表 (200+ 行)
│
├── 📁 cli/ # 命令列介面
│ └── argument_parser.py # 參數解析 (100+ 行)
│
├── 📁 config/ # 配置模組
│ └── default_settings.py # 預設設定
│
├── 📁 tests/ # 測試模組
│ ├── test_basic_functionality.py
│ ├── test_monitor.py
│ └── ...
│
├── 📁 examples/ # 使用範例
│ ├── basic_usage.py # 基本使用範例
│ ├── realtime_monitoring.py # 即時監測範例
│ └── targets.txt # 範例目標清單
│
├── 📁 docs/ # 文件
│ ├── PROJECT_ARCHITECTURE.md # 架構文件
│ ├── perpose.md # 專案目的
│ └── API.md # API 文件
│
└── 📁 output_data/ # 輸出目錄
├── csv/ # CSV 檔案
├── charts/ # 圖表檔案
└── logs/ # 日誌檔案
-
Fork 專案 並建立功能分支
git checkout -b feature/awesome-new-feature
-
實作功能 並遵循程式碼規範
# 程式碼格式化 black . --line-length 88 isort . --profile black # 型別檢查 mypy core/ utils/ models/
-
撰寫測試 確保功能正確性
# tests/test_new_feature.py def test_awesome_feature(): scanner = TracerouteScanner() result = scanner.awesome_method() assert result.is_awesome()
-
提交變更 並推送到遠端
git commit -m "feat: add awesome new feature" git push origin feature/awesome-new-feature -
建立 Pull Request 並等待審核
- Python 風格: 遵循 PEP 8 和 Black 格式
- 註解語言: 繁體中文註解，英文變數名稱
- 測試覆蓋: 新功能必須達到 80% 以上覆蓋率
- 文件更新: 重要功能需同步更新 README 和 API 文件
<類型>(<範圍>): <簡短描述>
<詳細描述>
<相關 issue 或 PR>
類型選項:
feat: 新功能fix: 錯誤修復docs: 文件更新style: 程式碼格式調整refactor: 程式碼重構test: 測試相關chore: 建置或工具相關
- WebUI 介面: 基於 FastAPI 的 Web 管理介面
- 資料庫支援: 持久化儲存監測記錄
- API 端點: RESTful API 支援
- 效能優化: 非同步掃描和快取機制
- 進階視覺化: 互動式路由圖表
- 機器學習: 異常檢測和預測分析
- 分散式掃描: 多節點協作掃描
- 容器化: Docker 和 Kubernetes 支援
- 雲端整合: AWS/Azure/GCP 整合
- 行動應用: 手機 APP 支援
- 企業功能: RBAC、審計日誌、合規報告
- 國際化: 多語言支援
此專案採用 MIT 授權條款，詳細內容請參閱 LICENSE 檔案。
本專案使用了以下優秀的開源套件：
- nmap: GPL-2.0 License
- Rich: MIT License
- Click: BSD-3-Clause License
- Pandas: BSD-3-Clause License
- Loguru: MIT License
- 🌍 nmap 官方網站
- 📚 nmap 參考手冊
- 🐍 Python Rich 文件
- 🔧 網路診斷最佳實踐
# 🚀 完整功能演示
uv run python demo_all_features.py
# 📖 互動式教學
uv run python examples/interactive_tutorial.py
# 🧪 效能基準測試
uv run python examples/benchmark_suite.py- ✨ 新增即時監測功能: 持續監控網路狀態和路由變化
- 📊 增強版 CSV 報告: 詳細統計、趨勢分析、跳點行為分析
- 📈 互動式 HTML 報告: 包含圖表、視覺化和深入分析
- 🔄 防護機制: 自動防止掃描重疊和資源衝突
- ⌨️ 改進中斷處理: 優雅的 Ctrl+C 處理和清理機制
- 🎯 優化 nmap 參數: 提升掃描精確度和效率
- 📋 跳點穩定性分析: 檢測和報告路由穩定性
- 🚀 效能優化: 記憶體使用優化和並行處理改進
- 🎯 基礎功能: TCP/UDP traceroute 支援
- 📄 CSV 輸出: 結構化資料匯出功能
- 📊 HTML 報告: 美觀的網頁報告生成
- 📦 批量掃描: 多目標批次處理支援
- 📈 表格顯示: Rich 美化的終端表格輸出
- 🔧 命令列介面: 完整的 CLI 參數支援
- 🏗️ 模組化架構: 可擴展的程式設計架構
🌟 如果這個專案對您有幫助，請給我們一個 Star！
💬 有問題或建議嗎？歡迎提出 Issue 或 Pull Request！
使用 ❤️ 和 ☕ 在台灣開發 | Made with ❤️ and ☕ in Taiwan