antwnakys/reconforge

# 🛠️ ReconForge      一个**模块化的侦察与漏洞评估框架** —— 这是一个轻量级、 可扩展的引擎，可针对已授权目标运行可插拔的侦察*模块*， 将其输出关联至统一的发现模型，把每个 结果映射至 **MITRE ATT&CK**，并以 Markdown、JSON 和 HTML 格式生成专业报告。 你可以将其视作 `nmap` + `nuclei` + 报告层等工具的微缩版、易读且从零开始的实现 —— 旨在*演示它们的工作原理*， 全程端到端，且**零第三方依赖**。 ``` ___ ___ | _ \___ __ ___ _ _ ___ | __|__ _ _ __ _ ___ | / -_) _/ _ \ ' \/ -_) | _/ _ \ '_/ _` / -_) |_|_\___\__\___/_||_\___| |_|\___/_| \__, \___| |___/ ``` ## 为什么开发它 我的其他安全仓库都是专注于单一用途的脚本（端口扫描器、 header 检查器、哈希破解器）。ReconForge 是将这些想法 整合到一个**连贯框架**中的项目，并展示了真实工具所需的工程设计：插件架构、异步扫描引擎、共享的发现模型、scope/授权安全机制以及多格式报告 —— 全部经过测试。当有人要求“给我看点比脚本更大的东西”时，我就会展示这个项目。 ## 核心特性 - **插件架构** —— 一个模块就是一个类 + 一个装饰器。引擎会自动发现它。添加新功能绝不需要修改中央列表。 - **异步引擎** —— 目标并发扇出；在每个目标内部，模块按阶段顺序运行（*发现 → 枚举 → 评估*），以便后续模块能复用早期结果（开放的端口用于 Web 枚举，Web 枚举用于内容发现）。 - **统一的发现模型** —— 模块从不直接打印；它们*返回*发现结果。一次扫描可以从相同的数据渲染出 Markdown、JSON 和独立的 HTML 报告。 - **MITRE ATT&CK 映射** —— 每个发现都会被打上与其相关的技术标签，因此报告能与蓝队使用相同的语言。 - **安全第一** —— 强制性的授权标志，可选的 scope 白名单（hosts/CIDRs），以及对 CIDR 扩展的硬性上限。 - **对 CI 友好** —— 当发现任何 **HIGH+** 级别的问题时以非零状态退出，因此你可以据此拦截 pipeline。 - **零依赖** —— 纯 Python 标准库，支持 Python 3.9+。 ## 安装 ``` git clone https://github.com/antwnakys/reconforge.git cd reconforge pip install -e . # installs the `reconforge` command ``` 或者不安装直接运行： ``` python -m reconforge --help ``` ## 用法 ``` # 列出框架能做的所有事情 reconforge modules # 对单个授权主机的全面评估，保存所有报告格式 reconforge scan example.com --authorized -o report -f all # 非标准端口上的 Web 应用 reconforge scan https://staging.example.com:8443 --authorized # 一个内部 /29 范围，仅限端口 22/80/443，限制于 scope 文件 reconforge scan 10.10.10.0/29 -p 22,80,443 --scope scope.txt --authorized # 仅保留你想要的模块 reconforge scan example.com -m port_scan,http_enum --authorized # 在不触碰目标的情况下进行规划 reconforge scan example.com --dry-run ``` 关键 flags：`-p/--ports`（`22,80,443` 或 `1-1024`），`-m/--modules`， `-x/--exclude`，`--timeout`，`--concurrency`，`--scan-all`（扫描不响应 TCP ping 的主机），`--scope FILE`，`-o/--output`，`-f/--format` `{md,json,html,all}`。 ### Scope 文件 每行一个主机或 CIDR；允许使用 `#` 注释。如果提供此文件，任何不在此列表中的目标都会被跳过： ``` # engagement scope — Acme Corp，授权于 2026-07-01 example.com 10.10.10.0/24 ``` ## 输出示例 针对特意设置的本地易受攻击目标运行（参见 [`examples/`](examples/)）会产生： ``` # ReconForge 报告 - **Risk score:** 34 ## 总结 | Severity | Count | | ---------- | ----- | | ‼ Critical | 1 | | ⬆ High | 1 | | ▲ Medium | 2 | | ▪ Low | 3 | ## 发现 #### ‼ [Critical] 暴露的敏感路径: /.env [200] - **Module:** `content_discovery` - Exposed environment file — often contains DB/API credentials. (HTTP 200) - **Remediation:** Remove the file or block the path at the web server. - **ATT&CK:** T1595.003 (Active Scanning: Wordlist Scanning) #### ⬆ [High] 暴露的敏感路径: /.git/HEAD [200] - Exposed Git repository — source code & secrets may be recoverable. ``` HTML 报告（[`examples/demo_report.html`](examples/demo_report.html)）是一个 独立的单文件 —— 可安全地离线打开或作为电子邮件附件。 ## 内置模块 | 模块 | 阶段 | 功能描述 | ATT&CK | | ------ | ----- | ------------ | ------ | | `host_discovery` | discovery | 对常用端口进行 TCP-ping 以判断主机是否存活 | T1595.001 | | `port_scan` | discovery | 并发 TCP connect 扫描 + banner grabbing | T1046, T1595.001 | | `service_fingerprint` | enumeration | 标记明文/遗留/暴露的服务（telnet、Redis、旧版 OpenSSH 等） | T1592.002 | | `http_enum` | enumeration | 抓取 Web 根目录，评估 security headers，检测使用的技术 | T1595.002, T1592.002 | | `tls_inspect` | assessment | 过期 / 自签名 / 证书不匹配，弱 TLS 版本 | T1592.002, T1595.002 | | `content_discovery` | assessment | 探测高信号字典列表以发现暴露的 `.env`、`.git`、备份文件等 | T1595.003 | ## 架构 ``` ┌────────────┐ targets ───▶ │ Engine │ resolves + enforces scope, fans out └─────┬──────┘ │ per target, phase-ordered ┌─────────────────┼──────────────────┐ ▼ ▼ ▼ discovery enumeration assessment host_discovery service_fp tls_inspect port_scan ──────▶ http_enum ────────▶ content_discovery │ writes open_ports writes web_services │ └──────────── shared target.state ───────────┘ │ ▼ ┌────────────┐ │ Findings │ ─▶ Markdown / JSON / HTML └────────────┘ ``` - `reconforge/core/` —— 框架核心：`engine`、`module`（插件契约 + 注册表）、`findings`、`target`、`scope`、`attack`、`net`（异步 socket/HTTP/TLS 辅助工具）。 - `reconforge/modules/` —— 内置的侦察模块。 - `reconforge/reporting/` —— Markdown / JSON / HTML 渲染器。 ## 编写自定义模块 这正是框架的核心意义所在。只需在 `reconforge/modules/` 中放入一个文件： ``` from ..core import attack from ..core.findings import Severity from ..core.module import BaseModule, Context, Phase, register from ..core.target import Target @register class RobotsCheck(BaseModule): name = "robots_check" description = "Look for a robots.txt that leaks hidden paths." phase = Phase.ASSESSMENT attack = [attack.ACTIVE_SCANNING_VULN] async def run(self, target: Target, ctx: Context): from ..core.net import http_get findings = [] for port, svc in target.state.get("web_services", {}).items(): resp = await http_get(svc["url"].rstrip("/") + "/robots.txt", ctx.timeout) if resp and resp["status"] == 200 and "Disallow" in resp["body"]: findings.append(self.finding( target, title=f"robots.txt discloses paths ({port}/tcp)", severity=Severity.LOW, description="Disallow entries reveal hidden paths.", )) return findings ``` 在 `reconforge/modules/__init__.py` 中注册导入，它就会自动出现在 `reconforge modules` 中。 ## 测试 ``` pip install -e ".[dev]" pytest -q ``` 32 个测试涵盖了目标解析、发现模型、scope 强制执行、所有报告 渲染器，以及扫描一次性本地 HTTP 服务器的实时集成测试 —— 因此测试套件中的任何操作都不需要接触外部网络。 ## 路线图 - [ ] DNS/子域名枚举模块 - [ ] 用于内容发现的可插拔外部字典 - [ ] 针对单台主机的 Rate-limiting / 礼貌控制机制 - [ ] 针对指纹识别出的版本进行可选的 CVE 查询丰富化 - [ ] 针对大规模扫描的 JSONL 流式输出 ## 法律与道德 ReconForge 是一个用于学习和授权测试的工具。未经授权的扫描可能 违反相关法律，例如美国《计算机欺诈和滥用法》、英国《计算机 滥用法》以及其他地区的类似法律。**获取书面许可。保持在 scope 范围内。** ## 许可证 MIT —— 见 [LICENSE](LICENSE)。

标签：AES-256, Cloudflare, MITRE ATT&CK, Python, 实时处理, 密码管理, 异步框架, 插件系统, 无后门, 漏洞评估, 网络探针, 自动化侦查, 计算机取证, 逆向工具