Safebreach MCP

免责声明

这是一个实验项目，旨在展示MCP的SafeBreach功能。它没有得到SafeBreach的正式支持或验证。

SafeBreach MCP服务器

  

一个模型上下文协议（MCP）服务器，将AI代理与SafeBreach的漏洞和攻击模拟平台连接起来。通过具有专用域的多服务器架构实现自然语言查询和无缝集成。

🚀 快速开始

新团队成员

# 1. Clone and setup security tools (one-time setup)
git clone 
cd safebreach-mcp
./setup-security.sh

# 2. Configure your environment
cp .env.template .env
# Edit .env with your actual API tokens

# 3. ALWAYS launch Claude with security context
./claude-launcher.sh

🔒 安全第一发展

该项目实施了全面的安全措施，以防止API令牌泄漏：

• 自动秘密扫描 带有预提交挂钩
• Claude安全上下文 确保人工智能了解最佳实践
• 基于模板的配置 防止意外犯罪
• 多层验证 在CI/CD管道中

📚 看 团队_工作流.md 获取完整的开发指南。

目录

• 概述
• 特性
• 建筑
• 配置
• 安装
• 外部连接支持
• 用法

- 在Claude Desktop注册 - Windows配置

• API 参考
• 测试
• 发展
• 故障排除
• 安全注意事项
• 贡献

概述

此MCP服务器使AI代理能够与SafeBreach管理控制台交互，以：

• 检索模拟器信息和状态
• 访问测试执行历史和结果
• 查询模拟细节和安全控制有效性
• 检索安全控制事件和SIEM日志
• 访问与渗透测试报告类似的测试结果数据
• 分析攻击模拟结果和根本原因分析
• 在Breach Studio中创建、验证和管理自定义攻击

特性

🏗️ 建筑

• 多服务器架构：不同域的专用服务器（配置、数据、实用程序、剧本、工作室）
• 域名分离：通过独立扩展功能明确区分关注点
• 水平扩展：每台服务器都可以根据需求独立扩展

🔒 安全与连接

• 安全第一设计：本地主机仅默认使用承载令牌身份验证进行外部访问
• 外部连接支持：可选的具有HTTP授权安全性的外部网络访问
• 苏格兰和南方能源公司运输：用于实时通信的服务器发送事件传输

📊 数据管理

• 模拟器管理：查询SafeBreach模拟器、其状态和详细配置
• 测试历史：使用高级筛选功能检索分页的测试执行历史记录
• 仿真分析：访问详细的模拟结果，包括安全控制交互
• Playbook攻击：浏览和分析SafeBreach的全面攻击知识库
• Breach工作室：使用双脚本支持创建、验证和管理自定义攻击代码

🌐 整合

• 多环境支持：连接到多个SafeBreach环境（暂存、开发、生产）
• 选择加入缓存：可配置的本地缓存（默认禁用），以防止无限内存增长

建筑

多服务器体系结构（推荐）

核心共享组件：

• safebreach_mcp_core/：所有服务器的共享组件

- safebreach_auth.py：集中身份验证 - safebreach_base.py：所有MCP服务器的基类 - datetime_utils.py：共享日期时间实用程序 - environments_metadata.py：支持的SafeBreach环境的配置（通过环境变量支持单租户模式） - secret_utils.py：AWS SSM参数存储和Secrets Manager集成

专用服务器：

• safebreach_mcp_config/：配置服务器（端口8000）-模拟器操作
• safebreach_mcp_data/：数据服务器（端口8001）-测试和模拟数据
• safebreach_mcp_utilities/：实用程序服务器（端口8002）-日期时间函数
• safebreach_mcp_playbook/：Playbook服务器（端口8003）-Playbook攻击操作
• safebreach_mcp_studio/：Studio服务器（端口8004）-违反Studio代码验证和攻击管理

多服务器启动器：

• start_all_servers.py：并发多服务器启动器

附加组件：

• mcp_server_bug_423_hotfix.py：MCP初始化修复

工具注释

每个工具都附带MCP ToolAnnotations 因此客户端可以决定是否在呼叫前提示用户。

添加工具时，进行设置 readOnlyHint=True 除非它调用a 改变国家的API；如果效果无法逆转 客户端，也设置 destructiveHint=True.

配置

SafeBreach MCP服务器的配置包括：

• 指定哪些SafeBreach控制台在MCP的范围内。对于每个SafeBreach控制台，提供“url”、“account”和获取API密钥的提供程序（方法）
• 通过环境变量、AWS SSM或AWS机密管理器向MCP服务器提供API密钥

先决条件

对于所有用户（运行MCP服务器）：

• uv 包管理器（自动处理Python安装）
• SafeBreach API令牌（请参阅 API令牌 存储选项部分）

对于基于AWS的令牌存储（可选）：

• 为SSM参数存储或Secrets Manager访问配置的AWS凭据
• *注意：您还可以在没有AWS的情况下使用环境变量进行令牌存储*

仅适用于当地发展：

• Python 3.12+（如果不使用 uv 用于依赖关系管理）
• Git（用于克隆存储库）

安全漏洞环境

MCP服务器支持多种指定SafeBreach环境配置的方法：

方法1:JSON文件（SAFEBREACH_ENVS_File） 将环境变量设置为指向配置JSON文件：

export SAFEBREACH_ENVS_FILE=/path/to/more_envs.json

方法2:JSON字符串（SAFEBREACH_LOCAL_ENV）✨ 新 在环境变量中直接以JSON字符串形式提供配置：

export SAFEBREACH_LOCAL_ENV='{"my-console": {"url": "my-console.safebreach.com", "account": "1234567890", "secret_config": {"provider": "env_var", "parameter_name": "my_console_apitoken"}}}'

配置优先级：

1. 硬编码环境（基础）
2. SAFEBREACH_ENVS_FILE （延伸底座）
3. SAFEBREACH_LOCAL_ENV （扩展和覆盖）

基本JSON配置：

{
    "console-friendly-name": {
        "url": "my-console.safebreach.com",
        "account": "1234567890",
        "secret_config": {
            "provider": "env_var",
            "parameter_name": "my-console-apitoken"
        }
    }
}

通过每个服务URL增强配置✨ 新

{
    "microservices-console": {
        "url": "default.safebreach.com",
        "urls": {
            "config": "config-api.safebreach.com",
            "data": "data-api.safebreach.com",
            "playbook": "playbook-api.safebreach.com",
            "siem": "siem-api.safebreach.com"
        },
        "account": "1234567890",
        "secret_config": {
            "provider": "env_var",
            "parameter_name": "microservices_console_apitoken"
        }
    }
}

URL分辨率：

• 中的服务特定URL urls 覆盖默认值 url
• 没有特定URL的服务将回退到默认值 url
• 支持HTTP和HTTPS自动 https:// 加前缀

单租户配置（安全漏洞内部使用）

对于在SafeBreach管理控制台中的部署，MCP服务器使用环境变量支持单租户模式。这允许服务器连接到本地SafeBreach API，而不需要外部环境元数据配置。

环境变量：

# API endpoints for single-tenant deployment
export DATA_URL="http://localhost:3400"          # Data API endpoint
export CONFIG_URL="http://localhost:3401"        # Config API endpoint  
export SIEM_URL="http://localhost:3402"          # SIEM API endpoint
export ACCOUNT_ID="your-account-id"              # SafeBreach account ID

# API authentication
export console_name_apitoken="your-api-token"    # API token for the console

它是如何工作的：

• 设置环境变量时，服务器使用本地API端点
• 当未设置环境变量时，服务器将使用环境元数据回退到多租户模式
• 这使得在SafeBreach管理控制台中实现无缝部署成为可能

硬编码环境 在某些情况下，您可能更喜欢克隆仓库并对环境进行硬编码，以避免对环境设置的依赖。这可以通过编辑来实现 environments_metadata.py:

safebreach_envs = {
    "console-name": {
        "url": "console.safebreach.com", 
        "account": "account_id",
        "secret_config": {
            "provider": "aws_ssm",  # or "aws_secrets_manager" or "env_var"
            "parameter_name": "console-name-apitoken"
        }
    }
}

本地缓存配置

默认情况下，本地缓存为 残疾的 以防止长时间运行的会话中内存无限增长。您可以启用每个服务器的缓存，以提高性能并减少API调用：

# Enable caching for specific servers (disabled by default)
export SB_MCP_CACHE_CONFIG=true      # Config server
export SB_MCP_CACHE_DATA=true        # Data server
export SB_MCP_CACHE_PLAYBOOK=true    # Playbook server
export SB_MCP_CACHE_STUDIO=true      # Studio server

真理价值观: true, 1, yes, on 不区分大小写

何时启用缓存:

• 短期会话中，记忆增长不是问题
• 开发和测试场景
• 对同一数据进行重复查询时

何时保持缓存禁用（默认）:

• 长期运行的生产部署
• 内存受限环境
• 当数据新鲜度至关重要时

API令牌

SafeBreach API令牌可以使用三个不同的提供商存储：

AWS SSM参数存储（默认）：

aws ssm put-parameter --name "console-name-apitoken" --value "your-api-token" --type "SecureString"

2.AWS机密管理器：

aws secretsmanager create-secret --name "safebreach/console-name/api-token" --secret-string "your-api-token"

3.环境变量：

# For parameter_name "console-name-apitoken", set:
export CONSOLE_NAME_APITOKEN="your-api-token"

# Note: Dashes are automatically converted to underscores for environment variable lookup

安装

选项1：从Git直接安装（推荐）🚀

直接从存储库安装并运行MCP服务器：

远程安装的附加要求：

• 使用GitHub配置SSH密钥（推荐），或者
• 用于HTTPS身份验证的GitHub个人访问令牌
• uv 版本0.4.0+（请与 uv --version)for --from 旗帜支持

设置SSH访问GitHub：

1. 生成SSH密钥： ssh-keygen -t ed25519 -C "your_email@example.com"
2. 添加到SSH代理： ssh-add ~/.ssh/id_ed25519
3. 将公钥添加到GitHub：设置→ SSH和GPG密钥→ 新SSH密钥
4. 测试： ssh -T git@github.com

# Method 1: Install with SSH (recommended for private repos)
# Latest:
uv tool install --force git+ssh://git@github.com/SafeBreach/safebreach-mcp.git
# Specific version:
uv tool install --force git+ssh://git@github.com/SafeBreach/safebreach-mcp.git@1.1.0

# Update PATH if needed (uv will show a warning if required)
export PATH="/Users/$(whoami)/.local/bin:$PATH"  # or run: uv tool update-shell

# Run multi-server architecture (recommended)
safebreach-mcp-all-servers

# Or run individual servers
safebreach-mcp-config-server     # Port 8000
safebreach-mcp-data-server       # Port 8001
safebreach-mcp-utilities-server  # Port 8002
safebreach-mcp-playbook-server   # Port 8003
safebreach-mcp-studio-server    # Port 8004

# Method 2: Install with HTTPS authentication
# First, configure git credentials: git config credential.helper store
# Then install (git will prompt for credentials):
# Latest:
uv tool install git+https://github.com/SafeBreach/safebreach-mcp.git
# Specific version:
uv tool install git+https://github.com/SafeBreach/safebreach-mcp.git@1.1.0
safebreach-mcp-all-servers

# Method 3: Install with pip in a uv environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
# Latest:
uv pip install git+ssh://git@github.com/SafeBreach/safebreach-mcp.git
# Specific version:
uv pip install git+ssh://git@github.com/SafeBreach/safebreach-mcp.git@1.1.0
safebreach-mcp-all-servers

# Method 4: For newer uv versions (0.4.0+) with SSH
# Latest:
uv run --from git+ssh://git@github.com/SafeBreach/safebreach-mcp.git safebreach-mcp-all-servers
# Specific version:
uv run --from git+ssh://git@github.com/SafeBreach/safebreach-mcp.git@1.1.0 safebreach-mcp-all-servers

版本固定： 追加 @ 指向任何git URL以安装特定版本 （例如。， @1.1.0).看 发布 对于可用版本。

选项2：地方发展设置🛠️

1. 克隆存储库：

git clone git@github.com:SafeBreach/safebreach-mcp.git

1. 安装依赖项：

uv sync

外部连接支持

通常，MCP服务器部署在运行AI客户端应用程序的同一主机上（例如Claude Desktop）。这也是SafeBreach MCP服务器的默认运行模式。此外，SafeBreach MCP服务器支持在远程主机上运行服务器，使多个具有授权标头的客户端可以同时访问该服务器。

⚠️ 重要安全通知：应极其谨慎地使用以下部署模式。当前的授权方法是实验性的，不包含外部MCP连接的有效身份验证流。外部暴露会显著增加安全风险，只能在具有适当安全措施的受控环境中实施。

安全模型

• 默认行为：所有服务器都绑定到localhost（127.0.0.1）-无外部访问
• 外部访问：可选，需要明确配置
• 认证：外部连接需要带有Bearer令牌的HTTP授权标头
• 本地主机旁路：本地连接自动绕过身份验证
• 命令行控制：完全支持命令行参数，实现灵活部署

配置选项

环境变量：

# Global external access (all servers)
export SAFEBREACH_MCP_ALLOW_EXTERNAL=true
export SAFEBREACH_MCP_AUTH_TOKEN="your-secure-token"

# Server-specific external access
export SAFEBREACH_MCP_CONFIG_EXTERNAL=true      # Config server only
export SAFEBREACH_MCP_DATA_EXTERNAL=true        # Data server only  
export SAFEBREACH_MCP_UTILITIES_EXTERNAL=true   # Utilities server only
export SAFEBREACH_MCP_STUDIO_EXTERNAL=true      # Studio server only

# Custom bind host (default: 127.0.0.1)
export SAFEBREACH_MCP_BIND_HOST=0.0.0.0

命令行参数：

# Enable external connections for all servers
SAFEBREACH_MCP_AUTH_TOKEN="your-token" safebreach-mcp-all-servers --external

# Enable external connections for specific servers
SAFEBREACH_MCP_AUTH_TOKEN="your-token" safebreach-mcp-all-servers --external-data --external-utilities

# Custom bind host
SAFEBREACH_MCP_AUTH_TOKEN="your-token" safebreach-mcp-all-servers --external --host 0.0.0.0

# Help with usage examples
safebreach-mcp-all-servers --help

使用示例

本地开发（默认）：

# Secure localhost-only access - no external configuration needed
uv run start_all_servers.py

外部访问-所有服务器：

# Enable external connections for all servers
export SAFEBREACH_MCP_AUTH_TOKEN="your-very-secure-token"
export SAFEBREACH_MCP_ALLOW_EXTERNAL=true
uv run start_all_servers.py

# Or with command-line arguments
SAFEBREACH_MCP_AUTH_TOKEN="your-token" uv run start_all_servers.py --external

外部访问-特定服务器：

# Only Data and Utilities servers accessible externally, Config remains local-only
export SAFEBREACH_MCP_AUTH_TOKEN="your-secure-token"
export SAFEBREACH_MCP_DATA_EXTERNAL=true
export SAFEBREACH_MCP_UTILITIES_EXTERNAL=true
uv run start_all_servers.py

个人服务器外部访问：

# Run individual server with external access
export SAFEBREACH_MCP_AUTH_TOKEN="your-token"
export SAFEBREACH_MCP_DATA_EXTERNAL=true
uv run -m safebreach_mcp_data.data_server

客户端认证

访问外部启用的服务器时，客户端必须包含Authorization标头：

# Example HTTP request to external server
curl -H "Authorization: Bearer your-secure-token" \
     "http://your-server:8001/sse"

# Local connections don't require authentication
curl "http://localhost:8001/sse"

安全警告

启用外部连接后，服务器将记录安全警告：

🚨 SECURITY WARNING: Server binding to 0.0.0.0:8001 - accessible from external networks!
🔒 HTTP Authorization required for external connections
🔑 Set SAFEBREACH_MCP_AUTH_TOKEN environment variable for authentication
🌐 External connections enabled for: Data Server, Utilities Server
🏠 Local connections only for: Config Server
✅ SAFEBREACH_MCP_AUTH_TOKEN configured

Claude桌面与外部服务器的集成

对于外部服务器，请更新您的Claude Desktop配置：

{
  "mcpServers": {
    "safebreach-data-external": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://100.117.2.202:8001/sse",
        "--transport",
        "http-first",
        "--allow-http",
        "--header",
        "Authorization: Bearer your-secure-token"
      ]
    }
  }
}

用法🎯

启动MCP服务器

多服务器体系结构（推荐）

本地开发（默认-安全）：

# Run all servers concurrently on localhost only
uv run start_all_servers.py

# Or run individual servers
uv run -m safebreach_mcp_config.config_server     # Port 8000
uv run -m safebreach_mcp_data.data_server         # Port 8001
uv run -m safebreach_mcp_utilities.utilities_server # Port 8002
uv run -m safebreach_mcp_playbook.playbook_server # Port 8003
uv run -m safebreach_mcp_studio.studio_server    # Port 8004

外部访问：

# Enable external connections for all servers with environment variables
export SAFEBREACH_MCP_AUTH_TOKEN="your-secure-token"
export SAFEBREACH_MCP_ALLOW_EXTERNAL=true
uv run start_all_servers.py

# Enable external connections with command-line arguments
SAFEBREACH_MCP_AUTH_TOKEN="your-token" uv run start_all_servers.py --external

# Enable external connections for specific servers only
SAFEBREACH_MCP_AUTH_TOKEN="your-token" uv run start_all_servers.py --external-data --external-utilities

# Get help with all external connection options
uv run start_all_servers.py --help

单租户部署（SafeBreach内部）：

# Set single-tenant environment variables
export DATA_URL="http://localhost:3400"
export CONFIG_URL="http://localhost:3401"
export SIEM_URL="http://localhost:3402" 
export ACCOUNT_ID="your-account-id"
export console_name_apitoken="your-api-token"

# Start all servers (will use local APIs)
uv run start_all_servers.py

远程安装故障排除

在Claude Desktop注册🔗

Claude Desktop从文件中读取MCP服务器配置：

macOS/Linux： ~/Library/Application Support/Claude/claude_desktop_config.json

窗户： %APPDATA%\Claude\claude_desktop_config.json

本地开发配置

多服务器配置（本地主机）：

{
  "mcpServers": {
    "safebreach-config": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:8000/sse",
        "--transport",
        "http-first"
      ]
    },
    "safebreach-data": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:8001/sse",
        "--transport",
        "http-first"
      ]
    },
    "safebreach-utilities": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:8002/sse",
        "--transport",
        "http-first"
      ]
    },
    "safebreach-playbook": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:8003/sse",
        "--transport",
        "http-first"
      ]
    },
    "safebreach-studio": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:8004/sse",
        "--transport",
        "http-first"
      ]
    }
  }
}

Windows配置

多服务器配置（带外部服务器的Windows）：

{
  "mcpServers": {
    "safebreach-config-staging": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "mcp-remote",
        "http://your-server-ip:8000/sse",
        "--transport",
        "http-first",
        "--allow-http",
        "--header",
        "Authorization: Bearer your-auth-token-here"
      ]
    },
    "safebreach-data-staging": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "mcp-remote",
        "http://your-server-ip:8001/sse",
        "--transport",
        "http-first",
        "--allow-http",
        "--header",
        "Authorization: Bearer your-auth-token-here"
      ]
    },
    "safebreach-utilities": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "mcp-remote",
        "http://your-server-ip:8002/sse",
        "--transport",
        "http-first",
        "--allow-http",
        "--header",
        "Authorization: Bearer your-auth-token-here"
      ]
    },
    "safebreach-playbook": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "mcp-remote",
        "http://your-server-ip:8003/sse",
        "--transport",
        "http-first",
        "--allow-http",
        "--header",
        "Authorization: Bearer your-auth-token-here"
      ]
    }
  }
}

Windows用户注意事项: - 使用 "command": "cmd" 而不是 "npx" - 添加 "/c" 作为第一个论点 - 添加 --allow-http HTTP连接的标志（如果不使用HTTPS）

远程服务器配置

对于具有身份验证的外部/生产服务器：

{
  "mcpServers": {
    "safebreach-data-staging": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://100.117.2.202:8001/sse",
        "--transport",
        "http-first",
        "--allow-http",
        "--header",
        "Authorization: Bearer your-secure-token-here"
      ]
    },
    "safebreach-config-staging": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://100.117.2.202:8000/sse",
        "--transport",
        "http-first",
        "--allow-http",
        "--header",
        "Authorization: Bearer your-secure-token-here"
      ]
    },
    "safebreach-utils-staging": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://100.117.2.202:8002/sse",
        "--transport",
        "http-first",
        "--allow-http",
        "--header",
        "Authorization: Bearer your-secure-token-here"
      ]
    },
    "safebreach-playbook-staging": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://100.117.2.202:8003/sse",
        "--transport",
        "http-first",
        "--allow-http",
        "--header",
        "Authorization: Bearer your-secure-token-here"
      ]
    }
  }
}

OAuth 2.0自动发现支持

MCP服务器支持OAuth 2.0发现，用于与兼容客户端进行自动身份验证：

支持的OAuth 2.0端点：

• /.well-known/oauth-protected-resource -OAuth发现元数据
• /.well-known/oauth-authorization-server/sse -OAuth授权服务器元数据
• /register （POST）-动态客户端注册
• /auth （GET）-授权端点（需要Bearer令牌）
• /token （POST）-令牌端点（需要承载令牌）

安全功能：

• OAuth发现端点是可公开访问的（符合OAuth规范要求）
• 授权和令牌端点需要有效的承载令牌身份验证
• OAuth流与现有的Bearer令牌系统集成
• 为安全流提供完整的PKCE（代码交换证明密钥）支持

配置最佳实践

1. 发展：使用localhost配置进行本地开发
2. 生产：使用具有适当身份验证令牌的远程服务器配置
3. 认证：始终对外部/生产服务器使用Bearer令牌
4. 令牌安全：确保身份验证令牌的安全，并定期轮换

获取身份验证令牌

对于启用了身份验证的远程服务器，您需要Bearer令牌：

# Get token from deployment script output
python deploy_safebreach_mcp.py status --host your-server-ip

# Or check the environment file on the remote server
ssh user@server "cat ~/.config/safebreach-mcp/environment | grep SAFEBREACH_MCP_AUTH_TOKEN"

克劳德桌面连接故障排除

更新配置文件后，重新启动Claude Desktop以使更改生效。

API 参考📚

MCP服务器为SafeBreach操作提供以下工具：

可用工具

多服务器分布

配置服务器（端口8000）：

1. get_console_simulators ✨ 通过过滤增强
2. get_simulator_details

数据服务器（端口8001）： 3\. get_tests ✨ 通过过滤增强 4\. get_test_details ✨ 通过可选统计数据增强 5\. get_test_simulations ✨ 通过过滤增强 6\. get_simulation_details ✨ 通过可选扩展进行增强 7\. get_security_controls_events ✨ 新 -具有过滤功能的安全控制事件 8\. get_security_control_event_details ✨ 新 -详细的安全事件及其详细程度 9\. get_test_findings_counts ✨ 新 -按类型汇总调查结果并进行筛选 10\. get_test_findings_details ✨ 新 -经过全面过滤的详细结果 11\. get_test_drifts ✨ 新 -具有综合漂移类型分类的试运行之间的高级漂移分析 12\. get_full_simulation_logs ✨ 新 -全面的执行日志，带有详细的痕迹（~40KB），用于取证分析

播放服务器（端口8003）： 13\. get_playbook_attacks ✨ 新 -具有全面过滤功能的过滤和分页剧本攻击 14\. get_playbook_attack_details ✨ 新 -具有详细选项的详细攻击信息

工作室服务器（端口8004）： 15\. validate_studio_code ✨ 新 -通过SB011/SB012 lint检查进行两层代码验证 16\. save_studio_attack_draft ✨ 新 -使用双脚本支持创建新的攻击草稿 17\. update_studio_attack_draft ✨ 新 -更新现有攻击草稿 18\. get_all_studio_attacks ✨ 新 -带有状态/名称/用户过滤的分页攻击列表 19\. get_studio_attack_source ✨ 新 -检索目标和攻击者源代码 20\. run_studio_attack ✨ 新 -使用显式模拟器选择执行攻击 21\. get_studio_attack_latest_result ✨ 新 -带有日志和漂移跟踪的最新执行结果

公用事业服务器（端口8002）： 22\. convert_datetime_to_epoch 23\. convert_epoch_to_datetime

工具详细信息

1. get_console_simulators ✨ 通过过滤增强

- 检索给定控制台的已筛选SafeBreach模拟器 - 参数： - console （字符串，必填）-SafeBreach控制台名称 - status_filter （字符串，可选）-按“已连接”、“已断开”、“启用”、“禁用”或全部为“无”进行筛选 - name_filter （字符串，可选）-模拟器名称不区分大小写的部分匹配 - label_filter （字符串，可选）-模拟器标签上不区分大小写的部分匹配 - os_type_filter （字符串，可选）-按操作系统类型筛选（例如，“Linux”、“Windows”） - critical_only （bool，可选）-仅过滤关键模拟器（真/假/无） - order_by （字符串，默认“name”）-排序字段：“name”、“id”、“version”、“isConnected”、“is Enabled” - order_direction （字符串，默认“asc”）-排序方向：“asc“或”desc“ - 回报：增强响应 simulators, total_simulators，以及 applied_filters

1. get_simulator_details

- 获取特定模拟器的详细信息 - 参数： console （字符串）， simulator_id （字符串） - 返回：完整的模拟器配置和主机详细信息

1. get_tests ✨ 通过过滤增强

- 检索经过筛选和分页的测试执行历史记录 - 参数： - console （字符串，必填）-SafeBreach控制台名称 - page_number （int，默认0）-页码（从0开始） - test_type （字符串，可选）-按“验证”（BAS）、“传播”（ALM）或全部为“无”进行筛选 - start_date （int，可选）-筛选end_time>=start_date（Unix时间戳）的测试 - end_date （int，可选）-筛选end_time\=start_time（Unix时间戳）的模拟 - end_time （int，可选）-过滤end_time\<=end_time（Unix时间戳）的模拟 - playbook_attack_id_filter （字符串，可选）-按精确的剧本攻击ID匹配进行筛选 - playbook_attack_name_filter （字符串，可选）-按部分剧本攻击名称匹配进行筛选（不区分大小写） - 回报：增强响应 total_simulations, applied_filters，并过滤结果

1. get_simulation_details ✨ 通过可选扩展进行增强

- 获取特定模拟的详细结果 - 参数： - console （字符串，必填）-SafeBreach控制台名称 - simulation_id （字符串，必填）-用于获取详细信息的模拟ID - include_mitre_techniques （bool，可选，默认为False）-包括MITRE ATT&CK技术详细信息 - include_basic_attack_logs （bool，可选，默认为False）-包括模拟事件中主机的基本攻击日志 - include_simulation_logs （bool，可选，默认为False）-包括模拟执行日志 - 返回：使用可选扩展完成模拟结果

1. get_security_controls_events ✨ 新 -带过滤的安全控制事件

- 从SafeBreach SIEM日志中检索经过筛选和分页的安全控制事件 - 参数： - console （字符串，必填）-SafeBreach控制台名称 - test_id （字符串，必填）-用于获取安全事件的测试ID - simulation_id （字符串，必填）-用于获取安全事件的模拟ID - page_number （int，默认0）-页码（从0开始） - product_name_filter （字符串，可选）-按安全产品名称筛选（不区分大小写的部分匹配） - vendor_name_filter （字符串，可选）-按安全产品供应商筛选（不区分大小写的部分匹配） - security_action_filter （字符串，可选）-按安全操作过滤（例如，“阻止”、“允许”、“检测”） - connector_name_filter （字符串，可选）-按连接器名称筛选（不区分大小写的部分匹配） - source_host_filter （字符串，可选）-按源主机筛选（不区分大小写的部分匹配） - destination_host_filter （字符串，可选）-按目标主机筛选（不区分大小写的部分匹配） - 返回：已筛选的带有分页的安全控制事件和已应用的筛选器元数据

1. get_security_control_event_details ✨ 新 -具有详细级别的详细安全事件

- 获取具有可配置详细程度的特定安全控制事件的全面详细信息 - 参数： - console （字符串，必填）-SafeBreach控制台名称 - test_id （字符串，必填）-包含安全事件的测试ID - simulation_id （字符串，必填）-包含安全事件的模拟ID - event_id （字符串，必填）-用于获取详细信息的安全事件ID - verbosity_level （字符串，默认“标准”）-详细级别：“最小”、“标准”、“详细”、“完整” - 返回：带有详细程度控制字段的安全事件详细信息 - 详细程度： - 最小：基本标识（时间戳、产品、动作） - 标准：常用字段（添加源/目标、规则信息） - 详细的：扩展字段（添加技术细节、元数据） - 满的：所有可用字段（完整的事件数据）

1. get_test_findings_counts ✨ 新 -筛选结果总结

- 使用可选属性筛选按类型返回特定测试的结果计数 - 参数： - console （字符串，必填）-SafeBreach控制台名称 - test_id （字符串，必填）-用于获取结果计数的测试ID - attribute_filter （字符串，可选）-根据任何具有部分不区分大小写匹配的查找属性进行筛选 - 返回：按类型和应用的筛选器元数据统计的结果摘要 - 有助于：概述Propagate测试期间发现的安全发现 - 过滤：支持在所有查找属性之间进行部分匹配，包括类型、源、严重性、主机名、IP地址、端口、协议和嵌套数据结构 - 注：使用propagateSummary API检索所有模拟的测试级结果

1. get_test_findings_details ✨ 新 -全面过滤的详细结果

• 通过全面的筛选和分页返回特定测试的详细结果
• 参数：

- console （字符串，必填）-SafeBreach控制台名称 - test_id （字符串，必填）-用于获取详细结果的测试ID - page_number （int，默认0）-分页页码（从0开始） - attribute_filter （字符串，可选）-根据任何具有部分不区分大小写匹配的查找属性进行筛选

• 返回：包含分页元数据和应用过滤器信息的详细结果
• 适用于：深入分析类似于渗透测试报告的安全发现
• 过滤：在所有查找字段（包括嵌套对象、数组和复杂数据结构）中进行高级属性搜索
• 注意：检索所有模拟中的测试级结果（不是特定于模拟的结果）

1. get_test_drifts ✨ 新 -试运行之间的高级漂移分析

• 分析给定测试与最近一次同名测试之间的漂移
• 比较模拟结果，以确定执行之间安全态势的变化
• 参数：

- console （字符串，必填）-SafeBreach控制台名称 - test_id （字符串，必填）-用于分析漂移的当前测试ID

• 回报：全面的漂移分析，包括安全影响分类和详细的元数据
• 可用于：跟踪安全控制有效性的变化，识别安全态势趋势
• 分析类型：基线专用模拟、当前专用模拟、状态变化模拟
• 安全影响：将每种漂移类型分为积极、消极或中性安全影响

1. get_full_simulation_logs ✨ 新 -用于法医分析的综合执行日志

• 检索特定模拟的全面执行日志，包括详细的跟踪（~40KB logs字段）
• 主要用例：深度故障排除、取证分析、分步执行分析、详细的日志关联
• 参数：

- simulation_id （字符串，必填）-用于获取综合日志的模拟ID（例如，“1477531”） - test_id （字符串，必填）-包含模拟的测试ID（planRunId）（例如，'1764165600525.2'） - console （字符串，默认值为'default'）-SafeBreach控制台名称

• 返回：全面的执行数据，包括：

- logs （string）-具有完整跟踪输出的原始详细模拟器日志（~40KB） - simulation_steps （列表）-带时间信息的结构化分步执行 - details_summary （string）-发生错误时的异常回溯摘要 - output （string）-模拟初始化输出 - metadata （dict）-其他字段，如method_id、state、execution_times

• 缓存：结果缓存1小时以优化性能
• 注：用于综合日志分析；将get_simulation_details与include_basic_attack_logs一起用于摘要级日志

实用工具

1. convert_datetime_to_epoch

• 将ISO日期时间字符串转换为Unix纪元时间戳
• 参数： datetime_str （string，必填）-ISO格式日期时间字符串
• 返回：纪元时间戳和解析详细信息
• 适用于：为SafeBreach API筛选准备日期时间值

1. get_playbook_attacks ✨ 新 -过滤和分页剧本攻击

• 从全面的攻击知识库中检索经过筛选和分页的SafeBreach剧本攻击
• 参数：

- console （字符串，必填）-SafeBreach控制台名称 - page_number （int，默认0）-页码（从0开始） - name_filter （字符串，可选）-攻击名称不区分大小写的部分匹配 - description_filter （字符串，可选）-攻击描述中不区分大小写的部分匹配 - id_min （int，可选）-用于范围过滤的最小攻击ID - id_max （int，可选）-用于范围过滤的最大攻击ID - modified_date_start （字符串，可选）-在此ISO日期之后修改的筛选器攻击 - modified_date_end （字符串，可选）-在此ISO日期之前修改的筛选器攻击 - published_date_start （字符串，可选）-过滤在此ISO日期之后发布的攻击 - published_date_end （字符串，可选）-过滤在此ISO日期之前发布的攻击

• 返回：带有过滤元数据的分页攻击列表
• 适用于：浏览和搜索SafeBreach攻击手册

1. get_playbook_attack_details ✨ 新 -详细的攻击信息

• 通过可配置的详细程度获取特定SafeBreach剧本攻击的全面细节
• 参数：

- console （字符串，必填）-SafeBreach控制台名称 - attack_id （int，必填）-用于获取详细信息的攻击ID - include_fix_suggestions （bool，可选，默认为False）-包括补救建议 - include_tags （bool，可选，默认为False）-包含攻击分类标签 - include_parameters （bool，可选，默认为False）-包括攻击配置参数

• 返回：使用可选扩展名完成攻击详细信息
• 有助于：了解特定的攻击技术及其补救措施

1. convert_datetime_to_epoch

• 将ISO日期时间字符串转换为Unix纪元时间戳
• 参数： datetime_str （string，必填）-ISO格式日期时间字符串
• 返回：纪元时间戳和解析详细信息
• 适用于：为SafeBreach API筛选准备日期时间值

1. convert_epoch_to_datetime

• 将Unix纪元时间戳转换为可读的日期时间字符串
• 参数：

- epoch_timestamp （int，必填）-Unix时间戳为整数 - timezone （字符串，可选，默认“UTC”）-输出时区

• 返回：ISO日期时间字符串和格式化信息
• 适用于：解释SafeBreach API响应中的epoch时间戳

使用示例

基本模拟器检索（为了向后兼容性而保持不变）：

# Get all simulators
simulators = get_console_simulators("sample-console")

按状态筛选模拟器：

# Get only connected simulators
connected_sims = get_console_simulators("sample-console", status_filter="connected")

# Get only enabled simulators
enabled_sims = get_console_simulators("sample-console", status_filter="enabled")

按操作系统类型和关键性筛选：

# Get critical Linux simulators only
critical_linux = get_console_simulators("sample-console", os_type_filter="Linux", critical_only=True)

# Get Windows simulators ordered by version
windows_sims = get_console_simulators("sample-console", os_type_filter="Windows", order_by="version", order_direction="desc")

按名称和标签搜索：

# Find simulators with "server" in name
servers = get_console_simulators("sample-console", name_filter="server")

# Find production simulators
production_sims = get_console_simulators("sample-console", label_filter="production")

组合过滤：

# Get connected, enabled, non-critical Linux simulators ordered by name
result = get_console_simulators(
    console="sample-console",
    status_filter="connected",
    os_type_filter="Linux", 
    critical_only=False,
    order_by="name",
    order_direction="asc"
)

基本测试历史使用（为向后兼容性而不变）：

# Get first page of all tests
tests = get_tests("sample-console", 0)

按测试类型筛选：

# Get only validation tests (BAS)
validation_tests = get_tests("sample-console", test_type="validate")

# Get only propagation tests (ALM)
propagation_tests = get_tests("sample-console", test_type="propagate")

按时间窗口筛选：

import time

# Get tests from last 7 days
week_ago = int(time.time()) - (7 * 24 * 3600)
recent_tests = get_tests("sample-console", start_date=week_ago)

# Get tests from specific date range
start_date = 1640995200  # 2022-01-01
end_date = 1641081600    # 2022-01-02
tests_jan_1_2 = get_tests("sample-console", start_date=start_date, end_date=end_date)

按状态和名称筛选：

# Get failed tests only
failed_tests = get_tests("sample-console", status_filter="failed")

# Search for specific test campaigns
quarterly_tests = get_tests("sample-console", name_filter="quarterly")

定制订购：

# Get tests ordered by name alphabetically
tests_by_name = get_tests("sample-console", order_by="name", order_direction="asc")

# Get oldest tests first
oldest_tests = get_tests("sample-console", order_direction="asc")

组合过滤器：

# Get completed validation tests from last month, ordered by duration
last_month = int(time.time()) - (30 * 24 * 3600)
results = get_tests(
    console="sample-console",
    test_type="validate",
    status_filter="completed", 
    start_date=last_month,
    order_by="duration",
    order_direction="desc"
)

基本模拟检索（为向后兼容而保持不变）：

# Get all simulations for a test
simulations = get_test_simulations("sample-console", "test-id-123", 0)

按状态过滤模拟：

# Get only missed simulations (successful attacks)
missed_sims = get_test_simulations("sample-console", "test-id-123", 0, status_filter="missed")

# Get only prevented simulations
prevented_sims = get_test_simulations("sample-console", "test-id-123", 0, status_filter="prevented")

# Get only stopped simulations
stopped_sims = get_test_simulations("sample-console", "test-id-123", 0, status_filter="stopped")

按时间窗口筛选：

import time

# Get simulations from last 24 hours
day_ago = int(time.time()) - (24 * 3600)
recent_sims = get_test_simulations("sample-console", "test-id-123", 0, start_time=day_ago)

# Get simulations from specific time range
start_time = 1640995200  # 2022-01-01
end_time = 1641081600    # 2022-01-02
sims_jan_1_2 = get_test_simulations("sample-console", "test-id-123", 0, start_time=start_time, end_time=end_time)

按剧本攻击细节过滤：

# Get simulations for specific attack ID
attack_sims = get_test_simulations("sample-console", "test-id-123", 0, playbook_attack_id_filter="ATT-1234")

# Search for file-related attacks
file_attacks = get_test_simulations("sample-console", "test-id-123", 0, playbook_attack_name_filter="file")

# Search for credential attacks
cred_attacks = get_test_simulations("sample-console", "test-id-123", 0, playbook_attack_name_filter="credential")

组合模拟过滤器：

# Get missed file-related attacks from last week
week_ago = int(time.time()) - (7 * 24 * 3600)
results = get_test_simulations(
    console="sample-console",
    test_id="test-id-123",
    page_number=0,
    status_filter="missed",
    start_time=week_ago,
    playbook_attack_name_filter="file"
)

# Get all network attacks that were prevented or stopped
network_blocked = get_test_simulations(
    console="sample-console",
    test_id="test-id-123", 
    page_number=0,
    playbook_attack_name_filter="network"
)
# Note: Filter by status in separate calls since status_filter accepts single value

安全控制事件使用情况：

# Get all security control events for a simulation
events = get_security_controls_events("sample-console", "test-id-123", "sim-id-456")

# Filter by security product vendor
firewall_events = get_security_controls_events(
    console="sample-console",
    test_id="test-id-123", 
    simulation_id="sim-id-456",
    vendor_name_filter="Palo Alto"
)

# Filter by security action (blocked events)
blocked_events = get_security_controls_events(
    console="sample-console",
    test_id="test-id-123",
    simulation_id="sim-id-456", 
    security_action_filter="block"
)

# Combined filters: antivirus detections on specific host
av_detections = get_security_controls_events(
    console="sample-console",
    test_id="test-id-123",
    simulation_id="sim-id-456",
    product_name_filter="antivirus",
    source_host_filter="workstation-01",
    security_action_filter="detect"
)

详细的安全事件信息：

# Basic event details (standard verbosity)
event = get_security_control_event_details("sample-console", "test-123", "sim-456", "event-789")

# Minimal details for overview
minimal = get_security_control_event_details(
    console="sample-console",
    test_id="test-123", 
    simulation_id="sim-456",
    event_id="event-789",
    verbosity_level="minimal"
)

# Full details for investigation
full_details = get_security_control_event_details(
    console="sample-console",
    test_id="test-123",
    simulation_id="sim-456", 
    event_id="event-789",
    verbosity_level="full"
)

测试结果使用：

# Get basic findings counts for a test
findings_summary = get_test_findings_counts("sample-console", "test-id-123")

# Filter findings by type
credential_findings = get_test_findings_counts(
    console="sample-console",
    test_id="test-id-123",
    attribute_filter="credential"
)

# Filter by severity level
high_severity_findings = get_test_findings_counts(
    console="sample-console", 
    test_id="test-id-123",
    attribute_filter="high"
)

# Get detailed findings (first page)
detailed_findings = get_test_findings_details("sample-console", "test-id-123")

# Filter detailed findings by hostname
host_findings = get_test_findings_details(
    console="sample-console",
    test_id="test-id-123",
    page_number=0,
    attribute_filter="workstation-01"
)

# Filter by port or protocol
port_findings = get_test_findings_details(
    console="sample-console",
    test_id="test-id-123",
    attribute_filter="3389"
)

# Search across all attributes (case-insensitive)
search_findings = get_test_findings_details(
    console="sample-console",
    test_id="test-id-123",
    attribute_filter="rdp"
)

# Paginate through results
page_2_findings = get_test_findings_details(
    console="sample-console",
    test_id="test-id-123",
    page_number=1,
    attribute_filter="open"
)

Playbook攻击用法：

# Get all playbook attacks (first page)
attacks = get_playbook_attacks("sample-console")

# Filter attacks by name
file_attacks = get_playbook_attacks("sample-console", name_filter="file")

# Filter attacks by ID range
recent_attacks = get_playbook_attacks("sample-console", id_min=3000, id_max=4000)

# Filter attacks by modification date
import datetime
start_date = "2024-01-01T00:00:00Z"
recent_modified = get_playbook_attacks(
    console="sample-console",
    modified_date_start=start_date
)

# Combined filtering: credential attacks from specific time period
cred_attacks = get_playbook_attacks(
    console="sample-console",
    name_filter="credential",
    description_filter="harvest",
    published_date_start="2020-01-01T00:00:00Z"
)

# Get detailed attack information (basic)
attack_details = get_playbook_attack_details(
    console="sample-console",
    attack_id=3405
)

# Get attack details with all optional information
full_attack_details = get_playbook_attack_details(
    console="sample-console",
    attack_id=3405,
    include_fix_suggestions=True,
    include_tags=True,
    include_parameters=True
)

# Get attack details with specific verbosity options
attack_with_fixes = get_playbook_attack_details(
    console="sample-console",
    attack_id=3405,
    include_fix_suggestions=True,
    include_tags=False,
    include_parameters=False
)

测试🧪

该项目包括一个全面的测试套件，代码覆盖率为100%。

运行测试

# Run all multi-server tests
uv run pytest safebreach_mcp_config/tests/ safebreach_mcp_data/tests/ safebreach_mcp_utilities/tests/ safebreach_mcp_playbook/tests/ safebreach_mcp_studio/tests/ tests/ -v -m "not e2e"

# Run authentication tests
uv run python tests/run_auth_tests.py --quick --verbose

# Run specific server test suites
uv run pytest safebreach_mcp_config/tests/ -v   # Config server tests
uv run pytest safebreach_mcp_data/tests/ -v     # Data server tests
uv run pytest safebreach_mcp_utilities/tests/ -v # Utilities server tests
uv run pytest safebreach_mcp_playbook/tests/ -v  # Playbook server tests
uv run pytest safebreach_mcp_studio/tests/ -v -m "not e2e"  # Studio server tests

# Run with coverage report
uv run pytest safebreach_mcp_config/tests/ safebreach_mcp_data/tests/ safebreach_mcp_utilities/tests/ safebreach_mcp_playbook/tests/ safebreach_mcp_studio/tests/ tests/ --cov=. --cov-report=html -m "not e2e"

VS代码集成

该项目包括VS Code启动配置，以便于测试：

1. 按 F5 VS代码
2. 从可用的测试配置中选择：

- Run All Tests -完整的测试套件 - Run Unit Tests -仅限单元测试 - Run Integration Tests -仅集成测试 - Run Tests with Coverage -覆盖率分析测试 - Debug Specific Test -调试单个测试

测试在VS代码测试资源管理器中自动发现。

发展🔧

项目结构

.
├── safebreach_mcp_core/                # Shared components
│   ├── __init__.py
│   ├── safebreach_auth.py              # Centralized authentication
│   ├── safebreach_base.py              # Base MCP server class
│   ├── datetime_utils.py               # Datetime utilities
│   ├── environments_metadata.py        # Environment configurations
│   ├── secret_utils.py                 # Factory facade for secure credential management
│   └── secret_providers.py             # Pluggable secret provider interface
├── safebreach_mcp_config/              # Config server (Port 8000)
│   ├── __init__.py
│   ├── config_server.py                # Config MCP server
│   ├── config_functions.py             # Simulator business logic
│   ├── config_types.py                 # Simulator data transformations
│   └── tests/                          # Config server tests
│       ├── __init__.py
│       └── test_config_functions.py
├── safebreach_mcp_data/                # Data server (Port 8001)
│   ├── __init__.py
│   ├── data_server.py                  # Data MCP server
│   ├── data_functions.py               # Test/simulation/security event business logic
│   ├── data_types.py                   # Test/simulation/security event data transformations
│   └── tests/                          # Data server tests
│       ├── __init__.py
│       ├── test_data_functions.py
│       ├── test_data_types.py
│       └── test_integration.py
├── safebreach_mcp_utilities/           # Utilities server (Port 8002)
│   ├── __init__.py
│   ├── utilities_server.py             # Utilities MCP server
│   └── tests/                          # Utilities server tests
│       ├── __init__.py
│       └── test_utilities_server.py
├── safebreach_mcp_playbook/            # Playbook server (Port 8003)
│   ├── __init__.py
│   ├── playbook_server.py              # Playbook MCP server
│   ├── playbook_functions.py           # Playbook attack business logic
│   ├── playbook_types.py               # Playbook attack data transformations
│   └── tests/                          # Playbook server tests
│       ├── __init__.py
│       ├── test_playbook_functions.py
│       ├── test_playbook_server.py
│       ├── test_playbook_types.py
│       ├── test_integration.py
│       └── test_e2e.py
├── safebreach_mcp_studio/             # Studio server (Port 8004)
│   ├── __init__.py
│   ├── studio_server.py               # Studio MCP server
│   ├── studio_functions.py            # Studio attack business logic
│   ├── studio_types.py                # Studio data transformations
│   └── tests/                         # Studio server tests
│       ├── __init__.py
│       ├── test_studio_functions.py
│       └── test_e2e.py
├── tests/                              # Authentication and integration tests
│   ├── __init__.py
│   ├── pytest.ini                     # Pytest configuration
│   ├── README.md                       # Test documentation
│   ├── run_auth_tests.py               # Authentication test suite runner
│   └── test_external_authentication.py # Authentication wrapper unit tests
├── start_all_servers.py                # Concurrent multi-server launcher
├── mcp_server_bug_423_hotfix.py        # MCP initialization fix
├── .gitignore                          # Git ignore patterns
├── CLAUDE.md                           # Claude Code guidance
├── DESIGN.md                           # Design documentation
├── MANIFEST.in                         # Package manifest
├── pyproject.toml                      # Project configuration
├── README.md                           # Project documentation
├── requirements.txt                    # Python dependencies
└── uv.lock                             # UV lockfile

缓存行为

默认情况下禁用缓存 以防止无限内存增长。启用每台服务器 SB_MCP_CACHE_{SERVER}=true.

启用后，多服务器架构实现了具有1小时TTL的服务器特定缓存：

配置服务器：

• 模拟器缓存：每个控制台的模拟器数据
• 控制台隔离：每个SafeBreach控制台都有单独的缓存

数据服务器：

• 测试缓存：每个控制台的测试历史数据
• 模拟缓存：每次测试的模拟结果
• 安全事件缓存：每次模拟的安全控制事件
• 结果缓存：每次测试的测试结果数据
• 完整日志缓存：每次模拟的综合模拟日志
• 控制台/测试隔离：每个SafeBreach控制台和测试都有单独的缓存

播放服务器：

• 播放缓存：每个控制台的攻击剧本数据

工作室服务器：

• 草稿缓存：每个控制台/攻击的攻击草稿元数据（1小时TTL）

核心组件：

• 令牌缓存：每个控制台的API令牌（safebreach_auth.py）
• 提供商缓存：机密提供程序实例（Secret_utils.py）
• 秘密藏匿处：每个提供者检索的秘密（secret_providers.py）

公用事业服务器：

• 无状态：无缓存（纯实用函数）

启用缓存时：

• 自动过期：过期数据1小时后自动刷新
• 缓存隔离：每台服务器都维护自己的缓存
• 演出：减少了对重复查询的API调用

禁用缓存时（默认）：

• 每次请求时，所有数据都是从API中新鲜获取的
• 缓存数据没有内存增长
• 建议用于长时间运行的生产部署

添加新环境

方法1：编辑 environments_metadata.py 直接

safebreach_envs["new-console"] = {
    "url": "new-console.safebreach.com",
    "account": "account_id",
    "secret_config": {
        "provider": "aws_ssm",  # or "aws_secrets_manager" or "env_var"
        "parameter_name": "new-console-apitoken"
    }
}

方法2：使用JSON文件进行动态加载

1. 创建JSON文件（例如。， my_consoles.json):

{
    "new-console": {
        "url": "new-console.safebreach.com",
        "account": "account_id",
        "secret_config": {
            "provider": "env_var",
            "parameter_name": "new-console-apitoken"
        }
    }
}

1. 设置环境变量和令牌：

export SAFEBREACH_ENVS_FILE=/path/to/my_consoles.json
export NEW_CONSOLE_APITOKEN="your-api-token"

方法3：在环境变量中使用JSON字符串（建议用于容器）✨ 新

# Set configuration directly as JSON string
export SAFEBREACH_LOCAL_ENV='{"new-console": {"url": "new-console.safebreach.com", "account": "account_id", "secret_config": {"provider": "env_var", "parameter_name": "new_console_apitoken"}}}'

# Set the API token
export new_console_apitoken="your-api-token"

方法4：在AWS中存储令牌（用于AWS_ssm或AWS_secrets_manager提供程序）

# For AWS SSM
aws ssm put-parameter --name "new-console-apitoken" --value "your-api-token" --type "SecureString"

# For AWS Secrets Manager
aws secretsmanager create-secret --name "safebreach/new-console/api-token" --secret-string "your-api-token"

故障排除🔍

常见问题

远程MCP服务器问题

✅ 已解决：外部连接中间件错误：

• 错误: 'function' object has no attribute 'middleware' 使用时 --external 旗帜（固定）
• 根本原因：MCP SDK版本（1.11.0）已过时，远程服务器上缺少更新代码
• 决心：将MCP SDK更新到1.12.1，并部署了最新的身份验证包装器代码
• 当前状态：外部连接完全可通过承载令牌身份验证运行
• 访问：直接外部连接工作： curl -H "Authorization: Bearer token" http://server:port/sse

中间件Bug修复摘要：

1. 根本原因：过时的MCP SDK（1.11.0）+缺少代码更新
2. 已应用修复：升级到MCP SDK 1.12.1+部署了最新的safebreach_base.py
3. 结果：具有承载令牌身份验证的外部连接完全可用
4. 验证：身份验证工作（401无令牌，通过有效令牌）

安全注意事项🔒

• 默认安全性：默认情况下，所有服务器都绑定到localhost（127.0.0.1）-没有外部访问
• 外部访问控制：可选的外部连接需要显式配置和承载令牌身份验证
• 认证绕过：本地主机连接会自动绕过身份验证，以方便开发
• API代币存储：安全地存储在AWS SSM参数存储或环境变量中的SafeBreach API令牌
• 无数据记录：本地没有记录或缓存敏感数据
• HTTPS强制：对所有SafeBreach API通信强制使用HTTPS
• 连接超时：超时控制防止挂起连接（120秒）
• 安全警告：启用外部访问时进行全面日志记录
• 令牌验证：对所有具有正确错误响应的外部请求进行承载令牌验证

包裹信息📦

该项目提供了多种安装选项和各种入口点：

多服务器入口点：

• safebreach-mcp-all-servers：并发多服务器启动器（推荐）
• safebreach-mcp-config-server：仅配置服务器（端口8000）
• safebreach-mcp-data-server：仅数据服务器（端口8001）
• safebreach-mcp-utilities-server：仅公用事业服务器（端口8002）
• safebreach-mcp-playbook-server：仅限播放服务器（端口8003）
• safebreach-mcp-studio-server：仅限工作室服务器（端口8004）

包裹详细信息：

• 包名：safebreak mcp服务器
• 版本: 1.1.0
• 依赖项：boto3、请求、mcp（参见pyproject.toml）
• Python版本: 3.12+
• 分布：可通过git+ssh或git+https安装获得

贡献🤝

1. 从以下位置创建特征分支 master
2. 为新功能编写测试（保持100%的覆盖率）
3. 根据需要更新文档
4. 在提交PR之前运行完整的测试套件
5. 遵循现有的代码风格和模式

代码质量

• 保持100%的测试覆盖率
• 对所有函数参数使用类型提示
• 包含全面的文档字符串
• 遵循现有的错误处理模式