MehmetKozann/stealth-synscan

# synscan [](https://www.python.org/) [](https://opensource.org/licenses/MIT) [](https://www.apple.com/macos/) [](#) [](https://github.com/MehmetKozann/stealth-synscan/actions) `synscan` 是一款专为安全工程师、研究人员和渗透测试人员设计的轻量级、隐蔽型 raw-socket 端口扫描器。它支持半开 SYN 扫描、源 IP 伪装（诱饵）、通过动态 TCP 协议栈参数规避 OS 指纹识别，以及状态检查点记录，从而实现可恢复的扫描，并且零第三方库依赖。 ## 为什么选择 synscan？ 与传统的重型扫描框架不同，`synscan` 的设计初衷是轻量、模块化且完全自包含。 典型用例包括： - **受限的 Linux 环境：** 在有 Python 3 但无法安装其他第三方软件（`libpcap`）或包管理器（`apt`、`yum`、`pip`）的隔离系统上运行。 - **内部安全审计与红蓝对抗：** 在不留下沉重的第三方软件痕迹的情况下，执行授权的网络侦察。 - **教育与协议研究：** 通过易读的 Python 代码探索底层 raw TCP/IP 网络通信、RFC 1071 校验和计算以及自定义数据包构造。 - **安全实验室与 CTF 竞赛：** 在需要快速进行端口发现的极简 Docker 容器或测试环境中快速部署。 `synscan` 专注于可移植性和零外部库需求（不需要 `libpcap` 或 `pip` 包），同时提供高级 SYN 扫描功能。 ## 终端快速演示 ``` ______ _____ __ ___ _____ ______ ___ _ / __ \ \ / / \ \ / / / __|/ ___|/ _____// _ \ | | \__ \ \ V / \ V / \__ \\ \___ | / / /_\ \| | |___/ |_| |_| |___/\____/|/ /_/ \_\_| v1.0 Stealth TCP SYN (Half-Open) Port Scanner $ sudo python3 synscan.py 192.168.1.1 -p 22,80,443 --confirm --banner [*] Local IP: 192.168.1.105 | Decoys: 0 [*] Target: 192.168.1.1 | 3 ports | ~5 pps | decoys: 0 | confirm: on | banner: on [+] 192.168.1.1 22 open [+] 192.168.1.1 80 open [+] 192.168.1.1 443 open [*] 192.168.1.1: verifying 3 open ports... -> 192.168.1.1 22 banner: SSH-2.0-OpenSSH_8.9p1 Ubuntu-3ubuntu0.1 -> 192.168.1.1 80 banner: HTTP/1.1 200 OK (Server: nginx/1.18.0) [+] 192.168.1.1 scan finished in 4s (3/3 open): [22, 80, 443] [+] Scan complete. Found 3 open ports in total. ``` ## 技术概述与功能 | 功能 | `synscan` 实现细节 | |---|---| | **仅使用 Python 标准库** | 完全基于 Python 3 标准库（`socket`、`struct`、`select`）构建。无需 `libpcap` 或 `pip` 包。 | | **隐蔽 SYN（半开）扫描** | 构造原始 IPv4/TCP 头部以发起 SYN 探测，且无需完成 TCP 三次握手。 | | **诱饵 IP 伪装 (`--decoy`)** | 在每次探测突发中将真实源 IP 与诱饵地址（`IP,IP...` 或 `RND:N`）混合打乱。 | | **动态 TCP 指纹规避** | 根据动态 OS 协议栈配置，逐包随机化 TCP 头部选项（MSS、Window Scale、SACK permitted、TTL）。 | | **状态持久化与恢复** | 将扫描进度增量自动保存至 JSON（`.synscan_state.json`），以便后续恢复（`--resume`）。 | | **Banner 抓取 (`--banner`)** | 发现端口后建立完整的 TCP 连接，以获取应用服务 banner。 | ## 性能测试参考 | 目标范围 | 端口数量 | 模式 / 参数 | 实测耗时 | 速率 (pps) | |---|---|---|---|---| | 单主机 (`192.168.1.1`) | Top 27 端口 | 标准 SYN | ~1.2s | ~22.5 pps | | 单主机 (`192.168.1.1`) | 1 - 1024 (1024 个端口) | `--batch 256` | ~4.8s | ~213 pps | | 单主机 (`10.0.0.5`) | 1 - 1024 (1024 个端口) | `--decoy RND:4` | ~8.2s | ~124 pps | | 子网 (`192.168.1.0/24`) | Top 27 端口 | 批量处理 | ~14.5s | ~180 pps | ## 功能 - **隐蔽 SYN（半开）扫描：** 使连接保持在半开状态，不完成三次握手。 - **诱饵 IP 伪装：** 将真实源 IP 与诱饵地址（`--decoy RND:4` 或自定义 IP 列表）混合，以迷惑入侵检测系统。 - **OS 指纹规避：** 在请求中随机化 TCP 选项（MSS、Window Scale、SACK permitted）和初始 TTL，以融入正常的网络流量。 - **批量处理与自适应步调：** 采用 Nmap 风格的 SYN 批量发送，并根据网络响应速率动态调整延迟。 - **确认扫描：** 可选的二次验证扫描（`--confirm`），以消除误报。 - **Banner 抓取：** 在发现开放端口后自动获取服务 banner（`--banner`）。 - **状态持久化与恢复：** 保存扫描状态（`--state`）并无缝恢复中断的扫描（`--resume`）。 ## 工作原理（分步架构） ``` [ Target Specification ] ──> [ Target Expansion & DNS Resolve ] │ ▼ [ Output JSON / State ] <── [ Asynchronous Socket Listener ] ▲ │ (TCP SYN-ACK / RST / ICMP) [ Raw Packet Generator ] │ (Decoy Bursts) ▼ [ Target Network ] ``` ### 1. 目标与端口解析 扫描器会展开目标规范（单个 IP、CIDR 块如 `192.168.1.0/24`，或目标文本文件），并使用系统解析器解析域名。端口范围（例如 `1-1024`）将被解析并去重。 ### 2. Raw Socket 初始化 打开 raw socket 需要 `root` 权限： - `IPPROTO_RAW`：用于注入带有自定义头部的原始 IPv4 数据包。 - `IPPROTO_TCP`：用于捕获传入的 TCP 响应（SYN-ACK / RST）。 - `IPPROTO_ICMP`：用于检测 ICMP Type 3（Destination Unreachable）错误响应。 ### 3. 自定义 SYN 数据包构造与诱饵打乱 对于每个目标端口，`PacketBuilder` 会构造原始 IP 和 TCP 数据包头部： - **动态 TCP 协议栈参数：** 随机化 Window Size、MSS、Window Scale 和 SACK-permitted 选项，以对抗被动 OS 指纹识别。 - **基于源 IP 的 IP-ID 跟踪：** 为每个源 IP 维持真实且递增的 IP-ID 序列。 - **诱饵伪装：** 启用 `--decoy` 时，真实和诱饵数据包会在每次突发中随机打乱，以混淆源 IP。 ### 4. 异步响应处理 扫描器使用非阻塞的 `select.select()` 多路复用技术，并发监听 TCP 和 ICMP raw socket： - **SYN-ACK (`0x12`)：** 端口被记录为 **`OPEN`**。 - **RST (`0x04`)：** 端口被记录为 **`CLOSED`**。 - **ICMP Type 3 (Unreachable)：** 分析 ICMP 错误数据包中的原始 TCP 头部 payload 以映射源/目的端口，并将端口标记为 **`CLOSED`** 或 **`FILTERED`**。 - **超时：** 未应答的探测被标记为 **`FILTERED`**。 ### 5. 自适应速率步调 实时监控近期的响应模式。如果丢包率或过滤率上升（暗示存在速率限制或 IDS 干预），扫描器将动态降低发送速度。 ### 6. 验证与 Banner 抓取 - **确认扫描 (`--confirm`)：** 通过第二次 SYN 扫描重新测试发现的开放端口，以消除误报。 - **Banner 抓取 (`--banner`)：** 建立标准的完整 TCP 连接（`socket.create_connection`）以获取应用服务 banner。 ### 7. 状态检查点与导出 扫描进度会以增量方式序列化（`.synscan_state.json`）。中断操作（`Ctrl+C`）会优雅地保留状态，以便稍后通过 `--resume` 恢复扫描。最终结果将通过 `--out` 导出为结构化的 JSON。 ## 项目结构 ``` stealth-synscan/ ├── .github/ │ └── workflows/ │ └── ci.yml # GitHub Actions CI compilation & test pipeline ├── synscan/ │ ├── __init__.py # Package export definitions │ ├── __main__.py # Module entry point (python3 -m synscan) │ ├── banner.py # Service banner grabbing module │ ├── cli.py # CLI interface, ASCII banner & colored output │ ├── packet.py # PacketBuilder & RFC 1071 checksum engine │ ├── report.py # Target dataclass & StateManager persistence │ └── scanner.py # Main SYN scanning engine & target resolver ├── CHANGELOG.md # Version release history ├── CONTRIBUTING.md # Open-source contribution guidelines ├── LICENSE # MIT Open Source License ├── README.md # Project documentation ├── SECURITY.md # Security vulnerability disclosure policy ├── setup.py # Package installation script └── synscan.py # Standalone script execution entry point ``` ## 环境要求 - **操作系统：** Linux / macOS（兼容 POSIX） - **Python 版本：** Python 3.8+ - **权限：** raw socket 操作（`SOCK_RAW`）需要 `root` (sudo) 权限。 ## 安装 克隆仓库并在本地安装： ``` git clone https://github.com/MehmetKozann/stealth-synscan.git cd stealth-synscan sudo python3 synscan.py --help ``` 或者通过 `setup.py` 安装： ``` sudo python3 setup.py install ``` ## 快速使用示例 ### 1. 基础 SYN 扫描 扫描单个目标的常用端口： ``` sudo python3 synscan.py 192.168.1.1 -p 22,80,443 --rate 5 ``` ### 2. 带诱饵的全端口范围扫描 使用 4 个随机生成的诱饵源 IP 扫描 1-1024 端口： ``` sudo python3 synscan.py 10.0.0.5 -p 1-1024 --rate 8 --decoy RND:4 ``` ### 3. 服务验证与 Banner 抓取 扫描、通过二次扫描验证开放端口、抓取 banner，并导出为 JSON： ``` sudo python3 synscan.py 10.0.0.5 -p 21,22,80,443 --confirm --banner --out results.json ``` ### 4. CIDR 范围或文件输入 扫描文本文件或 CIDR 块中列出的目标： ``` sudo python3 synscan.py targets.txt -p 80,443 --rate 3 sudo python3 synscan.py 192.168.1.0/24 -p 80,443 ``` ### 5. 恢复中断的扫描 如果扫描被停止（例如 `Ctrl+C`），可从检查点文件恢复进度： ``` sudo python3 synscan.py 192.168.1.1 --resume .synscan_state.json ``` ## 命令行参数 | 选项 | 描述 | 默认值 | |---|---|---| | `target` | 目标 IP、CIDR 子网、逗号分隔列表或文本文件 | *必填* | | `-p, --ports` | 目标端口规范（例如 `80,443` 或 `1-1024`） | *Top 27 端口* | | `--rate` | 目标数据包发送速率（包/秒） | `5.0` | | `--decoy` | 诱饵 IP 列表（`IP,IP...` 或 `RND:N`） | `""` | | `--retries` | 未确认端口的重试次数 | `1` | | `--timeout` | 响应超时时间（秒） | `2.0` | | `--sport` | 固定源端口（`0` 表示动态随机端口） | `0` | | `--confirm` | 通过二次扫描验证开放端口 | `False` | | `--banner` | 从开放端口抓取服务 banner | `False` | | `--out` | 将扫描结果导出至 JSON 文件 | `""` | | `--resume` | 从文件恢复扫描状态 | `""` | | `--batch` | 每轮批量发送的 SYN 数据包数量 | `256` | | `-v, --verbose` | 启用 debug 日志输出 | `False` | ## 路线图 - [x] 高性能 TCP SYN（半开）扫描 - [x] 诱饵 IP 伪装 (`--decoy`) - [x] 动态 TCP 协议栈指纹规避 - [x] 服务 banner 抓取 (`--banner`) - [x] 可恢复的扫描状态检查点记录 (`--resume`) - [x] 子网展开与目标文件输入 - [ ] 多线程并行子网扫描 - [ ] UDP 端口扫描模式 (`--udp`) - [ ] 被动 OS 检测引擎 (`--os-detect`) ## 常见问题解答 (FAQ)

1. 为什么 synscan 需要 root (sudo) 权限？

SYN 扫描需要使用 raw socket（socket.SOCK_RAW）在二进制层面构造自定义 IPv4 和 TCP 头部。出于安全原因，POSIX 操作系统将 raw socket 的创建限制为 root 用户或具有 CAP_NET_RAW capability 的进程。

2. 为什么原生不支持 Windows？

Windows 内核默认禁用标准用户态 socket 的 raw socket 数据包注入（IPPROTO_RAW）。synscan 专为可完全访问原生 raw socket 的 POSIX 兼容环境（Linux 和 macOS）设计。

3. synscan 是否需要 libpcap 或第三方包？

不需要。synscan 使用 100% 纯 Python 标准库（socket、struct、select）编写。它零外部库依赖，不需要 libpcap、scapy 或 pip 包。

4. 扫描恢复功能是如何工作的？

在执行期间，synscan 会将检查点状态写入 JSON 文件（默认为 .synscan_state.json）。如果扫描被 Ctrl+C 中断，您可以通过运行 --resume .synscan_state.json 立即恢复扫描。

5. synscan 是否支持 CIDR 表示法和输入文件？

支持。您可以提供单个 IP 地址（>192.168.1.1）、CIDR 块（192.168.1.0/24）、逗号分隔列表（10.0.0.1,10.0.0.2），或者逐行包含目标列表的文本文件。

## 法律与安全免责声明 此工具专为教育目的、授权安全审计和防御性渗透测试而创建。未经事先书面许可擅自扫描网络是违法行为。作者不对因滥用本软件或由此造成的任何损害承担责任。 ## 许可证 基于 MIT 许可证分发。详情请参阅 [`LICENSE`](LICENSE)。

标签：Python, 插件系统, 数据统计, 无后门, 端口扫描, 逆向工具