karthitom/LumenRecon

# 💡 LumenRecon — 网络探测器      ## 什么是 LumenRecon？ LumenRecon 是一款模块化、终端优先的网络侦察工具，它在安全且对新手友好的界面中封装了 [Nmap](https://nmap.org)。传统的侦察工具通常让你阅读冗长的报告[...] 本项目严格为**防御性安全工作**而构建：了解你自己的攻击面、验证防火墙规则，并随着时间的推移监控资产变更。 ## 功能 - 💡 **探测器模型** — 严格的目标验证确保只有经过许可且格式正确的地址才会被发送到网络 - 🔒 使用带有 `list[str]` 命令的 `subprocess.run(shell=False)` — 实现 OS 命令注入风险零暴露 - ⚡ **三种扫描配置** — 从 5 秒钟的快速扫描到完整的 65535 端口深度扫描 - 🎨 **Rich 终端 UI** — 动画加载图标、带有颜色区分的端口表，以及格式化且适合新手的帮助菜单 - 📁 **导出 JSON 和 CSV** 到专属的 `reports/` 目录，并使用带时间戳的文件名 - 🧩 **完全模块化的代码库** — `cli.py` · `scanner.py` · `parser.py` · `reporter.py` · `main.py` - 🛡️ 自定义异常（`NmapNotFoundError`、`ScanTimeoutError`、`ScanError`），提供干净、可预测的错误处理 - 🔭 已为第二阶段做好准备：提供 `diff_scans()` 和 `run_scan_with_metadata()` 存根，用于资产变更检测 ## 项目结构 ``` lumenrecon/ ├── main.py # Orchestrator & entry point ├── cli.py # Argument parsing & strict input validation ├── scanner.py # Nmap subprocess execution (shell=False always) ├── parser.py # Raw nmap output → structured dicts ├── reporter.py # Terminal table rendering & file export ├── reports/ # Auto-created — exported JSON/CSV reports land here ├── requirements.txt └── README.md ``` ## 环境要求 | 要求 | 版本 | 备注 | |---|---|---| | Python | 3.10+ | 使用现代 type hint 语法 | | Nmap | 任何现代版本 | 必须位于系统的 `PATH` 中 | | rich | 13.7.1 | 通过 `requirements.txt` 安装 | ## 安装说明 ### 1 — 安装 Nmap LumenRecon 会将 nmap 作为外部进程调用。请先为你的操作系统安装它。 **Linux (Debian / Ubuntu)** ``` sudo apt-get update && sudo apt-get install -y nmap ``` **macOS (Homebrew)** ``` brew install nmap ``` **Windows** 从 [nmap.org/download.html](https://nmap.org/download.html) 下载并运行安装程序。 确保安装目录（例如 `C:\Program Files (x86)\Nmap`）已添加到你的 `PATH` 中。 验证安装： ``` nmap --version ``` ### 2 — 克隆仓库 ``` git clone https://github.com/karthitom/lumenrecon.git cd lumenrecon ``` ### 3 — 创建虚拟环境（推荐） 我们建议使用虚拟环境来隔离项目依赖。 推荐的 Python 版本：本项目目标是 Python 3.10+。使用以下命令确认： ``` python --version # 或 python3 --version ``` POSIX (macOS / Linux) ``` # 在项目目录中创建 venv python3 -m venv .venv # 激活 venv source .venv/bin/activate # 升级 pip 并安装 dependencies pip install --upgrade pip pip install -r requirements.txt ``` Windows (PowerShell) ``` # 创建 venv py -3 -m venv .venv # 激活 .\.venv\Scripts\Activate.ps1 # 升级 pip 并安装 dependencies python -m pip install --upgrade pip python -m pip install -r requirements.txt ``` Windows (cmd.exe) ``` py -3 -m venv .venv .venv\Scripts\activate.bat python -m pip install --upgrade pip python -m pip install -r requirements.txt ``` 可选工具 - Poetry：`poetry install`（如果项目使用 Poetry） - Pipenv：`pipenv install`（如果项目使用 Pipenv） 注意事项 - 将 `.venv/`（或你的虚拟环境目录）添加到 `.gitignore` 中，以避免将本地环境提交到版本库。 - 如果项目在 `pyproject.toml` 或其他元数据中指定了 Python 版本，请在此处参考该版本，而不是使用通用建议。 ### 4 — 安装 Python 依赖 ``` pip install -r requirements.txt ``` ## 使用说明 ### 基本语法 ``` python main.py -t [options] ``` ### 参数一览 | 参数 | 必需 | 默认值 | 描述 | |---|---|---|---| | `-t` / `--target` | **是** | — | 目标 IPv4（例如 `192.168.1.1`）或域名（例如 `example.com`） | | `-s` / `--scan-type` | 否 | `fast` | 扫描配置：`fast` · `service` · `full` | | `-o` / `--output` | 否 | 仅终端 | 导出格式：`json` 或 `csv` | | `--timeout` | 否 | `300` | 等待扫描的最长秒数 | | `-h` / `--help` | 否 | — | 显示完整的 LumenRecon 帮助菜单 | ## 使用示例 ### 最小化 — 快速扫描，仅输出到终端 ``` python main.py -t 192.168.1.1 ``` 扫描最常见的 100 个端口。结果将打印到终端。几秒钟即可完成。 ### 针对域名的服务检测 ``` python main.py -t example.com -s service ``` 扫描前 1000 个端口并检测服务名称和版本字符串（例如 `Apache httpd 2.4.54`）。准确显示每个端口上正在监听什么软件。 ### 导出 JSON 的完整扫描 ``` python main.py -t 10.0.0.5 -s full -o json ``` 结合版本检测扫描所有 65535 个端口。将带有时间戳的报告保存到 `reports/scan_10_0_0_5_.json`。 ### 带有较长超时的 CSV 导出 ``` python main.py -t 10.0.0.5 -o csv --timeout 600 ``` 快速扫描并导出为 CSV。`--timeout 600` 为缓慢或拥塞的网络提供了 10 分钟的响应时间。 ### 查看帮助菜单 ``` python main.py -h ``` 显示完整的 LumenRecon Rich 格式化帮助面板 — 参数说明、使用示例和扫描速度指南。 ## 扫描配置 | 配置 | Nmap 参数 | 扫描端口 | 典型速度 | |---|---|---|---| | `fast` | `-F` | 前 100 个 | ~5–15 秒 | | `service` | `-sV` | 前 1000 个 + 版本检测 | ~1–5 分钟 | | `full` | `-p- -sV` | 所有 65535 个 + 版本检测 | 10–30+ 分钟 | ## 输出文件 当使用 `--output json` 或 `--output csv` 时，文件将以带 UTC 时间戳的名称写入 `reports/` 目录： ``` reports/ └── scan_192_168_1_1_20250619_143022.json └── scan_example_com_20250619_143500.csv ``` **JSON 结构** ``` { "host": "192.168.1.1", "hostname": "router.local", "state": "up", "ports": [ { "port": 80, "protocol": "tcp", "state": "open", "service": "http", "version": "Apache httpd 2.4.54" } ] } ``` **CSV 列名** ``` host, hostname, host_state, port, protocol, state, service, version ``` ## 安全设计 LumenRecon 在每一层都秉持安全第一的原则： - **不执行 shell 命令。** `subprocess.run()` 始终以 `shell=False` 和 `list[str]` 命令调用。目标字符串是一个单独的列表元素 — 它永远不会被解释为 shell 命令[...] - **严格的输入白名单。** 在进行任何子进程调用之前，目标都会通过 Python 的 `ipaddress` 模块（用于 IPv4）和编译后的 RFC-1123 正则表达式（用于域名）进行验证。 - **拦截保留地址段。** 回环地址（`127.x`）、未指定地址（`0.0.0.0`）、多播地址和链路本地地址会在 CLI 层被明确拒绝。 - **输出格式受限。** `--output` 参数仅接受字面量字符串 `json` 或 `csv` — 没有任何自由格式的字符串会到达文件系统层。 - **最小化 nmap 表面。** 扫描配置仅使用端口枚举参数。没有操作系统检测（`-O`），没有脚本引擎（`-sC`），也没有暴力破解。 - **extra_flags 防护。** 任何由调用方提供的 nmap 参数必须是一个 `list[str]`，其中每个元素都以 `-` 开头，从而防止通过该参数进行位置参数注入。 ## 道德与法律声明 ## 路线图（第二阶段） - [ ] 持久化状态存储 — 保存扫描历史并检测运行期间的资产变更 - [ ] `diff_scans()` — 突出显示自上次扫描以来新打开或关闭的端口 - [ ] IPv6 支持 - [ ] 带 LumenRecon 品牌标识的 HTML 报告导出 - [ ] CI/CD 集成模式（遇到新打开的端口时返回非零退出代码） ## 许可证 MIT — 详情请参阅 `LICENSE`。

标签：CTI, Nmap封装, Python, 插件系统, 数据统计, 无后门, 端口扫描, 资产监控, 逆向工具