pyportscan 1.2.0__tar.gz

pyportscan-1.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JinGu123123
+
+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.

pyportscan-1.2.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: pyportscan
+Version: 1.2.0
+Summary: A multi-threaded Python port scanner with async support and banner grabbing.
+Author-email: JinGu123123 <gujin123123@outlook.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/JinGu123123/pyportscan
+Project-URL: Issues, https://github.com/JinGu123123/pyportscan/issues
+Keywords: port-scanner,network,security,asyncio
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pyportscan
+
+一个用 Python 实现的多线程 TCP 端口扫描器，支持端口范围解析、并发扫描和 Banner 抓取。用于学习网络安全与网络编程。
+
+## 功能
+
+- [x] 单端口 / 多端口 / 端口范围扫描
+- [x] 多线程并发加速
+- [x] 灵活的命令行参数（argparse）
+- [x] Banner Grabbing 服务识别
+- [x] 模块化设计，可作为 Python 库使用
+- [x] 单元测试覆盖核心逻辑
+- [x] UDP 扫描（计划中）
+- [ ] 导出扫描结果到 JSON/CSV（计划中）
+
+## 环境要求
+
+- Python 3.8+
+- 依赖见 `requirements.txt`
+
+## 开发环境
+
+### Python 部分
+- Python 3.8+
+- pytest（测试）
+
+### C 语言 SYN 扫描（阶段 7.3 准备）
+- WSL2（Windows Subsystem for Linux 2）
+- Ubuntu 26.04 LTS
+- gcc 15.2.0
+- make 4.4.1
+- libpcap-dev
+
+#### 在 WSL2 里安装
+
+```bash
+sudo apt update
+sudo apt install -y gcc make libpcap-dev
+
+## 安装
+
+```bash
+git clone git@github.com:JinGu123123/pyportscan.git
+cd pyportscan
+pip install -r requirements.txt
+```
+
+## 使用
+
+### 基本用法
+
+```bash
+# 扫描本机默认端口（1-1024）
+python main.py 127.0.0.1
+
+# 扫描指定端口
+python main.py 127.0.0.1 -p 22,80,443,8000
+
+# 扫描端口范围
+python main.py 127.0.0.1 -p 1-1024
+
+# 混合格式
+python main.py 127.0.0.1 -p 22,80,8000-8100,3306
+
+# 不抓取 banner（更快）
+python main.py 127.0.0.1 -p 1-1024 --no-banner
+
+# UDP 扫描
+python main.py 127.0.0.1 -p 53,123,161 --udp
+
+# 查看帮助
+python main.py -h
+```
+
+### 参数说明
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `host` | 目标主机（IP 或域名，必填） | - |
+| `-p, --ports` | 端口范围 | `1-1024` |
+| `-t, --timeout` | 连接超时（秒） | `1.0` |
+| `-w, --workers` | 并发线程数 | `100` |
+| `--no-banner` | 不抓取服务 banner | 关闭 |
+| `--udp` | 使用 UDP 扫描（默认 TCP） | 关闭 |
+| `-h, --help` | 显示帮助 | - |
+
+### 示例输出
+
+```
+$ python main.py 127.0.0.1 -p 1-1024
+开始扫描 127.0.0.1，端口数 1024
+开放端口：
+  135/tcp  (无法识别)
+  445/tcp  (无法识别)
+  902/tcp  220 VMware Authentication Daemon Version 1.10: SSL Required...
+  912/tcp  220 VMware Authentication Daemon Version 1.0, ServerDaemonProtocol:SOAP...
+```
+
+## Python API 用法
+
+除了命令行，`pyportscan` 也可以作为 Python 库使用：
+
+```python
+from pyportscan import parse_ports, scan_ports, grab_banner
+
+# 解析端口字符串
+ports = parse_ports("22,80,8000-8100")      # [22, 80, 8000, ..., 8100]
+
+# 扫描端口（不抓 banner）
+results = scan_ports("127.0.0.1", ports, grab=False)
+
+# 扫描端口并抓取 banner
+results = scan_ports("127.0.0.1", [8000], grab=True)
+for port, banner in results:
+    print(port, banner)
+
+# 单独抓取某个端口的 banner
+banner = grab_banner("127.0.0.1", 8000)
+
+# UDP 扫描
+results = scan_ports("127.0.0.1", [53, 123], udp=True)
+# [(53, 'open|filtered'), ...]
+```
+
+## 项目结构
+
+```
+pyportscan/
+├── pyportscan/              # 核心包
+│   ├── __init__.py          # 统一暴露 API
+│   ├── parse.py             # 端口范围解析
+│   ├── scan.py              # 端口扫描
+│   └── banner.py            # banner 抓取
+├── tests/                   # 单元测试
+│   ├── test_parse.py
+│   ├── test_scan.py
+│   └── test_banner.py
+├── main.py                  # CLI 入口
+├── requirements.txt
+├── README.md
+└── LICENSE
+```
+
+## 运行测试
+
+```bash
+# 安装测试依赖
+pip install -r requirements.txt
+
+# 运行全部测试
+pytest tests/ -v
+
+# 只运行某个测试文件
+pytest tests/test_parse.py -v
+```
+
+## 开发进度
+
+- [x] 阶段 0-3：基础扫描 + 并发扫描
+- [x] 阶段 4：命令行工具（argparse）
+- [x] 阶段 5：Banner Grabbing 服务识别
+- [x] 阶段 6：单元测试 + 项目整理
+- [x] 阶段 7.1：UDP 扫描
+- [x] 阶段 7.2：搭建 WSL2 开发环境
+- [ ] 阶段 7.3：C 语言 SYN 半开扫描
+## 免责声明
+
+本工具仅供学习与授权测试使用。请勿用于未授权的目标，否则后果自负。
+
+## License
+
+[MIT](LICENSE)

pyportscan-1.2.0/README.md

@@ -0,0 +1,172 @@
+# pyportscan
+
+一个用 Python 实现的多线程 TCP 端口扫描器，支持端口范围解析、并发扫描和 Banner 抓取。用于学习网络安全与网络编程。
+
+## 功能
+
+- [x] 单端口 / 多端口 / 端口范围扫描
+- [x] 多线程并发加速
+- [x] 灵活的命令行参数（argparse）
+- [x] Banner Grabbing 服务识别
+- [x] 模块化设计，可作为 Python 库使用
+- [x] 单元测试覆盖核心逻辑
+- [x] UDP 扫描（计划中）
+- [ ] 导出扫描结果到 JSON/CSV（计划中）
+
+## 环境要求
+
+- Python 3.8+
+- 依赖见 `requirements.txt`
+
+## 开发环境
+
+### Python 部分
+- Python 3.8+
+- pytest（测试）
+
+### C 语言 SYN 扫描（阶段 7.3 准备）
+- WSL2（Windows Subsystem for Linux 2）
+- Ubuntu 26.04 LTS
+- gcc 15.2.0
+- make 4.4.1
+- libpcap-dev
+
+#### 在 WSL2 里安装
+
+```bash
+sudo apt update
+sudo apt install -y gcc make libpcap-dev
+
+## 安装
+
+```bash
+git clone git@github.com:JinGu123123/pyportscan.git
+cd pyportscan
+pip install -r requirements.txt
+```
+
+## 使用
+
+### 基本用法
+
+```bash
+# 扫描本机默认端口（1-1024）
+python main.py 127.0.0.1
+
+# 扫描指定端口
+python main.py 127.0.0.1 -p 22,80,443,8000
+
+# 扫描端口范围
+python main.py 127.0.0.1 -p 1-1024
+
+# 混合格式
+python main.py 127.0.0.1 -p 22,80,8000-8100,3306
+
+# 不抓取 banner（更快）
+python main.py 127.0.0.1 -p 1-1024 --no-banner
+
+# UDP 扫描
+python main.py 127.0.0.1 -p 53,123,161 --udp
+
+# 查看帮助
+python main.py -h
+```
+
+### 参数说明
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `host` | 目标主机（IP 或域名，必填） | - |
+| `-p, --ports` | 端口范围 | `1-1024` |
+| `-t, --timeout` | 连接超时（秒） | `1.0` |
+| `-w, --workers` | 并发线程数 | `100` |
+| `--no-banner` | 不抓取服务 banner | 关闭 |
+| `--udp` | 使用 UDP 扫描（默认 TCP） | 关闭 |
+| `-h, --help` | 显示帮助 | - |
+
+### 示例输出
+
+```
+$ python main.py 127.0.0.1 -p 1-1024
+开始扫描 127.0.0.1，端口数 1024
+开放端口：
+  135/tcp  (无法识别)
+  445/tcp  (无法识别)
+  902/tcp  220 VMware Authentication Daemon Version 1.10: SSL Required...
+  912/tcp  220 VMware Authentication Daemon Version 1.0, ServerDaemonProtocol:SOAP...
+```
+
+## Python API 用法
+
+除了命令行，`pyportscan` 也可以作为 Python 库使用：
+
+```python
+from pyportscan import parse_ports, scan_ports, grab_banner
+
+# 解析端口字符串
+ports = parse_ports("22,80,8000-8100")      # [22, 80, 8000, ..., 8100]
+
+# 扫描端口（不抓 banner）
+results = scan_ports("127.0.0.1", ports, grab=False)
+
+# 扫描端口并抓取 banner
+results = scan_ports("127.0.0.1", [8000], grab=True)
+for port, banner in results:
+    print(port, banner)
+
+# 单独抓取某个端口的 banner
+banner = grab_banner("127.0.0.1", 8000)
+
+# UDP 扫描
+results = scan_ports("127.0.0.1", [53, 123], udp=True)
+# [(53, 'open|filtered'), ...]
+```
+
+## 项目结构
+
+```
+pyportscan/
+├── pyportscan/              # 核心包
+│   ├── __init__.py          # 统一暴露 API
+│   ├── parse.py             # 端口范围解析
+│   ├── scan.py              # 端口扫描
+│   └── banner.py            # banner 抓取
+├── tests/                   # 单元测试
+│   ├── test_parse.py
+│   ├── test_scan.py
+│   └── test_banner.py
+├── main.py                  # CLI 入口
+├── requirements.txt
+├── README.md
+└── LICENSE
+```
+
+## 运行测试
+
+```bash
+# 安装测试依赖
+pip install -r requirements.txt
+
+# 运行全部测试
+pytest tests/ -v
+
+# 只运行某个测试文件
+pytest tests/test_parse.py -v
+```
+
+## 开发进度
+
+- [x] 阶段 0-3：基础扫描 + 并发扫描
+- [x] 阶段 4：命令行工具（argparse）
+- [x] 阶段 5：Banner Grabbing 服务识别
+- [x] 阶段 6：单元测试 + 项目整理
+- [x] 阶段 7.1：UDP 扫描
+- [x] 阶段 7.2：搭建 WSL2 开发环境
+- [ ] 阶段 7.3：C 语言 SYN 半开扫描
+## 免责声明
+
+本工具仅供学习与授权测试使用。请勿用于未授权的目标，否则后果自负。
+
+## License
+
+[MIT](LICENSE)

pyportscan-1.2.0/pyportscan/__init__.py

@@ -0,0 +1,14 @@
+"""pyportscan - 一个多线程 TCP 端口扫描器"""
+
+from .parse import parse_ports
+from .scan import scan_port, scan_ports
+from .banner import grab_banner
+
+__version__ = "0.5.0"
+
+__all__ = [
+    "parse_ports",
+    "scan_port",
+    "scan_ports",
+    "grab_banner",
+]

pyportscan-1.2.0/pyportscan/banner.py

@@ -0,0 +1,38 @@
+"""服务 Banner 抓取模块"""
+
+import socket
+
+
+def grab_banner(host, port, timeout=2.0):
+    """连接端口，尝试获取服务 banner。返回字符串，失败返回 None。"""
+    sock = None
+    try:
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(timeout)
+        sock.connect((host, port))
+
+        # 尝试1：被动接收（SSH/FTP/SMTP 主动发）
+        try:
+            data = sock.recv(1024)
+            if data:
+                return data.decode(errors="ignore").strip()
+        except socket.timeout:
+            pass
+
+        # 尝试2：主动发 HTTP/1.1 请求
+        try:
+            req = (b"HEAD / HTTP/1.1\r\nHost: " + host.encode()
+                   + b"\r\nConnection: close\r\n\r\n")
+            sock.send(req)
+            data = sock.recv(1024)
+            if data:
+                return data.decode(errors="ignore").strip()
+        except socket.timeout:
+            pass
+
+        return None
+    except (socket.error, OSError):
+        return None
+    finally:
+        if sock:
+            sock.close()

pyportscan-1.2.0/pyportscan/parse.py

@@ -0,0 +1,20 @@
+"""端口范围解析模块"""
+
+
+def parse_ports(s):
+    """解析端口字符串，返回整数列表。
+
+    支持格式：
+        "80"              → [80]
+        "22,80,443"       → [22, 80, 443]
+        "8000-8005"       → [8000, 8001, ..., 8005]
+        "22,8000-8002"    → [22, 8000, 8001, 8002]
+    """
+    ports = []
+    for part in s.split(","):
+        if "-" in part:
+            start, end = part.split("-")
+            ports.extend(range(int(start), int(end) + 1))
+        else:
+            ports.append(int(part))
+    return ports

pyportscan-1.2.0/pyportscan/ports.py

@@ -0,0 +1,12 @@
+"""常用端口列表（参考 Nmap Top 100）"""
+
+TOP_PORTS = [
+    7, 9, 13, 21, 22, 23, 25, 26, 37, 53, 79, 80, 81, 88, 106, 110, 111, 113,
+    119, 135, 139, 143, 144, 179, 199, 389, 427, 443, 444, 445, 465, 513, 514,
+    515, 543, 544, 548, 554, 587, 631, 646, 873, 990, 993, 995, 1025, 1026,
+    1027, 1028, 1029, 1110, 1433, 1720, 1723, 1755, 1900, 2000, 2001, 2049,
+    2121, 2717, 3000, 3128, 3306, 3389, 3986, 4899, 5000, 5009, 5051, 5060,
+    5101, 5190, 5357, 5432, 5631, 5666, 5800, 5900, 6000, 6001, 6646, 7070,
+    8000, 8008, 8009, 8080, 8081, 8443, 8888, 9100, 9999, 10000, 32768,
+    49152, 49153, 49154, 49155, 49156, 49157,
+]

pyportscan-1.2.0/pyportscan/scan.py

@@ -0,0 +1,106 @@
+"""TCP 端口扫描模块"""
+
+import socket
+from concurrent.futures import ThreadPoolExecutor
+
+
+def scan_port(host, port, timeout=1.0):
+    """扫描单个 TCP 端口。返回 True 表示开放。"""
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    sock.settimeout(timeout)
+    try:
+        result = sock.connect_ex((host, port))
+        return result == 0
+    finally:
+        sock.close()
+
+
+def udp_scan_port(host,port,timeout = 2.0):
+    sock = socket.socket(socket.AF_INET,socket.SOCK_DGRAM)
+    sock.settimeout(timeout)
+    try:
+        sock.sendto(b"",(host,port))
+        try:
+            data, _ = sock.recvfrom(1024)
+            return "open"
+        except socket.timeout:
+            return "open|filtered"
+        except (ConnectionRefusedError,ConnectionResetError):
+            return "closed"
+    finally:
+        sock.close()
+
+
+def scan_ports(host, ports, timeout=1.0, max_workers=200, grab=False,udp=False,on_progress=None):
+    """
+    on_prograss:可选回调，每扫完一个端口调用一次
+                签名：on_progress(done,total,open_ports)
+    """
+
+    """并发扫描多个端口。
+
+    参数:
+        host: 目标主机
+        ports: 端口列表
+        timeout: 单个端口超时
+        max_workers: 并发线程数
+        grab: 是否抓取 banner
+
+    返回:
+        TCP (udp=False):
+            grab=False → [(port, None), ...]（仅开放端口）
+            grab=True  → [(port, banner), ...]
+        UDP (udp=True):
+            [(port, state), ...]   # state ∈ {"open", "closed", "open|filtered"}
+    """
+
+    ports = list(ports)
+    total = len(ports)
+    done = 0
+
+    # 第一步：并发扫描端口
+    open_ports = []
+    #UDP
+    if udp:
+        results = []
+        with ThreadPoolExecutor(max_workers=max_workers) as executor:
+            futures = {executor.submit(udp_scan_port,host,port,timeout):port
+                       for port in ports}
+            for future, port in futures.items():
+                done += 1
+                if on_progress:
+                    on_progress(done,total,results)
+                state = future.result()
+                if state != "closed":
+                    results.append((port,state))
+        results.sort()
+        return results        
+
+            
+    #TCP
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        futures = {executor.submit(scan_port, host, port, timeout): port
+                    for port in ports}
+        for future, port in futures.items():
+            done += 1
+            if on_progress:
+                on_progress(done,total,open_ports)
+            if future.result():
+                open_ports.append(port)
+
+    # 第二步：不抓 banner 直接返回
+    if not grab:
+        return sorted([(p, None) for p in open_ports])
+
+    # 第三步：并发抓 banner
+    from .banner import grab_banner    # 延迟导入，避免循环依赖
+    results = []
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        futures = {executor.submit(grab_banner, host, port, timeout): port
+                   for port in open_ports}
+        for future, port in futures.items():
+            banner = future.result()
+            results.append((port, banner))
+
+    results.sort()
+    return results

pyportscan-1.2.0/pyportscan/scan_async.py

@@ -0,0 +1,63 @@
+"""基于asyncio的异步端口扫描"""
+
+import asyncio
+
+
+async def scan_port_async(host,port,timeout=1.0,semaphore=None):
+    """异步扫描单个TCP端口
+    参数：
+        semaphore:可选的 asyncio.Semaphore,用于限流
+    返回：
+        True表示端口开放,False表示端口关闭/超时
+    """
+
+    if semaphore is not None:
+        async with semaphore:
+            return await _try_connect(host,port,timeout)
+    return await _try_connect(host,port,timeout)
+
+
+
+async def _try_connect(host,port,timeout):
+    #内部：尝试连接
+
+    try:
+        reader,writer = await asyncio.wait_for(
+            asyncio.open_connection(host,port),
+            timeout=timeout,
+        )
+        writer.close()
+        try:
+            await writer.wait_closed()
+        except Exception:
+            pass
+        return True
+    except(asyncio.TimeoutError,ConnectionRefusedError,OSError):
+        return False
+
+
+
+async def scan_ports_async(host,ports,timeout=1.0,max_concurrent=500):
+    """异步并发扫描多个端口
+    参数：
+        host:目标主机
+        ports:端口列表(或range)
+        timeout:单个端口超时
+        max_concurrent:最大并发数
+
+    返回：
+        [(port,None),...](暂不抓banner,格式与scan_ports一致)
+    """
+
+    ports = list(ports)
+    semaphore = asyncio.Semaphore(max_concurrent)
+
+    tasks = [
+        scan_port_async(host,port,timeout,semaphore)
+        for port in ports
+    ]
+    results = await asyncio.gather(*tasks)
+
+    open_ports = [p for p, ok in zip(ports,results)if ok]
+    open_ports.sort()
+    return [(p,None) for p in open_ports]

pyportscan-1.2.0/pyportscan.egg-info/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.4
+Name: pyportscan
+Version: 1.2.0
+Summary: A multi-threaded Python port scanner with async support and banner grabbing.
+Author-email: JinGu123123 <gujin123123@outlook.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/JinGu123123/pyportscan
+Project-URL: Issues, https://github.com/JinGu123123/pyportscan/issues
+Keywords: port-scanner,network,security,asyncio
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Security
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# pyportscan
+
+一个用 Python 实现的多线程 TCP 端口扫描器，支持端口范围解析、并发扫描和 Banner 抓取。用于学习网络安全与网络编程。
+
+## 功能
+
+- [x] 单端口 / 多端口 / 端口范围扫描
+- [x] 多线程并发加速
+- [x] 灵活的命令行参数（argparse）
+- [x] Banner Grabbing 服务识别
+- [x] 模块化设计，可作为 Python 库使用
+- [x] 单元测试覆盖核心逻辑
+- [x] UDP 扫描（计划中）
+- [ ] 导出扫描结果到 JSON/CSV（计划中）
+
+## 环境要求
+
+- Python 3.8+
+- 依赖见 `requirements.txt`
+
+## 开发环境
+
+### Python 部分
+- Python 3.8+
+- pytest（测试）
+
+### C 语言 SYN 扫描（阶段 7.3 准备）
+- WSL2（Windows Subsystem for Linux 2）
+- Ubuntu 26.04 LTS
+- gcc 15.2.0
+- make 4.4.1
+- libpcap-dev
+
+#### 在 WSL2 里安装
+
+```bash
+sudo apt update
+sudo apt install -y gcc make libpcap-dev
+
+## 安装
+
+```bash
+git clone git@github.com:JinGu123123/pyportscan.git
+cd pyportscan
+pip install -r requirements.txt
+```
+
+## 使用
+
+### 基本用法
+
+```bash
+# 扫描本机默认端口（1-1024）
+python main.py 127.0.0.1
+
+# 扫描指定端口
+python main.py 127.0.0.1 -p 22,80,443,8000
+
+# 扫描端口范围
+python main.py 127.0.0.1 -p 1-1024
+
+# 混合格式
+python main.py 127.0.0.1 -p 22,80,8000-8100,3306
+
+# 不抓取 banner（更快）
+python main.py 127.0.0.1 -p 1-1024 --no-banner
+
+# UDP 扫描
+python main.py 127.0.0.1 -p 53,123,161 --udp
+
+# 查看帮助
+python main.py -h
+```
+
+### 参数说明
+
+| 参数 | 说明 | 默认值 |
+|------|------|--------|
+| `host` | 目标主机（IP 或域名，必填） | - |
+| `-p, --ports` | 端口范围 | `1-1024` |
+| `-t, --timeout` | 连接超时（秒） | `1.0` |
+| `-w, --workers` | 并发线程数 | `100` |
+| `--no-banner` | 不抓取服务 banner | 关闭 |
+| `--udp` | 使用 UDP 扫描（默认 TCP） | 关闭 |
+| `-h, --help` | 显示帮助 | - |
+
+### 示例输出
+
+```
+$ python main.py 127.0.0.1 -p 1-1024
+开始扫描 127.0.0.1，端口数 1024
+开放端口：
+  135/tcp  (无法识别)
+  445/tcp  (无法识别)
+  902/tcp  220 VMware Authentication Daemon Version 1.10: SSL Required...
+  912/tcp  220 VMware Authentication Daemon Version 1.0, ServerDaemonProtocol:SOAP...
+```
+
+## Python API 用法
+
+除了命令行，`pyportscan` 也可以作为 Python 库使用：
+
+```python
+from pyportscan import parse_ports, scan_ports, grab_banner
+
+# 解析端口字符串
+ports = parse_ports("22,80,8000-8100")      # [22, 80, 8000, ..., 8100]
+
+# 扫描端口（不抓 banner）
+results = scan_ports("127.0.0.1", ports, grab=False)
+
+# 扫描端口并抓取 banner
+results = scan_ports("127.0.0.1", [8000], grab=True)
+for port, banner in results:
+    print(port, banner)
+
+# 单独抓取某个端口的 banner
+banner = grab_banner("127.0.0.1", 8000)
+
+# UDP 扫描
+results = scan_ports("127.0.0.1", [53, 123], udp=True)
+# [(53, 'open|filtered'), ...]
+```
+
+## 项目结构
+
+```
+pyportscan/
+├── pyportscan/              # 核心包
+│   ├── __init__.py          # 统一暴露 API
+│   ├── parse.py             # 端口范围解析
+│   ├── scan.py              # 端口扫描
+│   └── banner.py            # banner 抓取
+├── tests/                   # 单元测试
+│   ├── test_parse.py
+│   ├── test_scan.py
+│   └── test_banner.py
+├── main.py                  # CLI 入口
+├── requirements.txt
+├── README.md
+└── LICENSE
+```
+
+## 运行测试
+
+```bash
+# 安装测试依赖
+pip install -r requirements.txt
+
+# 运行全部测试
+pytest tests/ -v
+
+# 只运行某个测试文件
+pytest tests/test_parse.py -v
+```
+
+## 开发进度
+
+- [x] 阶段 0-3：基础扫描 + 并发扫描
+- [x] 阶段 4：命令行工具（argparse）
+- [x] 阶段 5：Banner Grabbing 服务识别
+- [x] 阶段 6：单元测试 + 项目整理
+- [x] 阶段 7.1：UDP 扫描
+- [x] 阶段 7.2：搭建 WSL2 开发环境
+- [ ] 阶段 7.3：C 语言 SYN 半开扫描
+## 免责声明
+
+本工具仅供学习与授权测试使用。请勿用于未授权的目标，否则后果自负。
+
+## License
+
+[MIT](LICENSE)

pyportscan-1.2.0/pyportscan.egg-info/SOURCES.txt

@@ -0,0 +1,19 @@
+LICENSE
+README.md
+pyproject.toml
+pyportscan/__init__.py
+pyportscan/banner.py
+pyportscan/parse.py
+pyportscan/ports.py
+pyportscan/scan.py
+pyportscan/scan_async.py
+pyportscan.egg-info/PKG-INFO
+pyportscan.egg-info/SOURCES.txt
+pyportscan.egg-info/dependency_links.txt
+pyportscan.egg-info/entry_points.txt
+pyportscan.egg-info/top_level.txt
+tests/test_banner.py
+tests/test_parse.py
+tests/test_scan.py
+tests/test_scan_ports.py
+tests/test_udp.py

pyportscan-1.2.0/pyportscan.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pyportscan-1.2.0/pyportscan.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pyportscan = main:main

pyportscan-1.2.0/pyportscan.egg-info/top_level.txt

@@ -0,0 +1 @@
+pyportscan

pyportscan-1.2.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=77.0.3"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "pyportscan"
+version = "1.2.0"
+description = "A multi-threaded Python port scanner with async support and banner grabbing."
+readme = "README.md"
+requires-python = ">=3.8"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "JinGu123123", email = "gujin123123@outlook.com" }
+]
+keywords = ["port-scanner", "network", "security", "asyncio"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Operating System :: OS Independent",
+    "Topic :: Security",
+]
+
+[project.urls]
+Homepage = "https://github.com/JinGu123123/pyportscan"
+Issues = "https://github.com/JinGu123123/pyportscan/issues"
+
+[project.scripts]
+pyportscan = "main:main"
+
+[tool.setuptools.packages.find]
+include = ["pyportscan*"]
+exclude = ["c_syn_scan*", "tests*"]

pyportscan-1.2.0/setup.cfg

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

pyportscan-1.2.0/tests/test_banner.py

@@ -0,0 +1,50 @@
+"""banner 模块的单元测试（用 mock 避免真实网络）"""
+
+import socket
+from unittest.mock import patch
+
+from pyportscan.banner import grab_banner
+
+
+@patch("pyportscan.banner.socket.socket")
+def test_grab_banner_receives_banner(mock_socket_cls):
+    """被动接收成功：SSH 主动发 banner"""
+    fake_sock = mock_socket_cls.return_value
+    fake_sock.recv.return_value = b"SSH-2.0-OpenSSH_8.0\r\n"
+
+    assert grab_banner("127.0.0.1", 22) == "SSH-2.0-OpenSSH_8.0"
+
+
+@patch("pyportscan.banner.socket.socket")
+def test_grab_banner_http_after_timeout(mock_socket_cls):
+    """被动超时 + 主动 HTTP 请求成功"""
+    fake_sock = mock_socket_cls.return_value
+    # 第一次 recv 抛 timeout，第二次 recv 返回 HTTP 响应
+    fake_sock.recv.side_effect = [
+        socket.timeout(),
+        b"HTTP/1.1 200 OK\r\nServer: nginx\r\n\r\n",
+    ]
+
+    result = grab_banner("127.0.0.1", 80)
+    assert result is not None
+    assert "200 OK" in result
+
+
+@patch("pyportscan.banner.socket.socket")
+def test_grab_banner_returns_none_on_timeout(mock_socket_cls):
+    """两次 recv 都超时 → 返回 None"""
+    fake_sock = mock_socket_cls.return_value
+    fake_sock.recv.side_effect = socket.timeout
+
+    assert grab_banner("127.0.0.1", 9999) is None
+
+
+@patch("pyportscan.banner.socket.socket")
+def test_grab_banner_handles_binary(mock_socket_cls):
+    """响应含非 UTF-8 字节：不崩溃"""
+    fake_sock = mock_socket_cls.return_value
+    fake_sock.recv.return_value = b"\xff\xfe\x00\x01binary"
+
+    result = grab_banner("127.0.0.1", 445)
+    # 不应该抛异常；decode(errors="ignore") 会丢掉坏字节
+    assert isinstance(result, str)

pyportscan-1.2.0/tests/test_parse.py

@@ -0,0 +1,25 @@
+"""parse_ports 的单元测试"""
+
+from pyportscan.parse import parse_ports
+
+
+def test_single_port():
+    assert parse_ports("80") == [80]
+
+
+def test_multiple_ports():
+    assert parse_ports("22,80,443") == [22, 80, 443]
+
+
+def test_range():
+    assert parse_ports("8000-8005") == [8000, 8001, 8002, 8003, 8004, 8005]
+
+
+def test_mixed():
+    assert parse_ports("22,8000-8002,3306") == [22, 8000, 8001, 8002, 3306]
+
+
+def test_range_boundary():
+    # range 的 +1 是经典坑，专门测边界
+    assert parse_ports("1-1") == [1]
+    assert parse_ports("65535-65535") == [65535]

pyportscan-1.2.0/tests/test_scan.py

@@ -0,0 +1,36 @@
+"""scan 模块的单元测试（用 mock 避免真实网络）"""
+
+from unittest.mock import patch
+
+from pyportscan.scan import scan_port
+
+
+@patch("pyportscan.scan.socket.socket")
+def test_scan_port_open(mock_socket_cls):
+    """端口开放：connect_ex 返回 0 → scan_port 返回 True"""
+    fake_sock = mock_socket_cls.return_value
+    fake_sock.connect_ex.return_value = 0
+
+    assert scan_port("127.0.0.1", 8000) is True
+
+
+@patch("pyportscan.scan.socket.socket")
+def test_scan_port_closed(mock_socket_cls):
+    """端口关闭：connect_ex 返回非 0 → scan_port 返回 False"""
+    fake_sock = mock_socket_cls.return_value
+    fake_sock.connect_ex.return_value = 111    # ECONNREFUSED
+
+    assert scan_port("127.0.0.1", 9999) is False
+
+
+@patch("pyportscan.scan.socket.socket")
+def test_scan_port_closes_socket(mock_socket_cls):
+    """scan_port 必须关闭 socket"""
+    fake_sock = mock_socket_cls.return_value
+    fake_sock.connect_ex.return_value = 0
+
+    scan_port("127.0.0.1", 8000)
+
+    fake_sock.close.assert_called_once()       # 验证 close 被调用了一次
+    fake_sock.close.assert_called_once()
+    fake_sock.settimeout.assert_called_once()   # 新增：验证 settimeout 被调用

pyportscan-1.2.0/tests/test_scan_ports.py

@@ -0,0 +1,74 @@
+"""scan_ports 的集成测试（mock socket，真跑线程池）"""
+
+import socket
+from unittest.mock import patch
+
+from pyportscan.scan import scan_ports
+
+
+@patch("pyportscan.scan.socket.socket")
+def test_scan_ports_tcp_no_banner(mock_socket_cls):
+    """TCP 模式，grab=False：所有端口都开放"""
+    fake_sock = mock_socket_cls.return_value
+    fake_sock.connect_ex.return_value = 0      # 所有端口开放
+
+    result = scan_ports("127.0.0.1", [80, 443], grab=False)
+
+    assert (80, None) in result
+    assert (443, None) in result
+    assert len(result) == 2
+
+
+@patch("pyportscan.scan.socket.socket")
+def test_scan_ports_tcp_with_banner(mock_socket_cls):
+    """TCP 模式，grab=True：抓 banner"""
+    fake_sock = mock_socket_cls.return_value
+    fake_sock.connect_ex.return_value = 0
+    fake_sock.recv.return_value = b"HTTP/1.1 200 OK\r\n"
+
+    result = scan_ports("127.0.0.1", [80], grab=True)
+
+    assert len(result) == 1
+    port, banner = result[0]
+    assert port == 80
+    assert "HTTP" in banner
+
+
+@patch("pyportscan.scan.socket.socket")
+def test_scan_ports_tcp_all_closed(mock_socket_cls):
+    """TCP 模式，所有端口关闭：返回空列表"""
+    fake_sock = mock_socket_cls.return_value
+    fake_sock.connect_ex.return_value = 111    # 非 0 = 关闭
+
+    result = scan_ports("127.0.0.1", [80, 443], grab=False)
+
+    assert result == []
+
+
+@patch("pyportscan.scan.socket.socket")
+def test_scan_ports_udp(mock_socket_cls):
+    """UDP 模式"""
+    fake_sock = mock_socket_cls.return_value
+    fake_sock.recvfrom.side_effect = socket.timeout    # 所有端口超时
+
+    result = scan_ports("127.0.0.1", [53], udp=True)
+
+    # 超时 → open|filtered，全部保留
+    assert (53, "open|filtered") in result
+
+
+@patch("pyportscan.scan.socket.socket")
+def test_scan_ports_udp_mixed(mock_socket_cls):
+    """UDP 模式：混合状态（closed 被过滤）"""
+    fake_sock = mock_socket_cls.return_value
+    # recvfrom 按顺序返回：第一次超时，第二次 ConnectionResetError
+    fake_sock.recvfrom.side_effect = [
+        socket.timeout(),
+        ConnectionResetError(),
+    ]
+
+    result = scan_ports("127.0.0.1", [53, 9999], udp=True)
+
+    # 53 → open|filtered，9999 → closed（被过滤）
+    assert (53, "open|filtered") in result
+    assert all(port != 9999 for port, _ in result)

pyportscan-1.2.0/tests/test_udp.py

@@ -0,0 +1,42 @@
+"""UDP 扫描的单元测试（用 mock 避免真实网络）"""
+
+import socket
+from unittest.mock import patch
+
+from pyportscan.scan import udp_scan_port
+
+
+@patch("pyportscan.scan.socket.socket")
+def test_udp_open(mock_socket_cls):
+    """收到 UDP 响应 → open"""
+    fake_sock = mock_socket_cls.return_value
+    fake_sock.recvfrom.return_value = (b"response", ("127.0.0.1", 53))
+
+    assert udp_scan_port("127.0.0.1", 53) == "open"
+
+
+@patch("pyportscan.scan.socket.socket")
+def test_udp_closed_win(mock_socket_cls):
+    """Windows 上收到 ICMP unreachable → ConnectionResetError → closed"""
+    fake_sock = mock_socket_cls.return_value
+    fake_sock.recvfrom.side_effect = ConnectionResetError()
+
+    assert udp_scan_port("127.0.0.1", 9999) == "closed"
+
+
+@patch("pyportscan.scan.socket.socket")
+def test_udp_closed_linux(mock_socket_cls):
+    """Linux 上收到 ICMP unreachable → ConnectionRefusedError → closed"""
+    fake_sock = mock_socket_cls.return_value
+    fake_sock.recvfrom.side_effect = ConnectionRefusedError()
+
+    assert udp_scan_port("127.0.0.1", 9999) == "closed"
+
+
+@patch("pyportscan.scan.socket.socket")
+def test_udp_filtered(mock_socket_cls):
+    """超时 → open|filtered"""
+    fake_sock = mock_socket_cls.return_value
+    fake_sock.recvfrom.side_effect = socket.timeout()
+
+    assert udp_scan_port("8.8.8.8", 53) == "open|filtered"