安全功能

本文档概述了 MCP 代理系统中实现的全面的安全功能。

标签即 OAuth 范围安全模型

核心概念

标签使用 tag:{tag-name} 格式（例如 tag:web、tag:db）映射到 OAuth 2.1 范围。这提供了细粒度的访问控制，客户端只能访问已明确授予其范围权限的服务器。

安全优势

细粒度的访问控制：客户端只能访问授权的服务器
标准合规性：正确使用 OAuth 2.1 范围
用户同意：通过 Web 界面明确批准请求的权限
故障安全设计：在任何验证失败时拒绝访问
范围过期：范围随访问令牌一起过期

范围验证安全

输入验证 (`src/utils/scopeValidation.ts`)

严格的格式验证：只允许 tag:[a-zA-Z0-9_-]+ 模式
长度限制：最大范围和标签长度强制执行
注入预防：阻止路径遍历、命令注入和特殊字符
计数限制：每个请求的最大范围数
重复检测：防止请求中出现重复范围

白名单方法

范围仅根据可用的服务器标签进行验证
不允许通配符或模式匹配
具有全面错误日志记录的故障安全验证

身份验证和授权

OAuth 2.1 实现 (`src/auth/sdkOAuthServerProvider.ts`)

PKCE 支持：防止授权码拦截
客户端注册：带有验证的动态客户端注册
令牌管理：安全的令牌生成、验证和撤销
会话管理：带有过期的安全会话存储
基于 Web 的同意：用于范围批准的用户友好同意界面

基于范围的授权中间件 (`src/transport/http/middlewares/scopeAuthMiddleware.ts`)

令牌验证：在每个请求上验证不记名令牌
范围强制执行：确保请求的标签被授予的范围所覆盖
向后兼容性：在禁用身份验证时无缝工作
故障安全设计：在任何错误条件下拒绝访问

速率限制

多层速率限制

通用 OAuth 端点：OAuth 操作的标准速率限制
敏感操作：对同意和令牌操作进行更严格的速率限制
自适应限制：不同操作类型的不同限制

速率限制功能

基于 IP 的限制：防止来自特定地址的滥用
时间窗口控制：可配置的速率限制时间窗口
安全日志记录：记录速率限制违规以进行监控
优雅降级：超出限制时提供适当的错误响应

安全中间件 (`src/transport/http/middlewares/securityMiddleware.ts`)

安全标头

X-Frame-Options：防止点击劫持攻击
X-Content-Type-Options：防止 MIME 类型嗅探
X-XSS-Protection：在浏览器中启用 XSS 保护
Content-Security-Policy：限制 HTML 响应的资源加载
Referrer-Policy：控制引荐来源信息泄漏

输入验证

注入保护：检测并阻止常见的注入模式
标头验证：验证所有 HTTP 标头是否存在可疑内容
查询参数验证：验证查询参数是否存在恶意内容
正文验证：验证 POST 操作的请求正文

会话安全

缓存控制：防止缓存敏感响应
机器人排除：防止索引 OAuth 端点
时序攻击预防：身份验证端点的随机延迟

审计日志记录

全面的审计跟踪 (`src/utils/scopeValidation.ts`)

范围操作：所有范围验证和授权事件
客户端识别：跟踪执行操作的客户端
成功/失败跟踪：记录成功和失败的操作
时间戳记录：所有安全事件的精确时间

安全事件日志记录

身份验证事件：登录尝试、令牌生成、失败
授权事件：范围授予、拒绝、违规
速率限制事件：超出限制时
安全违规：注入尝试、可疑活动

网络安全

传输安全

HTTPS 强制执行：所有生产流量都通过加密连接
CORS 配置：正确的跨域请求处理
请求大小限制：通过大请求防止 DoS

错误处理

安全的错误响应：错误消息中没有敏感信息
一致的错误格式：标准 OAuth 2.1 错误格式
错误日志记录：仅在服务器端记录详细错误

输入清理 (`src/utils/sanitization.ts`)

上下文感知清理

HTML 转义：防止 HTML 响应中的 XSS
URL 参数清理：安全处理 URL 参数
服务器名称清理：防止通过服务器名称注入
错误消息清理：安全显示错误消息

向后兼容性

禁用身份验证模式

优雅降级：禁用身份验证时功能齐全
标签筛选保留：禁用身份验证时保留原始标签筛选
配置灵活性：运行时启用/禁用身份验证

迁移支持

增量采用：可以逐步启用身份验证
现有客户端支持：禁用身份验证时可与非 OAuth 客户端一起使用

安全测试

全面的测试覆盖率

单元测试：范围验证、中间件功能
集成测试：完整的身份验证流程
安全测试：注入尝试、边缘情况、时序攻击
性能测试：速率限制和验证的负载测试

安全边缘情况

缓冲区溢出预防：输入长度验证
空字节注入预防：输入格式验证
Unicode 攻击预防：字符集限制
原型污染预防：安全的对象处理

安全最佳实践

开发指南

最小权限原则：授予最小必需的范围
故障安全设计：默认为拒绝访问
深度防御：多个安全层
定期安全审计：持续的安全监控

操作安全

安全的配置默认值：开箱即用的安全配置
特定于环境的设置：每个环境的不同安全级别
安全监控：实时安全事件监控
事件响应：明确的安全事件响应程序

合规性

标准遵守

OAuth 2.1：完全符合 OAuth 2.1 规范
RFC 7636：PKCE 实现
OWASP Top 10：防范常见的 Web 漏洞
安全标头：遵循安全标头最佳实践

隐私保护

数据最小化：仅收集和存储必要的数据
安全存储：加密的会话和令牌存储
访问日志记录：审计跟踪，不暴露敏感数据
用户同意：对所有数据访问的明确同意