ente0/mcpstrike

## 架构 ``` mcpstrike-client mcpstrike-server (MCP) hexstrike_server (TUI + Ollama) ---> (FastMCP, port 8889) ---> (port 8888, must be running) | v Ollama LLM (llama3.2, qwen3.5, etc.) Optional: mcpstrike-backend can replace hexstrike_server for local testing ``` **组件：** | 组件 | 角色 | 默认端口 | |---|---|---| | **hexstrike_server** | 外部后端 — 需单独启动 | 8888 | | `mcpstrike-server` | 通过 MCP 协议暴露 15 个工具，用于会话与命令管理 | 8889 | | `mcpstrike-client` | 交互式 TUI，驱动 Ollama 大型语言模型调用 MCP 工具 | — | | `mcpstrike-backend` *(可选)* | 轻量级本地后端，替代 hexstrike_server | **8890** | ## 安装 ### 使用 pipx（推荐） ``` # 标准安装（使用 hexstrike-server 作为后端） pipx install . # 可选独立后端 pipx install ".[backend]" ``` ### 使用 pip ``` pip install --user . # 可选独立后端 pip install --user ".[backend]" ``` ### 开发环境 ``` pip install -e ".[dev,backend]" ``` ## 快速开始 **必须先在 8888 端口运行 hexstrike_server**，然后再启动 mcpstrike。 ### 自动模式（推荐） ``` mcpstrike ``` `mcpstrike` 是堆栈启动器。它会打开三个平铺的 xterm 窗口（若无则回退到 tmux，最后是后台进程）。所有选项均可通过标志覆盖： ``` mcpstrike --model qwen3:8b mcpstrike --ollama-url http://10.0.0.5:11434 mcpstrike --sessions-dir /opt/pentest/sessions mcpstrike --font-size 15 --screen-width 2560 --screen-height 1440 mcpstrike --tmux # force tmux even if DISPLAY is set ``` 请查看 `mcpstrike --help` 获取所有选项。 ### 手动模式 ``` # 终端 1：MCP 服务器（指向 8888 上的 hexstrike_server） HEXSTRIKE_BACKEND_URL=http://localhost:8888 mcpstrike-server # 终端 2：客户端 mcpstrike-client --ollama-url http://:11434 --model qwen3.5 ``` ### 使用独立后端（无需 hexstrike_server） ``` # 终端 1：本地后端（端口 8890，与 8888 上的 hexstrike 无冲突） mcpstrike-backend # 终端 2：指向 mcpstrike-backend 的 MCP 服务器 HEXSTRIKE_BACKEND_URL=http://localhost:8890 mcpstrike-server # 终端 3：客户端 mcpstrike-client ``` 需要先执行 `pipx install ".[backend]"`。 ## 命令 ### mcpstrike（堆栈启动器） 在单个命令中启动完整堆栈。自动在 xterm、tmux 和后台模式之间选择。 ``` mcpstrike [OPTIONS] Network options: --ollama-url URL Ollama daemon URL (default: http://localhost:11434) --model NAME Ollama model to use (default: qwen3.5:latest) --hexstrike-port PORT hexstrike_server port (default: 8888) --mcp-port PORT mcpstrike-server port (default: 8889) Session options: --sessions-dir PATH Directory for session files (default: ~/hexstrike_sessions) GUI xterm options: --font-size PT xterm font size in points (default: 13) --screen-width PX Screen width for window tiling (default: 1920) --screen-height PX Screen height for window tiling (default: 1080) Launch mode: --tmux, --no-xterm Force tmux even if a display is available --xterm Force xterm (fails if DISPLAY is not set) ``` 所有网络选项也支持对应的环境变量（`OLLAMA_URL`、`OLLAMA_MODEL`、`HEXSTRIKE_PORT`、`MCPSTRIKE_PORT`、`HEXSTRIKE_SESSION_PATH`）。 **窗口布局（xterm，1920×1080）：** ``` ┌─────────────────────────┬─────────────────────────┐ │ hexstrike_server │ mcpstrike-server │ top ~54% ├─────────────────────────┴─────────────────────────┤ │ mcpstrike-client │ bottom ~46% └───────────────────────────────────────────────────┘ ``` ### mcpstrike-client 用于驱动渗透测试的交互式 TUI。 ``` mcpstrike-client [OPTIONS] Options: --mcp-url URL MCP server URL (default: http://localhost:8889/mcp) --ollama-url URL Ollama API URL (default: http://localhost:11434) --model, -m NAME Ollama model (default: llama3.2) --sessions-dir PATH Session files directory (default: ~/hexstrike_sessions) --no-native-tools Force JSON fallback mode (for older models) --no-auto-parse Disable automatic parser dispatch --debug Enable verbose error tracebacks ``` #### 交互命令 | 命令 | 描述 | |---|---| | `/help` | 显示所有可用命令 | | `/tools` | 列出服务器上发现的 MCP 工具 | | `/agent` | 切换自动代理模式（默认开启） | | `/prompt <#> ` | 生成并加载渗透测试提示模板 | | `/prompts` | 列出可用的提示模板及其编号 | | `/status` | 显示连接、模型和会话信息 | | `/model ` | 在运行时切换 Ollama 模型 | | `/native` | 切换原生工具调用与 JSON 回退 | | `/clear` | 清除对话历史 | | `/quit`、`/exit` | 退出客户端 | #### 输入模式 | 模式 | 用法 | |---|---| | 正常 | 输入消息并按回车 | | 多行 | 以 `<<<` 开头，输入多行内容，以 `>>>` 结尾 | | 文件输入 | `@path/to/file.txt` 加载文件内容作为输入 | #### 提示工作流程 mcpstrike 附带渗透测试提示模板。使用它们来引导评估流程： ``` /prompts # list templates with numbers /prompt 1 192.168.1.100 # generate autonomous prompt for target /prompt 2 10.0.0.5 -d example.com # guided prompt with domain go # send any message to start execution ``` 模板位于 `src/mcpstrike/client/prompts/templates/` — 您可以添加自己的 `.txt` 或 `.md` 文件。 ### mcpstrike-server 通过 MCP 协议暴露渗透测试工具的 FastMCP 服务器。 ``` mcpstrike-server ``` 环境变量： | 变量 | 默认值 | 描述 | |---|---|---| | `HEXSTRIKE_BACKEND_URL` | `http://localhost:8888` | 后端 API 地址（hexstrike 或 mcpstrike-backend） | | `MCPSTRIKE_HOST` | `0.0.0.0` | 服务器绑定地址 | | `MCPSTRIKE_PORT` | `8889` | 服务器绑定端口 | | `HEXSTRIKE_SESSION_PATH` | — | 会话文件的绝对路径（优先级最高） | | `HEXSTRIKE_SESSION_DIR` | — | `$HOME` 中的文件夹名称 | ### mcpstrike-backend（可选） 轻量级本地后端 — hexstrike_server 的替代方案。直接在本地机器上以子进程形式执行安全工具。 **需要安装 `backend` 额外组件：** `pipx install ".[backend]"` ``` mcpstrike-backend [OPTIONS] Options: --host TEXT Bind address (default: 0.0.0.0) --port INT Bind port (default: 8888) ``` 环境变量：`HEXSTRIKE_BACKEND_HOST`、`HEXSTRIKE_BACKEND_PORT`。 端点： | 方法 | 路径 | 描述 | |---|---|---| | GET | `/health` | 运行状况检查（含运行时长） | | POST | `/api/command` | 执行命令，返回标准输出/标准错误/退出码 | ### mcpstrike-prompt 独立的提示生成器 CLI。 ``` mcpstrike-prompt --target 192.168.1.100 --template autonomous mcpstrike-prompt --list # list templates mcpstrike-prompt -t 10.0.0.5 -d site.com --dry-run mcpstrike-prompt -t 10.0.0.5 -o ./prompts_out/ ``` ## MCP 工具参考 MCP 服务器暴露了 14 个工具，大型语言模型可以调用： ### 配置 | 工具 | 描述 | |---|---| | `get_config` | 返回当前服务器配置 | | `set_session_directory` | 在运行时更改会话目录 | ### 会话发现 | 工具 | 描述 | |---|---| | `discover_sessions` | 在多个目录中查找会话 | | `import_external_session` | 从外部路径导入会话文件夹 | ### 执行 | 工具 | 描述 | |---|---| | `health_check` | 向后端发送心跳 | | `execute_command` | 在后端执行安全命令 | ### 会话文件 | 工具 | 描述 | |---|---| | `create_session` | 创建新的渗透测试会话 | | `list_sessions` | 列出所有会话 | | `write_session_file` | 向会话文件写入内容 | | `read_session_file` | 从会话文件读取内容 | | `list_session_files` | 列出会话中的文件 | ### 解析器 | 工具 | 描述 | |---|---| | `parse_output` | 解析原始工具输出（nmap、whatweb、nuclei、nikto、dirb） | | `auto_parse_output` | 自动检测工具并路由到正确的解析器 | ### 发现结果 | 工具 | 描述 | |---|---| | `update_session_findings` | 将解析后的发现合并到 session_metadata.json | ## 代理模式 当代理模式开启（默认）时，客户端会运行自动循环： 1. 将对话与系统提示发送给 Ollama 2. 如果模型返回工具调用，则通过 MCP 执行 3. 将工具结果反馈回对话 4. 重复直到模型仅返回纯文本（无工具调用） 安全特性： - **最大迭代次数**：在 20 次连续工具调用后停止 - **上下文修剪**：滑动窗口保留最近 40 条消息，防止 Ollama 上下文溢出 - **Ctrl+C**：随时中止当前生成 - **自动保存**：命令输出自动保存到会话文件 - **自动解析**：输出解析为结构化发现（端口、漏洞等） - **发现持久化**：解析后的发现合并到 `session_metadata.json` ## 提示模板 mcpstrike 附带两个默认提示模板： ### 自主 全自主提示，包含决策框架。模型接收 - 目标信息与范围边界 - 完整工具集参考 - 决策框架（发现 -> 枚举 -> 渗透 -> 文档） - 工具使用最佳实践与反模式 - XSS/SQLi 工作流示例 ### 引导 分阶段编号（0-9）的逐步方法。更结构化，按顺序引导模型完成每个阶段。 ### 自定义模板 将 `.txt` 或 `.md` 文件添加到 `src/mcpstrike/client/prompts/templates/`。使用 `{{PLACEHOLDER}}` 语法： | 占位符 | 描述 | |---|---| | `{{TARGET}}` | 目标 IP 或主机名 | | `{{DOMAIN}}` | 域名 | | `{{SESSION_ID}}` | 自动生成的会话 ID | | `{{DATE}}` | 当前日期 | | `{{TEST_TYPE}}` | 测试类型（black_box、gray_box、web_app、network、full） | ## 配置 所有配置均通过环境变量或 `.env` 文件完成： ``` # 后端（hexstrike-server 或 mcpstrike-backend） HEXSTRIKE_BACKEND_URL=http://localhost:8888 # MCP 服务器 MCPSTRIKE_HOST=0.0.0.0 MCPSTRIKE_PORT=8889 # 客户端 MCPSTRIKE_MCP_URL=http://localhost:8889/mcp OLLAMA_URL=http://localhost:11434 OLLAMA_MODEL=llama3.2 # 会话 HEXSTRIKE_SESSION_PATH=/absolute/path/to/sessions HEXSTRIKE_SESSION_DIR=my_sessions # relative to $HOME ``` ## 项目结构 ``` src/mcpstrike/ config.py # Centralized settings (pydantic-settings) launcher.py # `mcpstrike` entry point — stack launcher with argparse backend/ # OPTIONAL — standalone local backend app.py # FastAPI subprocess execution server server/ wrapper.py # MCPServerWrapper (FastMCP lifecycle) app.py # MCP tool definitions (14 tools) client/ wrapper.py # MCPClientWrapper (JSON-RPC + SSE) ollama_bridge.py # Ollama streaming + tool-call dispatch tui.py # Interactive TUI (rich + prompt_toolkit) prompts/ generator.py # Template manager + prompt generation templates/ autonomous.txt # Full-autonomy pentest prompt guided.txt # Step-by-step guided prompt common/ filenames.py # Smart filename allocation for output formatters.py # Output extraction + report formatting parsers.py # nmap/whatweb/nuclei/nikto/dirb parsers ``` ## 需求 - Python >= 3.10 - 本地运行的 Ollama（或通过 `--ollama-url` 远程访问） - **hexstrike_server** 在 8888 端口运行，或使用 `.[backend]` 安装独立替代方案 - 后台机器上安装安全工具（nmap、nikto、sqlmap 等）

标签：AI安全, AI风险缓解, Chat Copilot, dalfox, FastMCP, Hexstrike, LLM评估, MCP, Model Context Protocol, nikto, Ollama, sqlmap, TUI, XSS, 会话管理, 安全测试, 攻击性安全, 数据统计, 本地安全测试, 渗透测试框架, 漏洞情报, 端口扫描, 终端渗透, 自动化渗透, 输出解析, 逆向工具, 防御