MQ-Sentinel

MQ-Sentinel

生产级、只读的 IBM MQ 诊断 MCP 服务，AI Agent 可以安全使用——零幻觉。

我将它作为一个认真的业余项目开发，旨在解决企业环境中一个真实且影响重大的问题。如今，它已成为一项出色的公开作品集项目，展示了系统工程、安全性、可观测性、生产部署，以及为 AI Agent 构建安全基础设施的能力。

0.5.0 — 覆盖全部 10 种 IBM MQ 类型的 8 个诊断工具。按设计只读。提示词注入防火墙。OIDC + RBAC。哈希链审计。已验证的 IBM Knowledge Center 引用（由 CI 强制执行）。支持 HPA 和气隙部署打包的生产级 Helm。

GitHub： https://github.com/pramodreddyboddu/mq-sentinel
在线演示： https://mq-sentinel.io
让更多人了解它： docs/LAUNCH.md

---

我解决的问题

企业 IBM MQ 团队常常要花数小时诊断以下问题：

• 2035 NOT_AUTHORIZED 风暴
• DLQ 队列暴增
• Native HA 副本延迟和脑裂
• 过时的集群成员
• z/OS 难题

传统工具要求用户具备深厚的专业知识，并手动查阅日志。出于安全和合规考虑，让大模型直接访问 MQ 是不可接受的。

MQ-Sentinel 为 Claude、Cursor、Grok 等 Agent 提供安全的 MCP 接口，返回准确且带有引用的诊断结果，绝不产生幻觉，也不执行破坏性命令。

---

问题

IBM MQ 团队（银行、电信、保险、政府机构）常常要花数小时处理：

• 2035 NOT_AUTHORIZED 通道风暴
• DLQ 队列暴增
• Native HA 副本延迟 / 脑裂
• 过时的集群成员
• z/OS QSG 难题

传统工具要求用户深入掌握 MQSC，并通过 grep 查找日志。让大模型直接访问 MQ，对安全/合规团队来说完全行不通。

MQ-Sentinel 解决了这个问题：为 Claude、Cursor、Grok 等提供安全、只读的 MCP 接口，返回类型化的根因 + 修复步骤 + 已验证的 IBM 文档——绝不编造，也不执行破坏性命令。

---

🎬 90 秒了解它

git clone https://github.com/pramodreddyboddu/mq-sentinel.git
cd mq-sentinel
make demo

观看 MQ-Sentinel 诊断真实的 2035 NOT_AUTHORIZED、INDOUBT 通道、含 1247 条消息的 DLQ，以及 Native HA 副本断连——所有诊断都在捆绑的夹具沙箱中进行。无需运行中的 IBM MQ。

 

想录制下来分享？运行 make demo-record，即可生成可在浏览器中播放的 asciinema 录屏。

快速自检（无需 MQ）：

uv run mq-sentinel doctor
uv run mq-sentinel tools     # list all diagnostics
uv run mq-sentinel info      # overview + security highlights

在 Claude、Grok、Cursor、Gemini、ChatGPT 中使用

一个 MCP 服务，无需为每家供应商单独安装插件。复制粘贴配置：docs/mcp-clients.md。

将它登记到 Agent 查找服务的位置：官方 MCP Registry（server.json）+ Smithery（smithery.yaml）。ChatGPT 需要托管的 HTTPS端点，而不是本地 stdio。

架构概览

flowchart TB
    subgraph Client["MCP Client (Claude / Cursor / Grok)"]
        P[Prompt]
    end

    subgraph Sentinel["MQ-Sentinel (read-only)"]
        OIDC[OIDC + RBAC]
        RL[Rate Limiter]
        DISP[Tool Dispatcher]
        ALLOW[MQSC Allowlist]
        CONN[Connector<br/>(pymqi / fixture)]
        RCS[RCS Engine +<br/>KC Registry]
        SAN[Output Sanitizer]
        AUDIT[Hash-chained<br/>Audit Log]
    end

    subgraph MQ["IBM MQ (read-only service account)"]
        QM[Queue Managers]
    end

    P -->|MCP stdio / HTTP| OIDC
    OIDC --> RL --> DISP
    DISP --> ALLOW
    ALLOW --> CONN
    CONN -->|raw output| RCS
    RCS --> SAN
    SAN --> AUDIT
    CONN --> QM
    QM -.->|DISPLAY only| CONN

安全性由设计保障。服务内部不运行大模型。每条引用都经过 CI 验证。

---

为什么它是一个出色的作品集项目

这不是玩具项目或周末演示。它展现了扎实的工程深度：

• 系统与安全工程：完整的威胁模型、多层只读强制机制、提示词注入防火墙、OIDC+RBAC、防篡改审计、强化容器、SBOM + 签名镜像。
• 生产运维：生产级 Helm（HPA、ServiceMonitor、NetworkPolicy）、气隙环境打包（RPM/DEB）、开箱即用的可观测性。
• AI Agent 基础设施：完整、安全的 MCP 服务（stdio + HTTP），专为 Claude、Cursor 和 Grok 等 Agent 的实际使用而设计。
• 企业领域专业知识：深入覆盖 10 种拓扑下的 IBM MQ，并提供考虑版本差异且经过验证的引用。
• 系统化交付：执行完整的 7 阶段组织就绪计划，并提供实际组织所需的合规材料。

使用 Grok Build（主要编码伙伴）构建，同时坚持严格的工程标准。

完整历程与计划：docs/ORG-READINESS-PLAN.md

另请参阅：VISION.md · CONTRIBUTING.md · DEVELOPMENT.md

---

历程（作品集故事）

我构建了 MQ-Sentinel，旨在解决企业 IBM MQ 环境中一个棘手且反复出现的问题，并将整个项目视为严肃的工程与作品集项目。

从架构设计到实现、文档、Helm、合规材料和润色，我都使用 Grok Build（xAI）作为主要编码伙伴。每一项重大决策都经过深思熟虑：只读优先、引用不会过时、纵深防御、生产级打包。

关键里程碑：

• 在编写第一个工具之前，设计了威胁模型和多层安全架构
• 为 10 种 MQ 变体交付了 8 个诊断工具，并通过 CI 强制要求引用 IBM Knowledge Center
• 生产部署（Helm + HPA + ServiceMonitor、distroless、气隙环境 RPM/DEB）
• 完整执行了 7 阶段组织就绪计划（参见上方链接）
• 271+ 项测试（包括安全负面测试）、严格的 mypy 检查，以及面向平台团队的全面文档

这展现了端到端的全面负责能力：深厚的领域知识、安全内建、生产运维，以及交付实际组织可以真正使用的成果。

这是我的公开作品集项目。 它展现了系统工程、安全、可观测性、AI 基础设施和严谨的交付能力。

使用 Grok Build 构建，并始终坚持高标准。

安全态势——内置于设计，而非事后补救

• 始终只读。 静态 MQSC 允许列表（仅允许 DISPLAY / DIS / PING CHANNEL）。通过三层机制拒绝破坏性动词：工具、连接器和 MQ 侧的 setmqaut。
• 提示词注入防火墙。 所有来自 MQ 的字符串都会经过清理（控制字符、零宽字符、ANSI、Unicode 标签字符、越狱标记），并在离开服务前封装在隔离信封中。
• URL 允许列表 + 实时验证。 响应只能引用 www.ibm.com；所有其他 URL 都会被屏蔽。注册表中的每条引用（20 多个原因代码、8 个 AMQ 代码、18 个主题页面）都会在 CI 中每日抓取——失效链接会导致构建失败，而不是让客户发现问题。
• 防篡改审计日志。 采用哈希链式 JSONL；mq-sentinel verify-audit 可检测任何追溯性修改。
• OIDC + RBAC。 主体的权限范围限定为 nonprod-read / prod-read / admin-audit。无法使用非生产环境令牌查询生产 QM。
• 强化运行时。 Distroless 镜像、非 root 用户、只读文件系统、移除功能、seccomp、网络出口允许列表。
• 供应链。 SBOM、cosign 签名镜像、CI 中的 pip-audit + Trivy，以及每个 PR 的安全门禁。

请参阅 SECURITY.md 和 docs/threat-model.md。

适用于组织 / 企业？
本项目专为真实组织（银行、政府、大型企业）打造。请查看完整历程：

请参阅 VISION.md，了解项目负责人的产品原则和长期思考。

• 组织就绪计划 — 端到端执行的 7 阶段计划
• 生产指南 + 平台团队入门指南
• 安全态势 + SOC2 证据清单
• RBAC 与身份验证示例（Okta、Entra ID、Keycloak）
• 生产级 Helm，支持 HPA、ServiceMonitor、网络策略和集群支持
• 可观测性 — 可直接导入的 Grafana + Prometheus 告警

---

技能与工程严谨性（项目亮点）

本项目展示的能力：

• 系统与安全工程 — 完整威胁模型、提示词注入防御、多层只读强制机制、OIDC+RBAC、哈希链式审计、Distroless 强化。
• 可观测性与生产运维 — 指标、仪表板、告警、运行手册、气隙环境打包、Helm 生产化。
• AI Agent 基础设施 — 构建了一个真实、安全的 MCP 服务（stdio + HTTP），可供大模型安全使用。
• 企业系统 — 深入掌握 IBM MQ，涵盖 10 种拓扑 + 感知版本的诊断。
• 软件工艺 — 271+ 项测试（包括安全测试）、严格的 mypy、ruff、CI 驱动的文档验证、SBOM + cosign 签名。
• 端到端交付 — 从创意到组织就绪的交付物，包括平台团队可实际使用的全面文档。

在保持高工程标准的同时，以 Grok Build 作为主要编码搭档，迭代构建而成。

支持的 IBM MQ 类型（第一阶段已完成）

独立 · 多实例 QM · RDQM · Native HA · Native HA + CRR · 统一集群 · 传统集群 · z/OS 队列共享组 · MQ Appliance · 容器化。

诊断工具

工具	覆盖范围	演示发现
diagnose_failed_channels	分布式通道	2035 NOT_AUTHORIZED、2009/2059 连接错误、INDOUBT、AMQ9202/9208/9503
analyze_dlq_and_suggest_reprocessing	DLQ（仅限标头——绝不读取消息正文）	按原因分组：2035/2080/2030/2051/2053/2079，检测回退循环
check_cluster_health	传统集群 + 统一集群	存储库不完整、CLUSQMGR 过时、成员已挂起、集群通道不健康
diagnose_native_ha_issues	K8s/OpenShift Native HA	副本状态、仲裁、日志重放延迟、脑裂、CRR 延迟
diagnose_rdqm_issues	本地部署的 RHEL RDQM	Pacemaker 仲裁、节点离线、DRBD 连接/磁盘、脑裂
diagnose_zos_qsg_issues	z/OS Queue Sharing Group	QSG 成员、CHIN、页面集、缓冲池、CF 结构
diagnose_multi_instance_issues	传统 MIQM	主动/备用状态、双活脑裂、备用权限、故障转移事件
full_mq_health_check	上述所有类型（组合检查）	执行摘要 + 按优先级排列的发现

支持的 MQ 版本

9.2 LTS、9.3、9.4（包括 9.4.4+）、z/OS。 连接时会自动检测版本；KC 文档链接会根据检测到的版本提供。

安装 — 选择适合你的方式

场景	命令	用时
Claude Code 插件	/plugin marketplace add pramodreddyboddu/mq-sentinel then /plugin install mq-sentinel@mq-sentinel (详情)	1 分钟
个人 / 初创公司笔记本（开发）	curl -fsSL https://raw.githubusercontent.com/pramodreddyboddu/mq-sentinel/main/scripts/install.sh | MQS_DEV_MODE=true MQS_DEV_MODE_ACK_INSECURE=yes bash	5 分钟
个人 / 初创公司（生产环境）	同上，并导出 MQS_AUTH_OIDC_* 环境变量	5 分钟
中型组织 Kubernetes	helm install mq-sentinel oci://ghcr.io/pramodreddyboddu/charts/mq-sentinel --set oidc.issuer=… --set oidc.audience=… --set oidc.jwksUrl=…	30 分钟
本地 K8s 概念验证（无实时 MQ）	cd examples/kind && ./install.sh	5 分钟
RHEL / Rocky / OEL	sudo dnf install https://github.com/pramodreddyboddu/mq-sentinel/releases/latest/download/mq-sentinel-0.4.0-1.x86_64.rpm	5 分钟
Debian / Ubuntu	sudo apt install ./mq-sentinel_0.4.0_amd64.deb	5 分钟
隔离网络环境（银行/政府）	在内部镜像 RPM，使用组织 GPG 签名，通过 Satellite / Aptly 部署	1 晚

完整指南：docs/INSTALL.md。有关 IBM MQ 客户端库，请参阅 docs/byom.md。

连接实际队列管理器

开箱即用时，MQ-Sentinel 会提供捆绑的演示 QM（DEMO_QM）。若要诊断自己的 QM，请设置 MQS_SERVER_INVENTORY_DIR（QM 列表）和 MQS_SERVER_SECRETS_DIR（凭据），并安装 mq 扩展（pymqi，需要 IBM MQ 客户端）。随后，服务会通过仅显示通道建立实时连接。docs/onboard-new-qm.md 介绍了遵循最小权限原则的 setmqaut / CHLAUTH 配置。

快速开始（开发者 / 贡献者）

make install        # uv sync + editable install
make test           # pytest
make ci             # lint + type + tests + security suite (everything CI runs)
make docker         # build the production container image
make rpm deb        # build RPM + DEB packages (requires `gem install fpm`)

参阅：

• DEVELOPMENT.md — 面向项目所有者的开发指南
• docs/usage-with-ai.md — 使用 Claude / Cursor / Grok 时的最佳提示词和模式
• docs/ORG-READINESS-PLAN.md — 达到组织就绪状态的完整历程

传输方式

# stdio (default — for Claude Desktop, Cursor, Claude Code)
uv run mq-sentinel serve

# HTTP (production — OIDC bearer auth, /healthz, /readyz, /metrics)
uv run mq-sentinel serve --transport http --host 0.0.0.0 --port 8080

有关 OIDC 配置、端点参考和运维说明，请参阅 docs/http-transport.md。

仓库结构

src/mq_sentinel/
  security/     command allowlist, output sanitizer, rate limiter
  audit/        hash-chained JSONL audit logger
  auth/         OIDC + RBAC
  inventory/    QM registry (pluggable)
  secrets/      pluggable secrets backend (default: filesystem/K8s)
  connectors/   MQ connection layer (pymqi + fixture)
  rcs/          Root Cause Summary engine + KC doc registry
  tools/        MCP tools (populated Phase 1+)
  telemetry/    OpenTelemetry + structured logging
  cli/          control-plane CLI
deploy/
  Dockerfile    distroless, non-root, read-only FS
  helm/         Kubernetes chart (security defaults on)
tests/
  security/     allowlist + injection firewall corpus (non-negotiable)
  unit/

组织就绪（已执行 7 阶段计划）

本项目有意经过完整的组织就绪计划（7 个阶段），以确保其适用于实际的平台/SRE 团队。查看完整计划和状态：

• docs/ORG-READINESS-PLAN.md
• docs/ORG-READINESS.md — 已完成全部 7 个阶段（截至 2026-06-22）

当前状态：已准备好供平台团队评估。

技术路线图

第 1 阶段（MCP 诊断工具）已完成。未来的技术事项请参阅 CHANGELOG.md：

• 0.4.0 — 根据 RCS 检查结果自动起草 ServiceNow / Jira 工单。
• 0.5.0 — SOC 2 证据包生成器。
• 历史遥测、隔离网络环境改进等。

安全修复有意不在范围内。MQ-Sentinel 仅报告问题。

面向组织

MQ-Sentinel 从设计之初就面向企业使用：

• 只读，可抵御提示词注入，支持 OIDC + RBAC
• 可验证的 IBM Knowledge Center 引用
• 生产部署选项（Kubernetes、RPM/DEB、隔离网络环境）
• 完整的审计跟踪

从这里开始：

• 组织就绪计划
• 生产指南
• 平台团队入门指南
• OIDC 示例
• 安全态势

Helm chart 包含生产环境配置、HPA、监控和网络策略。

许可证

专有 — © 2026 MG。请参阅 LICENSE。IBM® 和 IBM MQ® 是 IBM Corporation 的商标；MG 与 IBM 无关联。