Skip to content

Latest commit

 

History

History
93 lines (67 loc) · 6.29 KB

README.md

File metadata and controls

93 lines (67 loc) · 6.29 KB
Raw

Lucky CAT Logo

Lucky CAT - Crash All the Things!

BCH compliance

Note: ⚠️ CALL FOR MAINTAINERS 🚧

As stated in this issue we're currently unable to provide full support/maintenance for this project. Anyhow, feel free to contribute via PR's and we make sure to timely review the suggested changes to let this project not rot away.

What is Lucky CAT?

Lucky CAT (Crash All the Things!) is a distributed fuzzing testing suite with an easy to use web interface. It allows to manage several fuzzing jobs on several remote machines concurrently. Lucky CAT aims to be easily usable, scaleable, extensible, and fun.

Lucky CAT's origin is Joxean Koret's Nightmare Fuzzing Project. However, there may be only traces of Nightmare and Lucky CAT is more 2018-ish by relaying, amongst others, on Bootstrap, Docker, MongoDB, Python 3, and RabbitMQ.

Why use Lucky CAT?

Lucky CAT offers the following features:

  • Fuzz job management: primary focus on black box fuzzing and embedded devices
  • Easy deployment: thanks to Docker and Docker Compose
  • Scalability: Lucky CAT uses a micro service architecture backed by RabbitMQ
  • Easy integration: Lucky CAT provides a RESTful API to integrate it with your other tools
  • Responsive WebUI: for job management, crash analysis, and statistics
  • Fast command line client: for those who never leave the terminal...
  • Fuzzers included: tiny POSIX-compatible fuzzer cfuzz, afl, afl-otherarch wrappers and many more
  • Easy fuzzer integration: integrate other fuzzer into Lucky CAT by using either a Python template or a C template
  • Crash verification: local and remote crash verification with the gdb plugin exploitable

And because we use it to find bugs:

How to install Lucky CAT?

Requirements

You need a recent Linux distribution like Ubuntu 18.04 and at least Docker 18.06.0 as well as docker-compose 1.22.0 to build Lucky CAT. Even though you may not need to worry about the installation of further requirements thanks to Docker, Lucky CAT relies on many amazing open source projects (see PROPS.md).

Installation Process

Pull the whole project:

git clone https://github.com/fkie-cad/luckycat.git

Just use the script start_cluster.sh to build the app - if required - and start Lucky CAT. Afterwards navigate to https://localhost:5000 and create a new user.

In case you wish to remove Lucky CAT, you may use the script docker/clean_docker.sh. Please note that this script deletes all Docker images and containers on your system as well as your Lucky CAT data.

How to use Lucky CAT?

The workflow of Lucky CAT is as follows:

  • Create a new job either via the web interface or the REST API.
  • Deploy a fuzzer. Either you choose one of the prebuild fuzzers or your own (based on the the templates, see next section). Ensure a proper configuration (e.g. queue names).
  • Deploy (if possible) a verifier for crash verification (probably on the real device if you fuzzing some IoT thingy).
  • Start fuzzing and check on the results and stats in the web interface.

If you wish to integrate or automate Lucky CAT then you may want to have a look at its RESTful API.

How to extend Lucky CAT with a new fuzzer or verifier?

While there are several ways to extend the code, the easiest way is to integrate another fuzzer or verifier.

There are two example fuzzers in luckycat/fuzzers/templates. One of them is written in C and one in Python. Use them as basis and extend them in order to add another fuzzer to Lucky CAT. Similarly, you can extend Lucky CAT by building upon luckycat/verifier/templates.

Contribute

Contributions are always welcomed. Just fork it and open a pull request!

Acknowledgements

This project is partly financed by German Federal Office for Information Security (BSI).

License

    Copyright (C) 2018 -      Fraunhofer FKIE  (thomas.barabosch@fkie.fraunhofer.de)
    Copyright (C) 2013 - 2015 Joxean Koret     (admin@joxeankoret.com)

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
    
    Some plug-ins may have different licenses. If so, a license file is provided in the plug-in's folder.