cyberchef-mcp

CyberChef MCP 服务

本项目为 CyberChef 提供 Model Context Protocol (MCP) 服务接口，CyberChef 是由 GCHQ 打造的“网络瑞士军刀”。

通过运行此服务，你可以让 AI 助手（如 Claude、Cursor AI 等）原生地调用 CyberChef 庞大的 504 项数据处理操作 库——包括加密、编码、压缩和取证分析——并将其作为可执行工具使用。

最新版本： v4.2.0 | 版本说明 | 教程 | 示例 | 破坏性变更 | 安全策略

上游基础： GCHQ CyberChef v11.5.0 | 许可证： GPL-3.0-or-later（自 v2.0.0 起；v1.9.x 及更早版本仍为 Apache-2.0）

项目背景

CyberChef 是一个简单、直观的 Web 应用，可在浏览器中执行各种“网络”操作。它最初由 GCHQ 构思并构建。

本分支将 CyberChef 核心的 Node.js API 封装为 MCP 服务，弥合了自然语言 AI 意图与确定性数据处理之间的鸿沟。

分支关系

本项目与上游 GCHQ/CyberChef 仓库保持选择性同步关系：

• 从上游同步：src/core/**（不含三个生成路径）以及 src/node/ 中六个上游所有的 文件。逐字镜像——切勿手动编辑它们；分支的改动以重新应用的补丁形式存在。
• Web UI 组件：已移除（88 个文件，约 19,260 行）——MCP 服务不需要这些
• MCP 专用代码：本分支自有（src/node/mcp-server.mjs、src/node/lib/**、tests/mcp/、 工作流）
• 同步是单向的：仅拉取。自 v2.0.0 起，合并后的工作成果采用 GPL-3.0-or-later，因此 MCP 层的 改动无法回馈给 Apache-2.0 的上游。

确切范围、补丁模型以及同步冲突时的处理方式： 上游同步指南。

有关同步过程的详细信息，请参阅上游同步指南。

功能特性

MCP 工具

该服务将 CyberChef 操作作为 MCP 工具暴露出来：

• 可在 ARM 上运行，体积缩小 30%（v2.8.0）：镜像现已发布 linux/arm64 版本，同时保留 linux/amd64 —— 覆盖 Apple Silicon、Graviton、Raspberry Pi 4/5 —— 镜像体积从 643 MB 降至 453 MB。此外新增 CYBERCHEF_OFFLINE=true，适用于气隙主机：504 个操作中有 502 个本来就不接触网络，因此这是一个针对仅有的两个会联网操作的 fail-closed 开关，检查依据是配方而不是工具名称。架构、规格建议与气隙安装请参见边缘部署指南，体积缩减的实现与验证方式请参见发布说明。
• 可观测（v2.7.0）：在 /metrics 提供一个无依赖的 Prometheus 端点（20 个指标族，默认关闭 —— 与健康探针不同，它会报告哪些工具被使用、使用频率以及输入有多大，这属于侦察面），遵循 MCP 语义约定的 OpenTelemetry span，以及每条日志行上的 trace_id/span_id。它只增加一个包：OTel API，而非 SDK —— 实测为 1 个包 / 2.6 MB / +9 ms，而 SDK 是 71 个包 / 50 MB / +100 ms，后者会让 v2.6.0 在每次 stdio 启动时辛辛苦苦优化掉的启动开销退回一半以上。SDK 由你提供，因此所有 OTLP 后端都能用，而不是只支持选定的少数几个。附带Grafana 仪表盘、告警规则和可运行的 Prometheus 栈 —— 全部在真实服务器上执行过，而不是仅做审阅。工具参数绝不记录：约定将其标记为 Opt-In，而对本服务来说，参数就是敏感材料。
• HTTP 上的 OAuth 2.1 认证（v2.5.0）：本服务充当 OAuth 2.1 资源服务器 —— RFC 9728 受保护资源元数据、基于 JWKS 的 bearer 校验，以及 RFC 8707 受众绑定，后者正是阻止为其他服务签发的令牌在此处被重放的检查。基于 scope 的 RBAC，共三个 scope（cyberchef:read、cyberchef:write、cyberchef:network），其中工具所需的 scope 是由其注解推导出来的，而不是来自一张会过期的表。审计日志记录谁调用了什么。除非设置了 CYBERCHEF_AUTH_ISSUER，否则关闭，并且有意不应用于 stdio —— MCP 规范指出 stdio SHOULD NOT 使用 OAuth，因为当客户端已经拥有该进程时，bearer 令牌保护不了任何东西。
• 多租户（v2.5.0）：操作缓存、配方存储、并发池和审计轨迹按租户隔离，租户从已校验令牌上的 claim 读取（CYBERCHEF_TENANT_CLAIM）—— 绝不从调用方控制的请求头读取。若没有它，共享 HTTP 部署上的任何调用方都能列出、修改和删除其他调用方保存的配方，而 clear() 会一次性销毁所有租户的数据。除非配置，否则关闭，并且在未设置 CYBERCHEF_AUTH_ISSUER 的情况下配置它会直接启动报错，而不是静默降级。
• 约 185 ms 内启动（v2.6.0）：过去需要约 1.3 秒，其中约 1.15 s 用于在回答任何请求之前导入全部 505 个操作实现 —— 每次启动都要付出这个代价，在 stdio 上也是如此，而每个编辑器都是这样启动本服务的。505 个操作的 barrel 现在只由需要它的三个工具加载（cyberchef_search、批量搜索和已保存配方执行）。tools/list 由元数据构建，普通操作调用只加载它所运行的那一个操作 —— 已验证：cyberchef_bake 在完全不加载 barrel 的情况下即可完成。后台预热曾尝试过、测量过，然后被移除：模块加载会阻塞事件循环，因此它只是把开销挪到了第一个请求之前。
• 可作为服务部署（v2.6.0）：提供Helm chart 和 Compose 文件，包含存活/就绪/启动探针，以及滚动更新期间不丢失任何请求的 drain。存活探针在 drain 期间有意保持健康 —— 此时存活探针失败会导致 Pod 在 drain 中途被杀死。该 chart 拒绝渲染服务在启动时会拒绝的配置，因此它们会在 helm template 阶段失败，而不是变成 crashloop。
• 对授权服务器的调用有界（v2.6.0）：JWKS 发现此前没有超时（Node 的 fetch 默认就没有），也完全不缓存失败，因此签发方故障会让每个请求变成两次可能挂起、直到操作系统放弃的外呼。现在有 5 s 截止时间和熔断器：针对宕机签发方的 20 次校验从 40 次外呼尝试降至 10 次。
• 十九个并非操作的分析工具（v2.4.0，历经 v3.11.0 扩展）：最初四个是 cyberchef_xor_key_length（通过重合指数求重复密钥 XOR 的密钥长度）、cyberchef_cyclic_pattern（De Bruijn 模式与溢出偏移，与 pwntools 的 cyclic 字节兼容）、cyberchef_hash_identify（哈希格式及对应的 hashcat 模式和 John 格式名）和 cyberchef_rsa_attack（Fermat、共享因子、Wiener 和无填充小 e）。v3.3.0 又加入十二个（古典密码、crib dragging、熵扫描、哈希破解与统计、JWT 弱点、明文评分、多密钥 RSA、替换密码与 Vigenère 破解、时间戳识别、语料库差异比对），随后是 v3.4.0 的 cyberchef_ecdsa_recover（从复用的 ECDSA nonce 恢复私钥）和 v3.8.0 的 cyberchef_cert_chain（对 X.509 证书包排序，以密码学方式验证每一环，并将链的有效期窗口报告为其各成员有效期的交集，两端都取）。cyberchef_pqc_identify 于 v3.11.0 加入：它能指出密钥、签名或密文背后的 NIST 后量子参数集 —— ML-KEM（FIPS 203）、ML-DSA（FIPS 204）或 SLH-DSA（FIPS 205）—— 有 DER 可读时依据 OID，没有时依据字节长度，后一种情况下它会报告所有候选并明确说明，而不是随便挑一个。参见分析工具。操作是对单个输入执行纯 run(input, args)，无法表达分析；cyberchef_bake 也不行，因为配方是流水线，不是循环。自 v4.1.0 起，在默认的 index 面上通过 cyberchef_analyse({tool, arguments}) 访问它们，而在 curated 和 all 上它们仍被直接列出 —— 其中十九个曾占 index 的 68%，被列出只是因为 cyberchef_describe_operation 拒绝它们并指向 tools/list，这使得列表成为它们唯一的 schema 路径。这里有意没有插件加载器 —— node:vm 不是安全边界，而且这是实测出来的，不是想当然（ADR 0002）。
• 协议修订版 2026-07-28（v2.3.0）：与 2025 时代版本一起，在 stdio 和 HTTP 上由同一套处理器提供服务。现有客户端不受影响 —— v1-SDK 客户端在同一批注册项上仍协商 2025-11-25。在 HTTP 上，两个时代由 SDK 自身的分类器按请求路由，因此 2025 流量保持有会话的接线方式，而现代流量按请求提供服务。
• 三种传输方式（v2.3.0）：stdio、Streamable HTTP，以及通过 Unix 域套接字或回环 TCP 的套接字绑定（CYBERCHEF_TRANSPORT=socket），每个连接一个固定的服务实例。它不携带认证，因此除非显式允许，非回环绑定会被拒绝，Unix 套接字以 0600 创建。这里有意没有 WebSocket 传输 —— MCP 并未定义它。
• 每个图像操作都能正常工作（v2.3.0）：其中 17 个返回的是 Node 的共享缓冲区池而不是图像 —— 输出无法读取，多出来的部分则是该进程最近分配的内容。Add Text To Image 在这个 fork 中自 v1.7.1 起就从未工作过。两者都作为 fork 补丁修复。
• 图像和音频以图像和音频返回（v2.2.0）：Generate QR Code、Render Image 和图像集返回 MCP image 内容块；Play Media 返回 audio 块。在 v2.2.0 之前，html-to-text 转换会删除载荷，这些操作返回空字符串 —— 它们从未在 MCP 上工作过。其他二进制内容保持字节无损的 latin1 文本，或在 CYBERCHEF_BINARY_OUTPUT=base64 时使用 base64。
• 每个工具都带工具注解（v2.2.0）：readOnlyHint、destructiveHint、idempotentHint、openWorldHint 以及可读的 title，这样客户端就能对纯操作跳过审批提示。这些例外是实测出来的，不是猜的 —— 只有 HTTP request 和 DNS over HTTPS 会访问网络，而幂等性则是通过将每个候选运行两次并比较来确定的。
• 提示词与资源（v2.2.0）：五个工作流提示词（analyse-unknown-data、extract-iocs、deobfuscate-script、identify-hash、decode-chain），适用于你还不知道需要 504 个操作中的哪一个时；已保存配方则以可读资源的形式暴露在 recipe://<id>。
• cyberchef_bake：“全能工具”。对输入执行完整的 CyberChef 配方（一串操作）。非常适合复杂的多步转换（例如“先 Base64 解码，再 Gunzip，然后美化 JSON”）。
• 全部 505 个操作，无需为 504 个 schema 付出代价（v2.1.0）：tools/list 默认是一个索引 —— 23 个工具、15,620 字节，而不是 546 个工具、427,123 字节。每个操作仍然可达：cyberchef_categories -> cyberchef_list_operations -> cyberchef_describe_operation 可逐层下探到其中任何一个，cyberchef_search 可按关键词找到某个操作，cyberchef_bake 可按名称运行其中任何一个。19 个分析工具也以同样方式可达，通过 cyberchef_describe_operation 和 cyberchef_analyse —— 在 v4.1.0 之前它们被列在每个面上，其中十九个占 index 的 68%，因为 describe_operation 过去会拒绝它们并指向 tools/list，使列表成为它们唯一的 schema 路径。如果你更愿意预加载，可使用 CYBERCHEF_TOOL_SURFACE=curated（120 个工具、109,548 字节）或 =all（全部 546 个、427,123 字节）；两者仍然直接列出每一个分析工具。参见用户指南。
  • cyberchef_to_base64 / cyberchef_from_base64
  • cyberchef_aes_decrypt
  • cyberchef_sha2
  • cyberchef_yara_rules
  • ...以及数百个更多。
• cyberchef_search：一个实用工具，帮助 AI 发现可用的操作及其描述。
• 配方管理（v1.6.0）：10 个用于保存、组织和复用多操作工作流的工具
  • cyberchef_recipe_create / cyberchef_recipe_get / cyberchef_recipe_list
  • cyberchef_recipe_update / cyberchef_recipe_delete / cyberchef_recipe_execute
  • cyberchef_recipe_export / cyberchef_recipe_import
  • cyberchef_recipe_validate / cyberchef_recipe_test
• 高级功能（v1.7.0）：5 个面向企业级能力的新工具
  • cyberchef_batch - 以并行或串行模式执行多个操作
  • cyberchef_telemetry_export - 隐私优先的使用分析（可选加入）
  • cyberchef_cache_stats / cyberchef_cache_clear - 缓存检查与管理
  • cyberchef_quota_info - 资源配额与用量跟踪
• 迁移工具 —— 已在 v4.0.0 中移除。 cyberchef_migration_preview、cyberchef_deprecation_stats 和 cyberchef-migrate 二进制的存在是为了帮助调用方升级到 v2.0.0，那是九个小版本之前。它们被宣传在每个面上，占用每次 tools/list 的 995 字节，而当时仍在发出的唯一警告是 DEP007 —— 一个已撤回的代码，其自身文本写着“无需操作”。你的 v1 格式配方不需要迁移：位置参数、裸字符串操作和命名对象参数如今烘焙结果完全一致。
  • cyberchef_ 前缀是永久性的。 DEP001、DEP007 和 DEP008 宣布将在 v1.8.0 中移除它，并在 v2.0.0 中被撤回：移除它只能节省 tools/list 载荷的 2.6%，却会在 MCP 的扁平命名空间中造成 19 个工具名冲突，并破坏所有现有集成。请继续使用 cyberchef_to_base64、cyberchef_bake 和 cyberchef_search。参见 v2.0.0 破坏性变更。
• 工作线程池（v1.9.0）：将 CPU 密集型操作卸载到工作线程
  • cyberchef_worker_stats - 监控工作线程池利用率、活动/已完成任务以及池配置
  • 通过 CYBERCHEF_ENABLE_WORKERS=true 环境变量启用
  • 可配置池大小、空闲超时以及路由到工作线程的最小输入大小

技术亮点

• Docker 化：以自包含的 Docker 容器形式运行，基于 Chainguard Wolfi Node.js 基础镜像（撰写时为 v26.8.1），通过摘要固定并由 Dependabot 每周升级。与已发布的 v3.1.0 镜像相比实测：磁盘占用 453 MB，gzip 压缩发布 tarball 为 141 MB，以 UID 65532（nonroot）运行。基础镜像每日重建，且不包含任何包管理器（apk、wget 和 curl 均不存在）——但它确实包含 BusyBox shell 和 npm，因此请将容器被攻破视为已获得可用 shell。此处此前曾声称“无 shell”和“磁盘占用 726 MB”；两者均有误，更正记录见 v3.1.0 基准。
• 双注册表发布：镜像同时发布到 Docker Hub 和 GitHub Container Registry（GHCR），以实现最大可访问性并优化 Docker Scout 健康评分。
• 供应链证明：SBOM 和来源证明附加到 Docker Hub 镜像，以增强安全透明度与合规性（SLSA Build Level 3）。
• 双传输（v1.9.0；自 v2.0.0 起为按会话 HTTP）：通过 CYBERCHEF_TRANSPORT=http 使用 Stdio（默认）或 Streamable HTTP。每个 HTTP 客户端都拥有自己的会话和自己的 MCP 服务实例，并支持 CORS、DNS 重绑定防护和会话上限。参见 HTTP 传输指南。
• 带进度的 MCP 流式传输（v1.9.0）：操作通过 MCP SDK 进度令牌机制发送 notifications/progress，以便在长时间运行的任务期间实时更新状态。
• 工作线程池（v1.9.0）：基于 Piscina 的工作线程将 CPU 密集型操作（AES、Blowfish、bcrypt、scrypt、PBKDF2 等）卸载，以防止事件循环阻塞。池大小和路由阈值均可配置。
• Schema 校验：所有输入都会依据使用 zod 从 CyberChef 内部类型系统派生的 schema 进行校验。
• 现代 Node.js：自 v4.0.0 起要求 Node.js >=26 <27，且已发布镜像运行 Node 26 —— 最低版本与运行时现在为同一版本，而非相差两个主版本。
• 配方管理（v1.6.0）：保存并复用多操作工作流，支持完整 CRUD 操作、多种格式导入/导出（JSON/YAML/URL/CyberChef）、支持嵌套的配方组合，以及涵盖 5 个类别的 25+ 个生产就绪配方精选库。详见 配方管理指南。
• 高级功能（v1.7.0）：企业级能力，包括批处理（最多 100 个操作的并行/顺序执行）、隐私优先的遥测收集（默认禁用，不采集输入/输出数据）、用于保护资源的滑动窗口速率限制、带检查工具的增强缓存，以及资源配额跟踪（并发操作、数据大小）。所有功能均可通过环境变量配置，且默认值安全。详见 发行说明。
• 增强可观测性（v1.5.0）：使用 Pino 进行结构化 JSON 日志记录以支持生产监控、带可操作恢复建议的全面错误处理、带指数退避的自动重试逻辑、通过 UUID 跟踪进行请求关联、用于防止级联故障的熔断器模式，以及用于大型操作渐进式结果的流式基础设施。详见 发行说明。
• 性能优化（v1.4.0）：操作结果的 LRU 缓存（默认 100MB）、大输入自动流式传输（10MB+ 阈值）、可配置资源限制（最大输入 100MB，超时 30s）、内存监控，以及全面的基准测试套件。配置选项参见 性能调优指南。
• 上游同步自动化（v1.3.0；在 v2.0.0 中重建）：每周监控上游发布、原子化整树镜像、以补丁形式携带 fork 变更（若补丁不再适用则同步失败）、全面校验（1,246 个 MCP + 241 个 Node-API + 2,289 个操作测试），以及紧急回滚。参见 上游同步指南。
• 安全加固（v1.4.5+）：Chainguard Wolfi 基础镜像，零 CVE 基准，非 root 执行（UID 65532），带构建失败阈值的自动化 Trivy 漏洞扫描，双 SBOM 策略（Docker Scout 证明 + CycloneDX），只读文件系统支持，SLSA Build Level 3 来源证明，以及关键 CVE 补丁的 7 天 SLA。修复了 12 个代码扫描漏洞中的 11 个，包括关键密码学随机性弱点和 7 个 ReDoS 漏洞。详见 安全策略 和 安全修复报告。
• 生产就绪：全面的 CI/CD，包含 CodeQL v4、自动化测试，以及带完整供应链证明的双注册表容器发布（Docker Hub + GHCR）。

快速开始

前置条件

• Node.js >=26 <27（用于 npm 安装），或者 Docker（用于容器）。

安装方式

方式 1：npm（推荐）

npx cyberchef-mcp

无需克隆、无需构建、无需 Docker 守护进程。对于 MCP 客户端，将其指向同一命令即可：

{
  "mcpServers": {
    "cyberchef": { "command": "npx", "args": ["-y", "cyberchef-mcp"] }
  }
}

也可以永久安装 — npm install -g cyberchef-mcp，然后运行 cyberchef-mcp。 这是该包附带的唯一可执行文件；cyberchef-migrate 已在 v4.0.0 中移除。

方式 2：从 Docker Hub 拉取

# Docker Hub provides health scores and supply chain attestations
docker pull parobek/cyberchef-mcp:latest
docker tag parobek/cyberchef-mcp:latest cyberchef-mcp
docker run -i --rm cyberchef-mcp

方式 2b：从 GitHub Container Registry 拉取（备选）

docker pull ghcr.io/doublegate/cyberchef-mcp_v4:latest
docker tag ghcr.io/doublegate/cyberchef-mcp_v4:latest cyberchef-mcp
docker run -i --rm cyberchef-mcp

方式 3：下载预构建镜像（离线安装）

对于无法直接访问 GHCR 的环境，请从 最新发布 下载预构建的 Docker 镜像 tar 包：

1. 下载 tar 包（压缩后 141 MB；基于已发布的 v3.1.0 资源实测，并非估算）：

   # Download from GitHub Releases
   wget https://github.com/doublegate/CyberChef-MCP/releases/download/v4.2.0/cyberchef-mcp-v4.2.0-docker-image.tar.gz
   

2. 将镜像加载到 Docker：

   docker load < cyberchef-mcp-v4.2.0-docker-image.tar.gz
   

3. 打标签以便使用：

   docker tag parobek/cyberchef-mcp:latest cyberchef-mcp
   

4. 运行服务：

   docker run -i --rm cyberchef-mcp
   

方式 4：从源码构建

1. 克隆仓库：

   git clone https://github.com/doublegate/CyberChef-MCP.git
   cd CyberChef-MCP
   

2. 构建 Docker 镜像：

   docker build -f Dockerfile.mcp -t cyberchef-mcp .
   

3. 运行服务（交互模式）： 此命令会启动服务并监听 stdin。这就是你的 MCP 客户端将要运行的内容。

   docker run -i --rm cyberchef-mcp
   

4. 可选：以增强安全性运行（只读文件系统）： 适用于生产环境中的最高安全性：

   docker run -i --rm --read-only --tmpfs /tmp:rw,noexec,nosuid,size=100m cyberchef-mcp
   

客户端配置

Cursor AI

1. 前往 Settings > Features > MCP。
2. 添加新服务：
   • Name: CyberChef
   • Type: command
   • Command: docker
   • Args: run -i --rm cyberchef-mcp

Claude Code（CLI）

添加到你的配置文件（通常为 ~/.config/claude/config.json）：

{
  "mcpServers": {
    "cyberchef": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "cyberchef-mcp"]
    }
  }
}

Claude Desktop

添加到你的 Claude Desktop 配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "cyberchef": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "cyberchef-mcp"]
    }
  }
}

添加配置后，重启 Claude Desktop。CyberChef 工具将出现在可用工具面板中。

性能与配置

版本 1.4.0 引入了全面的性能优化和可配置的资源限制。所有功能均可通过环境变量进行调整，以满足你的部署需求。

性能特性

操作结果的 LRU 缓存

• 自动缓存操作结果，消除冗余计算
• 可配置缓存大小（默认 100MB）和条目数量（默认 1000）
• 缓存键基于操作 + 输入 + 参数（SHA256 哈希）

大输入自动流式处理

• 超过 10MB 的输入自动使用分块处理
• 支持编码、压缩和哈希操作
• 对 100MB+ 文件进行内存高效处理
• 对非流式操作透明回退

资源限制

• 最大输入大小验证（默认 100MB）
• 操作超时强制执行（默认 30 秒）
• 防止内存溢出崩溃和失控操作

内存监控

• 定期将内存使用情况记录到 stderr
• 跟踪堆和 RSS 以便排查问题

配置选项

每项设置都可以在 cyberchef.config.json 文件中给出，也可以作为环境变量给出， 其中环境变量的优先级高于文件。没有任何设置是必需的：即使没有文件， 服务的行为也与以往完全一致。

{
  "server":   { "maxInputSize": 10485760, "operationTimeout": 30000 },
  "security": { "offline": true },
  "tools":    { "surface": "curated" }
}

格式错误的文件、未知的配置节或未知的设置都会让服务停止启动，并给出指明错误所在的消息， 而不是以无人选择的默认值启动。全部 61 项设置、它们所属的配置节及其对应的环境变量 都记录在**配置指南**中。

与这些设置等价的环境变量：

# Logging (v1.5.0+)
LOG_LEVEL=info                           # Logging level: debug, info, warn, error, fatal

# Retry Logic (v1.5.0+)
CYBERCHEF_MAX_RETRIES=3                  # Maximum retry attempts for transient failures
CYBERCHEF_INITIAL_BACKOFF=1000           # Initial backoff delay in milliseconds
CYBERCHEF_MAX_BACKOFF=10000              # Maximum backoff delay in milliseconds
CYBERCHEF_BACKOFF_MULTIPLIER=2           # Backoff multiplier for exponential backoff

# Streaming (v1.5.0+)
CYBERCHEF_STREAM_CHUNK_SIZE=1048576      # Chunk size for streaming (1MB)
CYBERCHEF_STREAM_PROGRESS_INTERVAL=10485760  # Progress reporting interval (10MB)

# Recipe Management (v1.6.0+)
CYBERCHEF_RECIPE_STORAGE=./recipes.json  # Storage file path
CYBERCHEF_RECIPE_MAX_COUNT=10000         # Maximum number of recipes
CYBERCHEF_RECIPE_MAX_OPERATIONS=100      # Max operations per recipe
CYBERCHEF_RECIPE_MAX_DEPTH=5             # Max nesting depth

# Batch Processing (v1.7.0+)
CYBERCHEF_BATCH_MAX_SIZE=100             # Maximum operations per batch
CYBERCHEF_BATCH_ENABLED=true             # Enable/disable batch processing

# Telemetry & Analytics (v1.7.0+)
CYBERCHEF_TELEMETRY_ENABLED=false        # Privacy-first: disabled by default

# Rate Limiting (v1.7.0+)
CYBERCHEF_RATE_LIMIT_ENABLED=false       # Disabled by default
CYBERCHEF_RATE_LIMIT_REQUESTS=100        # Max requests per window
CYBERCHEF_RATE_LIMIT_WINDOW=60000        # Time window in milliseconds

# Cache Management (v1.7.0+)
CYBERCHEF_CACHE_ENABLED=true             # Enable/disable caching

# Resource Quotas (v1.7.0+)
CYBERCHEF_MAX_CONCURRENT_OPS=10          # Maximum concurrent operations

# (Removed in v4.0.0) V2_COMPATIBILITY_MODE and CYBERCHEF_SUPPRESS_DEPRECATIONS went with the
# deprecation system they configured. Do not set them: the `compatibility` section is now an
# unknown section, and `cyberchef.config.json` fails CLOSED on one -- the server refuses to start
# with "unknown section \"compatibility\"". The env vars are simply ignored.

# Transport (v1.9.0+; per-session HTTP since v2.0.0)
CYBERCHEF_TRANSPORT=stdio                # Transport type: stdio or http
CYBERCHEF_HTTP_PORT=3000                 # HTTP transport port
CYBERCHEF_HTTP_HOST=127.0.0.1            # HTTP bind address (use 0.0.0.0 in a container)
CYBERCHEF_ALLOWED_HOSTS=                 # Comma-separated Host allowlist. DNS-rebinding protection
                                         # is ON by default (loopback names). Set this when binding
                                         # a non-loopback address; `*` disables the check.
CYBERCHEF_ALLOWED_ORIGINS=               # Comma-separated Origin allowlist; enables CORS. Required
                                         # by browser MCP clients (e.g. MCP Inspector's web UI).
CYBERCHEF_SESSION_TIMEOUT=1800000        # Idle HTTP session reap threshold (30 min)
CYBERCHEF_HTTP_MAX_BODY=4194304          # Maximum accepted HTTP request body (4 MiB)
CYBERCHEF_HTTP_PATH=/mcp                 # MCP endpoint path; any other path returns 404
CYBERCHEF_MAX_SESSIONS=100               # Cap on concurrent HTTP sessions; initialize 503s beyond it

# Worker Thread Pool (v1.9.0+)
CYBERCHEF_WORKER_MIN_THREADS=1           # Minimum worker threads
CYBERCHEF_WORKER_MAX_THREADS=4           # Maximum worker threads
CYBERCHEF_WORKER_IDLE_TIMEOUT=30000      # Worker idle timeout in milliseconds
CYBERCHEF_WORKER_MIN_INPUT_SIZE=1024     # Minimum input size for worker routing (bytes)

# Performance (v1.4.0+)
CYBERCHEF_MAX_INPUT_SIZE=104857600       # Maximum input size (100MB)
CYBERCHEF_OPERATION_TIMEOUT=30000        # Operation timeout in milliseconds (30s)
CYBERCHEF_STREAMING_THRESHOLD=10485760   # Streaming threshold (10MB)
CYBERCHEF_ENABLE_STREAMING=true          # Enable streaming for large operations
CYBERCHEF_ENABLE_WORKERS=false           # Enable worker thread pool (disabled by default)
CYBERCHEF_CACHE_MAX_SIZE=104857600       # Cache maximum size (100MB)
CYBERCHEF_CACHE_MAX_ITEMS=1000           # Cache maximum items

配置示例

高吞吐量服务（大文件）

docker run -i --rm --memory=4g \
  -e CYBERCHEF_MAX_INPUT_SIZE=524288000 \
  -e CYBERCHEF_STREAMING_THRESHOLD=52428800 \
  -e CYBERCHEF_CACHE_MAX_SIZE=524288000 \
  -e CYBERCHEF_OPERATION_TIMEOUT=120000 \
  ghcr.io/doublegate/cyberchef-mcp_v4:latest

低内存环境

docker run -i --rm --memory=512m \
  -e CYBERCHEF_MAX_INPUT_SIZE=10485760 \
  -e CYBERCHEF_STREAMING_THRESHOLD=5242880 \
  -e CYBERCHEF_CACHE_MAX_SIZE=10485760 \
  -e CYBERCHEF_CACHE_MAX_ITEMS=100 \
  ghcr.io/doublegate/cyberchef-mcp_v4:latest

带自定义限制的 Claude Desktop

{
  "mcpServers": {
    "cyberchef": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "CYBERCHEF_MAX_INPUT_SIZE=209715200",
        "-e", "CYBERCHEF_CACHE_MAX_SIZE=209715200",
        "ghcr.io/doublegate/cyberchef-mcp_v4:latest"
      ]
    }
  }
}

用于故障排查的调试日志（v1.5.0+）

docker run -i --rm \
  -e LOG_LEVEL=debug \
  -e CYBERCHEF_MAX_RETRIES=5 \
  ghcr.io/doublegate/cyberchef-mcp_v4:latest

用于 CPU 密集型操作的 Worker 线程池（v1.9.0+）

docker run -i --rm \
  -e CYBERCHEF_ENABLE_WORKERS=true \
  -e CYBERCHEF_WORKER_MAX_THREADS=8 \
  -e CYBERCHEF_WORKER_IDLE_TIMEOUT=60000 \
  ghcr.io/doublegate/cyberchef-mcp_v4:latest

用于浏览器/远程客户端的 HTTP 传输（v1.9.0+）

docker run --rm -p 3000:3000 \
  -e CYBERCHEF_TRANSPORT=http \
  -e CYBERCHEF_HTTP_PORT=3000 \
  -e CYBERCHEF_HTTP_HOST=0.0.0.0 \
  -e CYBERCHEF_ALLOWED_HOSTS=localhost:3000,127.0.0.1:3000 \
  ghcr.io/doublegate/cyberchef-mcp_v4:latest

CYBERCHEF_ALLOWED_HOSTS 是 v2.0.0 新增的。DNS 重绑定防护默认开启 —— 在未设置任何内容时， 服务只响应 localhost、127.0.0.1 和 [::1] —— 因此绑定非回环地址意味着需要列出你将用于访问它的 主机名，如上例所示。

回环地址并非豁免对象：DNS 重绑定的存在正是为了访问回环地址，其方式是让受害者的 浏览器将一个攻击者控制的域名解析为 127.0.0.1。浏览器随后将该请求视为 同源，因此不会发送预检请求，CYBERCHEF_ALLOWED_ORIGINS 也就无从谈起。完整 说明请参阅 HTTP 传输指南。

从 v2.0.0 起支持多个客户端同时连接。 在此之前，HTTP 传输是单个 进程级实例，因此第一个连接的客户端会成功，而之后的每个客户端都会被拒绝， 并返回 Invalid Request: Server already initialized（#36）。 现在每个客户端都会获得自己的会话和自己的 MCP 服务实例。请参阅 HTTP 传输指南。

有关详细的性能调优指导，请参阅性能调优指南。

性能基准测试

运行基准测试套件以衡量你的硬件上的性能：

# Install dependencies
npm install

# Generate required configuration
npx grunt configTests

# Run benchmarks
npm run benchmark

基准测试套件在多种输入大小（1KB、10KB、100KB）下测试 20 多项操作，涵盖以下类别：

• 编码操作（Base64、Hex）
• 哈希操作（MD5、SHA256、SHA512）
• 压缩操作（Gzip）
• 加密操作（AES）
• 文本操作（Regex）
• 分析操作（Entropy、Frequency Distribution）

安全性

本项目实现了全面的安全加固，并持续改进：

最新增强（v1.6.0）

• 配方管理系统：保存、组织并复用多操作工作流
  • CRUD 操作：创建、读取、更新、删除配方，并支持版本控制
  • 导入/导出：支持 JSON、YAML、URL 和 CyberChef 格式
  • 配方组合：在配方中嵌套配方，以构建复杂工作流
  • 配方库：5 个类别（密码学、编码、数据提取、取证、网络）中 25+ 个精选示例
  • 验证工具：执行前验证，并支持复杂度估算
  • 测试工具：部署前用示例输入测试配方
  • 10 个新的 MCP 工具：完整的配方生命周期管理
  • 完整使用文档请参阅配方管理指南

增强可观测性 (v1.5.0)

• 增强的错误处理：面向生产调试的全面错误报告
  • 8 种错误码：标准化的错误分类（INVALID_INPUT、MISSING_ARGUMENT、OPERATION_FAILED、TIMEOUT、OUT_OF_MEMORY、UNSUPPORTED_OPERATION、CACHE_ERROR、STREAMING_ERROR）
  • 丰富的上下文：详细的调试信息（输入大小、操作名称、请求 ID、时间戳）
  • 恢复建议：针对常见问题的可操作建议
  • 可重试分类：自动区分暂时性故障与永久性故障
• 基于 Pino 的结构化日志：生产级可观测性
  • JSON 日志：面向监控工具（Datadog、Splunk、ELK）的机器可读日志
  • 请求关联：基于 UUID 的跨操作请求追踪
  • 性能指标：耗时、吞吐量、缓存命中、内存使用
  • 可配置级别：通过 LOG_LEVEL 环境变量设置 debug、info、warn、error、fatal
• 自动重试逻辑：针对暂时性故障的弹性能力
  • 指数退避：1s → 2s → 4s，并加入抖动以防止惊群效应
  • 可配置重试次数：默认 3 次尝试，可通过 CYBERCHEF_MAX_RETRIES 自定义
  • 智能检测：自动重试超时、内存问题、网络错误
  • 熔断器：连续 5 次失败后打开，以防止级联问题
• MCP 流式传输基础设施：面向大型操作的渐进式结果
  • 分块处理：以内存高效的方式处理 100MB+ 输入
  • 进度报告：长时间运行的操作每 10MB 更新一次
  • 14 种受支持操作：编码（Base64、Hex）、哈希（MD5、SHA 系列）、文本操作
  • 可配置阈值：流式传输块大小和进度间隔

安全加固 (v1.4.6)

• Chainguard Wolfi 基础镜像：极简、每日重建、零 CVE 基线
  • 零 CVE 基线：每日安全更新，关键补丁 7 天 SLA
  • 攻击面缩小 70%：相比传统 Alpine/Debian 镜像，操作系统占用极小
  • 非 Root 执行：以 UID 65532（nonroot 用户）运行，镜像中不含任何包管理器
  • SLSA 构建级别 3 来源证明：可验证的供应链完整性
  • 多阶段构建：-dev 变体用于编译，精简运行时变体用于生产
• 只读文件系统支持：生产级不可变部署
  • 支持 docker run --read-only，并为 /tmp 挂载 tmpfs
  • 满足 PCI-DSS、SOC 2、FedRAMP 要求的合规就绪
  • 示例：docker run -i --rm --read-only --tmpfs /tmp:rw,noexec,nosuid,size=100m cyberchef-mcp
• 安全扫描失败阈值：自动化漏洞预防
  • Trivy 扫描器在 CI/CD 中配置为 exit-code: '1'
  • 构建在出现 CRITICAL 或 HIGH 漏洞时自动失败
  • 防止存在漏洞的镜像进入生产环境
• 双 SBOM 策略：全面的供应链透明度
  • 第 1 部分：Docker buildx 证明，用于自动化镜像仓库扫描（Docker Scout）
  • 第 2 部分：Trivy CycloneDX SBOM，用于离线合规审计
  • 两个 SBOM 均作为发布资产附加以供验证

代码安全（v1.4.1+）

• 12 个代码扫描漏洞中已修复 11 个：全面的安全加固已完成
  • 严重：修复了 GOST 库中不安全的密码学随机性——将 Math.random() 替换为 crypto.randomBytes()
  • 高危：解决了 6 个操作中的 7 个 ReDoS（正则表达式拒绝服务）问题
    • 已撤回——该防护已不复存在。 此修复的实现方式是向受影响的操作导入一个 SafeRegex.mjs 辅助模块。这些操作位于 src/core/operations/ 下，而 upstream-sync.yml 会从上游原样复制该目录，因此 后续的一次同步移除了所有导入。该模块已被删除，而不是作为死代码保留， 继续声称提供它已不再提供的防护。
    • 验证过程及其确立的一般规则见事件记录： 在 src/core/** 内进行手工修改，其修复的有效期取决于下一次同步。
• 全部 1,933 项测试通过：安全修复已通过全面的测试套件验证
• 完整详情见安全修复报告

供应链安全（v1.4.5+）

• 带证明的双注册表发布：增强安全透明度与合规性
  • Docker Hub：主要分发渠道，配有 Docker Scout 健康评分监控
  • GitHub Container Registry (GHCR)：次要分发渠道，用于集成 GitHub 生态
  • 两个注册表收到完全相同的镜像，并支持完整的证明
• Docker Scout 证明：构建完整性与软件透明度
  • 来源证明（mode=max）：完整的构建过程元数据（构建器、材料、配方），符合 SLSA 构建等级 3
  • SBOM 证明：以 SPDX-JSON 格式自动生成软件物料清单
  • 在 Docker Hub 上达到最佳 Docker Scout 健康评分（A 或 B 级）
  • 在健康评分计算中占 100 分中的 15 分——属于权重最高的策略类别之一
• 双 SBOM 策略：全面的软件透明度
  • Docker 证明 SBOM：附加到镜像清单，用于基于注册表的验证和 docker sbom 命令
  • Trivy SBOM 产物：独立的 CycloneDX 文件，用于离线审计和合规报告
  • 两个 SBOM 都包含完整的依赖树及版本信息
• Trivy 集成：每次构建都对容器和依赖进行扫描，并设置快速失败阈值
• GitHub 安全选项卡：所有发现均自动以 SARIF 格式上传
• 验证：使用 docker scout quickview 和 docker sbom 命令在本地检查证明

容器安全（v1.4.5+）

• Chainguard Wolfi：零 CVE 基线，每日重建
• 非 root 执行：容器以 UID 65532（nonroot）运行
• 只读文件系统：支持 --read-only 标志，用于不可变部署
• 最小攻击面：无包管理器（apk、wget 和 curl 均不存在），仅包含生产依赖。存在 BusyBox shell 和 npm——在 v3.2.0 之前，此处写的是“无 shell”，但对已发布镜像的实测表明并非如此。请据此评估容器被攻陷后的影响范围。
• 健康检查：内置容器健康监控

密码学加固（v1.2.5）

• Argon2 符合 OWASP 规范：默认参数遵循 OWASP 2024-2025 建议
  • 类型：Argon2id（混合抗侧信道 + 抗 GPU）
  • 内存：19 MiB（OWASP 最低要求）
  • 迭代次数：2（OWASP 针对 19 MiB 的建议值）
• 安全随机数生成：所有密码学操作均使用 crypto.randomBytes() 或 crypto.getRandomValues()
• CVE-2025-64756 已修复：更新 npm 以解决 glob 命令注入漏洞

自动化安全扫描

• CodeQL 分析：持续进行代码扫描，查找安全漏洞
• 每周扫描：定时扫描，捕获新发现的漏洞

安全部署

# Recommended: Run with maximum security options
docker run -i --rm \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=100m \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  cyberchef-mcp

# Note: the image already runs as non-root (UID 65532)
# --read-only requires tmpfs mount for /tmp directory

详细信息，请参阅：

• 安全策略 - 漏洞报告与安全策略
• 安全审计 - 全面的安全评估
• 安全修复报告 - 最新的漏洞修复
• 安全修复摘要 - 快速参考指南

项目路线图

最初的路线图规划了到 2027 年 8 月为止的 6 个阶段、共 19 个版本。它已被超越： 全部六个阶段均已完成，项目已处于 v4.2.0。保留下表是因为它 记录了每个阶段旨在做什么；docs/planning/ROADMAP.md 才是 实时来源，其中为每个已发布的版本各有一行。

阶段	版本	时间线	重点	状态
阶段 1：基础	v1.2.0 - v1.4.6	2025 年 Q4 - 2026 年 Q1	安全加固、上游同步、性能	已完成
阶段 2：增强	v1.5.0 - v1.7.3	2026 年 Q2	流式处理、配方管理、批处理	已完成
阶段 3：成熟	v1.8.0 - v2.0.0	2026 年 Q3	API 稳定化、追赶上游、重新许可、v2.0.0	v2.0.0 已发布
阶段 4：扩展	v2.2.0 - v2.4.0	2026 年 Q4	多模态（v2.2.0 已发布）、协议时效性与传输（v2.3.0 已发布）、工具注册表及其首批四个工具（v2.4.0 已发布）	已完成
阶段 5：企业级	v2.5.0 - v2.7.0	2027 年 Q1	OAuth 2.1、RBAC、审计日志与多租户（v2.5.0 已发布）、水平扩展与部署（v2.6.0 已发布）、指标、追踪与仪表盘（v2.7.0 已发布）	已完成
阶段 6：演进	v2.8.0 - v3.0.0	2027 年 Q2-Q3	边缘部署、AI 原生功能、v3.0.0	已完成 — 而且提前：v3.0.0 于 2026-09 发布，而非 2027 年 Q3
计划之外	v3.1.0 - v4.2.0	2026-09	针对官方套件的一致性、魔法重排序、arm64 基准测试、PQC 识别、退役 v2 迁移接口（v4.0.0）、v4.1.0 中的工具接口工作，以及 v4.2.0 中的调度整合	已发布，其中没有任何一项属于最初的六个阶段

外部项目集成 — 实际产出了什么。 规划树 （外部项目集成，30 份文档）从 8 个安全项目中规划了 80-120 个新工具。 对照已有的 504 个操作逐一衡量后，这一数字被大幅削减： v2.4.0 中发布了四个工具，借鉴了 xortool、pwntools、RsaCtfTool、hashcat 和 John — 而 如今已存在十九个，其中十二个在 v3.3.0 中加入，另外各有一个在 v3.4.0、v3.8.0 和 v3.11.0 中加入。八个项目中有四个没有 贡献任何内容，因为相关能力早已具备 — Magic 覆盖了 Ciphey、Ares 和 katana 核心所做的事情，而 cryptii 的编码在这些操作中有 26 个等价物。 cyberchef-recipes 预设语料库仍未构建。关于 从何处借鉴了什么，请参阅 THIRD-PARTY-NOTICES.md。

关于已发布的内容，请参阅完整路线图；关于正在关注的内容，请参阅v4 规划。这里出现一个主版本号，是因为协议迫使如此，而不是因为编号轮到了。

文档

初次接触？请从教程开始 — 引导你度过第一个小时，从 安装到解码一个真实样本。然后是 examples/，其中有八个可运行脚本， CI 在每次变更时都会执行，因此它们不会与代码脱节。

详细文档组织在 docs/ 目录中：

用户指南

• 用户指南：详细的安装与客户端配置
• 命令参考：所有可用 MCP 工具与操作的列表
• 配方管理指南：保存、组织与复用工作流的完整指南
• 上游同步指南：选择性上游同步工作流指南
• Docker Hub 设置指南：Docker Hub 发布与认证的快速入门指南
• Docker Scout 认证指南：供应链认证与健康评分的全面指南

开发指南

• Codecov 集成指南：覆盖率分析、打包分析与测试分析

技术文档

• 架构：MCP 服务的技术设计
• 技术实现：实现细节
• 性能调优指南：优化性能的配置指南

项目管理

• 产品路线图：v1.1.0 → v3.9.0 已发布，记录每个版本实际发现的内容，而非原计划的内容
• v4 规划：一份经过度量的计划与九份简要章程 —— 以及表明 v4.0.0 尚未排期 的度量结果，因为 MCP 草案规范自 2026-07-28 以来未累积任何变更
• 任务：按版本组织的 500 多项实现任务
• 开发阶段：每个开发阶段的冲刺分解
• 发布计划：各版本的单独规格说明（v1.2.0 - v3.0.0）
• 项目摘要：内部项目概览

战略规划

• 上游同步策略：自动化的 CyberChef 更新监控
• 安全加固计划：Docker DHI、非 root、SBOM 生成
• 多模态策略：通过 MCP 处理图像/二进制/音频
• 插件架构：自定义操作与沙箱化执行
• 企业功能：OAuth 2.1、RBAC、审计日志

v2.0.0 集成规划

• 外部项目集成：v2.0.0+ 集成的全面规划
  • 概览：集成策略与架构（4 个阶段、12 个冲刺、80-120 个新工具）
  • 阶段计划：基础、JavaScript 原生、算法移植、高级
  • 冲刺计划：12 个详细的冲刺分解与任务列表
  • 工具集成计划：各工具的集成策略（Ciphey、cryptii、xortool、RsaCtfTool、John、pwntools、katana、recipes）
  • 技术指南：工具注册、算法移植、测试、依赖

参考文档

• 安全工具参考：11 个安全工具及相关项目的技术文档
  • ares、ciphey：自动解码工具与算法
  • cryptii：模块化编码/解码系统
  • cyberchef-recipes、cyberchef-server：相关 CyberChef 项目
  • john-the-ripper：密码破解与哈希识别
  • katana、pwntools：CTF 与二进制利用工具
  • rsactftool、xortool：密码分析实用工具

安全与发布

• 安全策略：安全策略与漏洞报告
• 安全审计：全面的安全评估
• 安全修复报告：11 项漏洞修复的详细报告（ReDoS 与加密弱点）
• 安全修复摘要：近期安全改进的快速参考
• v2.0.0 破坏性变更：v2.0.0 的全面迁移指南，含弃用代码、示例与 FAQ
• v4.2.0 发布说明：为十个中八个行为一致的场景添加一个元工具——24 个分发分支缩减到 16 个——以及一次两个核心论断皆错的发布：它着手构建的那个门禁自 v3.7.0 起就已存在，而两条"完全相同"的配方分支其实并不相同（recipe_execute 会校验输入大小，recipe_export 被表双重编码）保留了各自的处理。行为保持通过真实客户端逐字节验证，而非仅作断言
• v4.1.0 发布说明：注册表工具获得导航路径并离开默认暴露面——索引从 41 个工具 / 44,968 字节降至 23 / 15,620，且没有任何工具变得不可达，而章程的核心论断在算术上根本不可能成立
• v4.0.0 发布说明：退役 v2 迁移暴露面——弃用系统、两个迁移工具以及 cyberchef-migrate bin，这些在每一个暴露面上为一个已过九个次版本的迁移做宣传
• v3.11.0 发布说明：后量子识别（cyberchef_pqc_identify，全部十八个 NIST 参数集），以及上一个版本警告过的覆盖率余量偏薄在一个版本之后就被触及
• v3.10.0 发布说明：runServer() 在每次测试导入时都会运行，在 23 个文件中武装了 process.exit(1)——而修复它导致覆盖率跌破门禁，因为这个 bug 一直在执行它自己
• v3.9.0 发布说明：一次没有章程的发布，从测量出发划定范围：magic 候选重排序、每个工作流一个 action 版本，以及通过真实客户端测得的暴露面数据
• v3.8.0 发布说明：两个被结转的阻碍因素其实从未被阻碍——arm64 基准测试所用的硬件 CI 其实已经存在，以及 cyberchef_cert_chain
• v3.7.0 发布说明：一个只检查了十一个文件中四个的一致性门禁；其操作计数部分现在能自行发现目标
• v3.6.0 发布说明：基准测试门禁是被测量出来的——通过有意的可调减速得出噪声下限与检测曲线，而非设定一个看似合理的阈值
• v3.5.0 发布说明：同主机基准测试比较，以及自所有权证明落地以来一直返回 count: 0 的 MCP 注册表列表
• v3.4.0 发布说明：三个从未生效的操作，以及 cyberchef_ecdsa_recover
• v3.3.0 发布说明：十二个分析工具——古典密码、crib dragging、熵扫描、哈希破解与统计、JWT 弱点、明文评分、多密钥 RSA、替换密码与 Vigenère 破解、时间戳识别、语料对比
• v3.2.0 发布说明：每个门禁都对照其自身论断进行检查——那个声称自己不可能失败的基准测试工作流，以及两份描述了一个无 shell 基础镜像却实际带有 shell 的文档
• v3.1.0 发布说明：2026 年代编码接缝处的缓存提示，以及被采纳为 oracle 的一致性测试套件
• v3.0.0 发布说明：MCP 2026-07-28 一致性及其迫使的破坏性清理——作用域过滤接入、错误码对齐，以及一个本会静默跳过这次发布本身的 npm 发布守卫
• v2.10.0 发布说明：统一配置文件，在 v2.0.0 宣布、在此才首次真正被读取——61 项设置，env 覆盖 file 覆盖 default，遇到未知键即失败关闭
• v2.9.0 发布说明：呈现输出在缓存之前解析，因此 JSON Beautify 不再返回无法解析的 JSON
• v2.8.1 发布说明：CI 测试受支持 Node 范围的两端，而非只测一端而镜像发布另一端
• v2.8.0 发布说明：在 amd64 之外加入 linux/arm64，以及基础设施扫描
• v2.7.0 发布说明：镜像通过 npm prune --omit=dev 从 643 MB 缩减到 453 MB，以及仅在 API 上的 OpenTelemetry span
• v2.6.0 发布说明：通过延迟对所有 505 个操作的导入，启动时间从约 1300 ms 缩短到约 185 ms；健康探针，以及滚动更新时不丢失任何请求的排空；一个 Helm chart 与 Compose 文件；对授权服务器调用设置 5 s 截止时间与断路器。**重新划定范围：**计划中的 Redis 会话存储解决的是 MCP 2026-07-28 已删除的问题——该协议没有会话。1,246 个 MCP 测试。
• v2.5.0 发布说明：多租户完成 Enterprise Features 里程碑——缓存、配方存储、并发池与审计追踪按租户隔离，身份仅取自已经验证过的 token。另外还有一个自 v1.7.0 以来从未限制过任何东西的速率限制器：它以每请求 UUID 为键，因此针对限制为 5 的 1000 个请求产生了 0 次拒绝和 1000 个泄漏的 map 条目。1,218 个 MCP 测试。
• v2.4.0 发布说明：工具注册表及其最初四个工具——基于重合指数的 XOR 密钥长度、与 pwntools 兼容的 De Bruijn 模式、带 hashcat 模式的哈希识别，以及四种 RSA 攻击。没有插件加载器，并有排除该方案的 node:vm 测量。更正了三份描述了无人做过的工作的文档。
• v2.3.0 发布说明：stdio 与 HTTP 上的协议修订版 2026-07-28、一个 socket 传输、npm 分发解除阻塞、17 个图像操作返回池化的底层 ArrayBuffer（无关字节）而非图像、Add Text To Image 首次生效、覆盖率门禁从 75/70/90/75 提升到 95/88/96/96、1,023 个 MCP 测试
• v2.2.0 发布说明：图像与音频作为内容块（Generate QR Code 曾返回 "" 且从未生效）、全部 527 个工具上的工具注解、提示词与资源、LM Hash 脱离 OpenSSL、未知参数被拒绝而非静默取默认值、955 个 MCP 测试
• v2.1.0 发布说明：工具列表层级（tools/list 缩小约 97%）、Zod 4 schema 修复、全部 10 个流控操作生效、AES 及其他 62 个 toggleString 操作修复、日志输出到 stderr、移除 60s 关闭挂起、教程 + 8 个可运行示例
• v2.0.0 发布说明：上游 v11.4.0（504 个操作）、GPL-3.0-or-later 重新许可、Node 24 最低版本、按会话的 HTTP 传输（#36）、272 项安全发现关闭、757 个 MCP 测试
• 开放告警处置：每一个 Dependabot 与代码扫描告警——已修复、附带理由抑制，或给出原因驳回
• v1.9.0 发布说明：MCP 流式传输、工作线程池、HTTP 传输、上游 v10.20.0、安全更新、689 个测试
• v1.8.0 发布说明：破坏性变更准备——弃用警告、迁移预览工具、v2.0.0 兼容模式
• v1.7.3 发布说明：参考文档与 v2.0.0 集成规划——42 个新文档文件、全面的安全工具参考
• v1.7.2 发布说明：CI 改进、测试扩展、文档更新——增强的工作流、150 个新测试、修正的指标
• v1.7.1 发布说明：仓库清理与工作流增强——移除 88 个未使用文件、增强上游同步
• v1.7.0 发布说明：高级功能——批处理、遥测、速率限制、缓存增强、资源配额
• v1.6.2 发布说明：技术债修复——解决 ESLint 错误、修正 ENABLE_WORKERS 默认值
• v1.6.1 发布说明：全面的测试覆盖（311 个测试，78.93% 覆盖率）与 Codecov 集成
• v1.6.0 发布说明：带 CRUD 操作、导入/导出与精选库的配方管理系统
• v1.5.0 发布说明：增强的错误处理、结构化日志、自动重试、流式传输基础设施
• v1.4.6 发布说明：Sprint 1 安全加固——Chainguard distroless 迁移、零 CVE 基线、只读文件系统支持
• v1.4.5 发布说明：供应链证明与文档重组
• v1.4.4 发布说明：Docker Hub 构建修复与 12 项安全漏洞修复
• v1.4.3 发布说明：依赖解析与 Node.js 22 兼容性
• v1.4.2 发布说明：CI/CD 改进与零警告工作流
• v1.4.1 发布说明：安全补丁——修复 11 项代码扫描漏洞
• v1.4.0 发布说明：借助缓存、流式传输与资源限制的性能优化
• v1.3.0 发布说明：带全面测试的上游同步自动化
• v1.2.6 发布说明：面向 Web 应用的 nginx:alpine-slim 优化
• v1.2.5 发布说明：带 OWASP Argon2 加固的安全补丁
• v1.2.0 发布说明：安全加固发布
• v1.1.0 发布说明：安全修复与 Node.js 22 兼容性
• v1.0.0 发布说明：MCP 服务初始发布

开发

本地设置

如果你想在没有 Docker 的情况下修改服务代码：

0. 使用固定版本的 Node。 .nvmrc 固定为 26（与 engines: >=26 <27 以及所有 CI 工作流一致），因此 nvm use / fnm use 会选择该版本。这一点值得主动执行而不是想当然：直到 v4.0.0 为止，该文件写的是 24，而版本下限早已是 26，因此版本管理器在整个发布周期内都悄悄 选择了一个低于下限的 Node。

   nvm use    # 或：fnm use
   node --version   # 预期为 v26.x
   

1. 安装依赖：

   npm install
   

2. 生成配置：（构建内部操作列表所必需）

   npx grunt configTests
   

3. 运行服务：

   npm run mcp
   

CI/CD

本项目使用 GitHub Actions 来确保稳定性与安全性：

核心开发工作流：

• MCP Server CI（core-ci.yml）：在 Node.js 26 上测试底层 CyberChef 逻辑与配置生成
• Docker Build（mcp-docker-build.yml）：构建、验证并对 cyberchef-mcp Docker 镜像进行安全扫描
• Pull Request Checks（pull_requests.yml）：针对拉取请求的自动化测试与验证
• Performance Benchmarks（performance-benchmarks.yml）：针对代码变更的自动化性能回归测试（v1.4.0+）

代码质量与覆盖率：

• Codecov 集成：全面的代码质量分析，包含三个独立组件
  • 覆盖率分析：使用 V8 提供程序进行自动化覆盖率跟踪，并在拉取请求上执行状态检查
    • 项目覆盖率阈值：95%（codecov.yml）
    • 补丁覆盖率阈值：新代码为 90%
    • 多种覆盖率格式：lcov、JSON、HTML、Cobertura
    • 组件级跟踪：MCP Server、Core Operations、Node API
  • Bundle 分析：通过 @codecov/webpack-plugin 进行 Webpack bundle 大小跟踪与可视化
    • 在拉取请求中自动检测 bundle 大小变化
    • 历史 bundle 大小趋势与优化洞察
    • 用于本地开发的 dry-run 模式
  • 测试分析：JUnit XML 测试结果报告与分析
    • 随时间跟踪测试性能
    • 检测不稳定测试
    • 监控测试执行时间
  • 配置：codecov.yml、覆盖率 flags、阈值、PR 评论
  • 完整的设置与使用文档见 Codecov Integration Guide

安全与发布工作流：

• Security Scan（security-scan.yml）：Trivy 漏洞扫描、SBOM 生成、每周定时扫描
• CodeQL Analysis（codeql.yml）：针对代码漏洞的自动化安全扫描（CodeQL v4）
• Release（mcp-release.yml）：在版本标签（v*）上发布 Docker 镜像至 GHCR 并附带 SBOM，自动创建 GitHub releases

上游同步自动化（v1.3.0+）：

• Upstream Monitor（upstream-monitor.yml）：每周（周日 UTC 中午）监控 GCHQ/CyberChef 的新版本，创建 GitHub issue 以供审核
• Upstream Sync（upstream-sync.yml）：选择性文件同步工作流 - 仅复制 src/core/operations/*.mjs 文件，防止被删除的 Web UI 组件被恢复，创建 PR 以供审核
• Rollback（rollback.yml）：带有状态比较与 ref-proj 指引的紧急回滚机制

所有工作流均使用最新的 CodeQL Action v4 进行安全扫描与 SARIF 上传。

测试

# Run all tests (requires Node.js >=26 <27; 241 Node-API + 2,289 operation tests)
npm test

# Run MCP validation test suite (1,728 tests across 75 files, with Vitest)
npm run test:mcp

# Run MCP tests with coverage report
npm run test:coverage

# Run performance benchmarks (v1.4.0+)
npm run benchmark

# Test Node.js consumer compatibility
npm run testnodeconsumer

# Lint workflows (matches the CI gate)
actionlint .github/workflows/*.yml

# Lint code
npm run lint

测试覆盖率： MCP 服务保持全面的测试覆盖率：

• 1,728 个 MCP 测试，分布在 75 个套件中，另有 241 个 Node-API 测试、2,289 个操作测试和 9 个可运行示例由 CI 执行
• 覆盖率阈值（vitest.config.mjs）：行 96%、语句 95%、分支 89%、函数 96%，其中 src/node/lib/** 单独保持为行 99 / 语句 99 / 分支 94 / 函数 100
• 当前覆盖率：行 96.44%、语句 95.50%、函数 96.84%、分支 89.88%（阈值为 96/89/96/95，对应行/分支/函数/语句）
• 注意：此处不列出各个套件名称，因为该列表已三次过时； ls tests/mcp/*.test.mjs 才是权威来源。

贡献

欢迎为 MCP 适配器做出贡献！我们欢迎：

• 缺陷报告：提交 issue 并附上详细的重现步骤
• 功能请求：先查看 Roadmap，然后提交 issue
• 拉取请求：查看 Tasks 了解需要开展工作的领域
• 文档：随时欢迎对指南和示例进行改进

开发工作流

1. Fork 仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 进行修改并充分测试
4. 使用约定式提交信息进行提交（feat:、fix:、docs: 等）
5. 推送到你的 fork 并提交拉取请求

如需为核心 CyberChef 操作做出贡献，请注明原始 GCHQ 仓库。

仓库信息

• 原始 CyberChef：GCHQ/CyberChef
• MCP 分支：doublegate/CyberChef-MCP
• 容器镜像仓库：
  • Docker Hub（主）：parobek/cyberchef-mcp - 带有 Docker Scout 健康评分和证明
  • GHCR（次）：ghcr.io/doublegate/cyberchef-mcp_v4 — v4.x。包名中带有主版本号，因此每条产品线保留各自的镜像，不会被原地取代：v3.x 仍位于 cyberchef-mcp_v3，v2.x 位于 cyberchef-mcp_v2。
  • GHCR（v1，已冻结）：ghcr.io/doublegate/cyberchef-mcp_v1
    • 仍可拉取；在 v1.9.x 产品线上接收仅安全类补丁，直至约 2027 年 3 月。
    • Apache-2.0，而非 GPL-3.0-or-later。
    • 仍然存在 #36 所报告的单一进程级 HTTP 传输， 因此同一时间只能有一个 HTTP 客户端连接。已在 v2.x 中修复，未向后移植。
• npm 包：cyberchef-mcp — 自 v2.5.0 起，每个版本标签 由 CI 发布。npx cyberchef-mcp 无需安装即可运行该服务； npm install -g cyberchef-mcp 会安装 cyberchef-mcp 命令。该包正是 MCP registry 列表中指向的制品，因此发布任务会等待 npm 提供该包后再 发布该列表。
• Glama 列表：doublegate/CyberChef-MCP — 一个独立的第三方目录，它会启动该服务并对其进行内省，而非 阅读其 README，并根据所发现的内容对质量和维护情况进行评分。所有权声明 位于仓库根目录的 glama.json。上方和下方的徽章 实时显示其当前评分；此处有意不将其转录到本文件中，因为从 服务中复制出来的数字终将过时。
• 问题追踪：GitHub Issues

支持

如果你觉得本项目有用，可以考虑支持其开发：

许可

自 v2.0.0 起，CyberChef-MCP 以 GPL-3.0-or-later 许可发布。 1.9.x 及更早版本仍为 Apache-2.0，不受影响。

上游 CyberChef 以 Apache 2.0 许可发布，并受 Crown Copyright 保护。从上游继承的文件保留其 Apache-2.0 头信息；完整文本保存在 LICENSE.Apache-2.0 中。这并非对 GCHQ 代码的重新许可——而是组合作品采用 GPLv3，Apache-2.0 对 GPLv3 的单向兼容性允许这样做。

这一变更源于 v2.0.0 引入了来自 GPL 许可参考工具的算法：katana 为 GPL-3.0-or-later（排除了 GPLv2），而 John the Ripper 为 GPL-2.0-or-later，同时 Apache-2.0 与 GPLv3 兼容但与 GPLv2 不兼容。GPL-3.0-or-later 是唯一同时接纳这三者的许可。相关推理记录在 ADR 0001 中，各组件归属信息见 THIRD-PARTY-NOTICES.md。

这对您意味着什么： 运行 CyberChef-MCP——包括通过 HTTP 提供服务——不承担任何义务，因为 GPLv3 没有网络使用条款。但分发其衍生作品则需承担义务：该衍生作品也必须采用 GPLv3。如果您的政策不允许 GPLv3，请继续使用 v1.9.x 系列，该系列仍为 Apache-2.0，并在其 LTS 窗口期内仅接收安全补丁。