lopezsistemas-dev/safescan-pyme

# SafeScan PYME **面向中小企业和个体户的私人网络安全代理，由 Gemini 和 VirusTotal/Google 威胁情报驱动。** SafeScan PYME 允许任何没有技术背景的员工提问*“我可以打开这个吗？”* —— 无论是文件、URL 还是可疑邮件 —— 并获得清晰、安全且易懂的回答：**打开、谨慎打开、拦截、上报或保持隔离**。 该产品的核心理念： 每个文件同时被视为两件事：一个**潜在威胁**（恶意软件、网络钓鱼、宏、伪装的可执行文件）和一个**潜在的敏感资产**（身份证号、IBAN、电话、客户或患者数据）。因此，并非所有文件的分析方式都相同：一个策略和隐私引擎会为每种情况决定合适的处理流程。 本项目作为 2026 年 7 月至 8 月开发的功能性 MVP，提交给**马拉加大学网络安全教席奖**（UMA — VirusTotal/Google）。 ## 快速运行 环境要求：Node.js 20 或更高版本。 ``` npm install npx prisma migrate dev # crea la BD SQLite y ejecuta el seed automáticamente npm run dev # http://localhost:3000 ``` 不需要任何 API 密钥：**MVP 在模拟模式下即可完整运行**。如果配置了 Gemini 和/或 VirusTotal 的真实密钥，真实连接器会自动激活（参见 [运行模式](#modos-de-funcionamiento)）。 其他命令： ``` npm test # tests del Policy & Privacy Engine (vitest) npm run lint # eslint npm run build # build de producción npm run db:reset # reinicia la BD demo (migraciones + seed) node scripts/make-demo-files.mjs # regenera los archivos de demo-files/ ``` ## 3 分钟演示（面向评审团的脚本） 1. **落地页** (`/`)：价值主张、架构和路线图。 2. **企业选择器** (`/seleccionar-empresa`)：3 个带有模拟私有域名的演示中小企业。以 **Pablo Ruiz**（Asesoría López 的员工）身份登录。 3. **案例 1 — 会计事务所**：在代理聊天中，上传 `demo-files/factura_urgente.zip`（附件图标 📎）。系统通过仅读取条目名称（无需解压），即可检测到 ZIP 文件**内部**的伪装可执行文件（`factura.pdf.exe`）。结论：**拦截**，隔离。 4. **案例 2 — 酒店**：切换至 **Andrés Vega**（Hotel Málaga Centro）并上传 `demo-files/reservas_agosto.xlsm`。宏 + 客户数据 → 触发 **Private Scanning** 流程（模拟）且结论为**上报**。 5. **案例 3 — 诊所**：切换至 **Javier Molina**（Clínica Sur）并上传 `demo-files/documentacion_paciente.pdf`。身份证号、IBAN 和健康数据（虚构）→ 极高敏感度 → **仅进行本地分析 + 人工审核**。PDF 绝不会离开当前环境；展示的数据将进行**脱敏处理**。 6. **案例 4 — 个体户**：“URL”选项卡，粘贴 `http://pagos-verificacion-urgente.top/verificar?id=8123` → 疑似网络钓鱼 → **拦截**。（也可以在“邮件”选项卡中粘贴 `demo-files/correo_phishing.txt`。） 7. **案例 5 — SafeDocs**：在不使用任何外部网站的情况下合并 `acta_reunion.pdf` 和 `presupuesto_marketing.pdf`。下载结果。 8. **仪表板** (`/dashboard`)：完整的历史记录、评分、结论、徽章（私有、隔离、Private Scanning、模拟）、报告、*解决* / *删除文件* / *清理过期文件* 按钮以及审计日志。 9. **报告** (`/dashboard/informe/[id]`)：双重报告（员工 + 主管），包含案例的完整可追溯性。 10. **策略** (`/politicas`)：各企业的阈值和规则；环境状态（模拟/真实）。 `demo-files/` 中的所有文件都是**无害的**，且仅包含虚构数据。 ## 架构 ``` Empleado ──▶ SafeScan Agent (chat) ──▶ Ingesta segura (validación + cuarentena) │ ▼ Containment Engine hash SHA-256 · tipo real (magic bytes) · doble extensión inspección de ZIP (solo nombres) · indicadores (URLs, emails, teléfonos, IBAN, DNI/NIE, keywords) enmascarados │ ▼ Policy & Privacy Engine threatScore (0-100) + sensitivityScore (0-100) │ ┌─────────────┬─────────────┬───┴──────────┬──────────────┐ ▼ ▼ ▼ ▼ ▼ HASH_LOOKUP URL_LOOKUP PRIVATE_SCANNING LOCAL_ONLY HUMAN_REVIEW (simulado en MVP) / QUARANTINE └─────────────┴─────────────┴──────────────┴──────────────┘ │ ▼ Threat Intelligence Layer (VirusTotal / mock) │ ▼ AI Agent Layer (Gemini / mock) → veredicto e informes ⚠ solo recibe metadatos, scores y señales enmascaradas │ ▼ Informe empleado + Informe responsable + AuditLog ``` ### 模块 | 模块 | 位置 | 功能 | |---|---|---| | SafeScan Agent | `src/components/agent-chat.tsx`, `/api/chat` | 对话式聊天：文件、URL 或邮件 | | Containment Engine | `src/lib/containment/` | 隔离、哈希、真实类型、ZIP、脱敏指标 | | Policy & Privacy Engine | `src/lib/policy/engine.ts` | 双重评分和流程决策（确定且可解释） | | Threat Intelligence | `src/lib/threat-intelligence/` | 接口 + 逼真的模拟 + VirusTotal API v3 连接器 | | AI Agent | `src/lib/ai-agent/` | 接口 + 模拟 + Gemini (REST) 连接器；报告 | | Pipeline | `src/lib/pipeline.ts` | 编排具有可观察进度（时间线）的各个阶段 | | SafeDocs | `src/lib/safedocs/` | 合并/提取/旋转/清理 PDF 元数据，100% 本地处理 | | Retención | `src/lib/retention.ts`, `src/instrumentation.ts` | 启动时清理过期文件 + 手动清理 | | Dashboard | `src/app/(portal)/dashboard/` | 历史记录、报告、隔离、审计 | ### 文件夹结构 ``` prisma/ schema + migraciones + seed (3 tenants, 5 casos demo) demo-files/ archivos inofensivos para la demo (ver LEEME.md) scripts/ generador de los archivos de demo storage/ cuarentena y salidas SafeDocs (creado en runtime, no versionado) src/ app/ App Router: landing, selector, (portal)/agente|analisis| safedocs|dashboard|politicas, api/* components/ UI propia (sin librerías de componentes externas) lib/ motores y servicios (lógica separada de la UI) ``` ## 环境变量 将 `.env.example` 复制到 `.env`。以下为专为演示设计的默认值： | 变量 | 默认值 | 描述 | |---|---|---| | `GEMINI_API_KEY` | *(空)* | Gemini 密钥。留空 → 使用模拟代理 | | `GEMINI_MODEL` | `gemini-2.0-flash` | 要使用的 Gemini 模型 | | `VIRUSTOTAL_API_KEY` | *(空)* | VirusTotal 密钥。留空 → 使用模拟威胁情报 | | `VIRUSTOTAL_PRIVATE_SCANNING_ENABLED` | `false` | 真实的 Private Scanning 功能（需要许可证和协议） | | `MOCK_SECURITY_ANALYSIS` | `true` | 即使有密钥也强制开启模拟模式 | | `DATABASE_URL` | `file:./dev.db` | 本地 SQLite（开发环境） | | `UPLOAD_DIR` | `./storage/quarantine` | 隔离文件夹 | | `RETENTION_HOURS` | `24` | 文件删除前的保留小时数 | | `MAX_UPLOAD_MB` | `25` | 上传大小限制 | | `ALLOWED_FILE_TYPES` | pdf, docx, xlsm, zip… | 接受分析的扩展名（可执行文件会被接受并标记为高风险） | ## 运行模式 ### 模拟模式（默认） 即使没有密钥，所有功能也能正常运行：威胁情报模块的模拟会根据本地信号生成**逼真且确定的**结论（相同文件 → 相同结果），而模拟代理会使用基于意图引导的模板进行回复。每次分析都会带有 **Mock** 徽章标记。 ### 真实 Gemini 模式 1. 在 Google AI Studio 获取密钥。 2. 在 `.env` 中设置 `GEMINI_API_KEY=...`（如需使用其他模型，可设置 `GEMINI_MODEL`）。 3. 重启服务器。 聊天和报告将转由 Gemini 生成。**通过架构设计保证数据最小化**：`ReportInput` 类型没有包含文件内容的字段；Gemini 仅接收元数据、评分、信号和已脱敏的指标。如果出现任何网络错误，系统会自动降级到模拟模式，而不会崩溃。 ### 真实 VirusTotal 模式 1. 获取 VirusTotal 密钥。 2. 在 `.env` 中设置 `VIRUSTOTAL_API_KEY=...` 和 `MOCK_SECURITY_ANALYSIS=false`。 3. 重启服务器。 这将启用 API v3 中记录的真实查询：哈希信誉查询（`GET /files/{sha256}`）和 URL 信誉查询（`GET /urls/{id}`）。仅发送**哈希和 URL**，绝不发送文档内容。公共 API 存在商业使用限制：真实的部署应在**作为授权托管服务的 Premium API** 上运行。 ### 私有扫描 Private Scanning 允许在不上传到公共语料库的情况下分析文件，其可见性仅限于组织内部且保留时间短 —— 这对于中小企业的敏感文档来说是完美的契合点。这是一项**需要 VirusTotal/Google 许可和协议的 Premium 功能**，因此在此 MVP 中： - `PRIVATE_SCANNING` 流程贯穿始终（策略引擎 → 流水线 → 报告 → 徽章）； - 结果是**模拟的**并始终带有标签：*“面向学术 MVP 的 Private Scanning 模拟。连接器已准备好进行授权集成。”*； - 连接器（`src/lib/threat-intelligence/virustotal.ts`）定义了接口和集成点，但**不会调用未经授权的私有端点**，也不会伪造它们。 ## MVP 的安全性与隐私性 已实施的决策： - **真实隔离**：文件以随机名称和中性扩展名（`.quarantine`，权限 0600）保存；从不被执行、打开或渲染。 - **通过二进制签名检测真实类型**：将声明的扩展名与魔数（magic bytes）进行对比（一个以 `MZ` 开头的 `.pdf` 实际上是可执行文件）。 - **检测双重扩展名**（`factura.pdf.exe`）：在文件名中以及 **ZIP 文件内部**（仅读取条目名称，无需解压）进行检测。 - **拦截可执行文件**：具有可执行文件扩展名或伪装的可执行文件 → 根据策略直接隔离。 - **PII 脱敏**：DNI/NIE（包含校验码验证）、IBAN、电话和电子邮件在**持久化存储和展示时始终保持脱敏状态**。 - **面向 AI 的数据最小化**：代理绝不会接收到文件本身或其内容（由 `ReportInput` 类型提供保证）。 - **基于敏感度的流程**：极其敏感的文档 → 仅进行本地分析，无外部查询。 - **可追溯性**：每个操作（上传、分析、结论、删除、保留、策略更改）都会按企业记录在 `AuditLog` 中。 - **可配置的保留策略**：服务器启动时清理 + 仪表板上的手动按钮 + 按文件手动删除。 - **输入验证**：使用 zod、大小限制和允许的扩展名列表。 - **租户隔离**：在所有查询和磁盘存储中实现分离。 ## MVP 的已知限制 - **无真实身份验证**：演示企业选择器使用简单的 cookie；任何用户都可以进入任何租户。第二阶段计划引入真实身份验证。 - **无动态沙箱**：不执行文件（出于安全考虑）；所谓的“动态分析”是模拟的。真实产品会使用 VirusTotal 的沙箱技术。 - **文本提取功能有限**：仅支持纯文本、HTML/CSV/EML 和 PDF（使用 `pdf-parse`）。对于 Office 和压缩文件，仅分析元数据、真实类型、ZIP 条目名称和哈希，而不分析其内容。 - **基础的 PII 启发式检测**：正则表达式 + DNI 校验码验证；真实产品会使用高级 DLP（第三阶段路线图）。 - **模拟 Private Scanning**（参见上一节）。 - **SQLite 和本地存储**：适用于 MVP；真实的多企业部署将需要 Postgres、加密存储和任务队列。 - **URL 分析不会访问页面**：仅评估词法、域名和信誉；不进行渲染或重定向跟踪。 ## 路线图 **MVP 阶段（7 月 - 8 月）** — 即本代码库：代理聊天、安全上传、隔离、双重评分、基于策略的流程、基于哈希和 URL 的模拟/真实威胁情报、基础 SafeDocs、仪表板、双重报告、审计和保留策略。 **第二阶段**：结合 Gemini Live API 的语音功能 · 授权的真实 Private Scanning 集成 · 真实身份验证 · 真实的自定义域名 · 邮件连接器 · 向主管发送警报 · 按部门制定规则。 **第三阶段**：MSSP/合作伙伴模型 · 健壮的多租户架构 · 计费系统 · 高级审计 · 高级 DLP · CDR（文档拆解与重建） · 高级 OCR · 与 Google Workspace 和 Microsoft 365 的集成。 ## 建议在报告中展示的截图 1. 带有“打开前先询问。”口号的落地页。 2. 包含问候语和快捷建议的代理聊天界面。 3. 正在进行分析的时间线。 4. `factura_urgente.zip` 案例的结果（拦截，威胁评分 100/100，ZIP 指标）。 5. 诊所案例的结果（敏感度 90+，仅本地分析，PII 已脱敏）。 6. 生成文档的 SafeDocs 界面。 7. 带有指标和审计日志的主管仪表板。 8. 员工/主管双重报告。 ## 学术说明 本 MVP 是为“网络安全与人工智能创新网络安全教席奖”（马拉加大学，与 VirusTotal SLU/Google 合作举办）而开发的。三个客户、他们的用户以及 `demo-files/` 中的所有数据都是虚构的。VirusTotal、Google 和 是其各自所有者的商标；此处对它们的使用均为描述性质，且完全在本次活动的框架内。

标签：GNU通用公共许可证, MITM代理, Node.js, 人工智能, 威胁情报, 开发者工具, 用户模式Hook绕过, 网络安全, 自动化攻击, 隐私保护