CyberChef Server: A Comprehensive Guide to Setting Up and Using the CyberChef API

CyberChef Server makes it possible to run CyberChef operations programmatically through an HTTP API. While CyberChef provides a powerful Node.js API, developers may want to use its data transformation and analysis capabilities from other programming languages. CyberChef Server provides a practical way to do this by accepting HTTP requests and returning processed results.

With this approach, you can integrate CyberChef recipes into Python scripts, shell workflows, web applications, and other tools that can send HTTP requests. It also supports recipes exported from the CyberChef web interface, making it easier to move from experimenting with an operation to automating it.

What Is CyberChef Server?

CyberChef is a web-based tool for performing data transformation, encoding, decoding, parsing, and other operations through configurable recipes. A recipe combines one or more operations to process an input.

CyberChef Server exposes these operations through an HTTP interface. A client sends a request containing the input data and recipe, and the server runs the recipe and returns the result. This makes CyberChef functionality accessible to languages and environments beyond JavaScript.

The project is available in the official CyberChef Server GitHub repository.

Key Features of CyberChef Server

• HTTP API access: Run CyberChef recipes from any programming language or tool that supports HTTP requests.
• Recipe compatibility: Use recipe JSON exported from the CyberChef web interface as part of an API request.
• Automated data processing: Integrate encoding, decoding, and other supported transformations into scripts and applications.
• Docker support: Build and run the server inside a container for a more isolated deployment.
• Local usage documentation: Access the server’s usage information through a browser after starting it, subject to the version’s available routes.

Installing CyberChef Server

You can run CyberChef Server locally using Node.js and npm. The exact runtime requirements may vary by repository version, so check the official README before installing dependencies.

Step 1: Clone the Repository

Clone the official repository and change into the project directory:

git clone https://github.com/gchq/CyberChef-server
cd CyberChef-server

Step 2: Install Dependencies

Install the Node.js dependencies with npm:

npm install

Ensure Node.js and npm are installed and available in your system’s PATH before running this command.

Step 3: Start the Server

Check the project’s documented start command. For versions that define the default start script, use:

npm start

The original setup instructions also refer to npm run, which lists the available npm scripts in many projects. If the command above is not supported by your checkout, review the scripts in package.json and follow the repository’s current instructions.

Step 4: Open the Local Server

Once the server starts successfully, open the following address in a browser:

http://localhost:3000/

If the running version provides documentation at the root route, you can use it to review the available API endpoints and request format.

Using the CyberChef Server API

The /bake endpoint accepts a POST request containing an input value and a CyberChef recipe. The example below submits a Morse-code string and asks CyberChef to convert it into readable text.

Example: Convert Morse Code Using curl

curl -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "input": "... ---:.-.. --- -. --. --..--:.- -. -..:- .... .- -. -.- ...:..-. --- .-.:.- .-.. .-..:- .... .:..-. .. ... ....",
    "recipe": {
      "op": "from morse code",
      "args": {
        "wordDelimiter": "Colon"
      }
    }
  }' \
  http://localhost:3000/bake

In this request:

• -X POST sends an HTTP POST request.
• Content-Type: application/json indicates that the request body contains JSON.
• input contains the Morse-code text to process.
• recipe specifies the CyberChef operation and its arguments.
• wordDelimiter tells the Morse-code operation to treat colons as word separators.

For this example, the expected decoded text is:

SO LONG, AND THANKS FOR ALL THE FISH

The precise response structure and formatting depend on the server version. The original example represents the result as a string value with a string type, such as:

{
  "value": "SO LONG, AND THANKS FOR ALL THE FISH",
  "type": "string"
}

Using Recipes Exported from CyberChef

One of CyberChef Server’s most useful features is its support for recipes exported from the CyberChef web interface. This allows you to develop and test a transformation interactively before automating it through the API.

1. Open CyberChef in your browser.
2. Add the operations you need and configure their arguments.
3. Test the recipe with representative input data.
4. Export or copy the recipe JSON using the options available in the interface.
5. Place the exported recipe in the recipe property of the JSON request sent to the server.

Using an exported recipe reduces the need to manually recreate operation names and arguments. However, compatibility can depend on the versions of CyberChef and CyberChef Server in use, so test the recipe against the server you have deployed.

Running CyberChef Server with Docker

Docker provides an alternative to installing and managing the application’s Node.js dependencies directly on your host system. You can build the image from the official repository and publish the service on local port 3000.

Step 1: Clone the Repository

git clone https://github.com/gchq/CyberChef-server
cd CyberChef-server

Step 2: Build the Docker Image

docker build -t cyberchef-server .

This command builds an image named cyberchef-server using the Dockerfile in the current directory.

Step 3: Run the Container

docker run -it --rm \
  --name=cyberchef-server \
  -p 3000:3000 \
  cyberchef-server

The options used here have the following purposes:

• -it runs the container interactively and keeps a terminal attached.
• --rm removes the container after it stops.
• --name=cyberchef-server assigns the container a recognizable name.
• -p 3000:3000 maps port 3000 on the host to port 3000 in the container.

After the container starts, try accessing http://localhost:3000/ from the host. If the service does not respond, check the container logs, port mapping, and the startup instructions for the version you built.

Common Use Cases

• Data transformation pipelines: Apply repeatable decoding, encoding, parsing, and conversion steps to incoming data.
• Security analysis workflows: Automate supported transformations when examining data during authorized incident response or security investigations.
• Cross-language integration: Call CyberChef operations from Python, Bash, or another environment that can make HTTP requests.
• Batch processing: Incorporate recipe execution into scripts that process multiple inputs, while handling errors and response formats appropriately.
• Prototyping and automation: Test a recipe in the browser and then reuse its JSON definition in a repeatable workflow.

Security and Deployment Considerations

CyberChef Server processes data submitted by clients, so consider the sensitivity and size of the input before exposing the service to other systems.

• Restrict access: Keep development instances bound to a trusted environment. Do not expose the API publicly unless you have designed and configured suitable access controls.
• Protect sensitive input: Avoid sending secrets, credentials, or confidential data to an instance that is not approved to process them.
• Monitor resource usage: Large inputs or complex recipes can consume significant CPU and memory. Apply appropriate request limits and operational monitoring for shared deployments.
• Maintain the deployment: Review the project’s current documentation, update dependencies through a controlled process, and test changes before deploying them.
• Validate outputs: Treat returned data as the result of a transformation, not as proof that the input is safe or trustworthy.

Conclusion

CyberChef Server extends CyberChef’s recipe-based data processing capabilities through an HTTP API. It lets developers and security professionals automate supported operations from languages other than JavaScript, reuse recipes created in the web interface, and run the service locally or in Docker.

For the latest installation requirements, API behavior, and deployment details, consult the official CyberChef Server repository and test the examples against your installed version.