CortexSynapse
   ](https://github.com/amshamah419/CortexSynapse/pkgs/container/cortexsynapse)
一个强大的MCP（模型上下文协议）服务器，使AI驱动的IDE和代理能够与实时XSOAR/XSIAM实例交互，以执行开发、测试和自动化任务。
概述
CortexSynapse弥合了人工智能开发工具（Windsurf、Roo Code、Cursor等）和Palo Alto Cortex平台（XSOAR/XSIAM）之间的差距。它提供了一个容器化的MCP服务器，该服务器将XSOAR和XSIAM API作为AI代理可以用来帮助开发人员构建、测试和验证安全自动化工作流程的工具。
主要用例：使开发人员能够使用自然语言与AI助手一起执行常见的XSOAR/XSIAM开发任务，例如：
- 创建和测试剧本
- 管理集成和自动化
- 查询事件和警报
- 运行XQL查询以进行威胁搜索
- 构建和部署自定义内容
- 调试安全工作流
为什么选择CortexSynapse？
作为一名使用XSOAR和XSIAM的开发人员，您需要经常与这些平台交互，以构建、测试和验证安全自动化。CortexSynapse允许您：
- 使用AI助手进行XSOAR/XSIAM开发 -告诉你的AI IDE“创建钓鱼调查剧本”或“查询最近的高严重性事件”
- 加快开发工作流程 -在人工智能的帮助下更快地构建和测试自动化
- 简化常见任务 -使用自然语言进行日常操作，如运行查询、更新事件或测试集成
- 与现代AI IDE集成 -与Windsurf、Roo Code、Cursor和其他MCP兼容工具无缝协作
主要特点
- 70个精选工具 -根据官方XSIAM/XSOAR OpenAPI规范生成，并经过过滤，专注于最有用的工作流程
- 7个统一工具（通过选择XSOAR或XSIAM platform 现场） - 39个XSIAM工具（事件、警报、XQL、端点、威胁情报） - 24个XSOAR工具（剧本、自动化、事件、仪表板、指标） - 📚 工具参考 -每个工具的综合文档
- 集装箱化部署 -Docker支持，可轻松与AI IDE工作流集成
- 实时API集成 -连接到实际的XSOAR/XSIAM实例
- 类型安全操作 -用于可靠AI代理交互的完整Python类型提示
- 可扩展架构 -通过提供OpenAPI规范添加自定义工具
项目结构
.
├── specs/ # OpenAPI specification files
│ ├── xsiam.yaml # XSIAM API specification
│ └── xsoar.yaml # XSOAR API specification
├── codegen/ # Code generation scripts
│ ├── __init__.py
│ └── generator.py # Main generator script
├── server/ # MCP server implementation
│ ├── __init__.py
│ ├── main.py # Server entry point
│ ├── generated_xsiam_tools.py # Auto-generated XSIAM tools
│ └── generated_xsoar_tools.py # Auto-generated XSOAR tools
├── tests/ # Test suite
│ ├── __init__.py
│ ├── test_codegen.py # Code generator tests
│ └── test_server.py # Server tests
├── .github/workflows/ # GitHub Actions
│ └── ci-cd.yml # CI/CD pipeline
├── Dockerfile # Container definition
├── pyproject.toml # Python project configuration
└── README.md # This file安全
🔒 CortexSynapse实现了企业级安全控制。看 安全.md 获取详细的安全文档。
主要安全功能：
- ✅ 输入验证和净化
- ✅ 速率限制（默认100个请求/60s）
- ✅ 错误消息清理以防止信息泄露
- ✅ 非根Docker容器执行
- ✅ 可配置的SSL/TLS验证
- ✅ 基于环境的凭证管理（没有硬编码的秘密）
- ✅ 所有请求上的安全标头
- ✅ CI/CD中的自动安全扫描
快速开始
与AI IDE一起使用
- 构建Docker容器:
docker build -t cortexsynapse .- 设置环境变量 （出于安全考虑建议）：
export XSOAR_API_URL="https://your-xsoar-instance.com"
export XSOAR_API_KEY="your-api-key"
export XSIAM_API_URL="https://your-xsiam-instance.com"
export XSIAM_API_KEY="your-xsiam-api-key"
export XSIAM_API_KEY_ID="your-key-id"- 配置您的AI IDE 要使用MCP服务器：
风帆/光标/房间代码： 添加到MCP设置（通常在 .windsurf/mcp.json, .cursor/mcp.json，或IDE设置）：
{
"mcpServers": {
"cortex": {
"command": "docker",
"args": [
"run",
"-i",
"--read-only",
"--security-opt=no-new-privileges",
"cortexsynapse"
],
"env": {
"XSOAR_API_URL": "${XSOAR_API_URL}",
"XSOAR_API_KEY": "${XSOAR_API_KEY}",
"XSIAM_API_URL": "${XSIAM_API_URL}",
"XSIAM_API_KEY": "${XSIAM_API_KEY}",
"XSIAM_API_KEY_ID": "${XSIAM_API_KEY_ID}"
}
}
}
}⚠️ 安全说明： 使用环境变量引用(${VAR_NAME})而不是硬编码凭证。
- 开始使用AI辅助 对于XSOAR/XSIAM开发：
- “查询过去24小时内的所有严重事件” - “创建勒索软件响应的新剧本” - “运行XQL查询以查找可疑的登录尝试” - “将事件#12345更新为已关闭状态”
本地开发
对于没有Docker的开发和测试：
# Clone and install
git clone https://github.com/amshamah419/Cortex-MCP.git
cd Cortex-MCP
pip install -e ".[dev]"
# Generate tools from OpenAPI specs (already generated by default)
python -m codegen.generator
# Run the MCP server
python -m server.main可用工具
所有70个工具都有详细的描述、参数和返回值。
统一工具（7个工具）
这些工具可用于XSOAR和XSIAM平台。使用 platform 参数指定要使用的平台：
- 事件：获取，更新
- 自动化/脚本：获取、创建/更新、导入、删除
- 日志：获取审核
XSIAM工具（39个工具）
按类别组织：
- XQL查询 （12个工具）-执行和管理用于威胁搜索的XQL查询
- 事件 （3个工具）-查询、更新和管理安全事件
- 警报 （8个工具）-检索和管理安全警报
- 端点 （7个工具）-查询和管理端点信息
- 响应行动 （3个工具）-隔离端点并采取响应行动
- 资产和身份 （11个工具）-管理主机、用户、IP和AD组
- 威胁情报 （3个工具）-管理IOC和声誉数据
- 政策与合规 （2个工具）-查看政策和违规行为
- 行政 （1个工具）-审计日志和RBAC
- 其他操作 （78个工具）-其他XSIAM操作
XSOAR工具（24个工具）
按类别组织：
- 事故与调查 （17个工具）-创建、更新和管理事件
- 指标 （12个工具）-管理威胁指标和IOC
- 仪表板和小部件 （11个工具）-管理仪表板和小部件
- 证据和条目 （6个工具）-添加条目和管理证据
- 自动化和脚本 （5个工具）-创建和管理自动化脚本
- 用户管理 （2个工具）-管理API密钥和用户
- 战术 （1个工具）-管理剧本
- 集成 （1个工具）-管理集成
- 内容管理 （1个工具）-导入分类器和映射器
- 其他操作 （29个工具）-其他XSOAR操作
通用开发工作流
示例1：借助人工智能进行威胁搜索
开发者：“向我展示上周所有源IP来自俄罗斯的严重事件”
AI 代理 使用：
xsiam_get_incidents带有严重性和日期范围过滤器- 按地理位置分析结果和筛选
- 用自然语言呈现研究结果
示例2：剧本开发
开发者：“创建一个测试事件来验证我的新钓鱼策略”
AI 代理 使用：
xsiam_create_incident创建测试事件xsoar_execute_playbook运行剧本xsiam_get_incidents验证结果
示例3：自动化测试
开发者：“运行XQL查询以查找失败的登录尝试，如果超过10次，则创建事件”
AI 代理 使用：
xsiam_start_xql_query使用适当的XQL语法xsiam_get_query_results检索结果xsiam_create_incident如果超过阈值
使用自定义工具进行扩展
虽然服务器附带了70个精选工具，但您可以通过提供额外的OpenAPI规范来添加自定义工具：
- 将您的OpenAPI规范添加到
specs/:
cp your-custom-api.json specs/- 重新生成工具：
python -m codegen.generator- 重建容器：
docker build -t cortexsynapse .生成器支持YAML和JSON OpenAPI规范，并自动将操作ID转换为snake_case函数名。
生成工具示例
从OpenAPI操作中：
paths:
/incidents:
get:
operationId: listIncidents
parameters:
- name: limit
in: query
schema:
type: integer生成器创建：
@server.call_tool()
async def list_incidents(
limit: int | None = None,
) -> List[types.TextContent]:
"""Retrieve a list of security incidents from XSIAM"""
# ... implementation项目结构
.
├── specs/ # OpenAPI specification files
│ ├── xsiam.json # XSIAM API specification (129 endpoints)
│ └── xsoar.json # XSOAR API specification (82 endpoints)
├── server/ # MCP server implementation
│ ├── main.py # Server entry point
│ ├── generated_xsiam_tools.py # Auto-generated XSIAM tools
│ └── generated_xsoar_tools.py # Auto-generated XSOAR tools
├── codegen/ # Code generation (for extending tools)
│ └── generator.py # Tool generator from OpenAPI specs
├── tests/ # Test suite
├── Dockerfile # Container for AI IDE integration
└── pyproject.toml # Python dependencies建筑
MCP服务器流
AI IDE/Agent → MCP Protocol → CortexSynapse Server → XSOAR/XSIAM API
↑ ↓
└──────── Natural Language ←────┘- 开发人员要求AI助手执行任务
- AI代理从70个可用工具中选择合适的工具
- MCP服务器执行对活动XSOAR/XSIAM实例的API调用
- 结果返回给AI代理进行处理和呈现
代码生成（可选-用于自定义工具）
要添加70个内置工具之外的自定义工具：
Custom OpenAPI Spec → generator.py → generated_custom_tools.py → Container Rebuild默认安装包括预生成的所有XSIAM/XSOAR工具，因此只有在使用自定义API扩展服务器时才需要生成代码。
技术细节
需求
- Python 3.10+
- Docker（用于使用AI IDE进行容器化部署）
- 具有API访问权限的活动XSOAR和/或XSIAM实例
依赖项
核心运行时依赖项（自动安装）：
mcp>=0.1.0-模型上下文协议实现httpx>=0.25.0-API调用的异步HTTP客户端pydantic>=2.0-数据验证和类型提示
开发依赖关系（用于扩展工具）：
pytest-测试框架black-代码格式ruff-Linting
故障排除
AI IDE集成问题
MCP服务器未连接：
- 确保Docker正在运行
- 检查容器是否成功启动：
docker run -i cortexsynapse - 验证IDE的MCP配置中是否正确设置了环境变量
API身份验证失败：
- 确认您的XSOAR/XSIAM API密钥有效
- 检查API URL是否正确且可访问
- 确保您的API密钥具有适当的权限
AI助手中未显示的工具：
- 更新MCP配置后重新启动AI IDE
- 检查IDE日志中的MCP连接错误
- 验证MCP协议版本兼容性
发展问题
未找到生成的工具：
python -m codegen.generator导入错误：
pip install -e ".[dev]"Docker构建失败：
# Ensure all required files exist
ls -la specs/ codegen/ server/
# Try building with verbose output
docker build -t cortexsynapse . --progress=plain安全
安全是CortexSynapse的首要任务。我们遵循行业最佳实践来保护您的凭据和数据。
安全功能
- 输入验证：所有输入都经过验证和消毒，以防止注射攻击
- 速率限制：防止API滥用（默认为100个请求/60s，可配置）
- 错误清理：对错误消息进行清理，以防止信息泄露
- 安全凭据：基于环境的配置可防止硬编码的秘密
- 非根执行：Docker容器以非root用户身份运行，以进行深度防御
- SSL/TLS验证：默认情况下启用可配置选项
- 安全标头：所有请求都包含以安全为重点的HTTP标头
- 自动扫描：CI/CD管道包括漏洞和秘密扫描
安全配置
通过环境变量配置安全设置：
# Request timeout (default: 30 seconds)
export API_TIMEOUT=30
# SSL/TLS verification (default: true)
export VERIFY_SSL=true
# Rate limiting
export RATE_LIMIT_REQUESTS=100
export RATE_LIMIT_WINDOW=60报告安全问题
请负责任地报告安全漏洞：
- 不要 安全漏洞的公开问题
- 直接联系存储库维护人员
- 看 安全.md 了解详细的报告指南
有关完整的安全文档，请参阅 安全.md.
贡献
我们欢迎捐款！该项目的重点是实现人工智能辅助的XSOAR/XSIAM开发。
优先领域：
- 通用开发工作流程的其他工具
- 更好的错误处理和调试支持
- 流行AI IDE的增强集成示例
- 大规模部署的性能优化
- 增强的安全性
贡献：
- 分叉存储库
- 创建一个专注于开发人员生产力的功能分支
- 使用真实的XSOAR/XSIAM实例进行测试
- 遵循安全最佳实践（请参阅security.md）
- 提交带有清晰用例描述的拉取请求
许可证
MIT许可证-有关详细信息，请参阅许可证文件
支持
关于问题和议题：
- GitHub问题：Bug报告和功能请求
- 安全问题：参见 安全.md 报告指南
- 讨论：人工智能辅助XSOAR/XSIAM开发的最佳实践
- 文档：检查
docs/和EXAMPLES.md获取详细指南
致谢
基于模型上下文协议（MCP）标准，用于AI到工具的集成。专为使用现代AI开发工具的Palo Alto Cortex平台开发人员设计。