Documentation for the Mechanical Phish.
The Mechanical Phish is open source! Mechanical Phish was created by Shellphish as our CRS for the DARPA Cyber Grand Challenge. It rocked it in the final event, winning 3rd place, and we are very proud of it.
The Cyber Grand Challenge was the first time anything like this was attempted in the security world. As such, Mechanical Phish is an extremely complicated piece of software, with an absurd amount of components. No blueprint for doing this existed before the CGC, so we had to figure things out as we went along. Unfortunately, rather than being a software development shop, we are a "mysterious hacker collective". This means that Mechanical Phish has some rough components, missing documentation, and ghosts in the machine. Our hope is that, going forward, we can polish and extend Mechanical Phish, as a community, to continue to push the limits of automated hacking.
Keep in mind that this was never designed to be turn-key, might not install without extreme effort, and might not work without a lot of tweaking. Otherwise, have at it!
So far, there are several glaring issues that came up during the runup to the CGC Final Event, the CFE itself, DEFCON, or our post-CGC analysis:
Overall, we're pretty surprised this thing ran at all! In the development of Mechanical Phish, we had to fix some bugs in some underlying components. We have fixes our fixes in the following forks, but we need to upstream them:
The CRS has a lot of moving parts. They have been distributed throughout several different github namespaces:
This is an index of all of the repositories, split by component.
The CRS Meister handles task scheduling.
The Ambassador talks to the CGC API to retrieve CBs, submit POVs, etc.
Scriba decides what exploits and RCBs to submit.
The CRS worker handles running the actual tasks that are scheduled by the worker. This part includes a lot of repositories working together.
There are several common components that don't fit in a single category above.
There are also many other repositories that act as dependencies for those above. We'll get a full list together at some point.
We have documented the process to setup a local development version here.
Scripts for setting up the full, kubernetes-powered distributed systems are here.
We plan to keep Mechanical Phish alive through our research and the support of the community. However, we are a small group of PhD students, and don't have much time to give support, as our primary task is to do research, publish papers, and graduate. Please understand this when creating support requests: if resolving a support question takes too much time, it will likely never be done. To maximize the chance of a resolution, meet us half way and try exploring the issue with us :-)