20 Getting started

GCHQDeveloper581 edited this page 2026-04-29 17:44:28 +01:00

Table of Contents

• Installing
• Compiling
• Repository structure

Installing

CyberChef uses the Grunt build system, so it's very easy to install. You'll need to carry out the following steps to get going:

1. Install Git
2. Install Node.js version 24 (nvm is usually a good way of managing your Node versions)
3. git clone https://github.com/gchq/CyberChef.git
4. cd CyberChef
5. npm install

npm will then install all the dependencies needed to build and run CyberChef.

Consider adding export NODE_OPTIONS=--max_old_space_size=2048 to your ~/.bashrc file. If you attempt to build a production version of CyberChef, you may get a "JavaScript heap out of memory" error if you do not set this environment variable. You can also run npm run setheapsize to do this but it will not persist between terminal sessions.

Compiling

Note that CyberChef only supports bash-based dev environments, so primarily Linux and Mac. You may be able to get a build working on Windows, but it is not officially supported.

npm has been configured with several scripts to aid in the development process:

npm start

Use this when developing new functionality. It will launch a web server on port 8080 hosting an uncompressed, development version of CyberChef, accessible by browsing to localhost:8080. Whenever a source file is modified, the development version will be rebuilt automatically.

npm run build

When you are ready to create a production build, run this command. It will lint, test, compile and compress all the source files and create a production-ready build in build/prod/.

npm run node

This will package up CyberChef as a NodeJS library. More info on this can be found here: https://github.com/gchq/CyberChef/wiki/Node-API

npm test

This will run all the pre-configured tests and output the results to stdout.

Repository structure

• .editorconfig - Text editor conventions stored in a cross-compatible format
• babel.config.js - - Babel transpilation configuration
• build/
  • prod/ - This folder contains the most recently built production version of CyberChef including the inline version. It is populated by running grunt prod.
• CHANGELOG.md
• CODE_OF_CONDUCT.md
• CONTRIBUTING.md
• Dockerfile - Dockerfile for building a containerised deployment of CyberChef
• eslint.config.mjs - ESLint code linting configuration
• Gruntfile.js - Grunt build process configuration
• LICENSE - The Apache 2.0 licence information
• nightwatch.json - Nightwatch browser testing configuation
• package.json - npm configuration and a list of all the dependencies
• package-lock.json - frozen version of the above with all dependencies (automatically generated by npm install)
• postcss.config.js - PostCSS configuration
• README.md - An introduction to CyberChef
• SECURITY.md
• src/
  • core/ - Core CyberChef files that make up the heart of the application
    • config/ - Files specifying the operation configurations
      • modules/ - Automatically generated module references
      • scripts/ - Scripts for automating parts of the maintenance and build processes
    • dishTypes/ - definitions of the types that can be passed in and out of operations
    • errors/ - Custom error types
    • lib/ - Libraries containing shared code for multiple operations
    • operations/ - Operation objects
    • vendor/ - Libraries that cannot currently be imported through npm
  • node/ - Wrappers for the NodeJS version of CyberChef
    • config/ - Files specifying the special operation configurations for the NodeJS version
      • scripts/ - Scripts for automating parts of the maintenance and build processes
  • `web/ - The code which makes up the CyberChef web app
    • `html/
      • `index.html - The CyberChef page structure
    • static/ - files included as-is in the web app
      • fonts/ - font files
      • images/ - various images used within the web app
        • logo/ - logos
    • stylesheets/ - styling for the app
      • components/ - individual UI components
      • layout/ - layout for main UI compnonents
      • operations/
      • themes/ - Look and feel styles
      • utils/ - additional style compononents
    • utils/ - functionality for major UI components
    • waiters/
    • workers/
• tests/ - CyberChef test suite
  • browser/ - Browser functional tests
    • output/ - Output/logs from the browser tests
  • lib/ - library files used by individual tests
  • node/ - tests for Node API
  • sampleData/
  • tests/ - individual test suites
    • lib/ - libraries used by test suites
  • operations/ - Unit tests for the Operations
    • tests/ - Individual operation test suites
  • samples/ - Sample data used in testing
    • files/ - Sample file data
• webpack.config.js - Webpack configuration