pyportscan 1.2.0__py3-none-any.whl

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/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/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/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/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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+pyportscan/__init__.py,sha256=jh4SeRwmFJt2nPhGk-VpdiHLhZN40tC-peizKVD7QDY,270
+pyportscan/banner.py,sha256=Wxm-7gdGFbNYnjiljAJXneY77743B20dw86Jk7434TY,1083
+pyportscan/parse.py,sha256=v4BCtEXGLF5ozXtrsSn7BpfCo-agnumpxQbl-kJrMU0,556
+pyportscan/ports.py,sha256=S9wmhw2wH6SdVTr90xCX1mOyyFmWUhYZ170xUFTE2ck,646
+pyportscan/scan.py,sha256=LgDWIUMTCPvH5XjYCW8NwTJkw2VoKhe4UfmbtkEoedo,3283
+pyportscan/scan_async.py,sha256=TV7fuWX0-r_NEmqcWU70_nrhCBPEmyHJjbeGGClaeUE,1682
+pyportscan-1.2.0.dist-info/licenses/LICENSE,sha256=Yf9TlBPFI80gE71BltBT6BJBWizr7LYx8x3al-x83no,1068
+pyportscan-1.2.0.dist-info/METADATA,sha256=AWRPg0S8Jrr9w8f9VtqeXzj2CRCjas8QpdE0szV-sGM,4922
+pyportscan-1.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pyportscan-1.2.0.dist-info/entry_points.txt,sha256=Uk-453EiJcfNykGnzhEv8JcipMjOKs4Lr6D0IL0op8U,41
+pyportscan-1.2.0.dist-info/top_level.txt,sha256=HdZkBhLcTORXYfdz_DUdTq4blFUCGJkXb0ByLyfH9J8,11
+pyportscan-1.2.0.dist-info/RECORD,,

pyportscan-1.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyportscan-1.2.0.dist-info/entry_points.txt

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

pyportscan-1.2.0.dist-info/licenses/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.dist-info/top_level.txt

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