rijul170/qualys-mcp
GitHub: rijul170/qualys-mcp
基于 MCP 协议的 Qualys 全功能管理服务器，将近 400 个 API 工具以分层安全模型暴露给 AI 客户端使用。
Stars: 0 | Forks: 0
# Qualys MCP
` / JSON |
| Gateway | `gateway..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](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 加密的数据块（推荐用于持久化部署）：**
```
# 每个 console 加密一次；该 blob 是用户范围的，并存储在 .secrets/ 下
.\encrypt-qualys-creds.ps1 -Console consulting -Platform US2
.\encrypt-qualys-creds.ps1 -Console cloud -Platform US2
# 通过 Launch 为每个 console 启动一个实例，分别对应 (:8781, :8782)
.\start-qualys-mcp.ps1
# ... 只有在你确实需要 active 时，才将它们作为 destructive tools 引入 console：
.\start-qualys-mcp.ps1 -EnableDestructive cloud
# 可选：通过 Scheduled Task watchdog 保持两者在 reboots 后依然 alive
.\register-qualys-mcp-task.ps1
```
有关每个 `QUALYS_*` 设置，请参见 [.env.example](.env.example)。
### 4. 将您的 MCP 客户端指向它
包含一个可直接用于 Claude Code 的 [`.mcp.json`](.mcp.json)：
```
{
"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=`
参数 — 因此，绝不可能因为单个 prompt 而意外执行破坏性调用。
阅读 [docs/SAFETY_AUDIT.md](docs/SAFETY_AUDIT.md) 了解完整的分层信息。
## 模块与工具清单
- 从 `qualys_mcp/modules/` 自动发现的 **59 个模块**。
- 默认注册了 **~360 个工具**；启用 `QUALYS_ENABLE_DESTRUCTIVE=true` 后为
**~400 个**（额外的约 40 个是受保护的破坏性
工具，否则它们将保持隐藏状态）。
- 分布在三种 API 体系中，少数模块跨越了其中两种。
完整的模块明细表（注册表名称、API 系列、工具数量、一句话描述）位于 [docs/MODULE_INDEX.md](docs/MODULE_INDEX.md) 中，而完整的
endpoint → 工具 → 操作分解位于
[docs/ENDPOINTS_TOOLS_ACTIONS.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](CONTRIBUTING.md)。
## 免责声明
这是一个独立的社区项目。它**不附属于 Qualys, Inc.，也未得到其
认可或支持。** "Qualys" 和产品名称是
其各自所有者的商标。请根据您的 Qualys 许可证和 API 条款，针对您自己的订阅使用本软件。本软件按
“原样”提供（参见 [LICENSE](LICENSE)）；您需对您在
您的环境中运行的内容负责 — 特别是破坏性层级。
## Star 历史
## 许可证
[MIT](LICENSE) © 2026 Rijul Sharma
标签：DevSecOps, GPT, MCP, Python, Qualys, 上游代理, 安全管理, 无后门, 漏洞管理, 逆向工具