p17860254
/
monkey
forked from p15670423/monkey
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

Copyedits for usage sections (#965) 

Copy edits - round 2
This commit is contained in:
MarketingYeti 2021-02-22 07:06:56 -05:00 committed by GitHub
parent c5371060c1
commit 8a1fec3f0b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
27 changed files with 244 additions and 288 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

20
docs/content/development/_index.md
View File

@ -13,31 +13,31 @@ Want to help secure networks? That's great!
## How should I start?
Here's a few short links to help you get started.
Here are a few short links to help you get started:
* [Getting up and running](./setup-development-environment) - To help you get a working development setup.
* [Contributing guidelines](https://github.com/guardicore/monkey/blob/master/CONTRIBUTING.md) - Some guidelines to help you submit.
* [Getting up and running](./setup-development-environment) - These instructions will help you get a working development setup.
* [Contributing guidelines](https://github.com/guardicore/monkey/blob/master/CONTRIBUTING.md) - These guidelines will help you submit.
## What are we looking for?
You can take a look at [our roadmap](https://github.com/guardicore/monkey/projects/5) to see what issues we're thinking about doing soon. We are looking for:
You can take a look at [our roadmap](https://github.com/guardicore/monkey/projects/5) to see what issues we're thinking about tackling soon. We are always looking for:
### More exploits! 💥
The best way to find weak spots in the network is by attacking it. The [Exploit template](https://github.com/guardicore/monkey/wiki/Exploit-templates) page will help you add exploits.
The best way to find weak spots in a network is by attacking it. The [exploit template](https://github.com/guardicore/monkey/wiki/Exploit-templates) page will help you add exploits.
It's important to note that the Infection Monkey must be perfectly reliable otherwise no one will use it, so avoid memory corruption exploits _unless they're rock solid_ and focus on the logical vulns such as Shellshock.
It's important to note that the Infection Monkey must be absolutely reliable. Otherwise, no one will use it, so avoid memory corruption exploits unless they're rock solid and focus on the logical vulns such as Shellshock.
### Analysis plugins 🔬
Successfully attacking every server in the network is no good unless the Monkey can explain how to prevent the attack. Whether it's detecting when the Monkey is using stolen credentials or when the Monkey can escape locked down networks, this is the part that actually helps secure different parts.
Successfully attacking every server in the network has little value if the Infection Monkey can't provide recommendations for reducing future risk. Whether it's explaining how the Infection Monkey used stolen credentials or escaped from locked-down networks, analysis is what helps users translate the Infection Monkey's activities into actionable next steps for improving security.
### Better code 💪
We always want to improve the core Monkey code, to make it smaller, faster and more reliable. If you have an idea of how to do it, or just want to modularise/improve test coverage for the code, do share!
We always want to improve the core Infection Monkey code to make it smaller, faster and more reliable. Please share if you have an idea that will help us meet these goals or modularize/improve test coverage.
### Documentation 📚
Every project requires better documentation. The Monkey is no different, so feel free to open PRs with suggestions, improvements or issues asking us to document different parts of the Monkey.
Every project requires excellent documentation. The Infection Monkey is no different. Please feel free to open pull requests with suggestions, improvements or issues and asking us to document various parts of the Monkey.
The Monkey's documentation is stored in the `/docs/content` directory.
The Infection Monkey's documentation is stored in the `/docs/content` directory.

16
docs/content/development/add-zero-trust-test.md
View File

@ -5,22 +5,22 @@ draft: false
weight: 100
---
## How to add a new Zero Trust test to the Monkey?
## How do I add a new Zero Trust test to the Monkey?
Assuming the Monkey agent is already sending the relevant telemetry, you'll need to add the test in two places.
Assuming the Infection Monkey agent is already sending the relevant telemetry, you'll need to add the test in two places.
### `zero_trust_consts.py`
In the file `/monkey/common/data/zero_trust_consts.py`,
In the file `/monkey/common/data/zero_trust_consts.py`:
1. Add the test name to the TESTS set
2. Add a relevant recommendation if exists
3. Add the test to the TESTS_MAP dict. Make sure that all statuses (except `STATUS_UNEXECUTED`) have finding explanations.
2. Add a relevant recommendation if it exists
3. Add the test to the TESTS_MAP dict. Ensure that all statuses (except `STATUS_UNEXECUTED`) have finding explanations.
### `telemetry/processing.py`
Find the relevant telemetry type you wish to test the finding in. This can be found in `/monkey/monkey_island/cc/services/telemetry/processing.py`. In the relevant `process_*_telemetry` function, add your Zero Trust testing code. Please put the zero trust tests under the `/monkey/monkey_island/cc/services/telemetry/zero_trust_tests` directory. There you can find examples of existing tests as well, so you'll know pretty much what you need to write.
Find the relevant telemetry type you wish to test the finding in next. These can be found in `/monkey/monkey_island/cc/services/telemetry/processing.py`. In the relevant `process_*_telemetry` function, add your Zero Trust testing code. Please put the Zero Trust tests under the `/monkey/monkey_island/cc/services/telemetry/zero_trust_tests` directory. There you can also find examples of existing tests as well, so you'll have a reference for what you need to write.
## How to test the new Zero Trust test I've implemented?
## How do I test the new Zero Trust test I've implemented?
Test ALL possible finding statuses you've defined in a fake network. Observe the events as well and see they were formatted correctly. If there's an algorithmic part to your Zero Trust test, please cover it using a Unit Test.
Test ALL possible finding statuses you've defined in a fake network. Ensure the events were formatted correctly by observing them. If there's an algorithmic part to your Zero Trust test, please cover it using a Unit Test.

14
docs/content/development/adding-post-breach-actions.md
View File

@ -6,17 +6,17 @@ tags: ["contribute"]
weight: 90
---
## What's this?
## What does this guide cover?
This guide will show you how to create a new _Post Breach action_ for the Infection Monkey. _Post Breach actions_ are "extra" actions that the Monkey can perform on the victim machines after it propagated to them.
This guide will show you how to create a new _post-breach action_ (PBA) for the Infection Monkey. PBA are "extra" actions that the Infection Monkey can perform on victim machines after propagating to them.
## Do I need a new PBA?
If all you want is to execute shell commands, then there's no need to add a new PBA - just configure the required commands in the Monkey Island configuration! If you think that those specific commands have reuse value in all deployments and not just your own, you can add a new PBA. If you need to run actual Python code, you must add a new PBA.
If all you want to do is execute shell commands, then there's no need to add a new PBA - just configure the required commands in the Monkey Island configuration! If you think that those specific commands have reuse value in other deployments besides your own, you can add a new PBA. Additionally, if you need to run actual Python code, you must add a new PBA.
## How to add a new PBA
### Monkey side
### From the Infection Monkey Side
#### Framework
@ -43,7 +43,7 @@ If your PBA consists only of simple shell commands, you can reuse the generic PB
Otherwise, you'll need to override the `run` method with your own implementation. See the `communicate_as_new_user.py` PBA for reference. Make sure to send the relevant PostBreachTelem upon success/failure. You can log during the PBA as well.
### Island side
### From the Monkey Island Side
#### Configuration
@ -67,10 +67,10 @@ You'll need to add your PBA to the `config_schema.py` file, under `post_breach_a
},
```
Now you can choose your PBA when configuring the Monkey on the Monkey island:
Now you can choose your PBA when configuring the Infection Monkey on the Monkey island:
![PBA in configuration](https://i.imgur.com/9PrcWr0.png)
#### Telemetry processing
If you wish to process your Post Breach action telemetry (for example, to analyze it for report data), add a processing function to the `POST_BREACH_TELEMETRY_PROCESSING_FUNCS` which can be found at `monkey/monkey_island/cc/services/telemetry/processing/post_breach.py`. You can look at the `process_communicate_as_new_user_telemetry` method as an example.
If you wish to process your PBA telemetry (for example, to analyze it for report data), add a processing function to the `POST_BREACH_TELEMETRY_PROCESSING_FUNCS`, which can be found at `monkey/monkey_island/cc/services/telemetry/processing/post_breach.py`. You can reference the `process_communicate_as_new_user_telemetry` method as an example.

28
docs/content/development/adding-system-info-collectors.md
View File

@ -6,21 +6,21 @@ tags: ["contribute"]
weight: 80
---
## What's this?
## What does this guide cover?
This guide will show you how to create a new _System Info Collector_ for the Infection Monkey. _System Info Collectors_ are modules which each Monkey runs, that collect specific information and sends it back to the Island as part of the System Info Telemetry.
This guide will show you how to create a new _System Info Collector_ for the Infection Monkey. System Info Collectors are modules that each of the Infection Monkey agents runs that collect specific information and send it back to the Monkey Island as part of the System Info Telemetry.
### Do I need a new System Info Controller?
### Do I need a new System Info Collector?
If all you want is to execute a shell command, then there's no need to add a new collector - just configure the required commands in the Monkey Island configuration in the PBA section! Also, if there is a relevant collector and you only need to add more information to it, expand the existing one. Otherwise, you must add a new Collector.
If all you want to do is execute a shell command, then there's no need to add a new System Info Collector - just configure the required commands in the Monkey Island's post-breach action (PBA) section! Also, if there is a relevant System Info Collector and you only need to add more information to it, simply expand the existing one. Otherwise, you must add a new System Info Collector.
## How to add a new System Info Collector
## How to add a new System Info Collector
### Monkey side
### From the Monkey Island Side
#### Framework
1. Create your new collector in the following directory: `monkey/infection_monkey/system_info/collectors` by first creating a new file with the name of your collector.
1. Create your new System Info Collector in the following directory: `monkey/infection_monkey/system_info/collectors` by first creating a new file with the name of your System Info Collector.
2. In that file, create a class that inherits from the `SystemInfoCollector` class:
```py
@ -29,7 +29,7 @@ from infection_monkey.system_info.system_info_collector import SystemInfoCollect
class MyNewCollector(SystemInfoCollector):
```
3. Set the Collector name in the constructor, like so:
3. Set the System Info Collector name in the constructor, like so:
```py
class MyNewCollector(SystemInfoCollector):
@ -39,15 +39,15 @@ class MyNewCollector(SystemInfoCollector):
#### Implementation
Override the `collect` method with your own implementation. See the `EnvironmentCollector.py` Collector for reference. You can log during collection as well.
Override the `collect` method with your own implementation. See the `EnvironmentCollector.py` System Info Collector for reference. You can log during collection as well.
### Island side
### From the Monkey Island Side
#### Island Configuration
#### Configuration
##### Definitions
You'll need to add your Collector to the `monkey_island/cc/services/config_schema.py` file, under `definitions/system_info_collectors_classes/anyOf`, like so:
You'll need to add your Sytem Info Collector to the `monkey_island/cc/services/config_schema.py` file, under `definitions/system_info_collectors_classes/anyOf`, like so:
```json
"system_info_collectors_classes": {
@ -76,7 +76,7 @@ You'll need to add your Collector to the `monkey_island/cc/services/config_schem
##### properties
Also, you can add the Collector to be used by default by adding it to the `default` key under `properties/monkey/system_info/system_info_collectors_classes`:
Also, you can add the System Info Collector to be used by default by adding it to the `default` key under `properties/monkey/system_info/system_info_collectors_classes`:
```json
"system_info_collectors_classes": {
@ -96,6 +96,6 @@ Also, you can add the Collector to be used by default by adding it to the `defau
#### Telemetry processing
1. Add a process function under `monkey_island/cc/telemetry/processing/system_info_collectors/{DATA_NAME_HERE}.py`. The function should parse the collector's result. See `processing/system_info_collectors/environment.py` for example.
1. Add a process function under `monkey_island/cc/telemetry/processing/system_info_collectors/{DATA_NAME_HERE}.py`. The function should parse the System Info Collector's result. See `processing/system_info_collectors/environment.py` for example.
2. Add that function to `SYSTEM_INFO_COLLECTOR_TO_TELEMETRY_PROCESSORS` under `monkey_island/cc/services/telemetry/processing/system_info_collectors/system_info_telemetry_dispatcher.py`.

36
docs/content/development/contribute-documentation.md
View File

@ -6,11 +6,11 @@ weight: 1
tags: ["contribute"]
---
The `/docs` folder contains the Monkey Documentation site.
The `/docs` folder contains the Infection Monkey Documentation site.
The site is based on [Hugo](https://gohugo.io/) and the [learn](https://themes.gohugo.io/theme/hugo-theme-learn/en) theme.
- [Directory Structure](#directory-structure)
- [Directory structure](#directory-structure)
- [content](#content)
- [static](#static)
- [config](#config)
@ -30,35 +30,35 @@ The site is based on [Hugo](https://gohugo.io/) and the [learn](https://themes.g
- [`failed to extract shortcode: template for shortcode "children" not found` or theme doesn't seem right?](#failed-to-extract-shortcode-template-for-shortcode-children-not-found-or-theme-doesnt-seem-right)
- [CSS is missing](#css-is-missing)
## Directory Structure
## Directory structure
By order of importance:
### content
### Content
The most important directory is `/content`: This is the directory which contains the content files. [Read this to understand how pages are organized in that folder](https://themes.gohugo.io//theme/hugo-theme-learn/en/cont/pages/).
The most important directory is `/content`. This is the directory which contains the content files. [Read this to understand how pages are organized in that folder](https://themes.gohugo.io//theme/hugo-theme-learn/en/cont/pages/).
### static
### Static
In this directory you should place images, `css` files, `js` files, and other static content the site should serve. To access that static content in a page, use something similar to this:
In this directory you should place images, `css` files, `js` files and other static content the site should serve. To access that static content in a page, use something similar to this:
```markdown
![AWS instance ID](../../images/setup/aws/aws-instance-id.png "AWS instance ID")
```
### config
### Config
This folder controls a lot of parameters regarding the site generation.
This folder controls many of the parameters regarding the site generation.
### themes
### Themes
This is the theme we're using. It's a submodule (so to get it you need to run `git submodule update`). It's our own fork of the [learn](https://themes.gohugo.io/hugo-theme-learn/) theme. If we want to make changes to the theme itself or pull updates from the upstream you'll do it here.
This is the theme we're using. It's a submodule (to get it you need to run `git submodule update`). It's our own fork of the [learn](https://themes.gohugo.io/hugo-theme-learn/) theme. If you want to make changes to the theme itself, or pull updates from the upstream, you'll do it here.
### layouts and archtypes
### Layouts and archtypes
This directory includes custom [HTML partials](https://gohugo.io/templates/partials/), custom [shortcodes](https://gohugo.io/content-management/shortcodes/), and content templates. Best to not mess with the existing stuff here too much, but rather add new things.
This directory includes custom [HTML partials](https://gohugo.io/templates/partials/), custom [shortcodes](https://gohugo.io/content-management/shortcodes/) and content templates. It's best not to mess with the existing stuff here too much, but rather add new things.
### public and resources
### Public and resources
These are the build output of `hugo` and should never be `commit`-ed to git.
@ -66,13 +66,13 @@ These are the build output of `hugo` and should never be `commit`-ed to git.
### Requirements
You have to [install `hugo`](https://gohugo.io/getting-started/installing/), a text editor that's good for markdown (`vscode` and `vim` are good options), and `git`.
You'll have to [install `hugo`](https://gohugo.io/getting-started/installing/), a text editor that's good for markdown (`vscode` and `vim` are good options) and `git`.
### Adding and editing content
#### Add a new page
Run `hugo new folder/page.md`. Optionally add `--kind chapter` if this is a new chapter page. For example, `hugo new usage/getting-started.md` created the Getting Started page.
Run `hugo new folder/page.md`. Optionally add `--kind chapter` if creating a new chapter page. For example, `hugo new usage/getting-started.md` created the Getting Started page.
#### Editing an existing page
@ -92,11 +92,11 @@ Run `hugo --environment staging` or `hugo --environment production`. This will c
##### `Error: Unable to locate config file or config directory. Perhaps you need to create a new site.`
What is your working directory? It should be `monkey/docs`.
Did you confirm your working directory? It should be `monkey/docs`.
##### `failed to extract shortcode: template for shortcode "children" not found` or theme doesn't seem right?
Have you ran `git submodule update`?
Have you run `git submodule update`?
##### CSS is missing

10
docs/content/development/setup-development-environment.md
View File

@ -8,17 +8,17 @@ tags: ["contribute"]
## Deployment scripts
To setup development environment using scripts look at the readme under [`/deployment_scripts`](https://github.com/guardicore/monkey/blob/develop/deployment_scripts). If you want to setup it manually or if run into some problems, read further below.
To set up a development environment using scripts, look at the readme under [`/deployment_scripts`](https://github.com/guardicore/monkey/blob/develop/deployment_scripts). If you want to set it up manually or run into problems, keep reading.
## Agent
The Agent, (what we refer as the Monkey), is a single Python project under the [`infection_monkey`](https://github.com/guardicore/monkey/blob/master/monkey/infection_monkey) folder. Built for Python 3.7, you can get it up and running by setting up a [virtual environment](https://docs.python-guide.org/dev/virtualenvs/) and inside it installing the requirements listed under [`requirements.txt`](https://github.com/guardicore/monkey/blob/master/monkey/infection_monkey/requirements.txt).
The agent (which we sometimes refer to as the Infection Monkey) is a single Python project under the [`infection_monkey`](https://github.com/guardicore/monkey/blob/master/monkey/infection_monkey) folder. The Infection Monkey agent was built for Python 3.7. You can get it up and running by setting up a [virtual environment](https://docs.python-guide.org/dev/virtualenvs/) and installing the requirements listed in the [`requirements.txt`](https://github.com/guardicore/monkey/blob/master/monkey/infection_monkey/requirements.txt) inside it.
In order to compile the Monkey for distribution by the Monkey Island, you need to run the instructions listed in [`readme.txt`](https://github.com/guardicore/monkey/blob/master/monkey/infection_monkey/readme.txt) on each supported environment.
In order to compile the Infection Monkey for distribution by the Monkey Island, you'll need to run the instructions listed in the [`readme.txt`](https://github.com/guardicore/monkey/blob/master/monkey/infection_monkey/readme.txt) on each supported environment.
This means setting up an environment with Linux 32/64-bit with Python installed and a Windows 64-bit machine with developer tools + 32/64-bit Python versions.
This means setting up an environment with Linux 32/64-bit with Python installed and a Windows 64-bit machine with developer tools, along with 32/64-bit Python versions.
## Monkey Island
## The Monkey Island
The Monkey Island is a Python backend React frontend project. Similar to the agent, the backend's requirements are listed in the matching [`requirements.txt`](https://github.com/guardicore/monkey/blob/master/monkey/monkey_island/requirements.txt).

10
docs/content/development/swimm.md
View File

@ -6,24 +6,24 @@ weight: 3
tags: ["contribute"]
---
The Monkey has development tutorials that use [`swimm.io`](https://swimm.io/) to help teach new developers how to perform common code tasks in the Monkey codebase and help the ramp-up process. The tutorial include adding new configuration values, new system info collectors, and more.
The Infection Monkey has development tutorials that use [`swimm.io`](https://swimm.io/) to help teach new developers how to perform common code tasks in the Infection Monkey codebase and accelerate the ramp-up process. The tutorials include adding new configuration values, new system info collectors and more.
![swimm logo](https://swimm.io/img/squarelogo.png "swimm logo")
# How to start learning
First, [sign up for swimm's beta](https://swimm.io/sign-beta). `swimm` is free for open-source projects, but as they're still in beta, you need to sign up in order to download it.
First, [sign up for swimm's beta](https://swimm.io/sign-beta). `swimm` is free for open-source projects, but as they're still in beta you'll need to sign up in order to download it.
After you've downloaded and installed `swimm`, open a shell in the Monkey repo folder and run:
After you've downloaded and installed `swimm`, open a shell in the Infeciton Monkey repo folder and run:
```shell script
swimm start
```
A local web server with the currently available tutorials should show up, and look something like this:
A local web server with the currently available tutorials should show up, and will look something like this:
![swimm server](https://i.imgur.com/NFBH4Vr.png "swimm server")
Choose which playlist you'd like to learn, click on it, and follow the instructions.
Choose which playlist you'd like to learn, click on it and follow the instructions.
🏊‍♀️🏊‍♂️

2
docs/content/reports/_index.md
View File

@ -8,6 +8,6 @@ pre = "<i class='fas fa-scroll'></i> "
# Infection Monkey's Reports
The Monkey offers three reports:
The Infection Monkey offers three reports:
{{% children description=true style="p"%}}

16
docs/content/reports/mitre.md
View File

@ -6,12 +6,12 @@ draft: false
---
{{% notice info %}}
Check out [the documentation for the other reports](../) and [the documentation for supported ATT&CK techniques as well](../../../reference/mitre_techniques).
Check out [the documentation for other reports available in the Infection Monkey](../) and [the documentation for supported ATT&CK techniques](../../../reference/mitre_techniques).
{{% /notice %}}
The Monkey maps its actions to the [MITRE ATT&CK](https://attack.mitre.org/) knowledge base: It provides a new report with the utilized techniques and recommended mitigations, to help you simulate an APT attack on your network and mitigate real attack paths intelligently.
The Infection Monkey maps its actions to the [MITRE ATT&CK](https://attack.mitre.org/) knowledge base. After simulating an advanced persistent threat (APT) attack, it generates a report summarizing the success of the techniques utilized along with recommended mitigation steps, helping you identify and mitigate attack paths in your environment.
Watch an overview video:
Watch the overview video:
{{% youtube 3tNrlutqazQ %}}
@ -21,17 +21,17 @@ The MITRE ATT&CK report is centred around the ATT&CK matrix:
![MITRE Report](/images/usage/reports/mitre-report-0.png "MITRE Report")
The Monkey rates your network on the attack techniques it attempted. For each technique, you can get
The Infection Monkey rates your network on the attack techniques it attempted, assigning one of the corresponding labels to each:
- {{< label danger Red >}}: The Monkey **successfully used** the technique in the simulation. That means your network is vulnerable to this technique being employed.
- {{< label warning Yellow >}}: The Monkey **tried to use** the technique, but didn't manage to. That means your network isn't vulnerable to the way Monkey employs this technique.
- {{< label danger Red >}}: The Infection Monkey **successfully used** this technique in the simulation. This means your network is vulnerable to the technique.
- {{< label warning Yellow >}}: The Infection Monkey **tried to use** the technique, but wasn’t successful. This means your network isn't vulnerable to the way Infection Monkey employed this technique.
- {{< label unused "Dark Gray" >}}: The Monkey **didn't try** the technique. Perhaps it wasn't relevant to this network.
- {{< label disabled "Light Gray" >}}: The Monkey **didn't try** the technique since it wasn't configured.
Then, you can see exactly HOW the technique was used in this attack, and also what you should do to mitigate it, by clicking on the technique and seeing the details. For example, let's look at the [**Brute Force**](https://attack.mitre.org/techniques/T1110/) technique that's a part of employing the [**Credentials Access**](https://attack.mitre.org/tactics/TA0006/) tactic:
By clicking on each of the listed techniques, you can see exactly how the Infection Monkey used it and any recommended mitigation steps. For example, let's look at the [**Brute Force**](https://attack.mitre.org/techniques/T1110/) technique that's a part of employing the [**Credentials Access**](https://attack.mitre.org/tactics/TA0006/) tactic:
![MITRE Report Credentials Access technique](/images/usage/reports/mitre-report-cred-access.png "MITRE Report Credentials Access technique")
In this example, you can see how the Monkey was able to use one old `root` password to access all machines in the network. When scrolling to the bottom of this list, you can also see the mitigation recommended, including **Account Use Policies** and implementing **Multiple Factor Authentication**.
In this example, you can see how the Infection Monkey was able to use an old `root` password to access all machines in the network. When scrolling to the bottom of this list, you can also see the mitigation steps recommended, including reconfiguring your **Account Use Policies** and implementing **Multi-factor Authentication**.
![MITRE Report Credentials Access technique](/images/usage/reports/mitre-report-cred-access-mitigations.png "MITRE Report Credentials Access technique")

56
docs/content/reports/security.md
View File

@ -6,93 +6,93 @@ description: "Provides actionable recommendations and insight into an attacker's
---
{{% notice info %}}
Check out [the documentation for the other reports as well](../).
Check out [the documentation for other reports available in the Infection Monkey](../).
{{% /notice %}}
The Monkey's Security Report is built to provide you with actionable recommendations and insight to the Attacker's view of your network. You can download a PDF of this example report:
The Infection Monkey's **Security Report** provides you with actionable recommendations and insight into an attacker's view of your network. You can download a PDF of an example report here:
{{%attachments title="Download the PDF" pattern=".*(pdf)"/%}}
The report is split into 3 main categories: "Overview", "Recommendations" and "The network from the Monkey's eyes".
The report is split into three main categories:
- [Overview](#overview)
- [High level information](#high-level-information)
- [Used Credentials](#used-credentials)
- [High-level information](#high-level-information)
- [Used credentials](#used-credentials)
- [Exploits and targets](#exploits-and-targets)
- [Security Findings](#security-findings)
- [Security findings](#security-findings)
- [Recommendations](#recommendations)
- [Machine related recommendations relating to specific CVEs](#machine-related-recommendations-relating-to-specific-cves)
- [Machine related recommendations relating to network security and segmentation](#machine-related-recommendations-relating-to-network-security-and-segmentation)
- [Machine-related recommendations relating to specific CVEs](#machine-related-recommendations-relating-to-specific-cves)
- [Machine-related recommendations relating to network security and segmentation](#machine-related-recommendations-relating-to-network-security-and-segmentation)
- [The network from the Monkey's eyes](#the-network-from-the-monkeys-eyes)
- [Network infection map](#network-infection-map)
- [Scanned servers](#scanned-servers)
- [Exploits and post-breach actions](#exploits-and-post-breach-actions)
- [Stolen Credentials](#stolen-credentials)
- [Stolen credentials](#stolen-credentials)
## Overview
The overview section of the report provides high-level information about the Monkey execution and the main security findings that the Monkey has found.
The overview section of the report provides high-level information about the Infection Monkey's execution and main security findings.
### High level information
### High-level information
The report starts with information about the execution, including how long the simulation took and from which machine the infection started from.
This section shows general information about the Infection Monkey's execution, including which machine the infection originated from and how long the breach simulation took.
![Overview](/images/usage/reports/sec_report_1_overview.png "Overview")
### Used Credentials
### Used credentials
The report will show which credentials were used for brute-forcing.
This section shows which credentials were used for brute-forcing.
![Used Credentials](/images/usage/reports/sec_report_2_users_passwords.png "Used Credentials")
### Exploits and targets
The report shows which exploits were attempted in this simulation and which targets the Monkey scanned and tried to exploit.
This section shows which exploits were attempted in this simulation and which targets the Infection Monkey scanned and tried to exploit.
![Exploits and Targets](/images/usage/reports/sec_report_3_exploits_ips.png "Exploits and Targets")
### Security Findings
### Security findings
The report highlights the most important security threats and issues the Monkey discovered during the attack.
This section highlights the most important security threats and issues discovered during the attack.
![Threats and issues](/images/usage/reports/sec_report_4_threats_and_issues.png "Threats and issues")
## Recommendations
This section contains the Monkey's recommendations for improving your security - what mitigations you need to implement.
This section contains recommendations for improving your security, including actionable mitigation steps.
### Machine related recommendations relating to specific CVEs
### Machine-related recommendations relating to specific CVEs
![Machine related recommendations](/images/usage/reports/sec_report_5_machine_related.png "Machine related recommendations")
![Machine-related recommendations](/images/usage/reports/sec_report_5_machine_related.png "Machine related recommendations")
### Machine related recommendations relating to network security and segmentation
### Machine-related recommendations relating to network security and segmentation
![Machine related recommendations](/images/usage/reports/sec_report_6_machine_related_network.png "Machine related recommendations")
![Machine-related recommendations](/images/usage/reports/sec_report_6_machine_related_network.png "Machine related recommendations")
## The network from the Monkey's eyes
This section contains the Infection Map and some summary tables on servers the Monkey has found.
This section contains the infection map and summary tables on servers the Infection Monkey found.
### Network infection map
This part shows the network map and a breakdown of how many machines were breached.
This section shows the network map and a breakdown of how many machines the Infection Monkey breached.
![Network map](/images/usage/reports/sec_report_7_network_map.png "Network map")
### Scanned servers
This part shows the attack surface the Monkey has found.
This section shows the attack surface the Infection Monkey discovered.
![Scanned servers](/images/usage/reports/sec_report_8_network_services.png "Scanned servers")
### Exploits and post-breach actions
This part shows which exploits and Post Breach Actions the Monkey has performed in this simulation.
This section shows which exploits and post-beach actions the Infection Monkey performed during the simulation.
![Exploits and PBAs](/images/usage/reports/sec_report_9_exploits_pbas.png "Exploits and PBAs")
### Stolen Credentials
### Stolen credentials
This part shows which credentials the Monkey was able to steal from breached machines in this simulation.
This section shows which credentials the Infection Monkey was able to steal from breached machines during this simulation.
![Stolen creds](/images/usage/reports/sec_report_10_stolen_credentials.png "Stolen creds")

22
docs/content/reports/zero-trust.md
View File

@ -6,14 +6,18 @@ description: "Generates a status report with detailed explanations of Zero Trust
---
{{% notice info %}}
Check out [the documentation for the other reports as well](../).
Check out [the documentation for other reports available in the Infection Monkey](../).
{{% /notice %}}
The Guardicore Infection Monkey runs different tests to evaluate your network adherence to key components of the Zero Trust framework as established by Forrester, such as whether you have applied segmentation, user identity, encryption and more. Then, the Monkey generates a status report with detailed explanations of security gaps and prescriptive instructions on how to rectify them.
The Guardicore Infection Monkey runs different tests to evaluate your network's adherence to the Zero Trust framework's key components established by Forrester, such as whether you have applied segmentation, verified user identities, enabled encryption and more. Then, the Infection Monkey generates a status report with detailed explanations of security gaps and prescriptive instructions for rectifying them.
Watch the overview video here:
{{% youtube z4FNu3WCd9o %}}
## Summary
This diagram provides a quick glance at how your organization scores on each component of the Forrester's Zero Trust model with **Failed**, **Verify**, **Passed** and **Unexecuted** verdicts.
This diagram provides you with a quick glance at how your organization scores on each pillar of the Forrester Zero Trust model with **Failed**, **Verify**, **Passed** and **Unexecuted** verdicts.
- {{< label danger Failed >}} At least one of the tests related to this component failed. This means that the Infection Monkey detected an unmet Zero Trust requirement.
- {{< label warning Verify >}} At least one of the tests' results related to this component requires further manual verification.
@ -24,24 +28,18 @@ This diagram provides a quick glance at how your organization scores on each com
## Test Results
See how your network fared against each of the tests the Infection Monkey ran. The tests are ordered by Zero Trust components so you can quickly navigate to the components you care about first.
This section shows how your network fared against each of the tests the Infection Monkey ran. The tests are ordered by Zero Trust pillar, so you can quickly navigate to the category you want to prioritize.
![Zero Trust Report test results](/images/usage/reports/ztreport2.png "Zero Trust Report test results")
## Findings
Deep-dive into the details of each test, and see the explicit events and exact timestamps in which things happened in your network. This will enable you to match up with your SOC logs and alerts and to gain deeper insight as to what exactly happened during each of the tests.
This section shows each test's details, including the explicit events and exact timestamps for the activities that took place in your network. This enables you to compare results with your SOC logs and alerts to gain more in-depth insights.
![Zero Trust Report Findings](/images/usage/reports/ztreport3.png "Zero Trust Report Findings")
## Events
The results are exportable. Click Export after clicking on Events to view them in a machine-readable format.
Your results are exportable. Click **Export** after clicking on **Events** to view them in a machine-readable format.
![Zero Trust Report events](/images/usage/reports/ztreport4.png "Zero Trust Report events")
## Overview Video
You can check out an overview video here:
{{% youtube z4FNu3WCd9o %}}

2
docs/content/setup/accounts-and-security.md
View File

@ -9,7 +9,7 @@ tags: ["usage", "password"]
## Security in the Infection Monkey
The first time you launch Monkey Island (the Infection Monkey CC server), you'll be prompted to create an account and secure your island. After account creation, the server will only be accessible via the credentials you entered.
The first time you launch Monkey Island (the Infection Monkey C&C server), you'll be prompted to create an account and secure your island. After account creation, the server will only be accessible via the credentials you entered.
If you want an island to be accessible without credentials, press *I want anyone to access the island*. Please note that this option is insecure, and you should only use it in development environments.

4
docs/content/usage/_index.md
View File

@ -8,6 +8,6 @@ pre = '<i class="fas fa-users-cog"></i> '
# Usage
If you're just starting with Infection Monkey, check out our [Getting Started](getting-started) page.
If you're new to the Infection Monkey, check out our [Getting Started](getting-started) page.
If you haven't downloaded Monkey yet, {{% button href="https://www.guardicore.com/infectionmonkey/#download" icon="fas fa-download" %}}Get Infection Monkey here{{% /button %}}!
If you haven't downloaded the Infection Monkey yet, {{% button href="https://www.guardicore.com/infectionmonkey/#download" icon="fas fa-download" %}}Get Infection Monkey here{{% /button %}}!

4
docs/content/usage/configuration/_index.md
View File

@ -7,9 +7,9 @@ weight: 3
pre: "<i class='fas fa-sliders-h'></i> "
---
# Configure the Monkey
# Configure the Infection Monkey
The Monkey is highly configurable. Nearly every part of it can be modified to turn it to a fast acting worm or into a port scanning and system information collecting machine.
The Infection Monkey is highly configurable. Nearly every part of it can be modified to turn it into a fast-acting worm or a port scanning and system information collecting machine.
{{% notice warning %}}
This section of the documentation is incomplete and under active construction.

2
docs/content/usage/configuration/basic-credentials.md
View File

@ -5,6 +5,6 @@ draft: false
description: "Configure credentials that the Monkey will use for propagation."
---
In this screen you can feed the Monkey with “stolen” credentials for your network, simulating an attacker with inside knowledge.
On this screen you can feed the Infection Monkey “stolen” credentials from your network, simulating an attacker with inside knowledge.
![Configure credentials](/images/usage/configuration/credentials.png "Configure credentials")

6
docs/content/usage/configuration/basic-network.md
View File

@ -7,6 +7,6 @@ description: "Configure settings related to the Monkey's network activity."
Here you can control multiple important settings, such as:
* Network propagation depth - How many hops from the base machine will the Monkey spread
* Local network scan - Should the Monkey attempt to attack any machine in its subnet
* Scanner IP/subnet list - Specific IP ranges that the Monkey should try to attack.
* Network propagation depth - How many hops from the base machine will the Infection Monkey spread?
* Local network scan - Should the Infection Monkey attempt to attack any machine in its subnet?
* Scanner IP/subnet list - Which specific IP ranges should the Infection Monkey should try to attack?

22
docs/content/usage/getting-started.md
View File

@ -7,7 +7,7 @@ pre: "<i class='fas fa-play-circle'></i> "
tags: ["usage"]
---
If you haven't deployed the Monkey Island yet, please [refer to our setup documentation](/setup)
If you haven't deployed the Monkey Island yet, please [refer to our setup documentation](/setup).
## Using the Infection Monkey
@ -15,26 +15,26 @@ After deploying the Monkey Island in your environment, navigate to `https://<ser
### First-time login
On your first login, you'll be asked to set up a username and password for the Monkey Island server. [See this page for more details](../../setup/accounts-and-security).
On your first login, you'll be asked to create a username and password for the Monkey Island server. [See this page for more details](../../setup/accounts-and-security).
### Run the Monkey
### Running the Infection Monkey
To get the Infection Monkey running as fast as possible, click **Run Monkey**. Optionally, you can configure the Monkey before you continue by clicking **Configuration** (see [how to configure the monkey](../configuration)).
To get the Infection Monkey running as fast as possible, click **Run Monkey**. Optionally, you can configure the Infection Monkey before you continue by clicking on **Configuration** (see [how to configure the Infection Monkey](../configuration)).
To run the monkey, select one of the following options:
To run the Infection Monkey, select one of the following options:
![Run Page](/images/usage/getting-started/run_page_with_arrows.jpg "Run Page")
1. Click **Run on C&C Server** to run the Infection Monkey on the Monkey Island server. This simulates an attacker trying to propagate through local network from Monkey Island machine.
2. Click **Run on machine of your choice** to download and execute the Infection Monkey on a machine of your choice. Then follow the instructions and execute the generated command on the machine of your choice. This simulates an attacker who has breached one of your servers. The Monkey will map all accessible machines and their open services and try to steal credentials and use its exploits to propagate.
1. Click **Run on C&C Server** to run the Infection Monkey on the Monkey Island server. This simulates an attacker trying to propagate through your local network from the Monkey Island machine.
2. Click **Run on machine of your choice** to download and execute the Infection Monkey on a machine of your choice. Then follow the instructions and run the generated command on the machine you selected. This simulates an attacker who has breached one of your servers. The Infection Monkey will map all accessible machines and their open services, attempting to steal credentials and use exploits to propagate.
![Run on machine of your choice](/images/usage/getting-started/run_page_button_no_arrow.jpg "Run on machine of your choice")
{{% notice tip %}}
If you're running in an AWS cloud environment, check out [Usage -> Integrations](../../usage/integrations) for information about how Monkey integrates with AWS.
If you're running the Infection Monkey in an AWS cloud environment, check out [Usage -> Integrations](../../usage/integrations) for information about how it integrates with AWS.
{{% /notice %}}
### Infection Map
### Infection map
Next, click **Infection Map** to see the Infection Monkey in action.
@ -48,8 +48,8 @@ Within a few minutes, the Infection Monkey should be able to find and attack acc
![Middle of Monkey execution](/images/usage/getting-started/single_exploitation.JPG "Middle of Monkey execution")
As the Infection Monkey continues, the map should be filled with accessible and “hacked” machines. Once all the Infection Monkeys have finished propagating, click **Reports** to see the reports. See [Infection Monkey Reports](../reports) for more info.
As the simulation continues, the Infection Monkey will fill in the map with data on accessible and "hacked" machines. Once all the Infection Monkeys have finished propagating, click **Reports** to see the reports. See [Infection Monkey Reports](../reports) for more info.
![End of Monkey execution](/images/usage/getting-started/exploitation_tunneling_arrow.jpg "End of Monkey execution")
Congratulations, you finished first successful execution of the Infection Monkey! 🎉 To thoroughly test your network, you can run the Infection Monkey from different starting locations using different configurations.
Congratulations, you finished your first successful execution of the Infection Monkey 🎉 ! To thoroughly test your network, you can run the Infection Monkey from different starting locations and use different configurations.

4
docs/content/usage/integrations/_index.md
View File

@ -7,8 +7,8 @@ weight: 10
pre: "<i class='fas fa-directions'></i> "
---
# Integrate the Monkey with 3rd party software
# Integrate the Infection Monkey with third-party software
The Monkey likes working together. See these documentation pages for information on each integration the Monkey currently offers:
The Infection Monkey likes working together! See these documentation pages for information on each integration the Infection Monkey currently offers:
{{% children description=true style="p"%}}

42
docs/content/usage/integrations/aws-run-on-ec2-machine.md
View File

@ -8,23 +8,23 @@ tags: ["aws", "integration"]
## When to use this feature
If your network is deployed on Amazon Web Services (with EC2 instances), and you'd like to run the Infection Monkey in order to test it, this page is for you. You can easily run the monkey on **various instances** within your network - in a secure fashion, **without** feeding the Island with any credentials or running shell commands on the machines you want to test.
If your network is deployed on Amazon Web Services (with EC2 instances) and you'd like to run the Infection Monkey to test it, this page is for you. You can easily run the Infection Monkey on various instances within your network in a secure fashion, without feeding it credentials or running shell commands on the machines you want to test.
The results will be exported to AWS security hub automatically, as well. To see more information about that, see the [Infection Monkey and AWS Security Hub documentation](https://github.com/guardicore/monkey/wiki/Infection-Monkey-and-AWS-Security-Hub).
The results will be exported to the AWS security hub automatically as well. To learn more about that topic, see the [Infection Monkey and AWS Security Hub documentation](https://github.com/guardicore/monkey/wiki/Infection-Monkey-and-AWS-Security-Hub).
![AWS EC2 logo](/images/usage/integrations/aws-ec2.svg?height=250px "AWS EC2 logo")
## Setup
Assuming your network is already set up in AWS EC2, follow these quick steps to get up and running.
Assuming your network is already set up in AWS EC2, follow the steps below to get up and running quickly.
### Monkey Island deployment
In order to run the Monkeys directly from the Monkey Island server, you need to deploy the Monkey Island server to an AWS EC2 instance in the same network which you want to test. For information about deploying the Monkey Island server, see [setup](../../../setup).
In order to run the Infection Monkey agents directly from the Monkey Island server, you need to deploy the Monkey Island server to an AWS EC2 instance in the same network which you want to test. For information about deploying the Monkey Island server, see [setup](../../../setup).
### Setup IAM roles
In order for the Island to successfully view your instances, you'll need to set appropriate IAM roles to your instances. You can read more about IAM roles [in Amazon's documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html), but it's not necessary in order to follow this setup.
In order for the Infection Monkey to successfully view your instances, you'll need to set appropriate IAM roles for your instances. You can read more about IAM roles [in Amazon's documentation](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html), but it's not necessary in order to follow this setup.
#### Creating a custom IAM role
@ -34,7 +34,7 @@ Go to the [AWS IAM roles dashboard](https://console.aws.amazon.com/iam/home?#/ro
#### Applying the IAM role to an instance
For each instance you'd like to access from the island, apply the new IAM role you've just created to the instance. For example:
For each instance you'd like to access from the Monkey Island, apply the new IAM role you've just created to the instance. For example:
![Applying a custom IAM role](/images/usage/integrations/monkey-island-aws-screenshot-4.png "Applying a custom IAM role")
@ -42,38 +42,38 @@ After applying the IAM role you should see this screen:
![Applying a custom IAM role](/images/usage/integrations/monkey-island-aws-screenshot-5.png "Applying a custom IAM role")
**Note: after setting IAM roles, the roles might take a few minutes (up to 10 minutes sometimes) to effectively kick in.** This is how AWS works and is not related to the Monkey implementation. See [this StackOverflow thread for more details.](https://stackoverflow.com/questions/20156043/how-long-should-i-wait-after-applying-an-aws-iam-policy-before-it-is-valid)
**Note: after setting IAM roles, the roles might take a few minutes (up to 10 minutes sometimes) to effectively kick in.** This is how AWS works and is not related to the Infection Monkey implementation. See [this StackOverflow thread for more details.](https://stackoverflow.com/questions/20156043/how-long-should-i-wait-after-applying-an-aws-iam-policy-before-it-is-valid)
### Setup SSM agent
### Setup the SSM agent
If your EC2 instances don't have the _SSM agent_ installed, they will not be able to execute SSM commands, which means you won't see them in the AWS machines table on the monkey island. Generally speaking, most new EC2 instances ought to have SSM pre-installed; The SSM Agent is installed, by default, on Amazon Linux base AMIs dated 2017.09 and later, and on Amazon Linux 2, Ubuntu Server 16.04, and Ubuntu Server 18.04 LTS AMIs.
If your EC2 instances don't have the _SSM agent_ installed, they will not be able to execute SSM commands, which means you won't see them in the AWS machines table on the Monkey Island. Generally speaking, most new EC2 instances should have SSM pre-installed. The SSM Agent is installed, by default, on Amazon Linux base AMIs dated 2017.09 and later, on Amazon Linux 2, Ubuntu Server 16.04 and Ubuntu Server 18.04 LTS AMIs.
See [Amazon's documentation about working with SSM agents](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent.html) for more details on how to check if you have an SSM agent and how to manually install one if you don't have one.
See [Amazon's documentation about working with SSM agents](https://docs.aws.amazon.com/systems-manager/latest/userguide/ssm-agent.html) for more details on how to check if you have an SSM agent and how to manually install one if you don't yet have it.
## Usage
### Running the monkey
### Running the Infection Monkey
When you run the Monkey Island on an AWS instance, the island detects it's running on AWS and present the following option in the _"Run Monkey"_ page, like so:
When you run the Monkey Island on an AWS instance, the island detects it's running on AWS and presents the following option on the _"Run Monkey"_ page:
![Running a Monkey on EC2 Instance](/images/usage/integrations/monkey-island-aws-screenshot-1.png "Running a Monkey on EC2 Instance")
After you click on "AWS run" you can choose one of the available instances as "patient zero" like so:
After you click on **Run on AWS machine of your choice** you can choose one of the available instances as "patient zero" by:
1. Choose the relevant Network Interface
2. Select the machines you'd like to run the Monkey on
3. Click "Run on Selected Machines", and watch the monkey go! 🐒
1. Choosing the relevant network interface
2. Selecting the machines you'd like to run the Infection Monkey on
3. Clicking **Run on Selected Machines** — now watch the Infection Monkey go! 🐒
![Running a Monkey on EC2 Instance](/images/usage/integrations/monkey-island-aws-screenshot-2.png "Running a Monkey on EC2 Instance")
## Notes
- The machines which can use IAM roles and be listed MUST be internet connected (or you can set up a proxy for IAM). This is standard AWS practice and you can read about it (and about how to set up the required proxy machines) in AWS IAM documentation.
- You can see the monkey in [the AWS marketplace](https://aws.amazon.com/marketplace/pp/B07B3J7K6D).
- The machines which can use IAM roles and be listed MUST be internet connected (or you can set up a proxy for IAM). This is standard AWS practice and you can read about it (and about how to set up the required proxy machines) in the AWS IAM documentation.
- You can view the Infection Monkey in [the AWS marketplace](https://aws.amazon.com/marketplace/pp/B07B3J7K6D).
### Appendix A: Specific policy permissions required
The IAM role will need to have, at least, the following specific permissions:
The IAM role will need to have, at minimum, the following specific permissions:
#### For executing the Monkey on other machines - SSM
@ -100,7 +100,7 @@ Here's the policy of the IAM role, as a JSON object:
}
```
#### For exporting security findings to the Security Hub - security hub
#### For exporting security findings to the AWS Security Hub - security hub
_Note: these can be set on the Monkey Island machine alone, since it's the only one exporting findings to the AWS secutiry hub._
@ -126,7 +126,7 @@ Here's the policy for SecurityHub, as a JSON object:
}
```
The JSON object for both of the policies combined therefore is:
The JSON object for both of the policies combined is:
```json
{

20
docs/content/usage/integrations/aws-security-hub.md
View File

@ -10,31 +10,31 @@ The Infection Monkey integration with the [AWS Security Hub](https://docs.aws.am
![AWS security hub logo](/images/usage/integrations/AWS-Security-Hub-logo.png "AWS security hub logo")
The integration will send _all_ Infection Monkey findings (typically low tens of findings) to the security hub at the end of a Monkey breach simulation.
The integration will send all Infection Monkey findings (typically 10 to 40) to the AWS Security Hub at the end of a breach simulation.
## Setup
If the correct permissions have been set on the AWS IAM role of the Monkey Island machine, then the Island will automatically export its findings to the AWS security hub.
If the correct AWS IAM role permissions have been set on the Monkey Island machine, it will automatically export its findings to the AWS Security Hub.
### Specific permissions required for security hub
### Specific permissions required for the AWS Security Hub
- `"securityhub:UpdateFindings"`
- `"securityhub:BatchImportFindings"`
Note that the integration is specifically between your Monkey Island and the security hub. The Infection Monkey is an free project and there is no centralised infrastructure.
Note that this integration is specifically between your Monkey Island and the AWS Security Hub. The Infection Monkey is a free project, and there is no centralized infrastructure.
### Enabling finding reception
Before starting the scan, make sure that AWS Security Hub is accepting findings by enabling Infection Monkey
integration. Find **GuardiCore: AWS Infection Monkey** integration on the list and click on **Accept findings**.
Before starting the scan, make sure that the AWS Security Hub is accepting findings by enabling the Infection Monkey integration. Find **GuardiCore: AWS Infection Monkey** integration on the list and click on **Accept findings**.
![Enabled integration](/images/usage/integrations/security-hub-enable-accepting-findings.png "Enabled integration")
## Integration details
The Infection Monkey reports the following types of issues to the AWS security hub: `Software and Configuration Checks/Vulnerabilities/CVE`.
The Infection Monkey reports the following types of issues to the AWS Security Hub: `Software and Configuration Checks/Vulnerabilities/CVE`.
Specifically, the Island sends findings for all vulnerabilities it finds along with generic findings on the network (such as segmentation issues). Our normalized severity is 100, while most issues we report range between 1 and 10.
Specifically, the Infection Monkey sends findings for all vulnerabilities it finds along with generic findings on the network (such as segmentation issues). Our normalized severity is 100, while most issues we report range between 1 and 10.
## Regions
@ -42,9 +42,9 @@ The Infection Monkey is usable on all public AWS instances.
## Example
After setting up a monkey environment in AWS and attaching the correct IAM roles to the monkey island machine, the report findings were exported to the security hub.
After setting up the Infection Monkey in AWS and attaching the correct IAM roles to your Monkey Island machine, the report findings were exported to the AWS Security Hub.
1. Navigate to `Findings`.
2. Press on a specific finding to see more details and possible solutions.
2. Click on a specific finding to see more details and possible solutions.
![AWS Security hub console example](/images/usage/integrations/security-hub-console-example.png "AWS Security hub console example")

5
docs/content/usage/use-cases/_index.md
View File

@ -8,12 +8,11 @@ pre = "<i class='fas fa-map-marked-alt'></i> "
# Use cases
This section describes possible use cases for the Infection Monkey and helps to
understand how this tool can be configured.
This section describes possible use cases for the Infection Monkey and how you can configure the tool.
You can also refer to [our FAQ](../../faq) for more specific questions and answers.
{{% notice note %}}
No worries! The Monkey uses safe exploiters and does not cause any permanent system modifications that impact security or operations.
Don't worry! The Infection Monkey uses safe exploiters and does not cause any permanent system modifications that could impact security or operations.
{{% /notice %}}
## Section contents

23
docs/content/usage/use-cases/attack.md
View File

@ -8,31 +8,22 @@ weight: 2
## Overview
Infection Monkey can simulate various [ATT&CK](https://attack.mitre.org/matrices/enterprise/) techniques on the network.
Use it to assess your security solutions' detection and prevention capabilities. Infection Monkey will help you find
which ATT&CK techniques go unnoticed and will provide recommendations about preventing them.
The Infection Monkey can simulate various [ATT&CK](https://attack.mitre.org/matrices/enterprise/) techniques on the network. Use it to assess your security solutions' detection and prevention capabilities. The Infection Monkey will help you find which ATT&CK techniques go unnoticed and provide specific details along with suggested mitigations.
## Configuration
- **ATT&CK matrix** You can use ATT&CK configuration section to select which techniques you want the Monkey to simulate.
Leave default settings for the full simulation.
- **Exploits -> Credentials** This configuration value will be used for brute-forcing. We use most popular passwords
and usernames, but feel free to adjust it according to the default passwords used in your network. Keep in mind that
long lists means longer scanning times.
- **Network -> Scope** Disable “Local network scan” and instead provide specific network ranges in
the “Scan target list”.
- **ATT&CK matrix** You can use the ATT&CK configuration section to select which techniques you want the Infection Monkey to simulate.
For the full simulation, use the default settings.
- **Exploits -> Credentials** This configuration value will be used for brute-forcing. The Infection Monkey uses the most popular default passwords and usernames, but feel free to adjust it according to the default passwords common in your network. Keep in mind a longer list means longer scanning times.
- **Network -> Scope** Disable “Local network scan” and instead provide specific network ranges in the “Scan target list”.
![ATT&CK matrix](/images/usage/scenarios/attack-matrix.png "ATT&CK matrix")
## Suggested run mode
Run the Infection Monkey on as many machines in your environment as you can to get a better assessment. This can be easily
achieved by selecting the “Manual” run option and executing the command shown on different machines in your environment
manually or with your deployment tool.
Run the Infection Monkey on as many machines as you can. You can easily achieve this by selecting the “Manual” run option and executing the command shown on different machines in your environment manually or with your deployment tool. Additionally, you can use any other run options you see fit.
## Assessing results
The **ATT&CK Report** shows the status of ATT&CK techniques simulations. Click on any technique to see more details
about it and potential mitigations. Keep in mind that each technique display contains a question mark symbol that
will take you to the official documentation of ATT&CK technique, where you can learn more about it.
The **ATT&CK Report** shows the status of simulations using ATT&CK techniques. Click on a technique to see more details about it and potential mitigations. Keep in mind that each technique display contains a question mark symbol that will take you to the official documentation of the specific ATT&CK technique used, where you can learn more about it.

24
docs/content/usage/use-cases/credential-leak.md
View File

@ -8,30 +8,28 @@ weight: 5
## Overview
Numerous attack techniques(from phishing to dumpster diving) might result in a credential leak,
Numerous attack techniques (from phishing to dumpster diving) might result in a credential leak,
which can be **extremely costly** as demonstrated in our report [IResponse to IEncrypt](https://www.guardicore.com/2019/04/iresponse-to-iencrypt/).
Infection Monkey can help assess the impact of stolen credentials by automatically searching
where these credentials can be reused.
The Infection Monkey can help you assess the impact of stolen credentials by automatically searching
where bad actors can reuse these credentials in your network.
## Configuration
- **Exploits -> Credentials** After setting up the Island add the users' **real** credentials
(usernames and passwords) to the Monkey's configuration (Don't worry, this sensitive data is not accessible and is not
distributed or used in any way other than being sent to the monkeys, and can be easily eliminated by resetting the Monkey Island's configuration).
- **Internal -> Exploits -> SSH keypair list** Monkey automatically gathers SSH keys on the current system.
For this to work, Monkey Island or initial Monkey needs to have access to SSH key files(grant permission or run Monkey as root).
To make sure SSH keys were gathered successfully, refresh the page and check this configuration value after you run the Monkey
- **Exploits -> Credentials** After setting up the Monkey Island, add your users' **real** credentials
(usernames and passwords) here. Don't worry; this sensitive data is not accessible, distributed or used in any way other than being sent to the Infection Monkey agents. You can easily eliminate it by resetting the configuration of your Monkey Island.
- **Internal -> Exploits -> SSH keypair list** When enabled, the Infection Monkey automatically gathers SSH keys on the current system.
For this to work, the Monkey Island or initial agent needs to access SSH key files.
To make sure SSH keys were gathered successfully, refresh the page and check this configuration value after you run the Infection Monkey
(content of keys will not be displayed, it will appear as `<Object>`).
## Suggested run mode
Execute the Monkey on a chosen machine in your network using the “Manual” run option.
Run the Monkey as a privileged user to make sure it gathers as many credentials from the system as possible.
Execute the Infection Monkey on a chosen machine in your network using the “Manual” run option.
Run the Infection Monkey as a privileged user to make sure it gathers as many credentials from the system as possible.
![Exploit password and user lists](/images/usage/scenarios/user-password-lists.png "Exploit password and user lists")
## Assessing results
To assess the impact of leaked credentials see Security report. It's possible that credential leak resulted in even
more leaked credentials, for that look into **Security report -> Stolen credentials**.
To assess the impact of leaked credentials see the Security report. Examine **Security report -> Stolen credentials** to confirm.

42
docs/content/usage/use-cases/network-breach.md
View File

@ -8,44 +8,40 @@ weight: 3
## Overview
Whether it was the [Hex-men campaign](https://www.guardicore.com/2017/12/beware-the-hex-men/) that hit your
Internet-facing DB server, a [cryptomining operation that attacked your WordPress site](https://www.guardicore.com/2018/06/operation-prowli-traffic-manipulation-cryptocurrency-mining-2/)
or any other malicious campaign – the attackers are now trying to go deeper into your network.
From the [Hex-Men campaign](https://www.guardicore.com/2017/12/beware-the-hex-men/) that hit
internet-facing DB servers to a [cryptomining operation that attacks WordPress sites](https://www.guardicore.com/2018/06/operation-prowli-traffic-manipulation-cryptocurrency-mining-2/) or any other malicious campaign – attackers are now trying to go deeper into your network.
Infection Monkey will help you assess the impact of internal network breach, by trying to propagate within it
using service vulnerabilities, brute-forcing and other safe attack methods.
Infection Monkey will help you assess the impact of a future breach by attempting to propagate within your internal network using service vulnerabilities, brute-forcing and other safe exploiters.
## Configuration
- **Exploits -> Exploits** You can review the exploits Infection Monkey will be using. By default all
- **Exploits -> Exploits** Here you can review the exploits the Infection Monkey will be using. By default all
safe exploiters are selected.
- **Exploits -> Credentials** This configuration value will be used for brute-forcing. We use most popular passwords
and usernames, but feel free to adjust it according to your native language and other factors. Keep in mind that long
lists means longer scanning times.
- **Exploits -> Credentials** This configuration value will be used for brute-forcing. The Infection Monkey uses the most popular default passwords and usernames, but feel free to adjust it according to the default passwords common in your network. Keep in mind a longer list means longer scanning times.
- **Network -> Scope** Make sure to properly configure the scope of the scan. You can select **Local network scan**
and allow Monkey to propagate until maximum **Scan depth**(hop count) is reached or you can fine tune it by providing
specific network ranges in **Scan target list**. Scanning local network is more realistic, but providing specific
targets will make scanning process substantially faster.
- **(Optional) Internal -> Network -> TCP scanner** You can add custom ports your organization is using.
- **(Optional) Monkey -> Post Breach Actions** If you only want to test propagation in the network, you can turn off
all post breach actions. These actions simulate attacker's behaviour after getting access to a new system, but in no
way helps to exploit new machines.
and allow Monkey to propagate until maximum **Scan depth**(hop count) is reached, or you can fine tune it by providing
specific network ranges in **Scan target list**. Scanning a local network is more realistic, but providing specific
targets will make the scanning process substantially faster.
- **(Optional) Internal -> Network -> TCP scanner** Here you can add custom ports your organization is using.
- **(Optional) Monkey -> Post-Breach Actions** If you only want to test propagation in the network, you can turn off
all post-breach actions. These actions simulate an attacker's behavior after getting access to a new system but in no
way helps the Infection Monkey exploit new machines.
![Exploiter selector](/images/usage/use-cases/network-breach.PNG "Exploiter selector")
## Suggested run mode
Decide which machines you want to simulate a breach on and use the “Manual” run option to start Monkeys there.
Use high privileges to run the Monkey to simulate an attacker that was able to elevate its privileges.
You could also simulate an attack initiated from an unidentified machine connected to the network (a technician
laptop, 3rd party vendor machine, etc) by running the Monkey on a dedicated machine with an IP in the network you
Decide which machines you want to simulate a breach on and use the “Manual” run option to start the Infection Monkey on them.
Use administrative privileges to run the Infection Monkey to simulate an attacker that was able to elevate their privileges.
You could also simulate an attack initiated from an unidentified machine connected to the network (e.g., a technician
laptop or third-party vendor machine) by running the Infection Monkey on a dedicated machine with an IP in the network you
wish to test.
## Assessing results
Check infection map and security report to see how far monkey managed to propagate in the network and which
vulnerabilities it used in doing so. If you left post breach actions selected, you should also check ATT&CK and
Zero Trust reports.
Check the infection map and Security report to see how far The Infection Monkey managed to propagate in your network and which
vulnerabilities it successfully exploited. If you left post-breach actions selected, you should also check the MITRE ATT&CK and
Zero Trust reports for more details.
![Map](/images/usage/use-cases/map-full-cropped.png "Map")

35
docs/content/usage/use-cases/network-segmentation.md
View File

@ -8,42 +8,33 @@ weight: 4
## Overview
Segmentation is a method of creating secure zones in data centers and cloud deployments that allows companies to
isolate workloads from one another and secure them individually, typically using policies. A useful way to test
the effectiveness of your segmentation is to ensure that your network segments are properly separated, e,g, your
Development is separated from your Production, your applications are separated from one another etc. Use the
Infection Monkey to verify that your network segmentation is configured properly. This way you make sure that
even if a certain attacker has breached your defenses, it can't move laterally between segments.
Segmentation is a method of creating secure zones in data centers and cloud deployments. It allows organizations to isolate workloads from one another and secure them individually, typically using policies. A useful way to test your company's segmentation effectiveness is to ensure that your network segments are properly separated (e.g., your development environment is isolated from your production environment and your applications are isolated from one another).
[Segmentation is key](https://www.guardicore.com/use-cases/micro-segmentation/) to protecting your network. It can reduce the network's attack surface and minimize the damage caused during a breach.
You can use the Infection Monkey's cross-segment traffic feature to verify that your network segmentation configuration is adequate. This way, you can ensure that, even if a bad actor breaches your defenses, they can't move laterally between segments.
[Segmentation is key](https://www.guardicore.com/use-cases/micro-segmentation/) to protecting your network, reducing
the attack surface and minimizing the damage of a breach. The Monkey can help you test your segmentation settings with
its cross-segment traffic testing feature.
## Configuration
- **Network -> Network analysis -> Network segmentation testing** This configuration setting allows you to define
subnets that should be segregated from each other. If any of provided networks can reach each other, you'll see it
in security report.
- **(Optional) Network -> Scope** You can disable **Local network scan** and leave other options by default if you only want to
test for network segmentation without any lateral movement.
- **(Optional) Monkey -> Post Breach Actions** If you only want to test segmentation in the network, you can turn off
all post breach actions. These actions simulate attacker's behaviour after getting access to a new system, so they
might trigger your defence solutions which will interrupt segmentation test.
subnets that should be segregated from each other. If any of the provided networks can reach each other, you'll see it
in the security report.
- **(Optional) Network -> Scope** You can disable **Local network scan** and leave all other options at the default setting if you only want to test for network segmentation without any lateral movement.
- **(Optional) Monkey -> Post-Breach Actions** If you only want to test segmentation in the network, you can turn off all post-breach actions. These actions simulate an attacker's behavior after getting access to a new system, so they might trigger your defense solutions and interrupt the segmentation test.
## Suggested run mode
Execute Monkeys on machines in different subnetworks using the “Manual” run option.
Execute The Infection Monkey on machines in different subnetworks using the “Manual” run option.
Note that if Monkey can't communicate to the Island, it will
not be able to send scan results, so make sure all machines can reach the island.
Note that if the Infection Monkey can't communicate to the Monkey Island, it will
not be able to send scan results, so make sure all machines can reach the the Monkey Island.
![How to configure network segmentation testing](/images/usage/scenarios/segmentation-config.png "How to configure network segmentation testing")
## Assessing results
Check infection map and security report for segmentation problems. Ideally, all scanned nodes should only have
edges with the Island Server.
Check the infection map and security report for segmentation problems. Ideally, all scanned nodes should only have edges with the Monkey Island Server.
![Map](/images/usage/use-cases/segmentation-map.PNG "Map")

45
docs/content/usage/use-cases/other.md
View File

@ -7,55 +7,48 @@ weight: 100
---
## Overview
This page provides additional information about configuring monkeys, tips and tricks and creative usage scenarios.
This page provides additional information about configuring the Infection Monkey, tips and tricks and creative usage scenarios.
## Custom behaviour
If you want Monkey to run some kind of script or a tool after it breaches a machine, you can configure it in
**Configuration -> Monkey -> Post breach**. Just input commands you want executed in the corresponding fields.
You can also upload files and call them through commands you entered in command fields.
If you want the Infection Monkey to run a specific script or tool after it breaches a machine, you can configure it in
**Configuration -> Monkey -> Post-breach**. Input commands you want to execute in the corresponding fields.
You can also upload files and call them through the commands you entered.
## Accelerate the test
To improve scanning speed you could **specify a subnet instead of scanning all of the local network**.
The following configuration values also have an impact on scanning speed:
- **Credentials** - the more usernames and passwords you input, the longer it will take the Monkey to scan machines having
remote access services. Monkeys try to stay elusive and leave a low impact, thus brute forcing takes longer than with
loud conventional tools.
- **Network scope** - scanning large networks with a lot of propagations can become unwieldy. Instead, try to scan your
- **Credentials** - The more usernames and passwords you input, the longer it will take the Infection Monkey to scan machines that have
remote access services. The Infection Monkey agents try to stay elusive and leave a low impact, and thus brute-forcing takes longer than with loud conventional tools.
- **Network scope** - Scanning large networks with a lot of propagations can become unwieldy. Instead, try to scan your
networks bit by bit with multiple runs.
- **Post breach actions** - you can disable most of these if you only care about propagation.
- **Internal -> TCP scanner** - you can trim the list of ports monkey tries to scan increasing performance even further.
- **Post-breach actions** - If you only care about propagation, you can disable most of these.
- **Internal -> TCP scanner** - Here you can trim down the list of ports the Infection Monkey tries to scan, improving performance.
## Combining different scenarios
Infection Monkey is not limited to the scenarios mentioned in this section, once you get the hang of configuring it,
you might come up with your own use case or test all of suggested scenarios at the same time! Whatever you do,
Security, ATT&CK and Zero Trust reports will be waiting for you!
The Infection Monkey is not limited to the scenarios mentioned in this section. Once you get the hang of configuring it, you might come up with your own use case or test all of the suggested scenarios at the same time! Whatever you do, the Infection Monkey's Security, ATT&CK and Zero Trust reports will be waiting for you with your results!
## Persistent scanning
Use **Monkey -> Persistent** scanning configuration section to either have periodic scans or to increase reliability of
exploitations by running consecutive Infection Monkey scans.
Use **Monkey -> Persistent** scanning configuration section to either run periodic scans or increase the reliability of exploitations by running consecutive scans with the Infection Monkey.
## Credentials
Every network has its old “skeleton keys” that should have long been discarded. Configure the Monkey with old and stale
passwords, but make sure that they were really discarded using the Monkey. To add the old passwords, in the island's
configuration, go to the “Exploit password list” under “Basic - Credentials” and use the “+” button to add the old
passwords to the configuration. For example, here we added a few extra passwords (and a username as well) to the
configuration:
Every network has its old "skeleton keys" that it should have long discarded. Configuring the Infection Monkey with old and stale passwords will enable you to ensure they were really discarded.
To add the old passwords, go to the Monkey Island's **Exploit password list** under **Basic - Credentials** and use the "+" button to add the old passwords to the configuration. For example, here we added a few extra passwords (and a username as well) to the configuration:
![Exploit password and user lists](/images/usage/scenarios/user-password-lists.png "Exploit password and user lists")
## Check logged and monitored terminals
To see the Monkey executing in real-time on your servers, add the **post-breach action** command:
`wall “Infection Monkey was here”`. This post breach command will broadcast a message across all open terminals on
the servers the Monkey breached, to achieve the following: Let you know the Monkey ran successfully on the server.
Let you follow the breach “live” alongside the infection map, and check which terminals are logged and monitored
inside your network. See below:
To see the Infection Monkey executing in real-time on your servers, add the **post-breach action** command:
`wall “Infection Monkey was here”`. This post-breach command will broadcast a message across all open terminals on the servers the Infection Monkey breached to achieve the following:
- Let you know the Monkey ran successfully on the server.
- Let you follow the breach “live” alongside the infection map.
- Check which terminals are logged and monitored inside your network.
![How to configure post breach commands](/images/usage/scenarios/pba-example.png "How to configure post breach commands.")

22
docs/content/usage/use-cases/zero-trust.md
View File

@ -8,35 +8,25 @@ weight: 1
## Overview
Infection Monkey will help you assess your progress on your journey to achieve Zero Trust network.
The Infection Monkey will automatically assess your readiness across the different
Want to assess your progress in achieving a Zero Trust network? The Infection Monkey can automatically evaluate your readiness across the different
[Zero Trust Extended Framework](https://www.forrester.com/report/The+Zero+Trust+eXtended+ZTX+Ecosystem/-/E-RES137210) principles.
## Configuration
- **Exploits -> Credentials** This configuration value will be used for brute-forcing. We use most popular passwords
and usernames, but feel free to adjust it according to the default passwords used in your network.
Keep in mind that long lists means longer scanning times.
- **Network -> Scope** Disable “Local network scan” and instead provide specific network ranges in the “Scan target list”.
- **Exploits -> Credentials** This configuration value will be used for brute-forcing. The Infection Monkey uses the most popular default passwords and usernames, but feel free to adjust it according to the default passwords common in your network. Keep in mind a longer list means longer scanning times.
- **Network -> Scope** Disable “Local network scan” and instead provide specific network ranges in the “Scan target list.”
- **Network -> Network analysis -> Network segmentation testing** This configuration setting allows you to define
subnets that should be segregated from each other.
In general, other configuration value defaults should be good enough, but feel free to see the “Other” section
for tips and tricks about other features and in-depth configuration parameters you can use.
In general, other configuration value defaults should be good enough, but feel free to see the “Other” section for tips and tricks about more features and in-depth configuration parameters you can use.
![Exploit password and user lists](/images/usage/scenarios/user-password-lists.png "Exploit password and user lists")
## Suggested run mode
Run the Monkey on as many machines as you can. This can be easily achieved by selecting the “Manual” run option and
executing the command shown on different machines in your environment manually or with your deployment tool.
In addition, you can use any other run options you see fit.
Run the Infection Monkey on as many machines as you can. You can easily achieve this by selecting the “Manual” run option and executing the command shown on different machines in your environment manually or with your deployment tool. Additionally, you can use any other run options you see fit.
## Assessing results
See the results in the Zero Trust report section. “The Summary” section will give you an idea about which Zero Trust
pillars were tested, how many tests were done and test statuses. Specific tests are described in the “Test Results”
section. The “Findings” section shows details about the Monkey actions. Click on “Events” of different findings to
observe what exactly Infection Monkey did and when it was done. This should make it easy to cross reference events
with your security solutions and alerts/logs.
You can see your results in the Zero Trust report section. “The Summary” section will give you an idea about which Zero Trust pillars were the Infection Monkey tested, how many tests were performed and test statuses. Specific tests are described in the “Test Results” section. The “Findings” section shows details about the Monkey actions. Click on “Events” of different findings to observe what exactly the Infection Monkey did and when it did it. This should make it easy to cross reference events with your security solutions and alerts/logs.