richardsonjf / cherrybomb

Stop half-done API specifications! Cherrybomb is a CLI tool that helps you avoid undefined user behaviour by validating your API specifications.

Stop half-done API specifications

💣 What is Cherrybomb?

Cherrybomb is a CLI tool that helps you avoid undefined user behavior by validating your API specifications.

Our CLI tool is open source, enabling support from both the OpenAPI and Rust communities.

🔨 How does it work?

It takes in an OAS file, runs a series of checks on it to make sure everything is on par with the OAS, and outputs a detailed table with any alerts found, guiding you to the exact problem and location to help you solve it quickly.

It can also take in your logs and check them for business logic flaws.

🐾 Get Started

Installation

Using cURL

Linux/MacOS:

curl https://cherrybomb.blstsecurity.com/install	| /bin/bash

The script requires sudo permissions to move the cherrybomb bin into /usr/local/bin/.
(If you want to view the shell script(or even help to improving it - /scripts/install.sh)

Direct download

You can also download the binary file directly from our website.
This is a binary file and you DO NOT have to install Rust. If you use this method you should run this command:

mkdir ~/.cherrybomb

To create a .cherrybomb dir in the home directory.

Usage

After installing the CLI, verify it's working by running

cherrybomb --version

OpenAPI specification scan

cherrybomb oas --file <PATH> --config <PATH> --verbosity <0/1/2> --format <cli/txt/json> --output <PATH>

Output example for verbosity level 1:

Output example for verbosity level 0:

Generate Parameter Table

cherrybomb param-table --file <PATH> --name <SINGLE PARAM NAME(OPTIONAL)>

Table output example:

Generate Endpoint Table

cherrybomb ep-table --file <PATH> --name <SINGLE PARAM NAME(OPTIONAL)>

Table output example:

Configuration options:

You can configure the OAS scan using the config.json file in your .cherrybomb director that we create by default in your home path(after one scan at least or downloading using the install script).

Go through only part of the checks

Full scan:

{
  "scan_type":"Full",
	...
}

Only run the server url and the default response checks:

{
  "scan_type":["SERRVER URL","DEFAULT RESPONSE"],
	...
}

Fail or not when the highest alert level is info

{
  "fail_on_info":true,
	...
}

More features

First, we have a mapping module that relies on HTTP logs and builds a map of the API.
Start mapping your logs by running

cherrybomb map --file <LOGS_FILE_PATH> --output <OUTPUT_FILE_NAME> --hint <OAS FILE NAME>

If you don't have an HTTP log file, but you have Burp suite logs, you are in luck, go to the scripts folder, there is a convertor script over there.
If there are any other formats you need conversion scripts to, message us on the discord server.
For futher insights, you can view your map visually in our web based visualizer: https://www.blstsecurity.com/cherrybomb/Visualizer.

In the future, if you want to load new logs to an existing map file, run

cherrybomb load --file <LOGS_FILE_PATH> --map <MAPPED_FILE_PATH>

🪦 (!)Deprecation notice:

The Attacker and Decider modules will be deprecated(!) in our the next release(version 0.6). We are doing it since we have barely seen any usage of the modules thus far. Please let us know if you are indeed using those features and don't want them to be deprecated.

🚧 Roadmap

• OAS 3 support
• Passive checks
• Parameter table
• Improve installation script
• Endpoints table
• YAML support (currently only JSON is supported)
• Custom scans - optional checks + optional output
• Ignore alerts + don't fail on info
• More passive checks
• Swagger 2 support (currently only version 3 is supported)
• Homebrew/APT support
• GraphQL schema support
• Active scans
• Swagger and logs validator (compares your logs with the swagger to verify correctness)

🍻 Integration

For all methods of integrating with BLST, please go to the integrations folder.

💪 Support

Documentation

Please read our documentation to understand the format of sessions our mapper needs to function correctly.

Get help

If you have any questions, please send us a message to [email protected] or ask us on our discord server.
You are also welcome to open an Issue here on GitHub.

🤝 Contributing

You can find contribution options from our open issues, you should look for the "More passive checks" issue(it's a great issue to start from). You can also find info about contributing new checks to Cherrybomb here.
If you have any question or need any help talk to us over at our discord server to see where and how can you contribute to our project.