F0CUSMSK/PortScanner
GitHub: F0CUSMSK/PortScanner
一个基于 Python 标准库的友好型端口扫描工具，旨在帮助初学者通过实践学习计算机网络与多线程编程知识。
Stars: 0 | Forks: 0
# 🔍 PortScanner - 了解网络是如何工作的！
一个**友好且具教育意义**的端口扫描器，能让你在使用过程中学习网络知识！
你可以把它想象成一个“网络侦探”，敲击各个门（端口）看看哪些会有回应。
## ✨ 功能
- **快速并行扫描** - 同时扫描多个主机和端口
- **服务检测** - 识别开放端口上运行的服务
- **多种导出格式** - JSON, TXT 和 HTML 报告
- **专业的日志记录** - 彩色控制台输出和文件日志
- **教育导向** - 学习网络、socket 和线程知识
- **无外部依赖** - 仅使用 Python 标准库
## 📦 安装与快速开始
### 前置条件：Python 3.7+
检查你的 Python 版本：
```
python3 --version
```
### 选项 1：快速运行（免安装）
```
# 克隆仓库
git clone https://github.com/yourusername/portscanner.git
cd portscanner
# 在 interactive mode 下运行
python3 main.py --interactive
```
### 选项 2：安装包
```
git clone https://github.com/yourusername/portscanner.git
cd portscanner
pip install -e .
```
**无需使用 pip 安装依赖！** 我们仅使用 Python 的标准库。
👉 **[查看 GETTING_STARTED.md 获取详细说明](GETTING_STARTED.md)**
## 🎓 教育价值
本项目教你学习：
- **Socket 与 TCP/IP** - 网络连接是如何工作的
- **Threading** - 用于提升速度的并行处理
- **端口状态** - OPEN, CLOSED, FILTERED 概念
- **服务检测** - 端口到服务的映射（IANA 标准）
- **CLI 开发** - 命令行参数解析
- **专业代码** - 类型提示、文档和错误处理
## ⚠️ 重要免责声明
**本工具仅供教育目的使用。**
- ✅ 扫描你自己的网络
- ✅ 在获得明确的书面许可后进行扫描
- ✅ 学习网络概念
- ❌ 未经许可，请勿扫描他人的网络
- ❌ 请勿用于恶意目的
- ❌ 未经授权的网络扫描可能是违法的
## 🚀 快速开始（只需 5 分钟！）
### 1️⃣ 不知道从何开始？
**试试交互模式！** 它会问你一些友好的问题：
```
python main.py --interactive
```
如果你是新手，这非常完美——只需回答问题，剩下的交给我们！
### 2️⃣ 知道自己想要什么？
```
# 扫描你的计算机（最容易测试）
python main.py --target 127.0.0.1 --ports 1-1000
# 扫描你的家庭网络（请先征求许可！）
python main.py --target 192.168.1.1 --ports 1-1000
# 同时扫描多台计算机
python main.py --target 192.168.1.1,192.168.1.2 --ports 1-1000
```
就是这样！它会显示哪些端口是“开放的”（有服务响应），并告诉你可能正在运行哪些服务。
## 📚 新手指南
### 什么是“端口”？
假设你的电脑是一栋公寓楼：
- 电脑就是这栋楼
- 端口就像是门（编号为 1-65535）
- 有些门后有服务（SSH, HTTP 等）
- 有些门是锁着的（关闭的端口）
- 有些被保安挡住了（防火墙/被过滤的）
**常见端口示例：**
- 端口 22: SSH（安全的远程登录）
- 端口 80: HTTP（网站）
- 端口 443: HTTPS（安全网站）
- 端口 3306: MySQL（数据库）
### 当你运行扫描时会发生什么？
```
1. You tell us which computer to scan (IP address)
2. We send small "hello" messages to each port
3. If a port says "hello back!" → It's OPEN ✓
4. If it says "go away!" → It's CLOSED ✗
5. If it doesn't answer → It's FILTERED (firewall blocking)
6. We create a nice report showing what we found
```
### 运行你的第一次扫描
**步骤 1：找到一个要扫描的 IP**
最安全的扫描 IP 是你自己的电脑：
```
# Windows：打开 Command Prompt
ipconfig
# Mac/Linux：打开 Terminal
ifconfig
```
寻找类似于 `192.168.x.x` 或 `10.0.0.x` 的 IP
**步骤 2：运行扫描**
```
python main.py --target YOUR_IP_HERE --ports 1-1000
```
将 `YOUR_IP_HERE` 替换为你找到的 IP。
**步骤 3：等待结果**
你会看到一个进度条。完成后，它会为你显示开放的端口！
**步骤 4：查看报告**
在 `reports/` 文件夹中查看：
- `scan_*.html` - 精美报告（可在浏览器中打开！）
- `scan_*.txt` - 简单的文本版本
- `scan_*.json` - 用于分析的数据
## 🤔 常见问题 (FAQ)
### “我会用这个弄坏什么东西吗？”
不会！这个工具只会：
- 发送连接尝试（就像敲门一样）
- 不会利用任何漏洞
- 不会发送恶意数据
- 不会修改任何东西
它是完全安全且只读的。
### “如果我不知道 IP 地址怎么办？”
**选项 1：** 查找你自己的 IP：
```
# Windows
ipconfig
# Mac/Linux
ifconfig
```
**选项 2：** 扫描你的本地网络：
```
python main.py --target 192.168.1.1 --ports 1-1000
```
### “为什么有些扫描需要更长的时间？”
端口扫描需要时间，因为我们正在：
- 并行连接到许多端口（多线程）
- 等待响应（默认超时 = 2 秒）
- 检查的端口越多 = 耗时越长
**让它更快：**
```
python main.py --target 192.168.1.1 --ports 1-1000 --threads 100 --timeout 1.0
```
### “我应该扫描什么？”
**合适的目标（你拥有它们）：**
- ✅ 你自己的电脑 (127.0.0.1)
- ✅ 你的家庭网络（需获得允许）
- ✅ 实验室设备（在学校/培训中）
- ✅ 你搭建的测试服务器
**不合适的目标（需先获得许可）：**
- ❌ 朋友的电脑
- ❌ 学校的网络
- ❌ 公司的网络
- ❌ 互联网上的随机 IP 地址
### “这些颜色代表什么？”
```
🟢 Green = Good/Success
🔴 Red = Problem/Error
🟡 Yellow = Warning
🔵 Blue = Information
```
### “为什么它显示 OPEN, CLOSED, FILTERED？**
- **OPEN** 🟢: 服务正在监听，我们成功连接了！
- **CLOSED** 🔴: 端口存在，但没有程序在监听
- **FILTERED** 🟡: 防火墙阻止了我们的尝试（无响应）
### “我可以扫描一个网站吗？”
**技术上是可以的，但是：**
- 你需要该网站的 IP 地址
- 网站所有者可能设置了防火墙
- 你可能会触发安全警报
- **务必先获得许可！**
```
# 查找网站的 IP
nslookup google.com # Windows
dig google.com # Mac/Linux
# 但未经许可请勿扫描！
```
### “我遇到了错误。该怎么办？”
常见错误及解决方法：
**“Invalid IP address”**
```
❌ python main.py --target "hello.world"
✅ python main.py --target 192.168.1.1
```
**“Port range invalid”**
```
❌ python main.py --ports 500-200 (start > end)
✅ python main.py --ports 200-500
```
**“Need admin/root for ports 1-1023”**
```
# Windows：以 Administrator 身份运行
# Mac/Linux：
sudo python3 main.py --target 192.168.1.1 --ports 1-1023
```
### “如何从文件中读取进行扫描？”
创建一个名为 `targets.txt` 的文件：
```
192.168.1.1
192.168.1.2
192.168.1.3
# 你可以使用 # 添加注释
192.168.1.4
```
然后：
```
python main.py --file targets.txt --ports 1-1000
```
### “如果我想扫描很多端口怎么办？”
```
# 扫描所有 65535 个端口（每台计算机大约需要 30 秒）
python main.py --target 192.168.1.1 --ports all
# 或者指定一个大范围
python main.py --target 192.168.1.1 --ports 1-65535
```
## 📖 学习路径
### 级别 1：初学者
- [ ] 运行交互模式：`python main.py --interactive`
- [ ] 扫描你自己的电脑：`python main.py --target 127.0.0.1`
- [ ] 查看 `reports/` 文件夹中的 HTML 报告
- [ ] 阅读代码和注释
### 级别 2：中级
- [ ] 扫描你的家庭网络
- [ ] 了解不同端口上运行的服务
- [ ] 查看 JSON 报告以了解数据格式
- [ ] 修改代码以添加自定义消息
### 级别 3：高级
- [ ] 研究 `host_scanner.py` 中的线程架构
- [ ] 理解 `port_scanner.py` 中 socket 的工作原理
- [ ] 添加新功能（Banner 抓取、UDP 扫描等）
- [ ] 将数据用于分析/自动化
## 🏗️ 工作原理（简版）
### 全局概览
```
1. You run: python main.py --target 192.168.1.1
2. We ask: "What IP? What ports? How many threads?"
3. We check: "Are these valid? Do these files exist?"
4. We scan: "Hello port 22? Port 80? Port 443?"
(We do this 50 at a time to be fast)
5. We identify: "Port 22 is open → SSH service"
6. We report: "Found 3 open ports! Here's an HTML report"
7. Done! You can view the report in your browser
```
### 线程 - 为什么它这么快
**没有线程（慢）：**
```
Port 1: Check, wait 2 seconds
Port 2: Check, wait 2 seconds
Port 3: Check, wait 2 seconds
...
Total: 2000 seconds for 1000 ports 😴
```
**使用线程（快 - 我们的方式）：**
```
Ports 1-50: Check all at once, wait 2 seconds
Ports 51-100: Check all at once, wait 2 seconds
...
Total: 40 seconds for 1000 ports ⚡
```
我们使用了一种叫做 **ThreadPoolExecutor** 的机制，就像有 50 个工人同时在检查端口一样！
## 📖 命令行选项
### 必填项（其中之一）：
```
--target, -t IP Single IP or comma-separated (192.168.1.1,192.168.1.2)
--file, -f PATH File containing IPs (one per line)
--interactive Ask me friendly questions! (recommended for beginners)
```
### 可选项：
```
--ports, -p RANGE Port range: "1-1000" or "all" (default: 1-1000)
Examples: "22", "22-443", "1-65535", "all"
--threads INT Threads per host (default: 50, max: 256)
--timeout FLOAT Socket timeout in seconds (default: 2.0)
--export FORMATS Export: json, txt, html, all (default: txt)
--output, -o DIR Output directory (default: reports)
--verbose, -v Enable verbose output
--quiet, -q Minimal output (only results)
```
## 📊 输出示例
### 控制台输出
```
╔════════════════════════════════════════════════════════════════════╗
║ PortScanner - Starting Multi-Host Scan ║
║ 5 targets ║
╚════════════════════════════════════════════════════════════════════╝
═════════════════════════════════════════════════════════════════════
=== Scanning Host: 192.168.1.1 ===
═════════════════════════════════════════════════════════════════════
[250/1000] 25% ████████░░░░░░░░░░░░░░░░ 192.168.1.1
[+] 22/tcp OPEN → SSH (Secure Shell)
[+] 80/tcp OPEN → HTTP (HyperText Transfer Protocol)
[+] 443/tcp OPEN → HTTPS (HTTP Secure)
✓ Host 192.168.1.1 scan complete: 3 open, 997 closed, 0 filtered (2.45s)
```
### JSON 报告
```
{
"metadata": {
"scan_time": "2024-06-23T14:30:45",
"tool": "PortScanner",
"version": "1.0.0"
},
"scan_summary": {
"total_hosts": 1,
"total_ports_scanned": 1000,
"total_open_ports": 3,
"total_closed_ports": 997,
"total_filtered_ports": 0,
"total_scan_time": 2.45,
"avg_time_per_host": 2.45
},
"hosts": {
"192.168.1.1": {
"open_ports": [22, 80, 443],
"services": [
{
"port": 22,
"protocol": "tcp",
"service": "ssh",
"description": "Secure Shell (SSH)"
}
]
}
}
}
```
### HTML 报告
美观且具有交互性的 HTML 报告，包含：
- 统计摘要
- 可视化图表和进度条
- 按主机分组的端口详情
- 移动端响应式设计
- 适合打印的布局
## 📖 命令行选项
### 必填项（其中之一）：
```
--target, -t IP Single IP or comma-separated (192.168.1.1,192.168.1.2)
--file, -f PATH File containing IPs (one per line)
```
### 可选项：
```
--ports, -p RANGE Port range: "1-1000" or "all" (default: 1-1000)
Examples: "22", "22-443", "1-65535", "all"
--threads INT Threads per host (default: 50, max: 256)
--timeout FLOAT Socket timeout in seconds (default: 2.0)
--export FORMATS Export: json, txt, html, all (default: txt)
--output, -o DIR Output directory (default: reports)
--verbose, -v Enable verbose output
--quiet, -q Minimal output (only results)
```
## 🏗️ 项目结构
```
PortScanner/
├── main.py # CLI entry point
├── requirements.txt # Dependencies (empty - no external deps!)
├── README.md # This file
│
├── portscanner/
│ ├── __init__.py
│ │
│ ├── utils/
│ │ ├── __init__.py
│ │ ├── validator.py # Input validation
│ │ └── logger.py # Logging & colored output
│ │
│ ├── scanner/
│ │ ├── __init__.py
│ │ ├── port_scanner.py # Core TCP socket scanning
│ │ ├── service_detector.py # Port-to-service mapping
│ │ └── host_scanner.py # Multi-host orchestrator
│ │
│ └── exporters/
│ ├── __init__.py
│ ├── json_exporter.py # JSON export
│ ├── txt_exporter.py # Plain text export
│ └── html_exporter.py # HTML report export
│
├── reports/ # Output directory (auto-created)
│ ├── scanner.log # Scan log
│ ├── scan_20240623_143045.json
│ ├── scan_20240623_143045.txt
│ └── scan_20240623_143045.html
│
└── targets.txt # Example: IPs to scan (one per line)
```
## 🔬 架构
### 两级线程
**级别 1：主机并行**
- 同时扫描 5 个主机
- 每个主机获取独立的资源
**级别 2：端口并行**
- 每个主机同时扫描 50 个端口
- 使用 ThreadPoolExecutor 进行线程池管理
**结果：** 5 个主机 × 50 个端口 = 同时扫描 250 个端口！
### 模块依赖
```
main.py
├─ validator.py (Input validation)
├─ logger.py (Logging)
├─ host_scanner.py (Multi-host orchestrator)
│ ├─ port_scanner.py (Single-host TCP scanning)
│ ├─ service_detector.py (Service mapping)
│ └─ logger.py
└─ exporters/
├─ json_exporter.py
├─ txt_exporter.py
└─ html_exporter.py
```
## 📚 关键概念解释
### 端口状态
- **OPEN** - 端口正在监听，连接被接受（有服务运行）
- **CLOSED** - 端口未监听，连接被主机拒绝
- **FILTERED** - 防火墙阻止了连接，未收到响应
### Socket 连接
1. 创建 TCP socket
2. 尝试连接到 `host:port`
3. 如果成功 → 端口为 OPEN
4. 如果被拒绝 → 端口为 CLOSED
5. 如果超时 → 端口为 FILTERED（防火墙）
### 线程架构
```
Sequential (SLOW):
Port 1→3s, Port 2→3s, Port 3→3s = 9 seconds
Parallel (FAST):
Ports 1,2,3 at once = 3 seconds
```
我们使用带有 50 个工作线程的 `ThreadPoolExecutor` 来实现这一点。
### IANA 端口分类
- **0-1023**（Well-known）：系统服务（SSH, HTTP, DNS 等）
- **1024-49151**（Registered）：特定应用程序（MySQL, PostgreSQL 等）
- **49152-65535**（Dynamic）：由 OS 进行的临时/短暂使用
## 🔐 安全与道德
### 本工具的功能
✅ 尝试连接到端口的 TCP 连接
✅ 检测哪些端口有响应
✅ 根据端口号识别可能的服务
✅ 仅供教育用途 - 不进行漏洞利用
### 本工具不会做的事
❌ 利用漏洞
❌ 发送恶意 payload
❌ 暴力破解或破解密码
❌ 执行提权操作
❌ 访问或窃取数据
### 合法使用
本工具**仅**适用于：
- 你自己的网络
- 你拥有明确书面许可进行扫描的系统
- 教育学习环境
- 你自己的实验室设备
## 📈 性能提示
### 为了实现快速扫描
```
# 增加 threads，降低 timeout（适用于快速网络）
python main.py --target 192.168.1.1 --ports 1-65535 --threads 100 --timeout 1.0
```
### 为了实现稳定扫描
```
# 减少 threads，增加 timeout（适用于缓慢/远程网络）
python main.py --target example.com --ports 1-65535 --threads 20 --timeout 5.0
```
### 针对大量主机
```
# 并行扫描多个 hosts
python main.py --file many_targets.txt --ports 1-1000
```
## 🐛 故障排除
### 端口需要管理员/root 权限？
某些系统限制扫描特权端口（1-1023）。请使用以下命令运行：
```
# Windows（Admin Command Prompt）
python main.py --target 192.168.1.1 --ports 1-1023
# Linux/Mac（使用 sudo）
sudo python3 main.py --target 192.168.1.1 --ports 1-1023
```
### 扫描速度慢？
增加线程并减少超时时间：
```
python main.py --target 192.168.1.1 --threads 150 --timeout 1.0 --ports 1-1000
```
### 没有结果？
检查目标是否可达：
```
ping 192.168.1.1 # Test connectivity first
```
## 📝 示例工作流
### 快速本地网络扫描
```
python main.py --target 192.168.1.0/24 --ports 1-1000 --export all
```
### 从文件扫描多个主机
```
# 创建 targets.txt，每行一个 IP
python main.py --file targets.txt --ports 1-1000 --export all --output ./my_reports
```
### 带有日志的全面扫描
```
python main.py --target 192.168.1.1 --ports all --threads 100 --verbose
# 检查 reports/ 目录获取结果
```
## 🤝 贡献
这是一个教育项目。欢迎贡献：
- 更好的文档
- 额外的服务映射
- 性能改进
- Bug 修复
## 📜 许可证
MIT License - 详情请查看 LICENSE 文件
## 📚 学习资源
包含的概念将教你关于：
1. **网络**
- TCP/IP 协议栈
- Socket 与端口通信
- 网络服务
2. **Python 编程**
- 线程与并发
- 类型提示与注解
- 使用 argparse 进行 CLI 开发
- 文件 I/O 与序列化
3. **网络安全**
- 侦察技术
- 服务枚举
- 防御概念
## ⚠️ 免责声明
用户有责任确保他们拥有扫描任何网络或系统的明确许可。未经授权的网络扫描可能是违法的。本工具仅供教育目的提供。
**记住：能力越大，责任越大。** 🦸
## 🎯 未来增强功能
潜在的添加功能（教育性质）：
- UDP 端口扫描
- 用于主机发现的 Ping 扫描
- Traceroute 功能
- Banner 抓取（安全版本）
- SSL/TLS 检测
- Web 服务指纹识别
- DNS 枚举
## 📞 有疑问？
此工具旨在帮助你安全、负责任地学习网络安全概念。
扫描愉快！ 🎯
标签：Python, URL短链接分析, 插件系统, 数据统计, 无后门, 服务探测, 端口扫描, 网络工具, 网络教育, 逆向工具