Back
Engineering

Infection Monkey Tutorial: Start contributing using Swimm

Infection monkey

Infection Monkey powered by Guardicore is a popular Open Source project and essentially a Breach and Attack Simulation (BAS) tool that analyzes and breaks down the robustness of cloud-based development environments, regardless of if they are of the private or public type.

Shay Nehmad, a seasoned Open Source developer, and Shreya Malviya, a contributor to Infection Monkey, spoke to the participants about how Swimm is making it easier to contribute to the project and make a difference.

The resiliency to post-breach attacks and lateral movement is done with the help of automatic attack simulations that inject a random machine with a proprietary Infection Monkey code, which helps gauge and discover security loopholes and vulnerabilities. Think of it as an automated Pen Testing tool.

The 48 hour online event devoted to encouraging contributions to open source projects hosted by Brian Douglas of Github,  the Open Sauced community and backed by Swimm.

Check out the event here.

Getting Started with Infection Monkey using Swimm

Infection Monkey is very straightforward and user-friendly. The Monkey, is a proprietary tool that infects random machines in the target environment and propagates to them. And there is Monkey Island, a dedicated centralized dashboard to monitor the results and findings. More about the Infection Monkey installation process here.

The Map

Besides being a non-intrusive and plug-and-play tool, Infection Monkey requires zero maintenance and runs around the clock for comprehensive security analysis. Furthermore, users can also get actionable insights and recommendations with the ability to define alerts as per their requirements.

Swimm makes the onboarding of contributors to open source projects easier. Since everything related to Swimm is within the Infection Monkey (henceforth: IM) repository, all that you have to do is to clone that repo, start the terminal, and run the command “swimm start” on your terminal.

Once the server starts, it automatically opens the Swimm homepage, which already has playlists for IM. Currently, the repository includes three playlists (Post-breach action, Configuration, and System Info Collection). For this tutorial, we will use an extra-verbose playlist called “Adding a PBA in 5 Simple Steps”.

In a nutshell, Infection Monkey is a penetration testing tool and it simulates a person breaking into your system. Once the person is inside your system, they can perform additional actions after conducting the breach. In IM terminology, these are referred to as the “post-breach actions” or PBAs.

Define What Your New PBA Does

This is the actual coding step. As the name suggests, it basically defines what your new PBA does. So, briefly, you have to define what this step will do in IM (as stated in the description). This step also gives you instructions to run the manual test after you are done. But first, let’s do the main coding part.

All you have to do is copy the command from the Swimm interface and run it on your terminal. This will give you some information about this particular unit.

For example, the “Definition of done” says that you need a new constant defining what the PBA does. Now, you can ask Swimm to tell you which particular files are relevant to this specific Unit by running the command “Swimm Files”. It shows you the name of one file which is relevant to this Unit.

“This is pretty cool if you think about how you would do personal onboarding with someone. You would guide them toward the files relevant to what you are teaching.” - Shay Nehmad

So we have to see how to define the name of the PBA which is to be done in this file. This really shows how building the Unit correctly can “emulate” or replace the personal onboarding process. Also, another thing we should notice here is that this particular file is in the module called “common”.

This suggests that everything we will do here is going to affect both the Monkey and the Swimm server. Open this file.

The comments generated by Swimm show you where you need to add your code. But if you are not sure about what to do next, Swimm provides hints via the command `swimm hint`.

If you go back to the file and look at that PBA, it basically tells you what the PBA with the name “Timestomping” does. That’s how you will also define the name of your new PBA. Add your new PBA “POST_BREACH_SCHEDULE_JOBS” and save the file. You have refined your new PBA, but how do we know this works?

It's pretty easy when you are using Swimm. Let’s go back to the Swimm interface and learn about some easy and straightforward instructions to run the test.

Let’s study the result of this test from its image.

Whatever you added to the PBA definitions file, you should be able to see in the test report. Once you are done studying it, you can mark it as done with the command `swimm done`. This will take you to a Swimm status page (see below) that also allows you to compare your solution to the original codebase.

Implement a New PBA

Now, we know that the schedule jobs PBA is pretty dangerous because if someone is able to schedule jobs on your system, they can leave open a backdoor or ensure a virus downloads itself in case it gets deleted.

So do you now have to schedule jobs in your operating systems? Luckily, Infection Monkey already has these commands in the codebase.

So, all you need to do is fetch commands from a function called `get_commands_to_schedule_jobs`.

Once again, the description of this Unit also shows a manual test to run after writing the code. Just like in the previous Unit, we can play the Unit by copying the command from the Swimm interface and running it on your terminal. You can also request Swimm to tell you the relevant files with the same command.

This time it tells you that the relevant file is in a module called “infection_monkey” which suggests that whatever we will be doing is going to affect the Monkey (i.e. the virtual intruder simulated by Infection Monkey) itself. This makes sense because you will basically be adding new functionality.

So, once you open the file, you will see a comment that tells you where you need to add your new code. This is something that leaves no place for error.

Let’s ask Swimm for more hints about how to proceed with coding in this Unit.

Swimm provides you with two hints. Let’s go ahead with the first one which suggests you check the “Time Stomping” PBA to get an idea about the implementation.

We can see here that we are basically fetching Linux and Windows commands from a function called `get_timestomping_commands`. Then you will call the constructor for the parent class with the name of the PBA, the Linux commands, and the Windows commands as arguments.

So, you will do something similar to “schedule jobs” PBA.

Here, you can see the code fetches the commands from the function given in the description and it calls the constructor of the parent class.

Swimm has given you a second hint that notifies you to remove your PBA by removing the schedule jobs.

For that purpose, you can see a call to the function called `remove_scheduled_jobs`.

You can really walk through each line of the solution and see how building the Unit correctly nudged whoever’s solving it to write each line. So, from lines 13 to 18, that was the first hint telling you the general structure of how to implement post-breach actions in IM that are based on shell commands.

Following the hint shows you an example of how to write that code. Another cool thing pops up when we look at line 16. We can see the code is pulling the name of the PBA from the variable we defined in the previous Unit. The last line is from the second hint.

You may decide to not look at the hints and go blind trying to solve it. In this case, when you mark your unit done in Swimm and then compare it to the actual solution, you’ll find that discrepancy. If you forgot to remove the scheduled jobs, you will find it in the diff. It’s up to you as the Swimmer to choose if you’d rather see hints or not.

Now that you have added the code, let’s run the manual test by following the instructions in the Unit’s description.

You can see in the attack report that it successfully scheduled a job using `crontab`. Let’s mark the Unit as done in Swimm with the command `swimm done`. Just like the last step, you will be taken to a page that gives you more information about what changes you’ve just made.

This summary guides the person solving the Unit to read other parts of the code. Now that you have made some contributions, you are already more familiar with the lexicon, and manually tested your changes, you now have the context to figure out the code much quicker and improve your productivity when contributing to Infection Monkey!

Once again, Swimm will let you compare your solution to the original codebase. Now that you named the PBA and implemented it, the next step is to make sure that it actually shows up in the configuration. So, let’s move on to the fourth step, where you will be adding details about your PBA.

Add Details About Your New PBA

This is actually a pretty good example of how learning begets learning. Whenever you are trying to learn something new, you come across new terms, new terminology, and you look it up and research it. The MITRE ATT&CK technique is something you will encounter a lot and you need to be ready for it.

“The MITRE ATT&CK framework is an open-source knowledge base of attack tactics and techniques which were derived from real-world scenarios. This is something professionals in the cybersecurity industry refer to a lot." - Shreya Malviya

In this particular example, the “schedule jobs” PBA is related to two MITRE techniques that are shown in the description with their IDs. They basically do what the PBA does - scheduling jobs for Linux and Windows.

Here you can see a short recording of how the finder test should look so that it’s easier to ensure that whatever you’ve done is correct. Now, you know the drill - running the Unit by copying the command from the Swimm interface and checking the relevant files with the `swimm files` command.

This time you can notice that the module you are touching is `monkey_island`, which means that whatever we are doing will affect the server.

Let’s go ahead and open the file.

It shows where you need to add more code. But again, you are not really sure what to do here. So what do we do now? Yes, we ask Swimm for a hint. It tells you to look at the details of other techniques. Along with the description of this Unit in the Swimm interface, this gives you a pretty clear idea of what to do next.

For example, there’s a field called `info` which consists of an elaboration on what the PBA actually does. There’s also a field called `attack_techniques` where you link your PBA to the appropriate MITRE technique ID.

That’s exactly what we have done for our new PBA.

We create new fields: type, enum, title, info, and attack techniques. Then we will mark this Unit as done with the `swimm done` command.

This screen presents a summary of your latest actions along with some more information. Take your time to read these summaries carefully to understand what’s exactly happening. Now, we will move on to the fifth and the last Unit, which will revolve around a recent Pull Request (PR).

A Pull Request (PR) Demonstration

Since you already know all the files and how stuff works, we now look at an actual pull request (PR). The benefit here is seeing the real-world applicability of your newly-acquired knowledge. You get a second-hand experience by looking at the conversations that happened, including the code review comments.

For example, if you were wondering why post rejections in Infection Monkey are implemented with shell commands, you can see the conversation of someone looking at the pull request, asking that question, and the question gets answered. After going through the Units, this conversation actually gives you extra insight.

So when you do make your contribution with your own pull request, you can avoid all existing pitfalls or bottlenecks that may arise.

To Sum it Up

The demonstration clearly showed how modern onboarding tools are helping elevate productivity, improve cross-department collaboration, and create healthier code contributions.

Shay Nehmad wrapped up:

“Open Source projects don't come with a ton of responsibility, but companies must do their due diligence. Every LoC should be scrutinized. Big eCommerce, healthcare and financial/banking companies need to have a strong security posture. They can use tools like Swimm to optimize their products.