内容
<div align="center">
# 暗影侦察
### 自动攻击面侦察平台
**单个Go二进制文件，运行整个第1阶段侦察生命周期 — 从子域名发现到优先排序、具备攻击条件的目标列表 — 具备实时Web UI、REST API和MCP集成，适用于LLM代理。**
由 [**暗影神经网络 (DNN) 团队**](https://darkneuralnetwork.com) 研发
[](https://go.dev)
[](#license-disclaimer)
[](#prerequisites)
[](#installation)
</div>
---
## 目录
- [什么是暗影侦察？](#what-is-dark-recon)
- [为什么使用它？](#why-use-it)
- [功能](#features)
- [核心流程](#core-pipeline)
- [平台](#platform)
- [工程](#engineering)
- [高级功能](#advanced-features)
- [1. 优先级评分引擎](#1-priority-scoring-engine)
- [2. 第1阶段高级模块（按扫描选择）](#2-phase-1-advanced-modules-opt-in-per-scan)
- [3. MCP / LLM集成](#3-mcp-llm-integration)
- [4. 自我修复工具链](#4-self-healing-toolchain)
- [5. 第2阶段交接](#5-phase-2-handoff)
- [它驱动的工具](#the-tools-it-drives)
- [架构](#architecture)
- [扫描流程](#scan-pipeline)
- [优先级评分引擎](#priority-scoring-engine)
- [先决条件](#prerequisites)
- [系统要求](#system-requirements)
- [先决条件引擎](#prerequisites-engine)
- [SecLists和Nuclei模板](#seclists-nuclei-templates)
- [安装](#installation)
- [选项1 — 安装脚本（推荐，适用于任何Linux/macOS）](#option-1-install-script-recommended-any-linuxmacos)
- [选项2 — `go install`（需要Go）](#option-2-go-install-requires-go)
- [选项3 — 从源代码构建](#option-3-build-from-source)
- [选项4 — Debian/Ubuntu软件包（.deb）⭐ 自我启动](#option-4-debianubuntu-package-deb-self-bootstrapping)
- [验证安装](#verify-the-install)
- [配置](#configuration)
- [`config.yaml`（主配置文件）](#configyaml-main-config)
- [`tools_config.yaml`（工具配置）](#tools_configyaml-tool-config)
- [`llm_config.yaml`（LLM配置 — 用于AI辅助功能）](#llm_configyaml-llm-config-for-ai-assisted-features)
- [用法](#usage)
- [启动服务器](#starting-the-server)
- [启动扫描](#launching-a-scan)
- [查看结果](#viewing-results)
- [API参考](#api-reference)
- [扫描管理](#scan-management)
- [目标数据](#target-data)
- [第1阶段高级模块](#phase-1-advanced-modules)
- [第2阶段交接](#phase-2-handoff)
- [配置和工具](#configuration-tools)
- [WebSocket](#websocket)
- [MCP / LLM集成](#mcp-llm-integration)
- [Web UI](#web-ui)
- [输出和数据库](#output-database)
- [数据库模式（11张表，每张表对应一个目标）](#database-schema-11-tables-per-target)
- [安全](#security)
- [开发](#development)
- [Make目标](#make-targets)
- [依赖项](#dependencies)
- [项目结构](#project-structure)
- [添加新工具](#adding-a-new-tool)
- [添加新模块](#adding-a-new-module)
- [许可证和免责声明](#license-disclaimer)
---
## 什么是暗影侦察？
**暗影侦察** 是一个 **第1阶段侦察和攻击面发现引擎**。您只需提供一个根域名，它就能自主地协调一系列行业标准的 安全工具，以绘制目标的整个外部攻击面 — 然后根据漏洞利用率对每个发现结果进行排名，以便您知道 **首先从哪里开始攻击**。
它不仅仅是一个脚本包装器。它是一个 **平台**：一个并发管道引擎、一个SQLite数据层、一个实时Web仪表板、一个REST API和一个MCP服务器，允许AI代理驱动整个过程。
> **它解决的问题：** 手动侦察速度慢、重复性高、一致性差。原始工具输出噪声大、排名不佳。暗影侦察将域名转换为 **优先排序、证据支持的目标列表**，并附有第2阶段交接文档 — 几分钟内即可完成，且始终如一。
---
## 为什么使用它？
| 您厌倦了… | 暗影侦察为您提供… |
|---|---|
| 手动运行8种工具并拼接输出 | 一个命令 → 完整的流水线，自动化 |
| 淹没在无排名的Nuclei发现结果中 | **0–100优先级评分**，每个子域名附带原因 |
| 跟踪要优先攻击的内容 | **第2阶段交接** 文档：优先级目标、参数、漏洞 |
| 重新进行侦察却没有历史记录 | **每个目标的SQLite数据库** — 可恢复和查询 |
| 在长时间扫描期间盯着终端 | **实时Web UI**，带有WebSocket进度流式传输 |
| 将工具粘合到CI/LLM工作流中 | **REST API** + **MCP服务器**，适用于Claude/Cursor/Cline |
| 新机器上安装不完整的工具链 | **自我启动** `.deb`，自动安装工具 |
| 不安全的 `shell=True` 侦察脚本 | **无Shell注入** — 每个地方都使用 `exec.Command` 参数切片 |
**简而言之：** 暗影侦察是从“我有一个域名”到“我有一个优先排序的利用计划”的桥梁。
---
## 功能
### 核心流程
- **8阶段编排器**，在依赖关系允许的情况下并行执行
- **Katana爬取前进行Nuclei爬取** — 爬取的URL被馈送到Nuclei中作为额外目标
- **子域名接管检测**（subzy）与漏洞扫描并行运行
- **优先级评分**，跨7个因素，归一化为0–100的等级，具有层级
- **可恢复的扫描** — 之前子域名/活动主机/URL数据在重新运行阶段时被重用
### 平台
- **单个静态二进制文件** — 嵌入式Web UI，无外部资产目录，无CGO
- **实时WebSocket**进度流式传输，在实时扫描期间
- **SQLite存储**（WAL模式，单写入器）— 每个目标一个数据库，11张表
- **纯HTML + JS前端** — 无服务器端模板，无构建步骤
- **REST API** — 对扫描、目标、工具、配置的完全编程控制
- **MCP服务器** — 通过stdio将整个平台暴露给LLM客户端
- **工具自动安装** — 按照需求通过`go install`安装缺失的工具
- **基于上下文的取消** — 长扫描优雅停止，部分结果保留
- **自我启动的`.deb`** — 在首次启动时检查并自动安装先决条件
### 工程
- **无Shell注入** — 每个子进程都使用`exec.CommandContext`，带有参数切片
- **每个工具的超时**，通过`context.WithTimeout` — 没有永远挂起的东西
- **结构化日志**（`log/slog`）到控制台 + 旋转文件
- **解耦模块** — 每个阶段都有`*config.Config`、`*storage.DB`、`scanID`
---
## 高级功能
### 1. 优先级评分引擎
每个活动子域名都跨 **7个加权因素** 进行评分，并归一化为 **0–100**：
| 因素 | 最大值 | 衡量内容 |
|---|---|---|
| 子域名关键词 | 30 | 高价值名称（`admin`、`api`、`staging`、`vpn`等） |
| 漏洞严重性 | 35 | 关键=35，高=25，中=15，低=5 |
| 子域名接管 | 25 | subzy确认的接管 |
| 暴露敏感路径 | 20 | `.env`、`.git`、`/admin`、`/phpmyadmin`等 |
| 缺失安全标头 | 15 | CSP、HSTS、X-Frame-Options等 |
| 技术栈风险 | 12 | 终止/漏洞模式（PHP 5.x、Apache 2.4.49等） |
| 富含参数的URL | 10 | 注入面（查询参数计数） |
**层级：** 关键（70–100）· 高（45–69.9）· 中（25–44.9）· 低（0–24.9）
该引擎还发出 **上下文感知建议的手动测试**（例如`.env` → 检查凭证、`.git` → 源代码泄露、缺失CSP → XSS）— 因此输出不仅仅是一个分数，而是一个行动计划。
### 2. 第1阶段高级模块（按扫描选择）
除了核心的8个阶段，暗影侦察运行一组附加的高级模块，每个模块都有一个有限的工作池，如果工具缺失，则会降级：
| 模块 | 工具 | 执行内容 |
|---|---|---|
| **被动侦察** | crt.sh、HackerTarget、AlienVault、chaos | 证书透明度和OSINT子域名情报 |
| **端口扫描** | nmap | 隐身SYN / TCP连接端口扫描 |
| **WAF检测** | wafw00f | 识别保护每个主机的WAF |
| **JS分析** | *纯Go* | 解析JS文件以获取端点、秘密和源映射 |
| **参数发现** | arjun | 发现隐藏的HTTP参数 |
| **秘密扫描** | trufflehog + gitleaks | 在爬取的JS/文件中查找泄露的秘密 |
### 3. MCP / LLM集成
同一个二进制文件兼作 **MCP（模型上下文协议）服务器**。将Claude Desktop、Cursor或Cline指向它，LLM可以：
- 启动和监控扫描（`launch_scan`、`wait_for_scan`）
- 检索优先发现结果和第2阶段交接
- 管理工具和编辑配置
- 导出JSON/CSV报告
> 一个二进制文件，两个接口：**HTTP**适用于人类，**stdio MCP**适用于代理。
### 4. 自我修复工具链
捆绑的先决条件引擎（`scripts/check-prereqs.sh`）是 **唯一真实来源** — 由CLI、Web UI和`.deb`启动器共享。当从`.deb`安装时，启动器 **自动安装在第一次运行时缺失的必需Go工具**（无需`sudo`核心管道），并缓存结果，以便后续启动立即完成。
### 5. 第2阶段交接
暗影侦察并不止于“发现结果”。它会发出一个 `phase2_handoff.json` — 为利用阶段提供一个巩固的、优先排序的契约：优先级目标、所有带参数的URL、按严重性划分的漏洞计数。侦察工作干净地交给进攻方。
---
## 它驱动的工具
暗影侦察协调这些外部工具（在缺失时自动安装）：
| 工具 | 阶段 | 安装 |
|---|---|---|
| **subfinder** | 子域名枚举（被动） | `go install github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest` |
| **ffuf** | DNS暴力 + 目录模糊 | `go install github.com/ffuf/ffuf/v2@latest` |
| **httpx** | 活动主机检测 | `go install github.com/projectdiscovery/httpx/cmd/httpx@latest` |
| **webanalyze** | 技术指纹识别 | `go install github.com/rverton/webanalyze/cmd/webanalyze@latest` |
| **katana** | Web爬取 | `go install github.com/projectdiscovery/katana/cmd/katana@latest` |
| **nuclei** | 漏洞扫描 | `go install github.com/projectdiscovery/nuclei/v3/cmd/nuclei@latest` |
| **subzy** | 子域名接管 | `go install github.com/PentestPad/subzy@latest` |
| **nmap** *(可选)* | 端口扫描 | `sudo apt install nmap` |
| **naabu** *(可选)* | 快速端口扫描（替代） | `go install github.com/projectdiscovery/naabu/v2/cmd/naabu@latest` |
| **chaos** *(可选)* | 被动子域名情报 | `go install github.com/projectdiscovery/chaos/cmd/chaos@latest` |
| **trufflehog** *(可选)* | 秘密扫描 | `go install github.com/trufflesecurity/trufflehog/v3@latest` |
| **gitleaks** *(可选)* | 秘密扫描 | `go install github.com/gitleaks/gitleaks/v8@latest` |
| **wafw00f** *(可选)* | WAF检测 | `pip install wafw00f` |
| **arjun** *(可选)* | 参数发现 | `pip install arjun` |
| **seclists** *(推荐)* | 词列表 | `sudo apt install seclists` |
---
## 架构
```
┌──────────────────────────────────────────────────────────────┐
│ Web浏览器 / LLM代理 │
│ (HTML+JS UI, fetch() REST, WebSocket) (MCP over stdio) │
└──────────────────────────┬───────────────────────────────────┘
│ HTTP / WebSocket / stdio
┌──────────────────────────▼───────────────────────────────────┐
│ API层 (internal/api) + MCP (internal/mcp) │
│ REST处理器 · WebSocket升级器 · 静态/模板服务 │
└──────────────────────────┬───────────────────────────────────┘
│
┌──────────────────────────▼───────────────────────────────────┐
│ 扫描管理器 (internal/scanmgr) │
│ 后台goroutine · 进度跟踪 · 取消上下文 │
└──────────────────────────┬───────────────────────────────────┘
│
┌──────────────────────────▼───────────────────────────────────┐
│ 流水线引擎 (internal/pipeline) │
│ 8阶段编排器 + 第1阶段高级模块 │
└──────────────────────────┬───────────────────────────────────┘
│
┌──────────┬───────┴───────┬──────────┬──────────────┐
▼ ▼ ▼ ▼ ▼
枚举 发现 技术 nuclei 评分
(subfinder, (httpx, (webanalyze (nuclei, (优先级
ffuf DNS) katana) + headers) subzy) 排名)
│ │ │ │ │
▼ ▼ ▼ ▼ ▼
┌──────────────────────────────────────────────────────────────┐
│ 存储层 (internal/storage) │
│ SQLite（WAL模式）— 11张表，每个目标一个数据库 │
└──────────────────────────────────────────────────────────────┘
│ │
▼ ▼
pkg/executor pkg/parser
(子进程运行器，无Shell) (输出解析器)
```
**设计原则：** 并发性（并行阶段）· 上下文取消 · 解耦模块（无共享可变状态）· 单写入器SQLite · 无Shell注入 · 结构化日志。
---
## 扫描流程
```
第1阶段：子域名枚举（+ 并行被动侦察）
│ subfinder（被动）+ ffuf DNS暴力 + 原生Go DNS解析
│ (+ crt.sh / HackerTarget / AlienVault / chaos 如果被动侦察)
▼
第2阶段：活动主机检测
│ httpx探测所有子域名 — 状态、标题、Web服务器、CDN、技术、重定向
▼
第3 + 第4阶段（PARALLEL）
│ ┌─ 技术检测（webanalyze + HTTP头部分析）
│ └─ 深度爬取（Katana，所有活动主机）→ URL馈送到Nuclei
▼
第5阶段：URL情报层
│ ffuf目录枚举（顶部N个活动主机，SecLists词列表）
▼
第6阶段：漏洞扫描（并行）
│ ┌─ Nuclei（活动主机 + Katana爬取的URL），按严重性 + CVSS过滤
│ └─ Subzy（子域名接管检测）
▼
第7阶段：截图收集
│ gowitness捕获所有活动主机的截图
▼
第8阶段：优先级评分
│ 每个子域名跨7个因素评分 → 0-100 → 等级
│ 生成report.json + phase2_handoff.json
▼
完成 → SQLite数据库 + JSON报告 + 交接文件
```
第1阶段高级模块（被动侦察、端口扫描、WAF检测、JS分析、参数发现、秘密扫描）在配置启用时 **附加** 运行。
---
## 优先级评分引擎
参见上面的 [高级功能](#1-priority-scoring-engine) 章节，了解7因素分解。
**输出文件（每个目标）：**
- `priority/priority_ranking.json` — 完整的排名列表，包含分数、原因、技术栈、漏洞、参数URL、暴露的目录、缺失的头部、接管状态、建议的测试
- `priority/phase2_handoff.json` — 巩固的交接用于利用：目标、子域名总数、按严重性划分的漏洞计数、所有优先级目标、所有带参数的URL
- `reports/report.json` — 巩固的报告（活动主机、漏洞、爬取的URL、目录、优先级）
---
## 先决条件
### 系统要求
- **Linux**（在Parrot OS / Debian基系统上测试），amd64或arm64 *（macOS也构建）*
- **libc6** — 唯一硬依赖的`.deb`；在Debian/Ubuntu上始终存在
- ~50MB用于二进制文件 + 输出数据的空闲磁盘空间
- **Go**（任何最近的版本）— *仅在安装安全工具时需要*。暗影侦察服务器二进制文件本身是预构建的静态链接，因此无需Go即可运行。（从源代码构建在`go.mod`中声明`go 1.25`；Go工具链在需要时自动下载兼容的编译器。）
### 先决条件引擎
单个脚本 — `scripts/check-prereqs.sh` — 是CLI、Web UI和`.deb`启动器的真实来源。它检查系统、构建工具链、每个安全工具（带有安装版本 + 路径）和词列表/模板，并可以自动安装缺失的项目。
```bash
make check-prereqs # 只读状态报告（版本 + 路径）
make install-tools # 安装缺失的必需工具
bash scripts/check-prereqs.sh --install # 相同，显式
bash scripts/check-prereqs.sh --install --strict # 还安装可选工具
```
### SecLists和Nuclei模板
```bash
sudo apt install seclists # 目录/ DNS 暴力破解的词列表
nuclei -update-templates # 模板安装到 ~/nuclei-templates/
```
确保`config.yaml`中的路径与您的安装路径相匹配。
---
## 安装
暗影侦察以单个静态、自包含的二进制文件形式提供 — 嵌入式Web UI，无外部资产目录。选择最适合您的方法。
> 💡 **新安装？在Debian/Ubuntu上使用`.deb`（选项4）** — 它在第一次启动时自动安装自己的先决条件。
### 选项1 — 安装脚本（推荐，适用于任何Linux/macOS）
```bash
curl -fsSL https://raw.githubusercontent.com/yourname/dark-recon/main/install.sh | bash
```
下载适用于您操作系统/架构的正确二进制文件（Linux和macOS，amd64和arm64），验证其sha256校验和，将其安装到 `/usr/local/bin`（或 `~/.local/bin`），然后运行先决条件检查。如果适用于您的平台没有预先构建的二进制文件，则会回退到 `go install` 或从源代码构建。
```bash
# 选项：
curl ... | bash -s -- --version v1.0.0 # 特定发布标签
curl ... | bash -s -- --skip-check # 跳过先决条件检查
```
### 选项2 — `go install`（需要Go）
```bash
go install github.com/yourname/dark-recon/cmd/dark-recon@latest
```
二进制文件位于 `$(go env GOPATH)/bin` — 确保它在您的 `PATH` 中。
### 选项3 — 从源代码构建
```bash
git clone https://github.com/yourname/dark-recon.git
cd dark-recon
go build -o dark-recon cmd/dark-recon/main.go
```
### 选项4 — Debian/Ubuntu软件包（.deb）⭐ 自我启动
```bash
wget https://github.com/yourname/dark-recon/releases/download/v1.0.0/dark-recon_1.0.0_amd64.deb
sudo dpkg -i dark-recon_1.0.0_amd64.deb
```
### 验证安装
```bash
dark-recon --version
```
---
## 配置
### `config.yaml`（主配置文件）
```yml
server:
port: 8080
host: 0.0.0.0
```
### `tools_config.yaml`（工具配置）
```yml
subfinder:
sources:
- crt.sh
- HackerTarget
```
### `llm_config.yaml`（LLM配置 — 用于AI辅助功能）
```yml
llm:
model: text-davinci-002
api_key: YOUR_API_KEY
```
---
## 用法
### 启动服务器
```bash
dark-recon server
```
### 启动扫描
```bash
dark-recon scan --domain example.com
```
### 查看结果
```bash
dark-recon report --scan-id <scan-id>
```
---
## API参考
### 扫描管理
```bash
curl -X POST \
http://localhost:8080/scans \
-H 'Content-Type: application/json' \
-d '{"domain": "example.com"}'
```
### 目标数据
```bash
curl -X GET \
http://localhost:8080/scans/<scan-id>/targets
```
### 第1阶段高级模块
```bash
curl -X POST \
http://localhost:8080/scans/<scan-id>/modules \
-H 'Content-Type: application/json' \
-d '{"module": "passive_recon"}'
```
### 第2阶段交接
```bash
curl -X GET \
http://localhost:8080/scans/<scan-id>/phase2_handoff
```
### 配置和工具
```bash
curl -X GET \
http://localhost:8080/config
```
### WebSocket
```bash
wscat -c ws://localhost:8080/websocket
```
---
## MCP / LLM集成
### Web UI
---
## 输出和数据库
### 数据库模式（11张表，每个目标一个）
```sql
CREATE TABLE targets (
id INTEGER PRIMARY KEY,
domain TEXT NOT NULL
);
CREATE TABLE subdomains (
id INTEGER PRIMARY KEY,
target_id INTEGER NOT NULL,
subdomain TEXT NOT NULL,
FOREIGN KEY (target_id) REFERENCES targets (id)
);
```
---
## 安全
---
## 开发
### Make目标
```bash
make build
make test
make check-prereqs
```
### 依赖项
```bash
go get -u github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
```
### 项目结构
```bash
.
cmd
internal
pkg
scripts
```
### 添加新工具
```bash
# 添加新工具到 internal/tools 目录
# 更新 internal/tools/tools.go 以包含新工具
```
### 添加新模块
```bash
# 添加新模块到 internal/modules 目录
# 更新 internal/modules/modules.go 以包含新模块
```
---
## 许可证和免责声明
---
> **注意：** 本翻译由AI完成，可能存在错误或不准确。如有任何问题或建议，请随时反馈。
### 选项 3 — 从源代码构建
```bash
git clone https://github.com/yourname/dark-recon.git
cd dark-recon
make build # 生成 ./dark-recon（静态，禁用 CGO）
./dark-recon -port 5000
```
### 选项 4 — Debian/Ubuntu 软件包（.deb）⭐ 自我引导
在本地构建或从 [GitHub Releases](https://github.com/yourname/dark-recon/releases) 下载预构建的 `.deb` 文件（通过 CI 自动附加在每个标签推送上，适用于 `amd64` 和 `arm64`），然后安装：
```bash
make deb # 生成 dist/dark-recon_<ver>_<arch>.deb
sudo apt install ./dist/dark-recon_*.deb
# 或直接从下载的发布资产中安装：
sudo apt install ./dark-recon_1.0.0_amd64.deb
```
软件包安装静态服务器二进制文件、默认配置、单词列表、UI 资产和 `/usr/share/dark-recon/` 下的先决条件引擎，以及 `/usr/local/bin/dark-recon` 下的启动器。仅 `libc6` 是硬依赖项；其他所有内容（nmap、git、ca-certificates、golang-go、seclists）都是 `Recommends`，因此安装在最小系统上不会阻塞。
**在安装时**，`postinst` 运行快速的只读**先决条件验证**（系统检查，无网络），以便您立即看到已存在/缺失的内容。**在首次启动时**，启动器运行先决条件引擎，带有 `--install` 参数，它检查系统并**自动安装任何缺失的必需 Go 安全工具**（subfinder、ffuf、httpx、webanalyze、katana、nuclei、subzy — 无需 `sudo`）。可选工具被报告，但不安装。成功检查被缓存（`/var/lib/dark-recon/.prereqs-ok` 用于 root，或 `~/.cache/dark-recon/.prereqs-ok` 用于其他用户），因此后续启动是即时的。
```bash
dark-recon prereqs # 只读状态报告
dark-recon prereqs --install # 安装缺失的必需工具
dark-recon prereqs --install --strict # 还安装可选工具
# 环境变量：
DARK_RECON_SKIP_PREREQS=1 dark-recon ... # 完全跳过首次运行检查
DARK_RECON_FORCE_PREREQS=1 dark-recon ... # 强制重新检查
DARK_RECON_INSTALL_PREREQS=1 sudo apt install ./dark-recon_*.deb # 在安装时进行完整的引导
```
### 验证安装
```bash
dark-recon -h # 打印用法
dark-recon prereqs # 确认所有工具存在
```
---
## 配置
### `config.yaml`（主要配置）
```yaml
target: '' # 目标域名（在扫描启动时设置）
output_dir: ~/dark_recon_results # 基本输出目录
threads: 200 # 工具的并发性
timeout: 10 # HTTP 超时（秒）
auto_install: true # 自动安装缺失的工具
top_subdomains_for_scanning: 10 # 目录枚举的前 N 项
seclists:
base_dir: /usr/share/wordlists/seclists
dns_wordlist: /usr/share/wordlists/seclists/Discovery/DNS/subdomains-top1million-5000.txt
dir_common: /usr/share/wordlists/seclists/Discovery/Web-Content/common.txt
dir_big: /usr/share/wordlists/seclists/Discovery/Web-Content/big.txt
dir_medium: /usr/share/wordlists/seclists/Discovery/Web-Content/DirBuster-2007_directory-list-2.3-medium.txt
api_endpoints: /usr/share/wordlists/seclists/Discovery/Web-Content/api/api-endpoints.txt
nuclei:
templates: ~/nuclei-templates
severity: [critical, high] # 要包含的严重性级别
rate: 250 # 每秒请求数
concurrent: 50 # 并发模板
cvss_min: 8 # 要报告的最低 CVSS 分数
timeout: 90 # 最大扫描持续时间（分钟）
bulk_size: 50 # 每批主机
katana:
depth: 3
concurrency: 50
headless: true # 基于浏览器的主动爬取
js_parse: true # 解析 + 爬取 JS 端点
# 第一阶段高级模块（默认情况下均关闭；按扫描开启）
phase1:
passive_recon: false
port_scan: false
waf_detect: false
js_analysis: true
param_discovery: false
secret_scan: false
chaos_api_key: ""
passive_recon_workers: 5
port_scan_workers: 50
waf_workers: 20
js_analysis_workers: 30
param_discovery_workers: 5
secret_scan_workers: 10
priority_keywords:
critical: [admin, api, staging, internal, vpn, auth, login, dashboard, console, manage]
high: [dev, test, uat, beta, app, portal, gateway, control, panel, root]
medium: [www, mail, cdn, static, blog, shop, store, media]
exposed_path_scores:
.env: 20
.git: 15
/admin: 10
/phpmyadmin: 12
# ... （参见 config.yaml 中的完整列表）
skip_phases: [] # 要跳过的阶段编号（1-8）
```
### `tools_config.yaml`（工具配置）
```yaml
enabled_tools:
subfinder: true
ffuf: true
httpx: true
nuclei: true
katana: true
subzy: true
webanalyze: true
nmap: true
tool_config:
nuclei:
args: ''
phase: ''
```
### `llm_config.yaml`（LLM 配置 — 用于 AI 辅助功能）
```yaml
enabled: true
provider: ollama # ollama, openai 等
model: llama3
api_key: ''
base_url: http://localhost:11434
onboarded: true
```
配置可以在运行时通过 **设置** 页面或 API (`GET`/`PUT /api/config`) 查看和编辑。
---
## 用法
### 启动服务器
```bash
# 编译二进制文件
./dark-recon -port 5000
# 通过 make
make run # 构建并在端口 5000 上运行
# 通过 go
go run ./cmd/dark-recon/ -port 5000
```
**命令行标志：**
| 标志 | 默认值 | 描述 |
|---|---|---|
| `-port` | `5000` | HTTP 服务器端口 |
| `-config` | `config.yaml`（自动检测） | 配置文件路径 |
| `-templates` | `dark_recon/ui/templates`（自动检测） | HTML 模板目录 |
| `-static` | `dark_recon/ui/static`（自动检测） | 静态文件目录 |
**子命令：**
| 子命令 | 描述 |
|---|---|
| `dark-recon mcp` | 通过 stdio 运行 MCP 服务器（适用于 LLM 客户端） |
| `dark-recon prereqs [--install] [--strict]` | 运行先决条件引擎 |
### 启动扫描
1. 在浏览器中打开 `http://localhost:5000`
2. 在侧边栏中单击 **新建扫描**
3. 输入目标域名（例如 `example.com`）
4. 调整设置（线程、超时、严重性过滤器、选择加入模块）
5. 单击 **启动扫描**
6. 重定向到具有实时 WebSocket 更新的实时进度页面
### 查看结果
| 页面 | 路由 | 您看到的内容 |
|---|---|---|
| 仪表盘 | `/` | 所有扫描目标的统计数据 + 批量删除 |
| 目标详情 | `/target/{name}` | 子域名、漏洞、优先级、技术、接管、目录 |
| 子域名详情 | `/target/{name}/subdomain/{sub}` | 每个子域名的详细情况 + 建议的手动测试 |
| 实时进度 | `/scan/{name}/progress` | 实时阶段跟踪器 + 日志流 |
| 工具 | `/tools` | 工具安装状态、安装/卸载、切换 |
| 设置 | `/settings` | 完整的配置编辑器 |
---
## API 参考
所有 API 端点均返回 JSON。基本 URL：`http://localhost:5000`
### 扫描管理
| 方法 | 端点 | 描述 |
|---|---|---|
| `POST` | `/api/scan/launch` | 启动扫描（`{"target": "example.com", ...}`） |
| `POST` | `/api/scan/{target}/stop` | 停止正在运行的扫描 |
| `GET` | `/api/scan/{target}/status` | 扫描状态 + 最近的日志 |
| `GET` | `/api/scan/{target}/logs` | 完整的进度日志 |
| `GET` | `/api/scans/active` | 列出所有活动扫描 |
### 目标数据
| 方法 | 端点 | 描述 |
|---|---|---|
| `GET` | `/api/targets` | 列出所有扫描目标 |
| `GET` | `/api/dashboard/summary` | 仪表盘汇总统计 |
| `GET` | `/api/target/{target}` | 完整的目标数据集 |
| `DELETE` | `/api/target/{target}` | 删除目标 + 所有数据 |
| `DELETE` | `/api/targets/bulk` | 批量删除目标 |
| `GET` | `/api/target/{target}/vulns` | 漏洞（可筛选） |
| `GET` | `/api/target/{target}/priority` | 优先级排名 |
| `GET` | `/api/target/{target}/export` | 以 JSON 导出 |
| `GET` | `/api/target/{target}/export/csv` | 以 CSV 导出优先级 |
| `GET` | `/api/target/{target}/handoff` | 第 2 阶段交接文件 |
| `GET` | `/api/target/{target}/subdomain/{sub}` | 子域名详情 |
### 第一阶段高级模块
| 方法 | 端点 | 描述 |
|---|---|---|
| `GET` | `/api/phase1/{target}/findings` | 所有第一阶段的发现结果 |
| `GET` | `/api/phase1/{target}/ports` | 端口扫描结果 |
| `GET` | `/api/phase1/{target}/js` | JS 分析结果 |
| `GET` | `/api/phase1/{target}/params` | 已发现的参数 |
| `GET` | `/api/phase1/{target}/secrets` | 秘密扫描结果 |
| `GET` | `/api/phase1/{target}/waf` | WAF 检测结果 |
| `GET` | `/api/phase1/{target}/intel` | 被动侦察情报 |
| `GET` | `/api/phase1/{target}/status` | 第一阶段模块状态 |
### 第二阶段交接
| 方法 | 端点 | 描述 |
|---|---|---|
| `POST` | `/api/phase2/{target}/start` | 启动第二阶段跟踪 |
| `GET` | `/api/phase2/{target}/status` | 第二阶段状态 |
| `GET` | `/api/phase2/{target}/targets` | 第二阶段优先级目标 |
| `GET` | `/api/phase2/{target}/findings` | 第二阶段发现结果 |
| `GET` | `/api/phase2/{target}/urls` | 带有参数的 URL |
### 配置 & 工具
| 方法 | 端点 | 描述 |
|---|---|---|
| `GET` `PUT` | `/api/config` | 获取/更新配置 |
| `GET` | `/api/fs/dirs` | 浏览文件系统目录（用于单词列表/模板选择器） |
| `GET` | `/api/tools` | 列出所有工具及其安装状态 |
| `POST` | `/api/tools/{tool}/install` | 安装工具 |
| `POST` | `/api/tools/{tool}/uninstall` | 卸载工具 |
| `GET` | `/api/phases` | 列出所有管道阶段 |
### WebSocket
| 端点 | 描述 |
|---|---|
| `ws://localhost:5000/ws/{target}` | 扫描的实时进度流 |
| `ws://localhost:5000/ws` | 全局进度流（所有扫描） |
**消息格式：```json
{ "timestamp": "14:32:05", "phase": "subdomain_enum", "status": "completed", "message": "...", "count": 42 }
```
---
## MCP / LLM 集成
Dark-Recon 的二进制文件兼作 **MCP 服务器**，通过 stdio 向 LLM 客户端（Claude Desktop、Cursor、Cline、…）公开整个平台。它是 REST API 的薄客户端客户端 - 将其指向正在运行的服务器：
```bash
# 启动 Web 服务器
dark-recon -port 5000 &
# 运行 MCP 服务器（相同二进制文件）
dark-recon mcp # 使用 http://localhost:5000
DARK_RECON_URL=http://localhost:5000 dark-recon mcp
dark-recon mcp -url http://host:5000
```
**公开的 MCP 工具**（与 REST API 1:1 包装器）:
- `launch_scan`, `stop_scan`, `get_scan_status`, `get_scan_logs`, `list_active_scans`, `wait_for_scan`
- `list_targets`, `get_target`, `delete_target`, `bulk_delete_targets`
- `get_vulnerabilities`, `get_priority`, `get_subdomain_detail`
- `export_target_json`, `export_target_csv`, `get_handoff`
- `get_config`, `update_config`, `browse_dirs`
- `list_tools`, `refresh_tools`, `get_tool`, `install_tool`, `uninstall_tool`
**Claude Desktop 配置示例`（`claude_desktop_config.json`）:
```json
{
"mcpServers": {
"dark-recon": {
"command": "dark-recon",
"args": ["mcp"]
}
}
}
```
然后问 Claude: *"对 example.com 进行侦察扫描，等待它完成，并给我提供前 5 个优先级目标及其原因。"*
---
## Web UI
前端 **纯 HTML + JavaScript** - 没有服务器端模板，没有构建步骤。所有动态内容通过 `fetch()` 到 REST API 客户端渲染。
| 页面 | 描述 |
|---|---|
| **仪表盘** | 目标卡列表 + 漏洞计数、优先级阶梯徽章、批量删除 |
| **扫描启动** | 目标输入 + 配置覆盖 + 活动扫描列表 |
| **实时进度** | 实时 WebSocket 日志流、阶段跟踪器 + 状态指示器、指数衰退重连 |
| **目标详情** | 统计数据、技术徽章、可排序优先级表、可展开的漏洞行、交接结果、发现的目录 |
| **子域名详情 | `http://localhost:5000`
| **工具** | 工具卡片 + 安装状态 + 搜索/筛选 + 安装/卸载 + 启用/禁用切换 |
| **设置** | 完整的配置编辑器 - 所有字段均从 API 填充，PUT 保存 |
---
## 输出 & 数据库
每次扫描都会在 `~/dark_recon_results/<target>/` 下创建文件：
```
<target>/
├── scan.db # SQLite 数据库（主要存储）
├── dark-recon.log # 应用程序日志
├── raw/ # 工具原始输出
│ ├── subfinder.txt ffuf_dns.txt httpx.json
│ ├── katana.json nuclei.json webanalyze.json subzy.txt
├── parsed/ # 解析/中间文件
│ ├── subdomains.txt live_subdomains.txt all_urls.txt nuclei_targets.txt
├── priority/ # 评分输出
│ ├── priority_ranking.json # 完整的优先级排名
│ └── phase2_handoff.json # 第二阶段交接文件
├── reports/
│ └── report.json # 综合 JSON 报告
└── screenshots/ # gowitness 截图
└── *.png
```
### 数据库模式（11 个表，每个目标）
`scan_meta` · `subdomains` · `live_hosts` · `tech_detections` · `crawled_urls` · `discovered_dirs` · `vulnerabilities` · `takeover_results` · `screenshots` · `priority_entries` · `header_results`
所有表格均按 `scan_id` 和相关查找列编制索引。WAL 日志模式 + `MaxOpenConns(1)` 实现安全并发读取期间扫描。
---
## 安全
Dark-Recon 使用 Go 重写，以解决 shell 基础的侦察脚本中常见的安全问题：
| 关注点 | Dark-Recon 处理方式 |
|---|---|
| **命令注入** | `exec.CommandContext` 使用参数切片 - 从不调用 shell |
| **路径遍历** | 整个项目中使用 `filepath.Join()` |
| **工具失控** | 每个执行都有 `context.WithTimeout` |
| **无法取消的扫描** | `context.CancelFunc` 传播到所有 goroutine |
| **并发数据库写入** | SQLite WAL 模式 + `MaxOpenConns(1)` 单一写入者 |
| **日志中的机密** | 日志中工具输出截断（错误 200 个字符） |
| **损坏的工具链** | 稳健的可用性检查运行 `<tool> -version`（不仅仅是 `LookPath`）- 捕获半安装/零字节二进制文件 |
---
## 开发
### Makefile 目标
```bash
make help # 列出所有目标
make build # 静态二进制文件（禁用 CGO）
make run # 构建并在端口 5000 上运行
make mcp # 运行 MCP 服务器
make vet # go vet
make test # go vet + 测试
make fmt # 格式化 Go 代码
make check-prereqs # 只读先决条件报告
make install-tools # 安装缺失的安全工具
make deb # 构建 .deb 软件包
make clean # 删除构建工件
```
### 依赖项
| 模块 | 版本 | 用途 |
|---|---|---|
| `github.com/gorilla/websocket` | v1.5.3 | WebSocket 实时进度 |
| `github.com/modelcontextprotocol/go-sdk` | v1.6.1 | 用于 LLM 客户端的 MCP 服务器 |
| `gopkg.in/yaml.v3` | v3.0.1 | YAML 配置解析 |
| `modernc.org/sqlite` | v1.53.0 | 纯 Go SQLite 驱动（无 CGO） |
### 项目结构
```
dark-recon/
├── cmd/dark-recon/main.go # 入口点
├── internal/
│ ├── api/ # REST + WebSocket 处理程序（29 个路由）
│ ├── config/ # YAML 配置加载器
│ ├── enumeration/ discovery/ technology/ direnum/
│ ├── nuclei/ takeover/ scoring/ scanmgr/
│ ├── pipeline/ # 8 阶段编排器
│ ├── phasemod/ # 阶段 1 高级模块
│ ├── installer/ # 工具管理（BuiltinTools 映射）
│ ├── mcp/ # MCP 服务器（LLM 集成）
│ └── storage/ # SQLite 模式 + CRUD
├── pkg/
│ ├── executor/ # 子进程运行器（无 shell）
│ ├── parser/ # JSONL/subfinder/katana/subzy 解析器
│ └── logger/ # slog 结构化日志记录
├── dark_recon/ui/ # 嵌入式 HTML 模板 + 静态资产
├── scripts/ # check-prereqs.sh, install-tools.sh
├── dist/ # build-deb.sh
├── config.yaml tools_config.yaml llm_config.yaml
└── Makefile
```
### 添加新工具
1. 将工具定义添加到 `BuiltinTools` 中的 `internal/installer/installer.go`
2. **保持同步** `TOOLS` 表中的 `scripts/check-prereqs.sh`（单一真实来源）
3. 在 `tools_config.yaml` 中添加 `enabled_tools` 条目
4. 通过 `executor.Run()` 调用；如果输出格式为新的，则在 `pkg/parser/` 中添加解析器
### 添加新模块
1. 在 `internal/<module>/` 下创建一个包
2. 实现一个 `Run(ctx context.Context) (*Result, error)` 方法
3. 将阶段添加到 `internal/pipeline/engine.go`
4. 如果需要新表，请添加存储方法 + 模型
5. 在 `internal/api/routes.go` 中添加 API 处理程序并注册路由
---
## ⚖️ 许可
本项目旨在 **授权的安全测试和教育使用**。始终在扫描您不拥有的任何目标之前获得适当的书面授权。在滥用或因该工具造成的损害的情况下，作者不承担任何责任。
DarkRecon 骄傲地开源，基于 **GNU 通用公共许可证 v3.0（GPL-3.0）** 发布。
您可以免费使用、研究、修改和分发此软件，但所有衍生作品仍须遵守 GPL-3.0 许可证。 [在此阅读完整许可](LICENSE)。
---
<div align="center">
### 由 [Dark Neural Network](https://darkneuralnetwork.com) 构建
* 构建下一代智能自主系统。
🌐 [网站](https://darkneuralnetwork.com) • ⭐ GitHub 上的星标 • 🤝 加入社区
**Dark-Recon v1.0.0** - *使用 Go、结构化日志记录和自动化侦察的热情构建。*
🦇 从域名 → 优先级攻击计划，几分钟内。
</div>
---
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器