v2.10.0 release notes

Release Date: 2026-09-03 Upstream Base: CyberChef v11.4.0 (unchanged) Licence: GPL-3.0-or-later Node: >=24 <27

Highlights

The configuration file this project has been telling users to write since v1.8.0 now exists.

docs/v2.0.0-breaking-changes.md instructed users, under a heading reading “v2.0.0 (New)”, to create cyberchef.config.json. No loader was ever written. Before this release the only occurrence of that filename anywhere in the source was the deprecation message recommending it:

cyberchef.config.json present, asking for maxInputSize 1024
MAX_INPUT_SIZE actually in effect: 104857600
-> SILENTLY IGNORED

A user followed the published guide, wrote a file, restarted, and got no error, no warning and none of their settings.

Configuration

All 64 settings, in 15 sections, in one file:

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

environment variable  >  config file  >  built-in default

So docker run -e CYBERCHEF_OFFLINE=true still wins over a file baked into an image, and the startup log names anything the environment overrode, so the two never disagree silently:

Config file: /app/cyberchef.config.json (2 settings applied, 1 overridden by environment: tools.surface)

Nothing is required. With no file, the server behaves exactly as it did in v2.9.0.

Full settings table: the configuration guide, which is generated from the mapping in config-file.mjs and asserted against it by a test — so the document that caused this release cannot drift from the code again.

It fails closed

Malformed JSON, an unknown section, an unknown setting, or a value that is not a string, number, boolean or array stops the server:

cyberchef.config.json: unknown setting "security.offlien" (did you mean "offline"?).
Known settings in "security": auditEnabled, maxRegexLength, offline

The server did not start. Fix the file, or remove it to use environment variables only.

Deliberate, and it will occasionally annoy someone. This file sets the offline switch, the regex-length cap and the operation allowlist, and the defect being corrected is a configuration that was accepted and ignored. Starting on defaults an operator did not choose, and does not know they have, is the worse outcome.

Kubernetes and Compose

The Helm chart renders .Values.config into a ConfigMap and mounts it:

config:
  security:
    offline: true
  tools:
    surface: curated

With a checksum/config pod annotation, because a ConfigMap edit restarts nothing and the server reads its file once at startup — without it, helm upgrade reports success and every running pod keeps the old settings.

One thing to know: the chart sets CYBERCHEF_TRANSPORT, CYBERCHEF_HTTP_HOST, CYBERCHEF_HTTP_PORT and CYBERCHEF_HTTP_PATH itself, because a pod cannot serve without them. Since environment beats file, putting server.transport or http.port in config will not take effect. values.yaml says so where someone would write it, and the startup log names it.

v2.9.0’s chart deployed v2.8.1

Found while adding the above, by reading the version at the top of the compose file.

package.json                        2.9.0
deploy/compose image line           2.8.1
deploy/compose digest-pinning prose 2.8.1
Chart.yaml appVersion               2.8.1
values.yaml image.tag               2.8.1

The chart and compose file published with v2.9.0 deploy the previous release. Anyone who took the chart from that tag got v2.8.1 and none of its work.

AGENTS.md already carried a checklist naming those locations, with a note added after the second occurrence reading “two occurrences is a pattern, not an accident”. Three occurrences later, the honest conclusion is that a prose checklist cannot fail a build.

npm run check:versions can, and now runs in both CI workflows. It found all five drifts on its first run. A location that matches nothing fails too — that is how a consistency check quietly stops checking, when a file is reformatted and the pattern no longer matches.

If you deploy with the chart or the compose file, this release is the one that fixes your image tag.

Upgrading

Read this if you have a cyberchef.config.json.

Anyone who followed the migration guide between v2.0.0 and v2.9.0 has a file that has never done anything. On upgrading it starts taking effect. If it carries a stale offline: true or a narrow allowlist, that is a behaviour change you did not ask for in this release — check the contents before upgrading.

There is no honest way to both keep the promise and go on ignoring those files.

One thing helps: a file written against the guide’s old, aspirational schema named settings that never existed (cacheTTL, telemetry.endpoint, security.allowedOperations). Because unknown keys fail closed, such a file stops the server with a message naming the key rather than quietly applying half of itself.

Everything else is unchanged. No new dependencies, no protocol change, and no behaviour difference for a deployment with no config file.

Verification

npm run lint            clean
npm run check:versions  every version reference agrees
npm run test:mcp        1397 passed (54 files)
npm test                241 Node-API + 2289 operations passing
npm run test:coverage   gate passes
helm lint               clean
helm template           no config -> no ConfigMap, no mount, no annotation
                        with config -> mounted readOnly, checksum changes with content