josephManzambi/Secure-By-Design-Agentic
GitHub: josephManzambi/Secure-By-Design-Agentic
一个以安全设计为核心的教育项目，演示如何利用OWASP和NIST框架构建带有MCP工具的安全AI智能体，并提供配套的红队验证方案。
Stars: 0 | Forks: 0
# 🏗️ Secure-By-Design-Agentic
**一个教育性的开源项目，演示如何构建一个安全的
带有 MCP 工具集成的 AI Agent - 并与 OWASP、NIST 和 CSA 框架保持一致。**
## 目录
- [v1 中的内容](#whats-in-v1)
- [项目存在的原因](#why-this-project-exists)
- [架构概述](#architecture-overview)
- [框架对齐](#framework-alignment)
- [技术选型（附带理由）](#technology-choices-justified)
- [项目结构](#project-structure)
- [前置条件](#prerequisites)
- [快速开始](#quick-start)
- [两个阶段 (v1)](#the-two-phases-in-v1)
- [手动红队验证](#manual-red-team-validation)
- [路线图](#roadmap)
- [教育资源](#educational-resources)
- [贡献指南](#contributing)
- [许可证](#license)
## v1 中的内容
✅ **阶段 1 - 一个安全的 Agent**
具有输入验证、工具授权、输出过滤和结构化审计日志的深度防御架构。
不依赖 Agent 框架构建，因此每个安全边界都清晰可见。
✅ **阶段 2 - 一个安全的 MCP 服务器**
强化的 FastMCP 服务器，带有四个只读工具，演示了路径规范化、
参数列表形式的子进程调用、速率限制和通用错误信息。
✅ **手动红队验证**
来自 OWASP LLM01、LLM02、LLM05、LLM06 和 LLM10 的测试用例，您可以
手动运行以验证每一层防御。参见 [`docs/MANUAL_REDTEAM.md`](docs/MANUAL_REDTEAM.md)。
✅ **使用 mcp-scan 进行静态分析**
红队工具链中最稳定的组件会在每次推送时在 CI 中运行。
🛠️ **将在 v2 中推出** - 使用 [AI Red Team Orchestrator](https://github.com/josephManzambi/ai-redteam-orchestrator)
的完整自动化红队流水线，
前提是该项目在多次运行中能产生一致的结果。
## 项目存在的原因
带有工具访问权限的 AI Agent 正在各企业中激增。NIST 研究
（2025 年 1 月）表明，针对 AI Agent 的新型攻击策略在红队演练中
达到了 **81% 的成功率**，而针对基线防御的成功率仅为 11%。同时，
在 2026 年 1 月对 1,808 个公共 MCP 服务器的一次扫描中发现，**43%
存在命令注入漏洞**，13% 存在身份验证绕过，10% 存在路径遍历问题。
“部署一个 AI Agent”与“部署一个*安全的* AI Agent”之间的差距是
巨大的。本项目通过以下方式弥合这一差距：
1. 构建一个从一开始就基于最小权限、人机协同
和深度防御理念设计的**安全 Agent**
2. 构建一个**安全的 MCP 服务器**，演示针对生产 MCP 部署中发现的
真实漏洞的缓解措施
3. 提供**手动红队检查清单**（v1），在上游工具稳定后
将变为**自动化流水线**（v2）
每个组件都标注了其实现的具体 OWASP、NIST 或 CSA 控制。
## 架构概述
```
┌─────────────────────────────────────────────────────────┐
│ User Interface │
│ (CLI with human-in-the-loop) │
└──────────────────────┬──────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Secure Agent Layer │
│ │
│ ┌─────────────┐ ┌──────────────┐ ┌───────────────┐ │
│ │ Input Guard │ │ System Prompt│ │ Output Filter │ │
│ │ (Validator) │ │ (Constrained)│ │ (Sanitizer) │ │
│ └──────┬──────┘ └──────┬───────┘ └───────┬───────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ LLM (Ollama - qwen2.5:7b) │ │
│ └──────────────────────┬───────────────────────────┘ │
│ │ │
│ ┌──────────────────────▼───────────────────────────┐ │
│ │ Tool Call Authorization Layer │ │
│ │ • Allowlist enforcement │ │
│ │ • Parameter validation │ │
│ │ • Human confirmation for destructive ops │ │
│ │ • Audit logging │ │
│ └──────────────────────┬───────────────────────────┘ │
└─────────────────────────┼───────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Secure MCP Server (FastMCP) │
│ │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ read_log │ │ system_info │ │
│ │ (path-locked) │ │ (read-only) │ │
│ └────────────────┘ └────────────────┘ │
│ ┌────────────────┐ ┌────────────────┐ │
│ │ search_logs │ │ health_check │ │
│ │ (grep-only) │ │ (no params) │ │
│ └────────────────┘ └────────────────┘ │
│ │
│ Security controls: │
│ • No shell=True anywhere │
│ • Path canonicalization + allowlist │
│ • Input type validation on every parameter │
│ • Tool descriptions free of secrets │
│ • Rate limiting │
│ • Audit trail on every invocation │
└─────────────────────────────────────────────────────────┘
```
## 框架对齐
每一个设计决策都映射到具体的控制或建议。完整的控制级映射位于
[`docs/FRAMEWORK_ALIGNMENT.md`](docs/FRAMEWORK_ALIGNMENT.md)。
| 决策 | OWASP | NIST | CSA |
|---|---|---|---|
| 对所有工具参数进行输入验证 | LLM01 (Prompt Injection) | AI 600-1 §5.1 | AICM AIS-04 |
| 输出清理（敏感模式） | LLM05 (Improper Output Handling) | AI 600-1 §5.5 | AICM AIS-07 |
| 工具白名单强制执行 | LLM06 (Excessive Agency - Functionality) | AI 100-1 MAP 1.5 | AICM AIS-09 |
| 破坏性操作的人为确认 | LLM06 (Excessive Agency - Autonomy) | AI 100-1 GOVERN 1.4 | Scoping Matrix Scope 2 |
| 系统提示词中无密钥 | LLM07 (System Prompt Leakage) | AI 600-1 §5.7 | AICM IAM-03 |
| 路径规范化 | OWASP MCP Guide §4.3 | SP 800-53 SI-10 | AICM AIS-05 |
| 子进程调用中不使用 `shell=True` | OWASP MCP Guide §4.2 | SP 800-53 SI-10 | AICM AIS-05 |
| 工具调用的审计日志 | LLM09 (Misinformation) | AI 100-1 MEASURE 2.6 | AICM LOG-01 |
| 速率限制 | LLM10 (Unbounded Consumption) | AI 600-1 §5.10 | AICM AIS-12 |
| 敏感模式过滤 | LLM02 (Sensitive Info Disclosure) | AI 600-1 §5.2 | AICM DSP-04 |
| 审查工具描述以防投毒 | OWASP MCP Security Guide | - | AICM AIS-06 |
## 技术选型（附带理由）
选择每种技术都有特定的原因。有关完整的决策日志，请参阅
[`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。
### 运行时与模型
| 技术 | 原因 |
|---|---|
| **Python 3.11+** | 所有主要红队框架（PyRIT, Garak, Promptfoo 插件）的主要语言。使 v2 流水线保持在同一个生态系统中。 |
| **Ollama** | 完全本地推理 - 无需 API 密钥，无数据泄露风险，无供应商锁定。对于需要控制完整技术栈的安全测试至关重要。 |
| **qwen2.5:7b** | 开源权重模型 (Apache 2.0)，适合消费级硬件 (8GB VRAM)。规模足以实现真实的 Agent 行为，又足够小以实现快速迭代。 |
| **uv** | 带有锁定文件的确定性依赖解析。对于可重现的安全测试至关重要。 |
### Agent 架构
| 技术 | 原因 |
|---|---|
| **无框架（原生 Python）** | Agent 框架（LangChain, CrewAI 等）将我们试图保护的确切控制面抽象化了。NIST AI 100-1 GOVERN 1.1 要求了解系统的完整攻击面。 |
| **Ollama Python SDK** | 轻量级客户端，极小的依赖面。直接映射到 `POST /api/chat` - 没有隐藏的 middleware。 |
### MCP 服务器
| 技术 | 原因 |
|---|---|
| **FastMCP** | MCP 规范作者的参考实现。确保协议合规性且具有最小的攻击面。 |
| **不使用 `shell=True`** | OWASP MCP 指南 §4.2 明确禁止通过 shell 媒介的子进程调用。我们使用带有参数列表的 `subprocess.run([...], shell=False)`。 |
| **`pathlib` 用于路径操作** | `os.path.realpath()` + 前缀检查可防止路径遍历。OWASP MCP 指南 §4.3。 |
### 我们刻意不使用的技术
| 省略的部分 | 理由 |
|---|---|
| **LangChain / LlamaIndex** | 将 Agent 循环隐藏在抽象之后。对于安全教育而言，每个决策点都必须是可检查的。 |
| **基于 API 的模型（OpenAI, Anthropic）** | 您无法对不完全受您控制的事物进行全面红队测试。v2 中的可重现对抗性测试需要本地推理。 |
| **Docker（用于 Agent）** | 增加了一层掩盖安全边界的内容。我们教授的是进程级隔离。Docker 用于部署没问题；但不适合用于学习。 |
## 项目结构
```
Secure-By-Design-Agentic/
│
├── README.md # This file
├── LICENSE # MIT
├── pyproject.toml # Project metadata + dependencies
│
├── agent/ # Phase 1 - The Secure Agent
│ ├── __init__.py
│ ├── agent.py # Main agent loop
│ ├── input_guard.py # Input validation & sanitization
│ ├── output_filter.py # Output sanitization (sensitive patterns)
│ ├── tool_authorizer.py # Tool call authorization layer
│ ├── audit_logger.py # Structured audit logging
│ └── config.py # Agent configuration (no secrets)
│
├── mcp_server/ # Phase 2 - The Secure MCP Server
│ ├── __init__.py
│ ├── server.py # FastMCP server with hardened tools
│ ├── validators.py # Input validation utilities
│ ├── rate_limiter.py # Token-bucket rate limiter
│ └── audit.py # Server-side audit logging
│
├── redteam-v2-preview/ # ⚠️ Scaffolding for v2 - NOT used in v1
│ ├── README.md # Explains the v2 status
│ ├── mcp_client_config.json # Used by mcp-scan in CI
│ └── run_redteam.sh # Wrapper for the orchestrator (v2)
│
├── docs/ # Educational documentation
│ ├── ARCHITECTURE.md # Architecture decision log
│ ├── FRAMEWORK_ALIGNMENT.md # Full OWASP/NIST/CSA mapping
│ ├── THREAT_MODEL.md # STRIDE threat model
│ └── MANUAL_REDTEAM.md # v1 manual validation suite
│
└── .github/
└── workflows/
└── ci.yml # v1 CI: lint + import smoke test + mcp-scan
```
## 前置条件
| 工具 | 安装 | 用途 |
|---|---|---|
| [Python 3.11+](https://python.org) | 系统或 `pyenv` | 运行时 |
| [uv](https://docs.astral.sh/uv/) | `curl -LsSf https://astral.sh/uv/install.sh \| sh` | 依赖管理 |
| [Ollama](https://ollama.com) | `curl -fsSL https://ollama.com/install.sh \| sh` | 本地 LLM 推理 |
| [Node.js 18+](https://nodejs.org) | 系统包管理器 | 用于 `mcp-scan` 的 `npx` |
```
# 启动 Ollama 并拉取模型
ollama serve &
ollama pull qwen2.5:7b
```
## 快速开始
```
# 克隆仓库
git clone https://github.com/josephManzambi/Secure-By-Design-Agentic.git
cd Secure-By-Design-Agentic
# 安装依赖项
uv sync
# --- 运行安全 agent ---
uv run python -m agent.agent
# --- 独立运行安全 MCP server（用于测试） ---
uv run python -m mcp_server.server
# --- 对 MCP server 运行 mcp-scan ---
npx -y mcp-scan@latest scan -c redteam-v2-preview/mcp_client_config.json --json
```
## 两个阶段 (v1)
### 阶段 1 - 安全的 Agent
该 Agent 实现了具有四层安全防御的**深度防御**架构：
1. **输入守卫** - 在用户输入到达 LLM 之前对其进行验证。检测
Prompt 注入模式、编码攻击和过长的输入。
*(OWASP LLM01, NIST AI 600-1 §5.1)*
2. **受约束的系统提示词** - 定义 Agent 的角色，列出允许的
工具，并指示模型拒绝超出范围的请求。至关重要的是，
**这里不存储任何密钥** - 系统提示词被视为公开
信息。*(OWASP LLM07, NIST AI 600-1 §5.7)*
3. **工具授权层** - 拦截来自 LLM 的每一个工具调用，
根据白名单进行验证，检查参数类型和范围，并
对敏感操作要求人工确认。
*(OWASP LLM06, CSA Scoping Matrix Scope 2)*
4. **输出过滤器** - 在显示之前扫描 LLM 响应中的敏感模式（文件路径、
凭据、PII）。*(OWASP LLM02, LLM05)*
### 阶段 2 - 安全的 MCP 服务器
该 MCP 服务器公开了四个工具，每个工具演示了一种不同的安全
模式：
- **`read_log`** - 从锁定的目录读取日志文件。演示了路径
规范化、目录白名单和文件扩展名验证。
- **`system_info`** - 返回系统元数据。只读，无参数 -
演示了最小功能原则。
- **`search_logs`** - 按关键字搜索日志文件。演示了安全的
子进程使用（参数列表，无 shell）、输入长度限制和
字符白名单。
- **`health_check`** - 返回服务器状态。无参数，无副作用 -
演示了一个“默认安全”的工具。
## 手动红队验证
v1 附带了一个手动测试套件，涵盖了 OWASP LLM01、LLM02、LLM05、LLM06
和 LLM10。完整的套件 - 包括预期行为、审计日志条目和
解释 - 位于 [`docs/MANUAL_REDTEAM.md`](docs/MANUAL_REDTEAM.md)。
三个类别：
1. **静态分析** - 针对 安全服务器 运行 `mcp-scan`（在 CI 中通过）
2. **直接 Prompt 注入** - 验证 输入守卫 能捕获明显的攻击
3. **工具层攻击** - 验证 工具授权器 阻止未经授权的
调用，即使 LLM 会顺从
每个测试用例都列出了攻击、预期的防御响应以及
应该出现的审计日志条目。
## 路线图
### v1（当前版本）- 安全基础
- [x] 具有四层深度防御的安全 Agent
- [x] 带有四个工具的强化 MCP 服务器
- [x] 威胁模型 + 框架对齐文档
- [x] 手动红队验证套件
- [x] CI：lint + 导入冒烟测试 + mcp-scan
### v1 和 v2 之间 - 稳定 Orchestrator
- [ ] 解决 [ai-redteam-orchestrator](https://github.com/josephManzambi/ai-redteam-orchestrator) 中的 PyRIT 版本固定问题
- [ ] 验证连续三次运行产生一致的严重性分类
- [ ] 记录在稳定过程中遇到的故障模式
### v2 - 完整的自动化红队集成
- [ ] 将 orchestrator 连接到项目中（将 `redteam-v2-preview/` 移动到 `redteam/`）
- [ ] 将三层流水线添加到 CI（第 1 层 广泛扫描，第 2 层 OWASP +
mcp-scan，第 3 层 PyRIT 对抗）
- [ ] 针对安全 Agent + MCP 服务器运行完整的流水线
- [ ] 将结果报告提交到 `docs/RESULTS.md` 以保持透明
### 未来的考量
- [ ] 在安全的服务器旁添加一个故意设计得有漏洞的 MCP 服务器，用于
并排教学
- [ ] SBOM 生成 (OWASP LLM03 - Supply Chain)
- [ ] 比较不同 Ollama 模型的结果
- ] 容器隔离示例（生产级部署）
## 教育资源
### 引用的框架
- [OWASP Top 10 for LLM Applications 2025](https://genai.owasp.org/resource/owasp-top-10-for-llm-applications-2025/)
- [OWASP Practical Guide for Secure MCP Server Development](https://genai.owasp.org/resource/a-practical-guide-for-secure-mcp-server-development/) (2026 年 2 月)
- [OWASP Guide for Securely Using Third-Party MCP Servers](https://genai.owasp.org/resource/cheatsheet-a-practical-guide-for-securely-using-third-party-mcp-servers-1-0/) (2026 年 4 月)
- [NIST AI Risk Management Framework (AI 100-1)](https://www.nist.gov/itl/ai-risk-management-framework)
- [NIST AI 600-1 - Generative AI Profile](https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.600-1.pdf)
- [CSA AI Controls Matrix (AICM)](https://cloudsecurityalliance.org/artifacts/ai-controls-matrix)
- [CSA Agentic AI Security Scoping Matrix](https://cloudsecurityalliance.org/blog/2025/12/16/enhancing-the-agentic-ai-security-scoping-matrix-a-multi-dimensional-approach)
### 相关项目
- [AI Red Team Orchestrator](https://github.com/josephManzambi/ai-redteam-orchestrator) - v2 中搭载的红队流水线
- [Lance](https://github.com/josephManzambi/lance) - 高级 AI 安全测试框架（开发中）
## 贡献指南
这是一个教育项目。欢迎那些能改进安全覆盖范围、
添加框架映射或增强文档的贡献。请：
1. Fork 该仓库
2. 创建一个功能分支
3. 提交一个 PR，并清晰描述*做了什么*以及*为什么*
## 许可证
[MIT](LICENSE)
## 作者
**Joseph Manzambi** - Cloud & AI Security Engineer
- 网站: [manzambi.com](https://www.manzambi.com)
- GitHub: [@josephManzambi](https://github.com/josephManzambi)
标签：AI安全, AI治理, AI风险缓解, AI风险评估, API密钥检测, Chat Copilot, CISA项目, CSA, DevSecOps, DNS解析, Maven, MCP, NIST, Red Teaming, XML 请求, 上游代理, 云安全监控, 人工智能安全, 反取证, 合规性, 大模型安全, 安全合规, 安全基线, 安全左移, 安全开发, 安全教育, 安全架构, 安全测试, 安全评估, 开源项目, 恶意样本开发, 搜索语句（dork）, 攻击性安全, 教学环境, 数据展示, 模型上下文协议, 深度防御, 漏洞验证, 红队, 网络代理, 网络安全, 越权访问, 输入验证, 输出过滤, 逆向工具, 隐私保护, 静态分析