ghostmcp (Jason Allen Oneal)

GhostMCP

GhostMCP是一个面向生产的MCP服务器，用于授权的红队和安全行动。

它提供：

• 核心内置侦察和分析工具
• 在启动时发现二进制支持的Kali工具包装器
• 参与上下文支持(engagement_id, engagement_mode)
• 轻量级策略控制和审计链
• 非本地网关模式的传输/身份验证策略
• 运行时指标、运行状况探测和SIEM审计导出

文档

• docs/README.md
• docs/RUNBOOK.md

远程传输安全

GhostMCP支持 streamable-http 运输方式 GHOSTMCP_TRANSPORT_MODE=remote_gateway这允许服务器在与LLM客户端分离的主机上运行。

威胁模型和身份验证模式

1. AUTH_MODE=none: 硬封锁 在远程模式下，除非 GHOSTMCP_ALLOW_INSECURE_REMOTE_NO_AUTH=true 已设置。仅用于本地测试。
2. AUTH_MODE=token：需要 GHOSTMCP_AUTH_TOKEN。客户端必须在 auth_token 工具调用领域。
3. AUTH_MODE=mtls：最安全的模式。需要有效的CA、客户端证书和私钥。在传输层强制执行双向TLS。

建议：

• 总是使用 mtls 用于生产远程部署。
• 绑定到特定的内部接口(GHOSTMCP_HTTP_HOST)而不是 0.0.0.0 如果可能的话。
• 使用防火墙限制对 GHOSTMCP_HTTP_PORT.

部署快速启动

系统（Linux）

1. 编辑 deploy/systemd/ghostmcp.service 您的环境变量。
2. 链接或复制服务文件：

   sudo cp deploy/systemd/ghostmcp.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable --now ghostmcp

码头工人

docker build -f deploy/container/Dockerfile -t ghostmcp .
docker run -d \
  --name ghostmcp \
  -e GHOSTMCP_AUTH_MODE=token \
  -e GHOSTMCP_AUTH_TOKEN=your-secret-token \
  ghostmcp

工具类型

1） 核心工具（始终可用）

• dns_lookup_tool
• reverse_dns_tool
• whois_tool
• http_probe_tool
• tls_certificate_tool
• tls_certificate_expiry_tool
• tcp_port_scan_tool
• security_txt_tool
• ioc_extract_tool
• url_risk_score_tool
• subdomain_candidates_tool
• common_web_paths_tool
• toolchain_status_tool
• metrics_tool
• runtime_probe_tool
• server_health_tool

2） 经过整理的二进制备份工具（仅在安装时启用）

• nmap_service_scan_tool
• whatweb_tool
• nikto_tool
• amass_passive_tool
• gobuster_dir_tool
• sslscan_tool
• wafw00f_tool

3） 生成的原始二进制工具（仅在安装时启用）

• 图案： _raw_tool
• 非字母数字字符变为 _
• 例子： testssl.sh -> testssl_sh_raw_tool

需求

• Python 3.11+
• mcp 软件包（通过此项目安装）
• 可选：Kali工具打开 PATH 用于二进制支持的工具

安装

python -m venv .venv
source .venv/bin/activate
pip install -e .

配置

使用 .env.example 作为基线。

主要环境变量：

• GHOSTMCP_LOG_LEVEL （默认值： INFO)
• GHOSTMCP_LOG_FORMAT （默认值： json)
• GHOSTMCP_RATE_LIMIT_CALLS （默认值： 120)
• GHOSTMCP_RATE_LIMIT_WINDOW_SECONDS （默认值： 60)
• GHOSTMCP_MAX_PORTS_PER_SCAN （默认值： 256)
• GHOSTMCP_CONNECT_TIMEOUT_MS （默认值： 1500)
• GHOSTMCP_MAX_CONCURRENT_CONNECTS （默认值： 64)
• GHOSTMCP_ALLOW_PRIVATE_ONLY （默认值： true)
• GHOSTMCP_ALLOWED_CIDRS （可选）
• GHOSTMCP_ALLOWED_DOMAINS （可选）
• GHOSTMCP_BLOCKED_PORTS （默认包括 22,2375,2376,3389)
• GHOSTMCP_USER_AGENT （默认值： GhostMCP/0.1)
• GHOSTMCP_REQUIRE_ENGAGEMENT_CONTEXT （默认值： false)
• GHOSTMCP_MAX_TOOL_LEVEL (passive|active|intrusive，默认值： intrusive)
• GHOSTMCP_TRANSPORT_MODE (stdio|remote_gateway，默认值： stdio)
• GHOSTMCP_AUTH_MODE (none|token|mtls，默认值： none)
• GHOSTMCP_AUTH_TOKEN （令牌模式需要）
• GHOSTMCP_ALLOW_INSECURE_REMOTE_NO_AUTH （默认值： false；不安全覆盖）
• GHOSTMCP_MTLS_CA_CERT_PATH, GHOSTMCP_MTLS_CERT_PATH, GHOSTMCP_MTLS_KEY_PATH
• GHOSTMCP_HTTP_HOST, GHOSTMCP_HTTP_PORT （远程网关绑定设置）
• GHOSTMCP_UVICORN_LOG_LEVEL （默认值： info)
• GHOSTMCP_MAX_PASSIVE_PARALLEL, GHOSTMCP_MAX_ACTIVE_PARALLEL, GHOSTMCP_MAX_INTRUSIVE_PARALLEL
• GHOSTMCP_MAX_RAW_ARG_COUNT, GHOSTMCP_MAX_RAW_ARG_LENGTH, GHOSTMCP_MAX_RAW_RUNTIME_SECONDS
• GHOSTMCP_MAX_RAW_STDOUT_BYTES, GHOSTMCP_MAX_RAW_STDERR_BYTES
• GHOSTMCP_AUDIT_SINK_PATH （用于SIEM运输的JSONL接收器）
• GHOSTMCP_ALLOW_RUN_AS_ROOT （默认值： false)

跑

ghostmcp

这在stdio的前台运行（阻止终端）。使用 Ctrl+C 停止。

MCP客户端示例（克劳德桌面）

{
  "mcpServers": {
    "ghostmcp": {
      "command": "ghostmcp",
      "env": {
        "GHOSTMCP_ALLOW_PRIVATE_ONLY": "true",
        "GHOSTMCP_ALLOWED_CIDRS": "10.0.0.0/8,172.16.0.0/12,192.168.0.0/16",
        "GHOSTMCP_ALLOWED_DOMAINS": "example.com"
      }
    }
  }
}

参与模式

大多数工具接受：

• engagement_id （可选，除非政策要求）
• engagement_mode (default, passive, active, intrusive); default 被接受为的别名 passive
• auth_token （需要 remote_gateway + token 身份验证模式）

授权检查强制执行：

• 全局最大刀具级别(GHOSTMCP_MAX_TOOL_LEVEL)
• 每次通话参与模式上限
• 远程模式的身份验证策略(auth_token 用于令牌模式；mTLS模式的TLS客户端证书）
• 硬块打开 remote_gateway + AUTH_MODE=none 除非明确启用了不安全覆盖

审计与安全

GhostMCP发射：

• 结构化日志
• 带有哈希链的每次调用审计条目(prev_hash, event_hash)
• 可选JSONL审计接收器导出(GHOSTMCP_AUDIT_SINK_PATH)
• 每工具运行时指标(metrics_tool)
• 运行时编排探测(runtime_probe_tool)

范围控制：

• 目标/专用网络验证
• 可选域分配列表
• 可选CIDR列表
• 港口政策执行
• 原始工具参数策略（分配的令牌/标志、长度/计数限制）
• 运行时/输出上限和超时时强制终止子进程
• 每个工具类的并发控制（被动/主动/侵入式信号量）

检查运行时可用性

用途：

• toolchain_status_tool 用于已安装/缺失的二进制文件和已启用的二进制MCP工具
• server_health_tool 用于策略/配置快照和工具链摘要
• metrics_tool 用于呼叫/失败/超时/拒绝统计
• runtime_probe_tool 用于就绪/活性风格的运行时状态

发展

运行测试：

python -m unittest discover -s tests

E2E烟雾测试（可选）：

GHOSTMCP_E2E=1 python -m unittest tests/test_e2e_mcp.py

CI/CD

GitHub工作流包括：

• .github/workflows/ci.yml:

- 棉绒(ruff) - 类型检查(mypy) - 测试(unittest) - 静态安全扫描(bandit) - 依赖性审计(pip-audit) - 包构建 - 容器漏洞扫描(trivy)

• .github/workflows/codeql.yml：计划和PR/推送CodeQL分析
• .github/workflows/release.yml:

- 标签触发构建(v*) - Twine工件验证 - SBOM生成（SPDX） - 建立来源证明 - GitHub发布 - 可选的PyPI发布时间 PYPI_API_TOKEN 秘密存在

部署

• deploy/systemd/ghostmcp.service 用于systemd管理的流程生命周期
• deploy/container/Dockerfile 用于非根容器运行时
• deploy/apparmor/ghostmcp.apparmor 用于可选的AppArmor限制

运行时安全

• 默认情况下非根强制(GHOSTMCP_ALLOW_RUN_AS_ROOT=false)
• 建议最小写入占用空间（仅限日志/审计接收器）
• 包含可选的AppArmor配置文件，用于更严格的二进制限制

法律

仅在您明确授权评估的系统和网络上使用GhostMCP。

许可证

根据GNU Affero通用公共许可证v3.0或更高版本（AGPL-3.0或更高）授权。看 许可证.