webcvalejandropina-ui/soc-personal-project

## 📑 目录 - [它是做什么的？](#-a-qué-se-dedica) - [功能](#-capacidades) - [面板各区域说明](#-el-panel-por-áreas) - [AI、MCP、学习与记忆](#-ia-mcp-aprendizaje-y-memoria) - [架构](#️-arquitectura) - [项目结构](#-estructura-del-proyecto) - [快速开始](#-arranque-rápido) - [配置](#-configuración) - [模式、角色与安全](#-modos-roles-y-seguridad) - [部署](#-despliegue-vps-docker--portainer) - [测试与供应链](#-tests) - [文档](#-documentación) ## 🎯 它是做什么的？ SOC-PERSONAL-PROJECT 是一个**本地防御型 SOC（安全运营中心）**：一个 运行在你自己的机器上（Unraid、服务器或 VPS）的平台，致力于 在面临威胁时进行**监控、检测、告警和响应**，不依赖云。 典型用例：一个位于 reverse-proxy (SWAG/nginx) 和 fail2ban 之后 **正在生产环境中运行在线商店的 VPS**。机器人不停地探测诸如 `/wp-login.php`、`.env` 或 `/SDK/webLanguage` 等路由；该平台读取这些日志，进行评分， 向你发出重要事件的告警，并允许你**一键封锁、拒绝或封禁** — 所有操作都是可逆的，并且需要人工确认。 三个理念主导着设计： 1. **纯防御** — 不包含任何漏洞利用、攻击性持久化或规避技术。 2. **操作员至上** — 没有任何高风险操作可以在未经确认的情况下执行；即使是 AI 也无法自动确认，它只能提出建议。 3. **始终真实** — 如果防火墙真的拒绝了某项操作，它会连同真实原因一起标记为 `FAILED`；绝不假装已应用。 **AI 是可选的**：监控和防御功能在未配置任何 模型的情况下即可完全正常工作。 ## ✨ 功能 ### 👁️ 监控与检测 - **持续监控** — CPU / 内存 / 负载、进程、网络（传入/传出连接 + 被动 LAN 扫描）以及主机日志（auth、syslog、kernel）。 - **基于 JSON 的 drop-in 规则检测**：`metric_threshold`、`log_regex`、`connection_match`。每个匹配项都是一个带有自身权重的**发现**。 - **0-100 风险值** — 发现的结果通过一个**饱和**公式（`1 − Π(1 − wᵢ/100)`）进行组合：大量的发现会累加，但永远不会超过 100。 - **Skills** — 可激活的检测规则包（附带双语指南），可逆；不会在主机上执行任何操作。 ### 🌐 Nginx / Web - **可疑日志** — 对 `access.log` 中的重复请求（扫描/漏洞利用）进行排名，按路由分组，支持按状态/方法/主机过滤。 - **Deny map** — 生成 nginx 的 `map` 块以拒绝滥用路由。 - **监控 (cron)** — 针对超阈值的**新滥用路由**和**频繁请求**（同一路由大量重复，阈值可配置，按路由+时间窗口**去重**）发出告警。你标记为**合法**的路由将不再提醒。 - **报告** — 每日排名、前 10 名和增量批次分析（可选 GeoIP 和 AbuseIPDB 信誉查询，以及可选的自动封禁）。 ### 🚫 响应与封禁 - **带 gating 的缓解措施** — 规划封锁 IP（传入/传出）、停止服务等，并将它们通过**策略**（自动 / 需确认 / 拒绝）进行处理，带有 **rollback** 和 **TTL**（自动过期）。 - **fail2ban** — jails、封禁/解禁（通过 `docker exec` 在代理容器中执行）、按 IP 搜索和历史记录。 ### 🤖 AI（可选） - **AI 聊天** — 对话助手，**仅**使用 MCP 的工具；绝不捏造数据或自动确认操作。 - **SOC Orchestrator** — 将事件分析分配给专门的子代理（分类、threat-intel、响应、记忆等），带有循环控制和完整的**可追溯性**；提供**始终描述性的执行分析**（范围、通俗易懂的严重性结论、带细分的技术指标以及它准备好了什么）和可操作的判定，但不自行执行操作。 - **学习** — 一个会针对你日志中的真实模式**采访**你的聊天界面（例如：“我看到有 40 个针对 `/SDK/webLanguage` 的请求，它们是合法的还是我应该封锁？”），并将你确认的内容存储在**持久化记忆 (engram)** 中；这些知识会在每次对话时重新注入，甚至会为你**配置监控**。 - **提供商** — 使用你的 **ChatGPT 订阅**登录（OAuth，无需 API key），或注册一个兼容的提供商（OpenAI / Anthropic / Gemini / Ollama / OpenRouter / MCPO）。 ### 🔔 告警与报告 - **告警** — 带有状态（打开 / 已确认 / 已解决 / 已静音）的案例和事件，**合法 / 误报**结论，以及可配置的最低严重性。 - **渠道** — 电子邮件 (SMTP) 和 webhooks，带有可自定义且责任到人的 **HTML 模板**。 - **每日电子邮件报告** — 由 **AI 撰写**的执行摘要（如果没有模型，则使用确定性后备方案）和精心设计的 HTML（风险徽章、KPI、章节）；通过 CRON 进行调度。 ### 🕒 自动化与帮助 - **CRON** — 计划任务（检测、nginx 监控、批次、每日报告等）：停止、编辑或立即执行，每个任务都在其独立的页面上。 - **操作员控制台** — 信息命令（`/status`、`/scan`、`/network` 等）、实际执行命令（仅限操作员）以及 `llm <问题>` 以启动代理。 - **应用内帮助**（“?”按钮） — **指南**包含**按角色划分的欢迎信息**（“从这里开始”：问候、该角色能做什么和不能做什么、面板快捷方式和第一步）、可搜索且带有逐步指导；**文档**（带有侧边目录的专业导览）、**概念**（词汇表）和**架构**（仅限管理员）。所有内容均为**ES/EN 双语**，带有动画效果并遵循 `prefers-reduced-motion`。 ### 👥 多用户、角色与备份 - **登录与用户** — 带密码的账户（带盐值的 **PBKDF2-HMAC-SHA256** 哈希，常数时间验证）；管理员可以创建/编辑/删除账户，且不能删除所有的管理员（故障安全）。 - **按区域划分的角色** — `viewer` < `analyst` < `admin`；管理员根据角色决定每个用户可以查看**哪些区域**（“角色”页面）。面板（和指南）**仅显示该角色可以使用的功能**；后端通过路由（宽松联合）**强制执行**此限制，这不仅仅是 UI 层面的隐藏。 - **完全备份（导出/导入）** — 单个文件可迁移**整个**安装版本：配置、skills/规则/子代理、提供商（仅引用）、**用户**（仅包含哈希值，绝不包含明文密码）、**按角色划分的访问权限**、助手的**对话**以及**记忆** (engram)。**绝不**以明文形式传输密钥（SMTP/API keys 保留在 `0600` 存储中）；登录会话也不会被导出。 ### 🔐 本地化与审计 - 单个**加密的 SQLite** 数据库（`{appdata}/soc.db`，`0600`）；除了发送给已配置联系人的告警邮件外，不会有任何数据离开主机。 - 仅追加的**审计日志**，记录 MCP 执行的所有操作（谁、做了什么、何时），并对密钥进行脱敏处理。 ## 🧭 面板各区域说明 | 区域 | 用途 | |---|---| | **Dashboard** | 风险、主机状态、nginx 摘要、告警和近期活动。 | | **SOC AI** | 子代理编排器 + **学习**（采访并保存的聊天） + **已学到的知识**。 | | **AI 聊天** | 仅使用 MCP 工具的对话助手。 | | **子代理** | 编排器目录（模式、循环限制、编辑器）。 | | **告警** | 事件（确认/解决/静音，合法/误报）、渠道和负责人。 | | **日志** / **检查器** | 主机和网络日志；`access.log` 分析、排名、热门列表、报告和封锁。 | | **封禁** | fail2ban（jails、封禁、配置）。 | | **系统安全** | 系统和日志规则、已批准的连接、封锁/停止、nginx 监控。 | | **系统日志** | 可追溯性、MCP 审计、调用的代理和电子邮件发送记录。 | | **AI 配置** | Skills、MCPs 以及 SOC AI 和 AI 聊天的配置。 | | **CRON** | 计划任务。 | | **用户 / 角色**（管理员） | 访问账户以及每个角色可见的区域。 | | **配置** | 通用设置、完全备份（导出/导入）和操作员控制台。 | | **帮助** (`?`) | 指南（按角色欢迎） · 文档 · 概念 · 架构（管理员），双语。 | ## 🧠 AI、MCP、学习与记忆 - **MCP (Model Context Protocol)** — 面向系统的**防腐层**。所有对操作系统的访问（防火墙、日志、网络、进程、电子邮件、fail2ban 等）都通过 MCP 进行；每个**能力**都声明了 `read_only`、`risk` 和 `min_role`，并且在 `dry_run` 模式下不会触碰系统。AI 作为 MCP 服务器（`serve-mcp` 或 `/mcp`）的**客户端**进行连接，且只能使用这些工具。 - **AI 绝不独自做决定** — 它负责规划和建议；由操作员进行确认和签署。没有任何系统操作是由模型进行 gating 的。 - **学习 ↔ 监控** — 在学习聊天中，AI 会询问你关于高流量路由的情况，并根据你的回答将合法的路由标记出来，同时调整频繁请求的阈值（通过 `configure_nginx_watch` 工具）。 - **记忆 (engram)** — 持久化且**可选**；作为 Docker sidecar 运行在 `127.0.0.1` 上。它保存学到的内容（`learning` 类型），以便在每次对话时重新注入。 ## 🏗️ 架构 **严格的 Domain-Driven Design。** 每个*限界上下文*（`monitoring`、`detection`、 `response`、`policy`、`orchestration`、`skills`、`modelproviders`、`audit`、`alerting`、 `identity`、`intelligence`）都有 4 层：`domain`（纯业务逻辑，无 IO） → `application` （用例、端口） → `infrastructure`（适配器） → `interface`。 - **领域层从不触碰操作系统** — 一切都通过经过审计的 MCP（`afdpm/mcps/`）进行。 - **检测 → 响应流程** — 扫描 → 规则 → 发现 → 风险 → 策略 → 响应。 - **领域事件**（collect & dispatch），上下文之间没有直接调用。 - **`composition_root.py`** 是唯一的依赖注入（DI）组装处。 - **持久化** — 单一的本地 SQLite（WAL，`0600`），每个聚合根一张表。 ## 📂 项目结构 ``` afdpm/ # Núcleo (Python, solo stdlib en el core) contexts// # Bounded contexts DDD (domain/application/infrastructure/interface) mcps/ # MCPs: capa anticorrupción hacia el SO (base.py = contrato) shared_kernel/ # Bloques base (Entity, ValueObject, AggregateRoot, Result, SQLite) interface/ # CLI, API (FastAPI + lite server stdlib), MCP server, agente IA config/ # user_config, operator_auth, system_identity… composition_root.py # Único sitio de DI (cablea MCPs, repos, servicios) web/ # UI React (Vite, pnpm) — panel, Guía/Documentación/Conceptos docker/ # Dockerfiles (controlplane, engram) deploy/ · unraid/ # Scripts e instalación tests/ # pytest (o runner stdlib sin red) docs/ # Manual (ES/EN), imágenes, fuentes de la guía in-app release.sh · build-image.sh # Build de imágenes con marca «SOC-PERSONAL-PROJECT» docker-compose.yml # Compose portable (build desde el código); + variantes unraid/vps/windows portainer-stack.yml # Stack de ejemplo para Portainer ``` ## 🚀 快速开始 ``` export PYTHONPATH=. AFDPM_APPDATA=./_data # CLI (仅使用 stdlib，零依赖) python -m afdpm.interface.cli.main status # 备份 Panel + SSE (lite server，无需 build) → http://127.0.0.1:8723/ python -m afdpm.interface.cli.main serve # 多合一：Panel + API REST + MCP 位于 /mcp (单一进程) pip install ".[api,mcp]" python -m afdpm.interface.cli.main serve --api # Frontend 开发中 (必须使用 pnpm，参见 Supply-chain) corepack enable && pnpm -C web install --frozen-lockfile && pnpm -C web dev ``` ### Docker（推荐） 没有已发布的镜像：`docker-compose.yml` **从源码构建**。在 `docker-compose.*.yml` 中提供了针对 Unraid、VPS 和 Windows 的变体。 应用程序在主机的**根目录**提供服务；其 API 位于 `/api` 下。默认绑定到安全的本地地址（`127.0.0.1`）；暴露到局域网是显式的可选行为（`AFDPM_API_HOST=0.0.0.0`）。 ## ⚙️ 配置 所有配置都在**面板上进行管理**，并**加密**保存在 `{appdata}/soc.db` 中 （从不进行版本控制）。关键点： - **操作员 Token** — 保护敏感的写入和读取操作。来自 `AFDPM_OPERATOR_TOKEN` 或在启动时生成并持久化（`0600`）。 - **AI** — AI 配置 → AI 聊天 → 模型（ChatGPT 的 OAuth 或兼容的 API）。 - **记忆 (engram)** — 在其页面上激活它；作为可选的 Docker sidecar 运行。 - **告警** — 渠道（SMTP / webhook）、模板、最低严重性、负责人。 - **CRON** — 激活/编辑 nginx 监控（频繁请求阈值）、每日报告、批次任务等。 - **时区 / 日期格式 / 语言** — 影响整个面板和报告。 - **完全备份** — 配置 → 导出 会下载一个包含**所有内容**的单个 JSON 文件（配置、存储、包含哈希的用户、角色、对话和记忆）；导入功能可在另一个安装中恢复它。**没有明文密钥**（需在目标位置重新输入）。 ## 🔒 模式、角色与安全 - **模式** — `normal`（默认，**真实**操作） · `dry_run`（可选，仅显示预期效果）。 - **登录** — 使用 **PBKDF2-HMAC-SHA256** 的密码（每个用户一个盐值，常数时间比较）；绝不以明文形式保存或暴露密码。 - **按区域访问的角色** — `viewer` < `analyst` < `admin`。管理员定义每个角色可以查看的区域；后端通过路由**强制执行此限制**（不仅仅是在 UI 中隐藏）：如果角色拥有**任何**能够证明其合理性的区域，则允许调用，否则返回 403 拒绝。最高风险的操作（封禁、停止服务、立即执行 CRON、导出/导入）仅限管理员执行。 - **无密钥泄露的备份** — 导出文件包含 PBKDF2 哈希（不可逆），但**绝不**包含明文密码或 API keys；导入操作会验证角色并要求格式良好的哈希值，阻止 `command` 类型的规则，并且不会导出会话。 - **`subprocess` 始终使用 `shell=False`** 并进行输入验证（使用 `ipaddress` 验证 IP）。 - 高风险操作 → 需人工确认；所有关键的缓解措施都有 **rollback**。 - AI 只能将电子邮件发送给**已配置的联系人**（防止通过 prompt-injection 进行数据渗透）。 ## 📦 部署 (VPS Docker / Portainer) **黄金法则**：镜像在**开发机器**上构建，绝不要在小型的 VPS 上构建（构建过程会消耗大量内存，可能导致生产环境崩溃）。输出：通过 `scp` 上传并使用 `docker load` 加载的 **单架构 amd64** tarball。 ``` # 在开发团队中 (应用中立的「SOC」品牌标识)： ./release.sh vNNNN # → soc-controlplane-vNNNN.tar.gz + soc-engram-vNNNN.tar.gz + .sha256 # 在服务器上：对 .tar.gz 执行 docker load → Portainer → Stacks → soc → Update ``` 有关分步指南和安全注意事项，请参阅 [DESPLIEGUE.md](DESPLIEGUE.md)。 ## ✅ 测试 **403 个测试**（单元测试 · 集成测试 · 安全/供应链测试），使用 **pytest** 或通过一个**无网络依赖的 stdlib 运行器**（自动发现 `tests/**/test_*.py`，模拟 `pytest.raises`）。 它们涵盖了以下领域：检测和风险、nginx（监控、批次、域名、报告、deny-map）、 响应/防火墙和 fail2ban、告警和负责人、AI（仅限 MCP 的代理、编排器、 OAuth、提供商）、身份/角色/访问权限、记忆 (engram)、持久化和备份、 CRON 以及安全强化。 ``` pip install ".[dev]" && pytest # o el runner stdlib sin red python -m compileall -q afdpm # verificación rápida sin red pytest tests/unit/test_detection.py::test_risk_combines_saturating # un solo test ``` ## 🔗 供应链 (UI) `web/` 强制使用 **pnpm**：`package.json` 中的 `packageManager`、带有 `only-allow pnpm` 的 `preinstall`、包含 `ignore-scripts=true` + `frozen-lockfile` 的 `.npmrc`。不要使用 npm/yarn 或添加生命周期脚本。 ## 📖 文档 - **[docs/README.md](docs/README.md)** — **所有文档的索引**，按受众分组（入门 · 使用 · 运维 · 开发 · 参考）。 - **[INSTALAR.md](INSTALAR.md)** — 分步安装指南（Docker、Unraid、Windows 和原生）。 - **[DOCUMENTACION.md](DOCUMENTACION.md)** — 完整的操作员手册（11 个章节）。 - **[DESPLIEGUE.md](DESPLIEGUE.md)** — 编译并投入生产 (VPS / Portainer)。 - **[CONTRIBUTING.md](CONTRIBUTING.md)** — 如何贡献（环境、测试、DDD 风格、PR）。 - **[SECURITY.md](SECURITY.md)** — 漏洞报告和安全模型。 - **[docs/MANUAL.es.md](docs/MANUAL.es.md)** · **[docs/MANUAL.en.md](docs/MANUAL.en.md)** — 按菜单划分的参考手册（ES/EN 双语）。 - **[CLAUDE.md](CLAUDE.md)** — 架构和约定（用于开发）。 - **应用内帮助**（“?”按钮） — 指南 · 文档 · 概念 · 架构，ES/EN 双语。 ## 📄 许可证 **MIT** — 详见 [LICENSE](LICENSE)。**纯防御性**软件，按“原样”提供，不提供任何 保证；请仅在你管理的系统或网络中，或者在你拥有 明确授权的情况下使用。

标签：CISA项目, Fail2ban, IP 地址批量处理, Nginx监控, Python, React, Syscalls, 动态API解析, 安全运营中心(SOC), 无后门, 版权保护, 自定义脚本, 配置错误, 防御系统