MiguelG17/shadow-scout
GitHub: MiguelG17/shadow-scout
ShadowScout 是一款基于 Python 的 EASM 侦察与风险分析 CLI 工具，通过被动信息收集、CVE 关联和变更检测自动生成安全评估报告。
Stars: 0 | Forks: 0
# ShadowScout - EASM 侦察与风险引擎
**ShadowScout** 是一个用于外部攻击面管理（**EASM - External Attack Surface Management**）的 CLI 引擎。它主要分为两个阶段设计：一是被动发现与基础设施识别，二是风险分析、变更检测、实时查询漏洞（CVEs）以及生成 PDF 报告。
## 🚀 核心特性
* **被动侦察与映射：** 查询 **VirusTotal** API 以列出子域名并解析其 IP 地址。
* **外部服务扫描：** 通过 **Shodan** API 获取 Banner 和开放端口，无需直接与目标进行交互。
* **智能动态过滤：** 仅隔离并分析与指定目标域名相对应的子域名，避免数据交叉污染。
* **实时漏洞搜索：** 查询 **NIST 的 NVD (National Vulnerability Database) API** v2.0，以获取所检测服务的 CVEs 和 CVSS 评分。
* **持久化与历史记录控制：** 将所有扫描的详细信息存储在本地 **SQLite** 数据库中。
* **变更检测引擎：** 将当前扫描与之前的运行记录进行比较，以识别自上次扫描以来新增的子域名、新开放的端口或已关闭的端口。
* **执行报告生成：** 编译带有专业样式的 **PDF** 技术报告，可直接交付使用。
## 🛠️ 安装与配置
### 1. 克隆仓库
```
git clone https://github.com/MiguelG17/shadow-scout.git
cd shadow-scout
```
### 2. 配置虚拟环境并安装依赖
建议使用 Python 虚拟环境：
```
# Crear entorno virtual
python -m venv venv
# Activar en Windows (PowerShell)
.\venv\Scripts\Activate.ps1
# Activar en Linux/macOS
source venv/bin/activate
# Instalar dependencias requeridas
pip install -r backend/requirements.txt
```
### 3. 配置环境变量（`.env`）
在 `backend/` 文件夹中创建一个名为 `.env` 的文件，包含你的 VirusTotal 和 Shodan 的 API keys：
```
VT_API_KEY=tu_api_key_de_virustotal
SHODAN_API_KEY=tu_api_key_de_shodan
```
## 📖 工作流程与使用
ShadowScout 以模块化方式运行，分为两个简单的步骤：
### 步骤 1：侦察与扫描（侦察阶段）
此步骤被动收集子域名及其开放端口，并自动将其保存到该域名专属的 JSON 文件中：
```
python backend/main.py -d
```
* **示例：** `python backend/main.py -d google.com`
* 这将自动创建文件 `backend/google.com_phase2_result.json`。
### 步骤 2：风险分析与报告
此步骤读取该域名的 JSON 文件，查询 CVEs，查找与历史记录相比的变更，更新数据库并生成 PDF：
```
python main.py -d --cve --pdf
```
* **示例：** `python main.py -d google.com --cve --pdf`
* 将自动查找文件 `backend/google.com_phase2_result.json`。
* 将分析结果保存到数据库 `shadow_scout.db` 中。
* 生成 PDF 格式的报告，命名为 `reporte_seguridad.pdf`。
## 🎛️ CLI 详细选项
### 扫描器 (`backend/main.py`)
```
opciones:
-h, --help Muestra la ayuda y sale.
-d, --domain DOMAIN Dominio objetivo a escanear (Ej: uvigo.gal).
-o, --output OUTPUT Ruta del JSON de salida (Por defecto: backend/{dominio}_phase2_result.json).
```
### 主分析器 (`main.py`)
```
opciones:
-h, --help Muestra la ayuda y sale.
-d, --domain DOMAIN Dominio objetivo a analizar.
-i, --input INPUT JSON de entrada (Por defecto busca: backend/{dominio}_phase2_result.json).
--cve Habilita la consulta de CVEs en tiempo real con la NVD.
--pdf Genera el reporte ejecutivo en formato PDF.
-o, --output-pdf OUT Nombre del PDF generado (Por defecto: reporte_seguridad.pdf).
--no-db Deshabilita el guardado en la base de datos SQLite.
```
## 📂 项目结构
* **[main.py](file:///c:/Users/Miguel/Documents/GitHub/shadow-scout/main.py)：** 风险分析与报告阶段的主要 CLI 编排器。
* **[backend/main.py](file:///c:/Users/Miguel/Documents/GitHub/shadow-scout/backend/main.py)：** 被动子域名发现与扫描脚本（阶段 2）。
* **[backend/analyzer.py](file:///c:/Users/Miguel/Documents/GitHub/shadow-scout/backend/analyzer.py)：** 端口严重性评估逻辑。
* **[backend/cve_lookup.py](file:///c:/Users/Miguel/Documents/GitHub/shadow-scout/backend/cve_lookup.py)：** 与 NVD NIST 公共 API 的集成。
* **[backend/database.py](file:///c:/Users/Miguel/Documents/GitHub/shadow-scout/backend/database.py)：** SQLite 数据库管理与变更检测。
* **[backend/report_generator.py](file:///c:/Users/Miguel/Documents/GitHub/shadow-scout/backend/report_generator.py)：** 基于 ReportLab 的 PDF 模板生成器。
标签：GitHub, Python, 安全报告, 实时处理, 密码管理, 无后门, 逆向工具