matteocolazilli/GreenboneMCP

# GreenboneMCP 一个 MCP (Model Context Protocol) 服务器，通过 GMP (`python-gvm`) 将 AI 客户端连接到 Greenbone/OpenVAS。 ## 项目简介 `GreenboneMCP` 为 Greenbone/OpenVAS 中的扫描/报告工作流暴露了 MCP 工具，以便助手可以： - 创建并启动扫描， - 监控扫描进度， - 停止扫描， - 获取报告， - 对比运行之间的报告差异。 该服务器运行在 `stdio` 传输层上，并通过 Unix socket 与 `gvmd` 通信。 ## 项目状态 本项目是我的硕士论文的一部分，目前是一个概念验证。 仅当有明确的社区/用户兴趣时，才可能进一步开发。 欢迎贡献：随时打开 **Issues** 并提交 **Pull Requests**。（参见下方的 [贡献指南](README.md#contributing) 部分。） ## 服务器暴露的工具 ### 扫描工作流工具 这些工具始终被注册： - `start_scan` - `scan_status` - `fetch_latest_report` - `restart_scan` - `delta_report` ### 检查 / 控制工具 这些工具始终被注册： - `get_targets` - `get_target` - `get_tasks` - `get_port_lists` - `start_task` - `stop_task` ## 项目结构 ``` src/ ├── main.py # App entrypoint (stdio MCP server) ├── constants.py # Default UUIDs and report format constants ├── config/ │ ├── gvm_client_config.py # Env-based GVM client settings (USERNAME, PASSWORD, ...) │ └── logging_config.py # Logging configuration settings ├── core/ │ └── mcp_server.py # MCP wiring, GVM connection, tool registration ├── services/ │ └── gvm_client.py # Typed wrapper around python-gvm + XML parsing ├── tools/ │ ├── vm_workflow_tools.py # VM workflow orchestration tools │ ├── inspection_control_tools.py # Inspection/control tools for existing scan state │ └── utils/ │ ├── constants.py # Tool-scoped constants (scanner/config/port list IDs, formats) │ └── helpers.py # Internal parsing/formatting helpers for tool outputs └── models/ └── generated/ # Auto-generated dataclasses (xsdata output) ``` ## 系统要求 - Docker Engine + Docker Compose 插件 - 拥有可访问 `gvmd` Unix socket 的 Greenbone/OpenVAS 实例 - 有效的 GMP 凭证 ## 安装说明 ### 兼容性 此服务器仅在通过容器部署的 Greenbone/OpenVAS 上进行了测试，特别是使用官方容器设置的 Greenbone Community Edition：https://greenbone.github.io/docs/latest/22.4/container/ ### 前置条件 通过在包含 Greenbone `docker-compose.yml` 的目录中执行以下命令，确保官方 Greenbone Community Edition 容器设置正在运行： ``` docker compose -f /docker-compose.yml up -d ``` **注意**：官方 Greenbone compose 设置使用挂载在容器中 `/run/gvmd` 路径下的 `gvmd_socket_vol` 卷。 使用默认的 compose 配置，该命名卷通常可通过以下名称访问： `greenbone-community-edition_gvmd_socket_vol`。 在此项目中，使用相同的命名卷从 MCP 服务器容器访问 `gvmd` socket。 ### 1) 克隆此仓库 ``` git clone https://github.com/matteocolazilli/GreenboneMCP.git cd GreenboneMCP ``` ### 2) 构建此 MCP 镜像 ``` docker build -t greenbonemcp:latest . ``` ### 3) 创建 `.env` 配置并设置配置值 ``` cp .env.example .env ``` 使用你的凭证和所需设置编辑 `.env`。 你可以在运行时通过 `--env-file` 将此 `.env` 传递给 `docker run` 命令来使用它。 服务器从以下环境变量读取配置，如果未设置，则回退到默认值： - `USERNAME`：GMP 用户名（默认值：`admin`） - `PASSWORD`：GMP 密码（必填：无默认值，必须设置） - `LOG_LEVEL`：应用程序日志级别（默认值：`INFO`） ### 4) 配置 MCP 客户端并运行服务器 根据文档配置你的 MCP 客户端/代理，使用以下 `docker run` 命令运行 GreenboneMCP 服务器： ``` docker run --rm -i --env-file --name greenbonemcp --volume greenbone-community-edition_gvmd_socket_vol:/run/gvmd greenbonemcp:latest ``` **注意**：`--env-file` 路径必须指向你在第 3 步中创建的 `.env` 文件。 ### 5) 尽情使用！ 使用你的 MCP 兼容助手，通过此服务器暴露的工具与 OpenVAS 进行交互！ ## 贡献指南 - 打开 Issue 用于报告错误、提出想法或功能请求。 - 打开 Pull Request，包含集中的更改和清晰的描述。 欢迎并鼓励社区贡献。 ### 工具模块约定 为了保持工具模块的可维护性： - 将 MCP 工具处理程序保留在 `src/tools/*_tools.py` 中 - 将非工具辅助函数（解析、格式化、输出整形）保留在 `src/tools/utils/` 下（例如 `src/tools/utils/helpers.py`） - 使用 `src/services/gvm_client.py` 处理 GMP 交互原语，并将编排逻辑保留在工具处理程序中 ### 开发新工具 如果你想添加新的 MCP 工具（例如通过封装额外的 `python-gvm` 方法），你可能需要用于 XML 响应的新类型化模型。 此项目在 `src/models/generated` 下包含模型。 #### 添加新的数据类（当前方法） 目前，当你需要用于额外 GMP 响应的新数据类时，请手动添加它们。 推荐的工作流程： 1. 收集你想要支持的 GMP 方法的代表性 XML 响应。 2. 使用 `src/models/generated` 中的现有模型作为命名、类型和结构的参考。 3. 手动创建/更新数据类以匹配你需要的 XML 形状。 `gvm-tools` / `gvm-pyshell` 是从你的 Greenbone 实例获取真实 XML 响应样本的实用方法。 ## 许可证 本项目采用 **GNU GPL v3.0 或更高版本** 许可。 有关完整的许可证文本，请参见 [`LICENSE.md`](LICENSE.md)。 ## 第三方声明 本项目包含并依赖于第三方开源软件。 有关直接依赖项及其许可证的详细信息，请参见 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md)。

标签：AI 助手, AI 安全, FTP漏洞扫描, GMP 协议, GPT, GraphQL引擎检测, Greenbone, GUI应用, LLM 插件, MCP Server, Model Context Protocol, OpenVAS, PHP, Python, python-gvm, Rust语言, stdio 传输, 主机安全, 加密, 安全编排, 密码管理, 差异报告, 报告分析, 插件系统, 无后门, 概念验证, 漏洞扫描器, 漏洞管理, 网络安全, 请求拦截, 逆向工具, 隐私保护