Panther MCP Server

Panther MCP 服务

Panther 的 Model Context Protocol（MCP）服务提供以下功能：

1. 在 IDE 中编写和调优检测规则
2. 使用自然语言交互式查询安全日志
3. 对一个或多个警报进行分类、评论和解决

可用工具

警报

工具名称	描述	示例提示词
add_alert_comment	为 Panther 警报添加评论	"为警报 abc123 添加评论“看起来问题很严重”"
start_ai_alert_triage	为 Panther 警报启动 AI 分类分析，并提供智能洞察和建议	"为警报 abc123 启动 AI 分类" / "为警报 def456 生成详细的 AI 分析"
get_ai_alert_triage_summary	获取之前为指定警报生成的最新 AI 分类摘要	"获取警报 abc123 的 AI 分类摘要" / "显示警报 def456 的 AI 分析"
get_alert	获取指定警报的详细信息	"警报 8def456 的状态是什么？"
get_alert_events	获取指定警报的少量事件样本	"显示与警报 8def456 相关的事件"
list_alerts	使用全面的筛选选项（日期范围、严重程度、状态等）列出警报	"显示过去 24 小时内所有高严重程度的警报"
bulk_update_alerts	批量更新多个警报的状态、受理人和／或评论	"将警报 abc123、def456 和 ghi789 更新为已解决状态，并添加评论“已修复”"
update_alert_assignee	更新一个或多个警报的受理人	"将警报 abc123 和 def456 分配给 John"
update_alert_status	更新一个或多个警报的状态	"将警报 abc123 和 def456 标记为已解决"
list_alert_comments	列出指定警报的所有评论	"显示警报 abc123 的所有评论"

数据湖

工具名称	描述	示例提示词
query_data_lake	对 Panther 的数据湖执行 SQL 查询并同步返回结果	"查询过去一天内失败登录尝试的 AWS CloudTrail 日志"
get_table_schema	获取指定表的架构信息	"显示 AWS_CLOUDTRAIL 表的架构"
list_databases	列出 Panther 中所有可用的数据湖数据库	"列出所有可用的数据库"
list_database_tables	列出 Panther 数据湖中指定数据库的所有可用表	"panther_logs 数据库中有哪些表"
get_alert_event_stats	汇总多个警报的事件数据，分析其模式和关联关系，并生成基于时间的统计信息	"显示警报 abc123 和 def456 事件中的模式"

定时查询

工具名称	描述	示例提示词
list_scheduled_queries	列出所有定时查询，支持分页	"显示所有定时查询" / "列出前 25 个定时查询"
get_scheduled_query	按 ID 获取指定定时查询的详细信息	"获取定时查询“weekly-security-report”的详细信息"

数据源

| 工具名称 | 描述 | 示例提示词 | |-----------|-------------|---------------| | `list_log_sources` | 列出日志源，并支持按健康状态、日志类型和集成类型筛选 | “显示所有健康的 S3 日志源” | | `get_http_log_source` | 根据 ID 获取特定 HTTP 日志源的详细信息 | “显示 HTTP 源 ‘webhook-collector-123’ 的配置” |

检测

工具名称	描述	示例提示词
list_detections	列出 Panther 中的检测，并提供全面的筛选支持。支持多种检测类型，还可按名称、状态、严重性、标签、日志类型、资源类型、输出 ID（目标）等筛选。返回每项检测的 outputIDs，显示已配置的告警目标	“显示所有已启用且严重性为 HIGH、带有 ‘AWS’ 标签的规则” / “列出适用于 S3 资源的已禁用策略” / “查找所有 outputID 为 ‘prod-slack’ 的规则” / “显示向生产目标发送告警的检测”
get_detection	获取特定检测的详细信息，包括检测正文和测试。接受包含一种检测类型的列表：["rules"]、["scheduled_rules"]、["simple_rules"] 或 ["policies"]	“获取规则 ID abc123 的详细信息” / “获取策略 ID AWS.S3.Bucket.PublicReadACP 的详细信息”
disable_detection	将 enabled 设为 false，以禁用检测。支持 rules、scheduled_rules、simple_rules 和 policies	“禁用规则 abc123” / “禁用策略 AWS.S3.Bucket.PublicReadACP”

全局辅助函数

工具名称	描述	示例提示词
list_global_helpers	列出全局辅助函数，并提供全面的筛选选项（名称搜索、创建者、修改者）	“显示名称中包含 ‘aws’ 的全局辅助函数”
get_global_helper	获取特定全局辅助函数的详细信息和完整 Python 代码	“获取全局辅助函数 ‘AWSUtilities’ 的完整代码”

数据模型

工具名称	描述	示例提示词
list_data_models	列出用于控制规则中 UDM 映射的数据模型	“显示所有用于日志解析的数据模型”
get_data_model	获取特定数据模型的详细信息	“获取 ‘AWS_CloudTrail’ 数据模型的完整详情”

架构

工具名称	描述	示例提示词
list_log_type_schemas	列出可用的日志类型架构，并支持筛选	“显示所有与 AWS 相关的架构”
get_log_type_schema_details	获取特定日志类型架构的详细信息	“获取 AWS.CloudTrail 架构的完整详情”

指标

工具名称	描述	示例提示词
get_rule_alert_metrics	获取按规则分组的告警指标	“显示告警数量排名前 10 的规则”
get_severity_alert_metrics	获取按严重性分组的告警指标	“显示过去一周按严重性划分的告警数量”
get_bytes_processed_metrics	按日志类型和来源获取数据摄取指标	“显示按日志类型划分的数据摄取量”

用户与访问管理

| 工具名称 | 描述 | 示例提示词 | |-----------|-------------|---------------| | `list_users` | 列出所有 Panther 用户账户，支持分页 | “显示所有活跃的 Panther 用户” / “列出前 25 个用户” | | `get_user` | 获取特定用户的详细信息 | “获取用户 ID '' 的详细信息” | | `get_permissions` | 获取当前用户的权限 | “我有哪些权限？” | | `list_roles` | 列出所有角色，并提供筛选选项（按名称搜索、角色 ID、排序方向） | “显示名称中包含 'Admin' 的所有角色” | | `get_role` | 获取特定角色的详细信息，包括权限 | “获取 'Admin' 角色的完整详细信息” |

Panther 配置

按照以下步骤配置 API 凭据和环境。

1. 在 Panther 中创建 API 令牌：

   • 前往 Settings（齿轮图标）→ API Tokens

   • 创建具有以下权限的新令牌（建议先采用只读方式）：

   • 查看所需权限

     

2. 安全存储生成的令牌（例如，使用 1Password）

3. 从浏览器复制 Panther 实例 URL（例如，https://YOUR-PANTHER-INSTANCE.domain）

   • 注意：必须包含 https://

MCP 服务安装

选择以下一种安装方式：

Docker（推荐）

最简单的入门方式是使用我们预构建的 Docker 镜像：

{
  "mcpServers": {
    "mcp-panther": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "-e", "PANTHER_INSTANCE_URL",
        "-e", "PANTHER_API_TOKEN",
        "--rm",
        "ghcr.io/panther-labs/mcp-panther"
      ],
      "env": {
        "PANTHER_INSTANCE_URL": "https://YOUR-PANTHER-INSTANCE.domain",
        "PANTHER_API_TOKEN": "YOUR-API-KEY"
      }
    }
  }
}

**固定版本：**为确保生产环境稳定，请固定到特定版本标签：

"ghcr.io/panther-labs/mcp-panther:v2.2.0"

可在 GitHub Container Registry 查看可用标签。

UVX

对于 Python 用户，可以使用 uvx 直接从 PyPI 运行：

1. 安装 UV

2. 配置 MCP 客户端：

{
  "mcpServers": {
    "mcp-panther": {
      "command": "uvx",
      "args": ["mcp-panther"],
      "env": {
        "PANTHER_INSTANCE_URL": "https://YOUR-PANTHER-INSTANCE.domain",
        "PANTHER_API_TOKEN": "YOUR-PANTHER-API-TOKEN"
      }
    }
  }
}

**固定版本：**为确保生产环境稳定，请固定到特定版本：

"args": ["mcp-panther==2.2.0"]

可在 PyPI 查看可用版本。

MCP 客户端设置

Cursor

按照此处的说明配置项目级或全局 MCP 配置。非常重要：请勿将此文件提交到版本控制中。

配置完成后，前往 Cursor Settings > MCP 查看正在运行的服务：

提示：

• 使用 @ 符号并输入特定目录，明确指定要在哪个位置生成新规则。
• 为了让工具使用更加可靠，请尝试选择特定模型，例如 Claude 3.7 Sonnet。
• 如果 MCP 客户端无法找到 Panther MCP 服务提供的任何工具，请尝试重启客户端并确认 MCP 服务正在运行。在 Cursor 中，刷新 MCP 服务并开始新的聊天。

Claude Code

Claude Code 是 Anthropic 官方的命令行工具。使用 Docker 添加 Panther MCP 服务：

claude mcp add-json panther '{
  "command": "docker",
  "args": [
    "run",
    "-i",
    "-e", "PANTHER_INSTANCE_URL",
    "-e", "PANTHER_API_TOKEN",
    "--rm",
    "ghcr.io/panther-labs/mcp-panther"
  ],
  "env": {
    "PANTHER_INSTANCE_URL": "https://YOUR-PANTHER-INSTANCE.domain",
    "PANTHER_API_TOKEN": "YOUR-API-TOKEN"
  }
}'

或者，使用 UVX：

claude mcp add-json panther '{
  "command": "uvx",
  "args": ["mcp-panther"],
  "env": {
    "PANTHER_INSTANCE_URL": "https://YOUR-PANTHER-INSTANCE.domain",
    "PANTHER_API_TOKEN": "YOUR-API-TOKEN"
  }
}'

添加后，验证服务是否已配置：

claude mcp list

Claude Desktop

要与 Claude Desktop 配合使用，请手动配置 claude_desktop_config.json：

1. 打开 Claude Desktop 设置，前往 Developer 标签页
2. 点击“Edit Config”打开配置文件
3. 添加以下配置：

{
  "mcpServers": {
    "mcp-panther": {
      "command": "uvx",
      "args": ["mcp-panther"],
      "env": {
        "PANTHER_INSTANCE_URL": "https://YOUR-PANTHER-INSTANCE.domain",
        "PANTHER_API_TOKEN": "YOUR-PANTHER-API-TOKEN"
      }
    }
  }
}

4. 保存文件并重启 Claude Desktop

如果遇到问题，请尝试此处的故障排除步骤。

Goose CLI

与 Goose CLI 配合使用，Goose CLI 是 Block 的开源 AI Agent：

# Start Goose with the MCP server
goose session --with-extension "uvx mcp-panther"

Goose Desktop

与 Block 的开源 AI Agent Goose Desktop 搭配使用：

在“Extensions” -> “Add custom extension”中提供配置信息。

运行服务

MCP Panther 服务支持多种传输协议：

STDIO（默认）

用于本地开发和 MCP 客户端集成：

uv run python -m mcp_panther.server

Streamable HTTP

如需将其作为持久 Web 服务运行，请使用 HTTP 传输。适用于：

• 长时间运行的服务部署
• 多个客户端连接到同一服务
• 通过持续监控日志进行测试和调试

使用 Docker Run（后台运行）

docker run -d \
  --name panther-mcp-server \
  -p 8000:8000 \
  -e PANTHER_INSTANCE_URL=https://YOUR-PANTHER-INSTANCE.domain \
  -e PANTHER_API_TOKEN=YOUR-API-TOKEN \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  -e LOG_LEVEL=INFO \
  --restart unless-stopped \
  ghcr.io/panther-labs/mcp-panther:latest

使用 Docker Compose（推荐）

创建一个 docker-compose.yml 文件：

services:
  panther-mcp:
    image: ghcr.io/panther-labs/mcp-panther:latest
    container_name: panther-mcp-server
    ports:
      - "8000:8000"
    environment:
      - PANTHER_INSTANCE_URL=https://YOUR-PANTHER-INSTANCE.domain
      - PANTHER_API_TOKEN=YOUR-API-TOKEN
      - MCP_TRANSPORT=streamable-http
      - MCP_HOST=0.0.0.0
      - MCP_PORT=8000
      - LOG_LEVEL=INFO
    restart: unless-stopped

启动服务：

# Start in detached mode
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the server
docker-compose down

将 Claude Code 连接到 HTTP 服务

**重要：**服务运行在 HTTP（而非 HTTPS）上。请使用 http:// URL 配置 Claude Code：

# Add the HTTP endpoint (note: http:// not https://)
claude mcp add-json panther-http '{
  "url": "http://localhost:8000/mcp"
}'

# Verify configuration
claude mcp list

测试连接

# Test the HTTP endpoint
curl http://localhost:8000/mcp

# View server logs
docker logs -f panther-mcp-server
# Or with docker-compose:
docker-compose logs -f

你也可以使用 FastMCP 客户端进行测试：

import asyncio
from fastmcp import Client

async def test_connection():
    async with Client("http://localhost:8000/mcp") as client:
        tools = await client.list_tools()
        print(f"Available tools: {len(tools)}")

asyncio.run(test_connection())

Streamable HTTP 故障排除

端口已被占用

如果看到 Bind for 0.0.0.0:8000 failed: port is already allocated：

# Check what's using the port
lsof -i :8000

# Stop conflicting containers
docker ps | grep panther
docker stop <container-id>

# Or use a different port via MCP_PORT environment variable:
-e MCP_PORT=8080
# Then connect to: http://localhost:8080/mcp

无效 HTTP 请求警告

如果在日志中看到 WARNING: Invalid HTTP request received，通常意味着：

• Claude Code 正尝试通过 HTTPS 而非 HTTP 连接
• 检查配置使用的是 http:// 而非 https://
• 使用 claude mcp list 验证

环境变量

• MCP_TRANSPORT：设置传输类型（stdio 或 streamable-http）
• MCP_PORT：HTTP 传输端口（默认值：3000）
• MCP_HOST：HTTP 传输主机（默认值：127.0.0.1）
• MCP_LOG_FILE：日志文件路径（可选）
• MCP_MAX_RESULT_SIZE_CHARS：为每个工具声明 _meta["anthropic/maxResultSizeChars"]，使 Claude Code 将最多包含此字符数的文本结果直接内联返回，而不是保存到文件（可选；Claude Code 最多接受 500,000）

安全最佳实践

我们强烈建议遵循以下 MCP 安全最佳实践：

• **对 Panther API 令牌严格遵循最小权限原则。**将令牌权限范围限制为所需的最小权限，并将其绑定到 IP 允许列表或 CIDR 范围，以便令牌在泄露时无法被利用。按建议的周期（例如每 30d）轮换凭据。
• **在安全隔离的沙箱（例如 Docker）中托管 MCP 服务，并使用只读挂载。**这样可以将任何安全漏洞的影响范围限制在最小程度。
• **监控 Panther 凭据访问并检测异常。**编写一条 Panther 规则！
• **仅运行可信且经过官方签名的 MCP 服务。**运行前验证数字签名或校验和，审查工具代码，并避免使用非官方发布者提供的社区工具。

故障排除

查看服务日志以获取详细错误信息：tail -n 20 -F ~/Library/Logs/Claude/mcp*.log。下方列出了常见问题及解决方案。

运行工具

• 如果出现 {"success": false, "message": "Failed to [action]: Request failed (HTTP 403): {\"error\": \"forbidden\"}"} 错误，可能是你的 API 令牌缺少该工具所需的特定权限。
• 确保 Panther 实例 URL 设置正确。你可以在 MCP 客户端的 config://panther 资源中查看该 URL。

参与贡献

欢迎参与贡献，帮助改进 MCP-Panther！你可以通过以下方式提供帮助：

1. 报告问题：针对任何错误或功能请求提交 issue
2. 提交 Pull Request：Fork 仓库并提交修复错误或添加新功能的 PR
3. 改进文档：帮助我们让文档更加清晰、全面
4. 分享使用案例：告诉我们你如何使用 MCP-Panther，以及有哪些改进建议

请确保你的贡献符合我们的编码规范，并包含适当的测试和文档。

贡献者

本项目的存在离不开所有贡献者的付出。特别感谢来自 Block 的 Tomasz Tchorz 和 Glenn Edwards，他们在推动 MCP-Panther 作为与 Panther 联合开展的开源项目启动方面发挥了核心作用。

请参阅 CONTRIBUTORS.md，查看完整的贡献者名单。

许可证

本项目采用 Apache License 2.0 许可，详情请参阅 LICENSE 文件。