qualys-mcp

Qualys MCP

一个用于完整管理 Qualys 门户的 Model Context Protocol 服务，可向任何兼容 MCP 的客户端（Claude 和其他 MCP 主机）提供 VMDR、Policy Compliance、WAS、Cloud Agent、Container Security、TotalCloud、Patch Management、CSAM/GAV、EASM 和管理功能。

每个 Qualys 控制台运行一个进程（可根据订阅数量运行多个进程）。本项目基于 FastMCP 构建，使用单个客户端处理全部 三类 Qualys API，并采用严格的只读 / 写入 / 破坏性操作安全模型，凭据绝不会接触聊天内容或以明文形式存储。

---

主要特点

• 覆盖范围广 — 59 个自动发现的功能模块，涵盖整个 门户：VMDR、PC、WAS、Cloud Agent、Container Security、TotalCloud/CloudView、 Patch Management、CSAM/GAV、EASM、FIM、EDR、PCRS 和管理功能。
• 约 400 个工具 — list_hosts、list_host_detections、launch_scan、 search_was_findings、list_knowledgebase、get_cs_image_vulnerabilities 等数百个工具，每个工具均与有文档记录的 Qualys API 操作一一对应。
• 三类 API，一套客户端 — 经典“FO” XML API、QPS REST API 和通过 JWT 认证的 Gateway 均由 self._fo / self._qps / self._gateway 处理。
• 安全级别至关重要 — 每个工具都标注为只读、写入或破坏性操作。除非你针对每个控制台选择启用，否则破坏性工具（删除 / 清除 / 停用）不会注册；即使启用，每次调用仍需提供确认令牌。
• 惰性身份验证 — 导入或构造时不会发起网络调用；--check 可在完全离线且无需凭据的情况下运行。
• 严格保密 — 在 Windows 上，凭据仅存储在 DPAPI 加密的数据块中；在任何操作系统上，你都可以通过环境变量提供凭据。任何内容都不会写入代码仓库。

三类 API

类型	基础路径	身份验证	负载
经典“FO”	/api/2.0/fo/、/msp/	Basic + X-Requested-With 标头	表单 → XML
QPS REST	/qps/rest/	Basic	XML <ServiceRequest> / JSON
Gateway	gateway.<pod>.apps.qualys.com	Bearer JWT（来自 /auth）	JSON

架构

qualys_mcp/
  server.py     FastMCP server; lazy auth; --check offline validation
  registry.py   auto-discovers modules/*.py
  client.py     one client, three API regimes (FO / QPS / Gateway-JWT)
  config.py     per-console config + platform (POD) -> URL map
  common/       auth (HTTP mw), errors, logging, rate_limit, utils, xml
  modules/      base.py + one file per feature module (the bulk of the surface)

只需将文件放入 qualys_mcp/modules/ 即可添加功能 — 参见 docs/MODULE_BUILD_GUIDE.md。

快速开始

1. 安装

python -m venv .venv
# Windows:      .\.venv\Scripts\pip install -e .
# macOS/Linux:  ./.venv/bin/pip install -e .

2. 离线检查（无需凭据）

python -m qualys_mcp --check

列出所有发现的模块及其工具数量，然后退出 — 可用于初步冒烟测试。

3. 提供凭据

你需要一个 Qualys API 用户以及你的平台 / POD 代码（例如 US1、US2、 EU1；可在控制台 URL 中查找，或前往 Help → About 查看）。

任何操作系统 — 环境变量：

export QUALYS_USERNAME='api-user'
export QUALYS_PASSWORD='api-pass'
export QUALYS_PLATFORM='US2'          # or set QUALYS_API_URL / QUALYS_GATEWAY_URL
python -m qualys_mcp --transport streamable-http --host 127.0.0.1 --port 8781 --console-label consulting

Windows — DPAPI 加密数据块（推荐用于持久化部署）：

# Encrypt once per console; the blob is user-scoped and stored under .secrets/
.\encrypt-qualys-creds.ps1 -Console consulting -Platform US2
.\encrypt-qualys-creds.ps1 -Console cloud      -Platform US2

# Launch one instance per console (:8781, :8782)
.\start-qualys-mcp.ps1
#   ...opt into destructive tools for a console only when you mean it:
.\start-qualys-mcp.ps1 -EnableDestructive cloud

# Optional: keep both alive across reboots via a Scheduled Task watchdog
.\register-qualys-mcp-task.ps1

请参阅 .env.example，了解所有 QUALYS_* 设置。

4. 将 MCP 客户端连接到服务

随附可直接使用的 .mcp.json，适用于 Claude Code：

{
  "mcpServers": {
    "qualys-consulting": { "type": "http", "url": "http://localhost:8781/mcp" },
    "qualys-cloud":      { "type": "http", "url": "http://localhost:8782/mcp" }
  }
}

scripts/register_mcp_clients.py 展示了如何将相同的本地 HTTP 服务一次性注册到多个 MCP 客户端。

安全模型

• 工具标注为只读、写入或破坏性。
• 除非控制台以 QUALYS_ENABLE_DESTRUCTIVE=true 运行，否则不会注册破坏性工具（删除、清除、停用、卸载）。
• 即使启用了破坏性工具，每个工具也必须收到匹配的 confirm=<id> 参数才会执行，因此绝不会因单条提示词而意外触发破坏性操作。

完整的分级说明请参阅 docs/SAFETY_AUDIT.md。

模块和工具清单

• 从 qualys_mcp/modules/ 自动发现 59 个模块。
• 默认注册 约 360 个工具；启用 QUALYS_ENABLE_DESTRUCTIVE=true 后注册 约 400 个（额外的约 40 个是受保护的破坏性工具，否则会保持隐藏）。
• 分布在三种 API 类型中，少数模块涵盖其中两种。

每个模块的完整表格（注册表名称、API 系列、工具数量和单行说明）请参阅 docs/MODULE_INDEX.md；端点 → 工具 → 操作的完整明细请参阅 docs/ENDPOINTS_TOOLS_ACTIONS.md。

配置参考

变量	用途
QUALYS_USERNAME / QUALYS_PASSWORD	API 用户凭据
QUALYS_PLATFORM	POD 代码（US1…KSA1）——自动填入 API 和 Gateway URL
QUALYS_API_URL / QUALYS_GATEWAY_URL	为未列出的 POD 显式指定覆盖值
QUALYS_CONSOLE_LABEL	在日志中为控制台命名，并设置服务名称
QUALYS_ENABLE_DESTRUCTIVE	设为 true 以注册破坏性层级
QUALYS_MCP_MODULES	以逗号分隔的允许列表，用于将控制台限定为已获许可的模块
QUALYS_MCP_API_KEY	HTTP 传输的可选共享密钥

开发

pip install -e ".[dev]"
python -m qualys_mcp --check   # offline validation
pytest                          # unit tests (no network)
ruff check .                    # lint

欢迎贡献——请参阅 CONTRIBUTING.md。

免责声明

这是一个独立的社区项目，与 Qualys, Inc. 无关联、未获认可或支持。“Qualys”和产品名称均为各自所有者的商标。请根据 Qualys 许可和 API 条款，将本项目用于你自己的订阅。软件按“原样”提供（请参阅 LICENSE）；你需对在自身环境中运行的操作负责，尤其是破坏性层级。

Star 历史

许可证

MIT © 2026 Rijul Sharma