Getting started

n1474335 edited this page Jan 18, 2019 · 8 revisions

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 and its package manager, npm
  3. Install Grunt: npm install -g grunt-cli
  4. git clone https://github.com/gchq/CyberChef.git
  5. cd CyberChef
  6. npm install

npm will then install all the dependencies needed by Grunt.

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.

Compiling

Grunt has been configured with several tasks to aid in the development process:

grunt dev

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.

grunt prod

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. It will also create the inline version of CyberChef at the same location, called cyberchef.htm.

grunt node

This will package up CyberChef as a NodeJS library, creating the file build/node/CyberChef.js. It can then be loaded and used like so:

> var chef = require("./CyberChef.js")
undefined
> chef.bake("test", [{"op":"To Hex","args":["Space"]}]).then(r => { console.log(r) })
Promise {
... }
> { result: '74 65 73 74',
  type: 'string',
  progress: 1,
  duration: 2,
  error: false }
grunt test

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

grunt docs

Builds the codebase documentation and places it in the docs directory.

Repository structure

  • build/
    • dev/ - This will be populated with an uncompressed development build of CyberChef by running the grunt dev command.
    • prod/ - This folder contains the most recently built production version of CyberChef including the inline version. It is populated by running grunt prod.
    • node/ - Populated with the packaged NodeJS version of CyberChef by running the grunt node command.
  • src/
    • core/ - Core CyberChef files that make up the heart of the application
      • config/ - Files specifying the operation configurations
        • modules/ - Automatically generated module references
      • lib/ - Libraries containing shared code for multiple operations
      • errors/ - Custom error types
      • operations/ - Operation objects
      • vendor/ - Libraries that cannot currently be imported through npm
    • node/ - Wrappers for the NodeJS version of CyberChef
    • web/ - The code which makes up the CyberChef web app
      • css/
        • lib/ - Library CSS and Less files
        • structure/ - Structural styles to lay out the stage
        • themes/ - Look and feel styles
      • html/
        • index.html - The CyberChef page structure
      • static/ - Static files like images
  • docs/ - Codebase documentation, populated by running grunt docs.
  • test/
    • tests/ - Configuration for tests on operations and recipes
  • .babelrc - Babel transpilation configuration
  • .editorconfig - Text editor conventions stored in a cross-compatible format
  • .travis.yml - Travis CI build process configuration
  • Gruntfile.js - Grunt build process configuration
  • webpack.config.js - Webpack configuration
  • postcss.config.js - PostCSS configuration
  • LICENSE - The Apache 2.0 licence information
  • package.json - npm configuration and a list of all the dependencies
  • README.md - An introduction to CyberChef
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.