Threat Byte MCP

ThreatByte MCP

##

ThreatByte MCP是一个故意易受攻击的基于MCP的案例管理web应用程序。它通过服务器渲染的UI和真实的MCP服务器反映了现实的SOC分析师工作流程。这 MCP工具故意易受攻击 用于培训和演示。

\[！注意\] 仅用于受控环境中的教育用途。

特性

• 安全的网络身份验证（注册/登录/注销）
• 案例管理UI（创建/列出/查看案例）
• 与案件相关的注释和附件
• 通过MCP工具进行指标搜索和代理工作流程
• 使用基于模式的工具注册表进行代理定制

MCP服务器（SDK、JSON-RPC）

ThreatByte MCP是一种拆分架构：

• SOC Web App（客户端/UI）在端口5001上运行。
• MCP服务器（工具+代理）使用官方的MCP Python SDK（FastMCP）在端口5002上运行。

MCP服务器在以下位置公开JSON-RPC POST http://localhost:5002/mcp （流式HTTP）。web UI通过服务器端代理调用MCP服务器，以保持身份验证与SOC会话的一致性；代理通过SSE将代理响应流式传输到浏览器。一个样本 mcp.json 清单包含在回购根目录中。 所有直接MCP呼叫必须包括 MCP-Protocol-Version: 2025-11-25 和 Accept: application/json, text/event-stream.

架构（简化）：

          Browser
             |
             v
    +------------------+        X-TBMCP-Token + X-TBMCP-User        +-------------------+
    |  SOC Web App     |  ---------------------------------------> |     MCP Server     |
    |  (Flask, :5001)  |           /mcp-proxy (server-side)         |  (FastMCP, :5002)  |
    +------------------+                                            +-------------------+
             |                                                                  |
             v                                                                  v
         SQLite DB                                                      Tool registry
                                                                       Agent + tool handlers

架构（详细）：

Mode A (Web UI as HTTP MCP client)
  Browser (Analyst)
    |
    v
  SOC Web App (Flask, :5001)
    - Auth session (cookie)
    - Dashboards, cases, notes, files UI
    - POST /mcp-proxy forwards JSON-RPC
    - Injects X-TBMCP-Token + X-TBMCP-User to the MCP server
    |
    +--> SQLite DB (users/cases/notes/files/indicators)
    +--> Uploads (app/uploads)
    |
    v
  MCP Server (FastMCP, :5002)
    - /mcp JSON-RPC (Streamable HTTP)
    - Tool registry (mcp_tools)
    - Agent runtime + tool handlers
    - Persistence: agent_contexts, agent_logs, mcp_audit_logs

Mode B (Local agent/IDE as stdio MCP client)
  Local Agent / IDE (e.g., Claude Desktop) spawns:
    python run_mcp_server.py --stdio
  and communicates via stdin/stdout JSON-RPC (stdio transport).

图表： ThreatByte MCP架构图

Web应用程序与MCP服务器之间的MCP认证

web应用程序使用以下标头代理MCP调用：

• X-TBMCP-Token：来自的共享秘密 TBMCP_MCP_SERVER_TOKEN （在两台服务器上配置）。
• X-TBMCP-User：来自经过身份验证的SOC会话的当前用户id。

直接MCP调用需要相同的标头。

支持的工具：

• cases.create
• cases.list
• cases.list_all
• cases.get
• cases.rename
• cases.set_status
• cases.delete
• notes.create
• notes.list
• notes.update
• notes.delete
• files.upload （base64）
• files.list
• files.get （base64）
• files.read_path
• indicators.search
• agent.summarize_case
• agent.run_task
• tools.registry.list
• tools.builtin.list
• tools.registry.register
• tools.registry.delete

脆弱性主题（以培训为重点）

以下缺点是 故意出席 用于教学：

• 对象级授权中断（案例/注释/文件，list_all）
• 存储的XSS（笔记呈现为受信任的HTML）
• 指标搜索中的SQL注入
• 代理任务运行器中的快速注入
• 令牌管理不善和秘密暴露（提示、持久化上下文、完整日志中的硬编码令牌）
• 通过模式驱动的工具注册表覆盖导致工具中毒（MCP03）
• 过度信任客户端上下文（MCP标头身份欺骗）
• 通过读取任意文件 files.read_path
• 跨用户文件覆盖（共享文件名命名空间）

本地运行

cd ThreatByte-MCP
python -m venv venv_threatbyte_mcp
source venv_threatbyte_mcp/bin/activate
pip install -r requirements.txt
python db/create_db_tables.py
python run_mcp_server.py --http
python run.py

打开： http://localhost:5001

MCP服务器： http://localhost:5002/mcp

HTTP与stdio

此存储库提供两种MCP服务器传输：

• HTTP（流式HTTP）ThreatByte web应用程序使用什么。web应用程序是 仅限HTTP MCP客户端，通过服务器端 /mcp-proxy 货运代理。
• 标准：对于外部MCP客户端（例如IDE/代理客户端） 产卵 MCP服务器，并通过stdin/stdout进行通信。

示例：

# HTTP (required for the web app)
python run_mcp_server.py --http --host 127.0.0.1 --port 5002

# stdio (for MCP clients that support stdio transport; the web app will NOT work with this)
# In stdio mode there are no HTTP headers, so the server reads user context from env vars.
# Note: stdio mode runs the MCP server on AnyIO's Trio backend; ensure `trio>=0.28.0` is installed.
export TBMCP_MCP_SERVER_TOKEN=tbmcp-mcp-token
export TBMCP_MCP_USER_ID=1
python run_mcp_server.py --stdio

Claude桌面兼容性（工具名称）

一些MCP客户端（如Claude Desktop）强制执行严格的工具名称验证(^[a-zA-Z0-9_-]{1,64}$)并将拒绝虚线工具名称，如 cases.create.

要在Claude兼容模式下运行MCP服务器，请设置：

• TBMCP_TOOL_NAME_MODE=claude

这将工具暴露为下划线名称（例如。， cases_create, tools_registry_register, files_read_path)而不是虚线名称。

有关完整的演练（Windows+WSL stdio），请参阅 Claude桌面设置.

使用Docker或Podman运行

存储库包括 Dockerfile 以及初始化数据库并在一个容器中运行这两个服务的启动脚本：

• SOC Web应用程序已打开 :5001
• MCP服务器已打开 :5002

塑造形象：

# Docker
docker build -t threatbyte-mcp .

# Podman
podman build -t threatbyte-mcp .

运行容器：

# Docker
docker run --rm -p 5001:5001 -p 5002:5002 threatbyte-mcp

# Podman
podman run --rm -p 5001:5001 -p 5002:5002 threatbyte-mcp

使用可选环境变量运行：

# Docker
docker run --rm -p 5001:5001 -p 5002:5002 \
  -e TBMCP_MCP_SERVER_TOKEN=tbmcp-mcp-token \
  -e OPENAI_API_KEY=your_api_key \
  -e TBMCP_OPENAI_MODEL=gpt-4o-mini \
  threatbyte-mcp

# Podman
podman run --rm -p 5001:5001 -p 5002:5002 \
  -e TBMCP_MCP_SERVER_TOKEN=tbmcp-mcp-token \
  -e OPENAI_API_KEY=your_api_key \
  -e TBMCP_OPENAI_MODEL=gpt-4o-mini \
  threatbyte-mcp

在运行之间持久化SQLite数据（可选）：

# Docker
docker run --rm -p 5001:5001 -p 5002:5002 \
  -v "$(pwd)/db:/app/db" \
  -v "$(pwd)/app/uploads:/app/app/uploads" \
  threatbyte-mcp

# Podman
podman run --rm -p 5001:5001 -p 5002:5002 \
  -v "$(pwd)/db:/app/db:Z" \
  -v "$(pwd)/app/uploads:/app/app/uploads:Z" \
  threatbyte-mcp

填充样本数据

python db/populate_db.py --users 8 --cases 20 --notes 40 --files 20

这会创建随机用户、案例、注释和文件工件。所有用户密码均为 Password123!.

LLM集成（代理响应所需）

代理任务终结点需要真正的LLM。如果没有API密钥，代理将返回一个错误，指示它不可用。

环境变量：

• TBMCP_OPENAI_API_KEY 或 OPENAI_API_KEY
• TBMCP_OPENAI_MODEL （默认值： gpt-4o-mini)

只保留API密钥的服务器端，不要在浏览器中公开它们。

MCP服务器配置

SOC web应用程序使用共享令牌将MCP调用代理到MCP服务器。

环境变量：

• TBMCP_MCP_SERVER_URL （默认值： http://localhost:5002/mcp)
• TBMCP_MCP_SERVER_TOKEN （SOC应用程序和MCP服务器之间的共享密钥）

备注

• UI使用服务器渲染的模板。
• MCP工具暴露在 http://localhost:5002/mcp （JSON-RPC）。UI调用它们 /mcp-proxy.
• 培训有用的UI页面：

- My Cases （所有案例均归登录用户所有） - MCP Audit Logs （来自HTTP+stdio客户端的MCP工具调用的服务器端审计跟踪） - Agent Logs （内部代理运行跟踪；由填充 agent.run_task)

• 此应用程序故意不安全。不要将其部署到公共互联网。