engineeralialmasry/cedrus

# CEDRUS — 企业级红队与紫队治理 Agent 一个 Docker 化的、特定领域的 AI Agent，可帮助大型企业安全地规划、管理和验证红队和紫队演练。CEDRUS 将演练前的治理、风险评分、安全控制验证和 GRC 报告整合到一个单一的可解释决策支持系统中。 **当前版本：V17-8** — 这是一个注重性能、正确性和可观测性的版本。在本地 Ollama 7B 模型上运行。有关此版本的完整详细信息，请参阅 `OPTIMIZATION_REPORT.md` 和 `CHANGELOG_V17-8.md`。 ## 目录 - [概述](#overview) - [V17-8 中的新特性](#whats-new-in-v17-8) - [系统架构](#system-architecture) - [领域工具](#domain-tools) - [Agent 工作流](#agent-workflow) - [记忆与状态](#memory-and-state) - [数据层](#data-layer) - [安全、伦理与 GRC 边界](#safety-ethics-and-grc-boundaries) - [API 端点](#api-endpoints) - [入门指南](#getting-started) - [配置](#configuration) - [可观测性](#observability) - [测试](#testing) - [项目结构](#project-structure) - [局限性](#limitations) - [AI 开发工具披露](#ai-development-tools-disclosure) ## 概述 大型组织定期通过红队和紫队演练来测试其安全态势。如果在执行前没有明确定义范围、审批、交战规则、业务约束和安全控制，这些活动将带来真正的操作风险。在大多数企业中，技术测试、治理审批、风险评估和控制验证存在于由不同团队负责的独立文档中，从而导致责任分散。 CEDRUS 接收有关演练的结构化信息（范围、目标系统、业务关键性、现有控制、审批、约束），并生成带有依据的交战风险等级和执行/暂停决策、所需的审批矩阵、交战规则和安全限制、紫队演练计划、安全控制验证矩阵、带有补救路线图的 GRC 就绪管理报告，以及保存的、可审计的演练请求。 领域知识规模较小且基于规则，因此存储在结构化的本地文件和 SQLite 中，并通过确定性的工具进行访问，而不是使用 RAG pipeline。这使得系统更准确、更易于测试，并且完全可解释。 ## V17-8 中的新特性 此版本专注于延迟、正确性和可观测性，同时保留 Ollama 7B 模型并维持所有行为和输出质量。 性能：YAML/JSON 知识文件现在在启动时仅解析一次并进行缓存，而不是在每个请求时重新读取；移除了响应路径中冗余的知识库搜索；并添加了答案流式传输功能，以便在模型仍在生成时渲染出最初的单词。 可观测性：每请求监控现在会记录总耗时、router、LLM 和工具时间，以及 LLM 和工具调用计数，这些数据通过新的 `/api/metrics` 端点公开，并包含在每个聊天响应中。 正确性：强化了不安全请求过滤器，以捕获漏洞利用代码和绕过变体；演练创建不再因 Critical 关键性或 Testing 环境而崩溃；修复了两个调用了不存在后端路由的前端页面；并替换了已弃用的时间戳调用。测试套件从 32 个通过 / 7 个失败提升至 46 个通过 / 0 个失败。 ## 系统架构 CEDRUS 采用分层架构： | 层级 | 职责 | | --- | --- | | 聊天界面 | 由应用提供的 Web UI，带有流式传输的 copilot | | 编排层 | LangGraph 工作流、意图路由、停止条件、状态转换 | | LLM 推理核心 | 本地 Ollama 7B 模型；解释请求并编写最终答案 | | 工具层 | 用于查找、分析、操作和报告的强类型、确定性函数 | | 记忆层 | 短期对话上下文和显式工作状态 | | 数据层 | 结构化领域数据（YAML/JSON/CSV）和 SQLite 持久化 | | 容器层 | 包含 runtime、依赖项、健康检查和启动配置的 Docker 镜像 | ## 领域工具 每个工具都有明确的用途、输入 schema、输出 schema、确定性验证、显式错误行为和跟踪日志记录。 | 工具 | 类型 | 用途 | | --- | --- | --- | | `lookup_governance_policy()` | 信息 | 检索已批准的策略、交战规则、审批规则和控制基线 | | `assess_exercise_risk()` | 分析 | 根据关键性、暴露面、时间安排、数据敏感度和回滚准备情况计算演练风险 | | `validate_security_controls()` | 分析 | 评估选定控制措施相对于基线的有效性，并识别差距 | | `create_exercise_request()` | 操作 | 仅在明确确认后，在 SQLite 中创建或更新演练请求 | | `generate_governance_report()` | 报告 | 生成结构化的管理报告，包含范围、审批、限制、风险、控制和补救措施 | 其他工具支持合规差距分析和框架推荐。 ## Agent 工作流 该工作流是一个基于 router 的有界循环：按意图对请求进行分类（在置信度低时确定性地回退），收集任何缺失的必填字段，执行有界且经过验证的工具调用，应用安全网关以升级高风险或不受支持的请求，在任何状态更改操作之前要求明确确认，并在记录完整跟踪的同时生成最终答案。确定性的 router 在不调用 LLM 的情况下即可解决绝大多数轮次；模型仅在真正需要自然语言推理的地方使用。 ## 记忆与状态 短期记忆保留了当前的对话。工作记忆明确表示当前意图、已收集的字段、缺失的字段、待定的确认、最新的工具结果以及工作流状态，这可以防止 Agent 跳过审批、丢失字段或在确认之前创建记录。 ## 数据层 | 文件 / 表格 | 内容 | | --- | --- | | `governance_policies.yaml` | 审批规则、测试限制、生产安全要求、交战规则 | | `control_baseline.json` | MFA、日志记录、备份、网络隔离、特权访问和升级的控制预期 | | `risk_matrix.csv` | 可能性、影响、关键性、暴露面和风险等级映射 | | `exercise_templates.json` | 紫队规划模板、角色、成功标准、沟通计划 | | `compliance_frameworks.json`, `framework_selector.json` | 用于合规和推荐工具的框架目录 | | `cybersecurity_knowledge.json` | 结构化教育知识库 | | `exercises.db` (SQLite) | 已保存的演练请求、审批和结果 | ## 安全、伦理与 GRC 边界 CEDRUS 提供的是决策支持，而非授权。它不会生成漏洞利用代码、破坏性命令或未经授权的测试指令；它要求在创建或更新记录之前进行明确确认；它将高风险或不受支持的请求升级给人工授权人（CISO、GRC 官员或业务所有者）；它记录工具调用、决策、错误、回退事件和审批，以确保可审计性；并且它将所有领域知识保留在结构化的本地数据中，说明每项建议的来源，并传达不确定性，而不是做出毫无根据的断言。 ## API 端点 | 方法 | 路径 | 用途 | | --- | --- | --- | | GET | `/health` | 服务健康检查 | | POST | `/api/chat` | Copilot 交互（JSON 响应） | | POST | `/api/chat/stream` | Copilot 交互，逐个 token 进行流式传输（V17-8） | | GET | `/api/metrics` | 最近请求的性能摘要（V17-8） | | POST | `/api/policies/lookup` | 治理策略查找 | | POST | `/api/risk/assess` | 演练风险评估 | | POST | `/api/controls/validate` | 安全控制验证 | | POST | `/api/exercises` | 创建演练请求（需要确认） | | GET | `/api/exercises` | 列出已保存的演练 | | GET | `/api/reports/{exercise_id}` | 为演练生成治理报告 | | GET | `/api/compliance/frameworks` | 列出合规框架 | | POST | `/api/compliance/assess` | 合规差距分析 | | POST | `/api/framework/recommend` | 根据公司概况推荐框架 | 应用运行时，可在 `/docs` 获取交互式 API 文档。 ## 入门指南 ### 前置条件 - Docker 和 Docker Compose（用于容器化运行），或 Python 3.13（用于本地运行） - [Ollama](https://ollama.com) 在本地运行并配备 7B 模型： ollama pull qwen2.5:7b ### 使用 Docker 运行（推荐） ``` git clone https://github.com/engineeralialmasry/cedrus.git cd cedrus cp .env.example .env # adjust values if needed docker compose up --build ``` 然后打开 `http://localhost:8000`。 ### 本地运行 ``` python -m venv .venv # Windows: .venv\Scripts\activate | macOS/Linux: source .venv/bin/activate pip install -r requirements.txt uvicorn app.main:app --port 8000 ``` 然后打开 `http://localhost:8000`。 ## 配置 配置通过环境变量提供（参见 `.env.example`）。没有硬编码的密钥。 | 变量 | 描述 | | --- | --- | | `OLLAMA_BASE_URL` | Ollama 服务器 URL（默认为 `http://127.0.0.1:11434`） | | `OLLAMA_MODEL` | 模型标识符（默认为 `qwen2.5:7b`） | | `OLLAMA_TIMEOUT_SECONDS` | 模型的请求超时时间 | | `OLLAMA_KEEP_ALIVE` | 模型在内存中保持加载的时间（保持预热状态） | | `OLLAMA_NUM_CTX` | 上下文窗口大小 | | `CEDRUS_ALLOWED_ORIGINS` | 允许的 CORS 源 | ## 可观测性 每个请求都会记录一个 `request_performance` 跟踪，并且 `/api/chat` 响应带有一个 `performance` 对象，其中包含总耗时、router、LLM 和工具时间，以及 LLM 和工具调用次数。在任何聊天之后，`GET /api/metrics` 会返回最近一次请求的摘要，这对于现场演示和查看时间消耗在哪里非常方便。 ## 测试 ``` python -m pytest -q ``` 该套件涵盖了工具、数据库、工作流、安全路由、扩展的验证、缓存和指标层，以及流式传输和指标端点。预期结果：所有测试均通过。 ## 项目结构 ``` app/ api/ # FastAPI routes (chat, streaming, metrics, direct tools) core/ # logging and per-request performance metrics data/ # structured domain data (YAML/JSON/CSV) database/ # SQLAlchemy models and session memory/ # short-term and working memory models/ # Pydantic schemas services/ # Ollama client, routing, response generation, streaming tools/ # governance, risk, controls, exercises, reports, compliance workflow/ # LangGraph orchestration and streaming runner frontend/ # web UI and copilot evaluation/ # test cases and evaluation runner tests/ # pytest suite Dockerfile compose.yaml OPTIMIZATION_REPORT.md CHANGELOG_V17-8.md ``` ## 局限性 领域知识仅限于结构化的本地数据源；Agent 不会浏览外部存储库或访问实时信息。风险评分和控制验证是确定性的近似值，旨在用于决策支持，而非权威判断，并且在本项目范围内模拟了人工交接路径。任何演练的最终权力始终由负责的人类利益相关者掌握。 ## AI 开发工具披露 根据课程的学术规则，在构建和 V17-8 优化过程中使用了 AI 开发工具。所有更改均已通过测试套件的验证。

标签：AI智能体, AI风险缓解, Docker, GRC, 安全治理, 安全防御评估, 本地大模型, 版权保护, 紫队演练, 请求拦截, 逆向工具