Anywhere MCP Server

LevelBlue USM Anywhere MCP 服务

⚠️ 免责声明：这不是 LevelBlue 或 AlienVault 的官方产品。完整条款请参阅 DISCLAIMER.md。

一个可用于生产环境的 Model Context Protocol (MCP) 服务，可将 AI 助手连接到 LevelBlue 的 USM Anywhere 安全平台。通过自然语言执行高级安全查询、管理调查并分析威胁。

版本：3.0.0 作者：Javier Ballesteros ([email protected]) 许可证：GNU GPL v3.0 代码库：https://github.com/javierb507/anywhere-mcp-server

---

🚀 快速开始（3 分钟）

# 1. Clone and install
git clone https://github.com/javierb507/anywhere-mcp-server.git
cd anywhere-mcp-server
npm install && npm run build

# 2. Configure credentials
cp env.example .env
# Edit .env with your USM Anywhere credentials

# 3. Test connection
node test-connection.js

✅ 已准备就绪，可与 AI 助手集成！ 请参阅下方的集成示例。

---

什么是 MCP？

Model Context Protocol (MCP) 是一种开放协议，支持 AI 助手安全连接到外部数据源和工具。本服务实现了 MCP，可将 AI 助手与 LevelBlue USM Anywhere 连接起来，从而实现：

• 🤖 自然语言查询 → 高级 SQL/PPL 安全分析
• 🔍 自动化威胁搜寻 → AI 驱动的检测与调查
• 📊 调查管理 → 创建、更新和跟踪安全事件
• 🌐 威胁情报 → AlienVault OTX 集成

支持的 AI 平台：Claude Desktop、Claude Code、Cline (VS Code)、Cursor IDE、Zed Editor，以及任何兼容 MCP 的客户端。

---

功能

核心功能

• ✅ OAuth 2.0 身份验证 - 安全的客户端凭证流程
• ✅ 16 个 MCP 工具 - 完整覆盖 USM Anywhere API
• ✅ 高级查询引擎 - 执行 SQL 和 PPL 查询
• ✅ 调查管理 - 符合 SANS 标准的事件响应工作流
• ✅ 威胁情报 - AlienVault OTX API 集成
• ✅ 类型安全 - 使用 TypeScript 构建，并通过 Zod 进行验证
• ✅ 可用于生产环境 - 全面的错误处理和速率限制

预置安全查询

• 📚 15+ 个 SQL 查询 - 威胁搜寻、合规性、异常检测
• 📚 12+ 个 PPL 管道 - 行为分析和日志关联
• 📖 完整文档 - QueryLanguage/ 目录中的查询指南

---

可用的 MCP 工具

工具	描述
get_alarms	检索安全警报并进行筛选
get_events	检索安全事件
get_alarm_details	获取警报详细信息
get_event_details	获取事件详细信息
get_investigations	使用高级筛选条件列出调查
get_investigation_details	获取完整的调查详情
create_investigation	创建新的安全调查
update_investigation	更新调查状态/优先级
add_investigation_note	为调查添加备注
delete_investigation	删除调查
execute_advanced_query	执行 SQL/PPL 查询
validate_query_syntax	执行前验证查询
get_query_examples	获取预置查询示例
search_pulses	搜索 OTX 威胁情报
get_indicator	获取威胁指标信息（IP/域名/哈希值）
get_pulse	获取脉冲的详细信息

---

集成示例

Claude Desktop（macOS/Windows）

配置文件位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "usm-anywhere": {
      "command": "node",
      "args": ["C:\\path\\to\\anywhere-mcp-server\\dist\\index.js"],
      "env": {
        "ALIENVAULT_CLIENT_ID": "your_client_id",
        "ALIENVAULT_CLIENT_SECRET": "your_client_secret",
        "ALIENVAULT_SUBDOMAIN": "your_subdomain",
        "ALIENVAULT_ACCOUNT_NAME": "Default"
      }
    }
  }
}

重启 Claude Desktop → 查看 🔌 图标，确认 MCP 服务已连接。

Claude Code（CLI）

添加到 ~/.config/claude-code/config.json：

{
  "mcpServers": {
    "usm-anywhere": {
      "command": "node",
      "args": ["/path/to/anywhere-mcp-server/dist/index.js"],
      "env": {
        "ALIENVAULT_CLIENT_ID": "your_client_id",
        "ALIENVAULT_CLIENT_SECRET": "your_client_secret",
        "ALIENVAULT_SUBDOMAIN": "your_subdomain",
        "ALIENVAULT_ACCOUNT_NAME": "Default"
      }
    }
  }
}

Cline（VS Code 扩展）

添加到 VS Code 设置（JSON）：

{
  "cline.mcpServers": {
    "usm-anywhere": {
      "command": "node",
      "args": ["/path/to/anywhere-mcp-server/dist/index.js"],
      "env": {
        "ALIENVAULT_CLIENT_ID": "your_client_id",
        "ALIENVAULT_CLIENT_SECRET": "your_client_secret",
        "ALIENVAULT_SUBDOMAIN": "your_subdomain",
        "ALIENVAULT_ACCOUNT_NAME": "Default"
      }
    }
  }
}

Cursor IDE

在项目中创建 .cursor/mcp.json：

{
  "mcpServers": {
    "usm-anywhere": {
      "command": "node",
      "args": ["/path/to/anywhere-mcp-server/dist/index.js"],
      "cwd": "/path/to/anywhere-mcp-server",
      "env": {
        "ALIENVAULT_CLIENT_ID": "your_client_id",
        "ALIENVAULT_CLIENT_SECRET": "your_client_secret",
        "ALIENVAULT_SUBDOMAIN": "your_subdomain",
        "ALIENVAULT_ACCOUNT_NAME": "Default"
      }
    }
  }
}

📖 更多集成方式（Zed Editor、ChatGPT、通用 MCP）请参阅 INTEGRATION_GUIDE.md

---

使用示例

集成后，可以使用自然语言向 AI 助手提问：

安全分析

"Show me all critical alarms from the last 24 hours"
"Find failed login attempts from non-US countries"
"Detect potential brute force attacks in the last hour"
"Look for DNS queries longer than 40 characters (tunneling detection)"

调查管理

"Create a critical investigation for the SQL injection attempts in alarm abc-123"
"Show me all open investigations assigned to the security team"
"Add a note to investigation xyz-789 about remediation steps taken"
"Update investigation xyz-789 to resolved status"

高级查询

"Execute SQL query to find lateral movement in network traffic"
"Create PPL pipeline to analyze user behavior anomalies"
"Run the port scanning detection query from the security guide"
"Show me off-hours data transfers larger than 10MB"

威胁情报

"Search OTX for threat intelligence about domain malicious.com"
"Get indicator information for IP address 1.2.3.4"
"Show me recent pulses about ransomware"

---

配置

必需的环境变量

# USM Anywhere API v2.0 (Required)
ALIENVAULT_CLIENT_ID=your_client_id
ALIENVAULT_CLIENT_SECRET=your_client_secret
ALIENVAULT_SUBDOMAIN=your_subdomain

# Account Name (Required for queries)
ALIENVAULT_ACCOUNT_NAME=Default

# Legacy OTX API (Optional)
ALIENVAULT_OTX_API_KEY=your_otx_key

获取凭据：

1. USM Anywhere：登录 → Admin → Settings → API Credentials
2. OTX API 密钥：访问 https://otx.alienvault.com/api

重要说明：

• ALIENVAULT_SUBDOMAIN：仅填写子域名（例如，yourorg，而不是 yourorg.alienvault.cloud）
• ALIENVAULT_ACCOUNT_NAME：向 USM 管理员询问正确的账户名称
• 切勿将 .env 文件提交到版本控制中（已列入 .gitignore）

---

文档

核心文档

• QUICK_START.md - 5 分钟快速入门指南
• INTEGRATION_GUIDE.md - 适用于所有平台的完整集成指南
• DISCLAIMER.md - ⚠️ 法律条款与责任（使用前请阅读）
• CLAUDE.md - 面向 AI 助手和开发者的说明

查询文档

• QueryLanguage/advanced-sql-security-guide.md - 15+ 条 SQL 安全查询
• QueryLanguage/ppl-security-workflows.md - 12+ 个 PPL 流水线示例
• QueryLanguage/basicsql.md - SQL 基础知识和字段参考
• QueryLanguage/pplbasic.md - PPL 基础知识和命令

其他资源

• TO_FUTURE_DEVELOPERS.md - 跨越时空的理念与寄语 📜
• RELEASE_NOTES.md - Version 3.0.0 更新日志
• LICENSE - GNU GPL v3.0 完整文本

---

故障排除

连接问题

错误：身份验证失败

# Verify credentials
node test-connection.js

# Check .env file format
cat .env | grep ALIENVAULT

错误：未返回数据

• 确认 ALIENVAULT_ACCOUNT_NAME 正确
• 检查 USM Anywhere 中的用户权限
• 确保账户有权访问数据

MCP 服务问题

错误：spawn EACCES（权限被拒绝）

# Make server executable
chmod +x dist/index.js

# Verify permissions
ls -la dist/index.js
# Should show: -rwxr-xr-x

未检测到 MCP 服务

• 在 MCP 配置中使用绝对路径
• 重新构建项目：npm run build
• 检查 MCP 客户端日志中的错误

查询问题

500 内部服务器错误

• 确保账户名称正确
• 在查询中指定时间范围（默认值为 24h）
• 确认字段名称与数据架构一致

PPL 查询失败

• 已知问题：PPL 存在 JSON 编码问题
• 建议：在生产环境中使用 SQL 查询
• PPL 语法验证可正常工作，但执行可能会失败

---

开发

命令

# Build project
npm run build

# Development mode
npm run dev

# Run tests
npm test

# Clean build files
npm run clean

# Lint/typecheck
npm run lint

项目结构

anywhere-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── services/
│   │   └── alienvault.ts     # API service layer
│   ├── handlers/
│   │   └── tools.ts          # MCP tool handlers
│   └── types/
│       └── index.ts          # TypeScript types & Zod schemas
├── QueryLanguage/            # Query documentation
├── examples/                 # Configuration examples
├── dist/                     # Compiled output
└── test-connection.js        # Connection test script

---

支持与贡献

获取帮助

• GitHub Issues：https://github.com/javierb507/anywhere-mcp-server/issues
• 电子邮件：[email protected]
• 文档：参见 /QueryLanguage 和 /examples 目录

贡献

欢迎贡献！请按以下步骤操作：

1. Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 进行修改
4. 根据需要添加测试
5. 提交（git commit -m 'Add amazing feature'）
6. 推送（git push origin feature/amazing-feature）
7. 发起 Pull Request

注意：提交贡献即表示您同意根据 GNU GPL v3.0 授权您的贡献。

---

许可证与致谢

许可证

本项目根据 GNU General Public License v3.0 授权，详见 LICENSE 文件。

要点：

• ✅ 可免费使用、修改和分发
• ✅ 源代码必须保持开源
• ✅ 必须记录所做更改
• ✅ 衍生作品必须使用相同许可证
• ❌ 不提供任何担保
• ❌ 作者不对损害承担责任

作者

Javier Ballesteros

• 📧 电子邮件：[email protected]
• 💻 GitHub：@javierb507
• 🔗 LinkedIn：Javier Ballesteros

致谢

• LevelBlue - 提供 USM Anywhere API（docs.levelblue.com）
• AlienVault - 提供 OTX API（otx.alienvault.com）
• Anthropic - 提供 Model Context Protocol 规范
• 开源社区 - 提供贡献和反馈

商标

LevelBlue®、USM Anywhere®、AlienVault® 和 OTX® 均为其各自所有者的注册商标。本项目与这些公司无关，也未获得其认可。

---

官方文档链接

• LevelBlue USM Anywhere：https://docs.levelblue.com/documentation/usm-anywhere
• USM Anywhere API 参考：https://cybersecurity.att.com/documentation/api/usm-anywhere-apis.htm
• AlienVault OTX 门户：https://otx.alienvault.com/
• Model Context Protocol：https://modelcontextprotocol.io

---

⚠️ 重要提醒：这不是 LevelBlue 的官方产品。使用前请阅读 DISCLAIMER.md。请务必先在非生产环境中进行测试。