arthurpanhku/DocSentinel

DocSentinel
AI 驱动的 SSDLC 平台 —— 从需求到运维，全流程保障软件安全

## 什么是 DocSentinel？ **DocSentinel** 是一个面向安全团队的、AI 驱动的 **SSDLC（安全软件开发生命周期）平台**。它利用由 **LangGraph** 编排并由 **LangChain** 驱动的智能 AI agents，自动化软件开发生命周期所有六个阶段的安全活动。它能自动化审查与安全相关的**文档、表格和报告** —— 从需求、设计到开发、测试、部署和运维 —— 将输入内容与您的策略和知识库进行比对，生成包含风险、合规差距和补救建议的**结构化评估报告**。 DocSentinel 不再仅在发布前阶段审查文档，而是从第一天起就嵌入安全性： | SSDLC 阶段 | DocSentinel 的作用 | | :--- | :--- | | **需求** | 提取安全需求，识别合规义务 (GDPR, PCI DSS, SOC2) | | **设计** | 自动化威胁建模 (STRIDE/DREAD)，安全架构审查，SDR 报告 | | **开发** | 安全编码评估，SAST 发现分类，编码指导 | | **测试** | SAST/DAST 报告分析，渗透测试审查，漏洞优先级排序 | | **部署** | 配置安全审查，加固评估，发布签核 | | **运维** | 漏洞监控，事件响应协助，日志审计 | DocSentinel 构建为 **headless API + MCP 服务**，可集成到您的 CI/CD 管道、AI agents（Claude Desktop, Cursor, OpenClaw）以及现有的安全工作流中。 - **LangGraph 编排**：有状态的、基于图的 agent 工作流，支持按 SSDLC 阶段进行条件分支。 - **多格式输入**：PDF, Word, Excel, PPT, 文本 —— 解析为 LLM 的统一格式。 - **知识库 (RAG)**：上传策略和合规文档；agent 在评估时将其作为参考。 - **多种 LLM**：通过单一接口使用 OpenAI, Claude, Qwen, 或 **Ollama** (本地)。 - **结构化输出**：包含风险项、合规差距和可操作补救措施的 JSON/Markdown 报告。 非常适合需要在多个项目和 SSDLC 阶段扩展安全评估，而无需按比例增加人手的企业。 ## 为什么选择 DocSentinel？ | 痛点 | DocSentinel 解决方案 | | :--- | :--- | | **碎片化的 SSDLC 覆盖**
大多数工具只涉及测试/部署。 | **全生命周期 agents** 通过专用的 AI 角色覆盖所有 6 个 SSDLC 阶段。 | | **标准碎片化**
策略、标准和先例分散各处。 | 单一 **知识库** 确保发现的一致性和可追溯性。 | | **无自动化威胁建模**
威胁模型是临时创建的。 | **设计 Agent** 从架构文档生成 STRIDE/DREAD 威胁模型。 | | **繁重的问卷工作流**
无休止的审查循环。 | **自动化初审** 和差距分析减少了人工反复沟通的轮次。 | | **SAST/DAST 报告过载**
发现太多，上下文太少。 | **测试 Agent** 对发现进行分类、优先级排序，并将其映射到威胁模型。 | | **发布前审查压力**
所有问题最后都压在安全团队身上。 | **左移** 方法在需求和设计早期发现问题。**结构化报告** 帮助审查者专注于决策。 | | **规模与一致性的矛盾**
人工审查因审查者而异。 | **LangGraph 工作流** 和 **统一管道** 确保跨项目评估的一致性和可审计性。 | | **SSDLC 覆盖缺口**
安全介入在生命周期各阶段不均衡；早期阶段受到的审查较少。 | **阶段感知评估** 涵盖所有 6 个 SSDLC 阶段，配备专门的技能和检查清单。 | *完整的问题陈述和 SSDLC 阶段详情请参阅 [SPEC.md](./SPEC.md)。* ## 架构 DocSentinel 基于 **LangGraph** 构建以实现有状态的 agent 编排，并基于 **LangChain** 实现统一的 LLM 访问。六个特定阶段的 agents 由一个基于图的状态机协调，并具有跨阶段上下文共享。编排器协调解析、SSDLC 阶段路由、知识库 (RAG)、技能和 LLM。您可以根据环境需求使用云或本地 LLMs 以及可选的集成（例如 AAD, ServiceNow）。 ``` flowchart TB subgraph User["User / Security Staff"] end subgraph Access["Access Layer"] API["REST API / MCP"] end subgraph Orchestration["SSDLC Orchestration (LangGraph)"] Router["Phase Router"] A1["Requirements Agent"] A2["Design Agent"] A3["Development Agent"] A4["Testing Agent"] A5["Deployment Agent"] A6["Operations Agent"] end subgraph Core["Core Services"] KB["Knowledge Base (RAG)"] Parser["Parser"] Skill["Skills"] Mem["Memory"] end subgraph LLM["LLM Layer (LangChain)"] Abst["LLM Abstraction"] end subgraph Backends["LLM Backends"] Cloud["OpenAI / Claude / Qwen"] Local["Ollama / vLLM"] end User --> API API --> Router Router --> A1 & A2 & A3 & A4 & A5 & A6 A1 & A2 & A3 & A4 & A5 & A6 --> KB & Parser & Skill A1 & A2 & A3 & A4 & A5 & A6 --> Abst Abst --> Cloud & Local ``` **数据流（简化版）：** 1. 用户选择 SSDLC 阶段并上传文档（或选择让 SSDLC Router 自动检测阶段）。 2. **解析器** 将文件（PDF, Word, Excel, PPT, SAST/DAST 报告等）转换为文本/Markdown。 3. **LangGraph Router** 分发到适当的 **阶段 Agent(s)**，加载特定阶段的技能 + 检查清单。 4. 阶段 Agent 查询 **KB**（特定阶段的集合）并应用 **技能**；策略和证据并行运行，然后是起草者和审查者。 5. **LLM**（通过 LangChain）生成具有跨阶段可追溯性的结构化发现。 6. 返回 **评估报告**（风险、威胁、差距、补救措施、置信度、SSDLC 阶段）。 *详细架构：[ARCHITECTURE.md](./ARCHITECTURE.md) 和 [docs/01-architecture-and-tech-stack.md](./docs/01-architecture-and-tech-stack.md)。* ## 核心能力 ### SSDLC 全生命周期覆盖 六个专用 AI agents，每个都拥有特定阶段的技能、提示词和知识库集合。可运行单个阶段或完整的端到端 SSDLC 评估： - **需求**：安全需求，合规映射，初步风险分析。 - **设计**：架构审查，STRIDE/DREAD 威胁建模，SDR。 - **开发**：安全编码标准，代码审查发现。 - **测试**：SAST/DAST 报告分类，渗透测试评估。 - **部署**：发布就绪性，配置安全，加固。 - **运维**：事件响应，漏洞监控，日志审计。 ### 自动化安全评估 提交安全问卷、设计文档或审计报告。DocSentinel 使用配置的 LLMs 分析它们并识别： - **安全风险**：按严重程度分类（严重、高、中、低）。 - **合规差距**：针对 ISO 27001、PCI DSS 等框架的缺失控制措施。 - **补救步骤**：修复已识别问题的可操作建议。 ### 智能 Agent 编排 - **有状态工作流**：LangGraph 状态机在阶段间维护上下文 - **跨阶段可追溯性**：来自设计的威胁链接到测试中的测试用例和运维中的监控规则 - **条件路由**：Agents 根据项目风险等级、合规要求或用户选择激活 - **人机交互**：在阶段边界设置中断点供人工审查 - **检查点**：长时间运行的评估会持久化状态并恢复 ### RAG 驱动的知识库 上传您组织的安全策略、标准和过去的审计记录。特定阶段的集合确保每个 agent 检索最相关的上下文： - 需求：合规框架，安全策略 - 设计：威胁目录，安全模式 - 开发：安全编码标准 (OWASP) - 测试：漏洞数据库，补救指南 - 部署：CIS benchmarks，加固指南 - 运维：CVE 数据库，事件剧本 ### LangGraph Agent 编排 由 **LangChain + LangGraph** 驱动 —— 有状态的、基于图的 agent 工作流，支持按 SSDLC 阶段进行条件路由。并行执行策略和证据 agents，随后是起草者和审查者 agents。 ### API 优先 & MCP 就绪 设计为 headless 服务。通过 REST API 集成到 CI/CD 管道，或通过 MCP 作为 **超级工具** 在 AI agents（Claude Desktop, Cursor, OpenClaw）中使用。 ## Agent 集成 将 DocSentinel 连接到 **Claude Desktop**、**Cursor** 或 **OpenClaw**，将其作为强大的 SSDLC 安全技能使用。 ### 它能做什么？ 连接后，您可以向您的 AI agent 提问： ### 配置指南 #### Claude Desktop 添加到您的 `claude_desktop_config.json`： ``` { "mcpServers": { "docsentinel": { "command": "/path/to/DocSentinel/.venv/bin/python", "args": ["/path/to/DocSentinel/app/mcp_server.py"], "env": { "OPENAI_API_KEY": "sk-...", "CHROMA_PERSIST_DIR": "/absolute/path/to/data/chroma" } } } } ``` #### Cursor 1. 前往 **Settings > Features > MCP**。 2. 点击 **+ Add New MCP Server**。 - **Name**: `docsentinel` - **Type**: `stdio` - **Command**: `/path/to/DocSentinel/.venv/bin/python` - **Args**: `/path/to/DocSentinel/app/mcp_server.py` *完整指南请见 [docs/06-agent-integration.md](docs/06-agent-integration.md)。* ## 快速开始 ### 选项 A：一键部署（推荐） ``` git clone https://github.com/arthurpanhku/DocSentinel.git cd DocSentinel chmod +x deploy.sh ./deploy.sh ``` - **API 文档**: [http://localhost:8000/docs](http://localhost:8000/docs) ### 选项 B：手动设置 **前置条件**：**Python 3.10+**。可选：[Ollama](https://ollama.ai) (`ollama pull llama2`)。 ``` git clone https://github.com/arthurpanhku/DocSentinel.git cd DocSentinel python3 -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install -r requirements.txt cp .env.example .env # Edit if needed: LLM_PROVIDER=ollama or openai uvicorn app.main:app --reload --host 0.0.0.0 --port 8000 ``` - **API 文档**: [http://localhost:8000/docs](http://localhost:8000/docs) · **健康检查**: [http://localhost:8000/health](http://localhost:8000/health) - **审查控制台 (HITL)**: [http://localhost:8000/docs/review-console.html](http://localhost:8000/docs/review-console.html) ### 示例：提交 SSDLC 评估 ``` # 运行设计阶段评估（威胁建模） curl -X POST "http://localhost:8000/api/v1/assessments" \ -F "files=@examples/architecture-doc.pdf" \ -F "phase=design" \ -F "scenario_id=threat-modeling" # 响应：{ "task_id": "...", "status": "accepted" } # 获取结果 curl "http://localhost:8000/api/v1/assessments/TASK_ID" ``` ### 示例：上传到 KB 并查询 ``` # 将安全策略上传到 requirements KB collection curl -X POST "http://localhost:8000/api/v1/kb/documents" \ -F "file=@examples/sample-policy.txt" \ -F "collection=kb_requirements" # 查询 KB (RAG) curl -X POST "http://localhost:8000/api/v1/kb/query" \ -H "Content-Type: application/json" \ -d '{"query": "What are the access control requirements?", "top_k": 5}' ``` ## 托管部署 托管部署可在 [Fronteir AI](https://fronteir.ai/mcp/arthurpanhku-docsentinel) 上使用。 ## 项目结构 ``` DocSentinel/ ├── app/ # Application code │ ├── api/ # REST routes: assessments, KB, health, skills │ ├── agent/ # LangGraph orchestrator, phase agents, skills │ │ ├── orchestrator.py # LangGraph state machine & phase routing │ │ ├── agents/ # Phase-specific agent implementations │ │ ├── ssdlc/ # SSDLC pipeline: stage router, stage skills, checklists │ │ ├── skills_registry.py # Built-in skills per SSDLC phase │ │ └── skills_service.py # Skill CRUD and management │ ├── core/ # Config, guardrails, security, DB │ ├── kb/ # Knowledge Base (Chroma + LightRAG graph RAG) │ ├── llm/ # LangChain LLM abstraction (OpenAI, Ollama) │ ├── parser/ # Document parsing (Docling + SAST/DAST + legacy) │ ├── models/ # Pydantic / SQLModel models │ ├── main.py # FastAPI app entry point │ └── mcp_server.py # MCP Server for agent integration ├── tests/ # Automated tests (pytest) ├── examples/ # Sample files (questionnaires, policies, reports) ├── docs/ # Design & Spec documentation │ ├── 01-architecture-and-tech-stack.md │ ├── 02-api-specification.yaml │ ├── 03-assessment-report-and-skill-contract.md │ ├── 04-integration-guide.md │ ├── 05-deployment-runbook.md │ ├── 06-agent-integration.md │ └── schemas/ ├── .github/ # Issue/PR templates, CI (Actions) ├── Dockerfile ├── docker-compose.yml ├── docker-compose.ollama.yml ├── CONTRIBUTING.md ├── CODE_OF_CONDUCT.md ├── CHANGELOG.md ├── SPEC.md # PRD with SSDLC phase definitions ├── ARCHITECTURE.md # System architecture with LangGraph design ├── LICENSE ├── SECURITY.md ├── requirements.txt ├── requirements-dev.txt └── .env.example ``` ## 配置 | 变量 | 描述 | 默认值 | | :--- | :--- | :--- | | `LLM_PROVIDER` | `ollama` 或 `openai` | `ollama` | | `OLLAMA_BASE_URL` / `OLLAMA_MODEL` | 本地 LLM | `http://localhost:11434` / `llama2` | | `OPENAI_API_KEY` / `OPENAI_MODEL` | OpenAI | -- | | `CHROMA_PERSIST_DIR` | 向量数据库路径 | `./data/chroma` | | `PARSER_ENGINE` | 解析器: `auto`, `docling`, 或 `legacy` | `auto` | | `ENABLE_GRAPH_RAG` | 启用 LightRAG 图检索 | `true` | | `LANGGRAPH_CHECKPOINT_DIR` | LangGraph 检查点持久化 | `./data/checkpoints` | | `SSDLC_DEFAULT_PHASES` | 完整评估的默认阶段 | `requirements,design,development,testing,deployment,operations` | | `SSDLC_DEFAULT_STAGE` | 未指定时的默认 SSDLC 阶段 | `auto` | | `UPLOAD_MAX_FILE_SIZE_MB` / `UPLOAD_MAX_FILES` | 上传限制 | `50` / `10` | *完整选项请见 [.env.example](./.env.example) 和 [docs/05-deployment-runbook.md](./docs/05-deployment-runbook.md)。* ## 技术栈 | 层级 | 技术 | 用途 | | :--- | :--- | :--- | | **Agent 编排** | LangGraph | 有状态的基于图的 SSDLC 工作流引擎 | | **LLM 框架** | LangChain | 统一的 LLM 抽象、提示词、工具、RAG | | **Web/API** | FastAPI | 具有自动 OpenAPI 的异步 REST API | | **向量存储** | ChromaDB + LightRAG | 混合向量 + 图 RAG | | **解析** | Docling + legacy 回退 | 多格式文档解析 | | **LLM 提供商** | OpenAI, Ollama | 云端和本地 LLM 支持 | | **语言** | Python 3.10+ | 主要开发语言 | ## 文档和 PRD - **[ARCHITECTURE.md](./ARCHITECTURE.md)** — 系统架构：LangGraph 设计，SSDLC agents，数据流，部署。 - **[SPEC.md](./SPEC.md)** — 产品需求：SSDLC 阶段，功能，安全控制。 - **[CHANGELOG.md](./CHANGELOG.md)** — 版本历史；[Releases](https://github.com/arthurpanhku/DocSentinel/releases)。 - **设计文档** [docs/](./docs/)：架构，API 规范 (Open)，契约，集成指南，部署 runbook。 ## 开发与测试 ### 选项 A：一键测试（推荐） ``` chmod +x test_integration.sh ./test_integration.sh ``` ### 选项 B：手动 ``` pip install -r requirements-dev.txt pytest pytest tests/test_skills_api.py # Run specific test ``` ## 贡献 欢迎提交 Issues 和 Pull Requests。请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 了解设置、测试和提交指南。参与即表示您同意 [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)。 AI 辅助贡献：我们鼓励使用 AI 工具进行贡献！请查看 [CONTRIBUTING_WITH_AI.md](CONTRIBUTING_WITH_AI.md) 了解最佳实践。 提交技能模板：有一个很棒的 SSDLC 阶段安全角色吗？提交一个 [Skill Template](https://github.com/arthurpanhku/DocSentinel/issues/new?template=new_skill_template.md) 或将其添加到 `examples/templates/`。 ## 安全 - **漏洞报告**：有关负责任的披露，请参阅 [SECURITY.md](./SECURITY.md)。 - **安全要求**：遵循 [SPEC §7.2](./SPEC.md) 中的安全控制。 ## 许可证 本项目采用 **MIT License** 许可 —— 详情请见 [LICENSE](./LICENSE) 文件。 ## Star 历史 [](https://star-history.com/#arthurpanhku/DocSentinel&Date) ## 作者和链接 - **作者**: PAN CHAO (Arthur Pan) - **仓库**: [github.com/arthurpanhku/DocSentinel](https://github.com/arthurpanhku/DocSentinel) - **SPEC 和设计文档**: 见上方链接。 如果您在组织中使用 DocSentinel 或做出回馈，我们很乐意收到您的反馈（例如通过 GitHub Discussions 或 Issues）。

标签：AI智能体, AI风险缓解, DevSecOps, LangChain, LangGraph, MCP服务器, Python, RAG, Ruby, SSDLC, 上游代理, 多格式解析, 安全软件开发生命周期, 安全运营, 安全问卷, 扫描框架, 文档自动化, 无后门, 漏洞修复, 知识库, 网络安全, 网络安全培训, 轻量级, 逆向工具, 隐私保护, 风险分析