Merge remote-tracking branch 'upstream/develop' into smbexec_bugfix

docs/content/development/_index.md

@@ -15,7 +15,7 @@ Want to help secure networks? That's great!
 
 Here's a few short links to help you get started.
 
-* [Getting up and running](../setup-development-environment) - To help you get a working development setup.
+* [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.
 
 ## What are we looking for?

docs/content/usage/configuration/_index.md

@@ -17,4 +17,4 @@ This section of the documentation is incomplete and under active construction.
 
 See these documentation pages for information on each configuration value:
 
-{{% children description=true %}}
+{{% children description=true style="p"%}}

docs/content/usage/getting-started.md

@@ -15,7 +15,7 @@ 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](../accounts-and-security).
+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).
 
 ### Run the Monkey
 

docs/content/usage/integrations/_index.md

@@ -11,4 +11,4 @@ pre: "<i class='fas fa-directions'></i> "
 
 The Monkey likes working together. See these documentation pages for information on each integration the Monkey currently offers:
 
-{{% children description=true %}}
+{{% children description=true style="p"%}}

docs/content/usage/use-cases/_index.md

@@ -18,4 +18,4 @@ No worries! The Monkey uses safe exploiters and does not cause any permanent sys
 
 ## Section contents
 
-{{% children description=True %}}
+{{% children description=True style="p"%}}

docs/content/usage/use-cases/attack.md

@@ -0,0 +1,38 @@
+---
+title: "MITRE ATT&CK assessment"
+date: 2020-10-22T16:58:22+03:00
+draft: false
+description: "Assess your network security detection and prevention capabilities."
+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.
+
+
+## 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](/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.
+
+## 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.

docs/content/usage/use-cases/credential-leak.md

@@ -1,9 +1,9 @@
 ---
-title: "Credential Leak"
+title: "Credentials Leak"
 date: 2020-08-12T13:04:25+03:00
 draft: false
-description: "Assess the impact of successful phishing attack, insider threat, or other form of credentials leak."
+description: "Assess the impact of a successful phishing attack, insider threat, or other form of credentials leak."
-weight: 4
+weight: 5
 ---
 
 ## Overview 
@@ -16,8 +16,6 @@ where these credentials can be reused.
 
 ## Configuration
 
-#### Important configuration values:
-
 - **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).
@@ -26,15 +24,14 @@ For this to work, Monkey Island or initial Monkey needs to have access to SSH ke
 To make sure SSH keys were gathered successfully, refresh the page and check this configuration value after you run the Monkey
 (content of keys will not be displayed, it will appear as `<Object>`).
 
-To simulate the damage from a successful phishing attack using the Infection Monkey, choose machines in your network 
+## Suggested run mode
-from potentially problematic group of machines, such as the laptop of one of your heavy email users or 
+
-one of your strong IT users (think of people who are more likely to correspond with people outside of 
+Execute the Monkey on a chosen machine in your network using the “Manual” run option. 
-your organization). Execute the Monkey on chosen machines by clicking on “**1. Run Monkey**” from the left sidebar menu
+Run the Monkey as a privileged user to make sure it gathers as many credentials from the system as possible.
- and choosing “**Run on machine of your choice**”.
 
 ![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
+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**. 

docs/content/usage/use-cases/ids-test.md

@@ -1,55 +0,0 @@
----
-title: "IDS/IPS Test"
-date: 2020-08-12T13:07:47+03:00
-draft: false
-description: "Test your network defence solutions."
-weight: 5
----
-
-## Overview 
-
-The Infection Monkey can help you verify that your security solutions are working the way you expected them to.
- These may include your IR and SOC teams, your SIEM, your firewall, your endpoint security solution, and more.
-
-## Configuration
-
-#### Important configuration values:
-
-- **Monkey -> Post breach** Post breach actions simulate the actions an attacker would make on infected system.
- To test something not present on the tool, you can provide your own file or command to be ran. 
-
-The default configuration is good enough for many cases, but configuring testing scope and adding brute-force
- credentials is a good bet in any scenario. 
- 
-Running the Monkey on both the Island and on a few other machines in the network manually is also recommended,
- as it increases coverage and propagation rates.
-
-
-![Post breach configuration](/images/usage/use-cases/ids-test.PNG "Post breach configuration")
-
-## Assessing results
-
-After running the Monkey, follow the Monkeys’ actions on the Monkey Island’s infection map.
-
-Now you can match this activity from the Monkey timeline display to your internal SIEM and make sure your security
- solutions are identifying and correctly alerting on different attacks.
-
-- The red arrows indicate successful exploitations. If you see red arrows, those incidents ought to be reported as
- exploitation attempts, so check whether you are receiving alerts from your security systems as expected.
-- The orange arrows indicate scanning activity, usually used by attackers to locate potential vulnerabilities.
- If you see orange arrows, those incidents ought to be reported as scanning attempts (and possibly as segmentation violations).
-- The blue arrows indicate tunneling activity, usually used by attackers to infiltrate “protected” networks from
- the Internet. Perhaps someone is trying to bypass your firewall to gain access to a protected service in your network?
- Check if your micro-segmentation / firewall solution identify or report anything.
-
-While running this scenario, be on the lookout for the action that should arise:
- Did you get a phone call telling you about suspicious activity inside your network? Are events flowing
- into your security events aggregators? Are you getting emails from your IR teams?
- Is the endpoint protection software you installed on machines in the network reporting on anything? Are your
- compliance scanners detecting anything wrong?
- 
-Lastly, check Zero Trust and Mitre ATT&CK reports, to see which attacks can be executed on the network and how to
- fix it.
- 
- ![Map](/images/usage/use-cases/map-full-cropped.png "Map")
-

docs/content/usage/use-cases/network-breach.md

@@ -3,7 +3,7 @@ title: "Network Breach"
 date: 2020-08-12T13:04:55+03:00
 draft: false
 description: "Simulate an internal network breach and assess the potential impact."
-weight: 1
+weight: 3
 ---
 
 ## Overview 
@@ -17,7 +17,6 @@ Infection Monkey will help you assess the impact of internal network breach, by
 
 ## Configuration
 
-#### Important configuration values:
 - **Exploits -> Exploits** You can review the exploits 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
@@ -34,6 +33,15 @@ all post breach actions. These actions simulate attacker's behaviour after getti
 
 ![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 
+wish to test.
+
+
 ## Assessing results
 
 Check infection map and security report to see how far monkey managed to propagate in the network and which 

docs/content/usage/use-cases/network-segmentation.md

@@ -2,18 +2,18 @@
 title: "Network Segmentation"
 date: 2020-08-12T13:05:05+03:00
 draft: false
-description: "Test network segmentation policies for apps that need ringfencing or tiers that require microsegmentation."
+description: "Verify your network is properly segmented."
-weight: 3
+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.
+isolate workloads from one another and secure them individually, typically using policies. A useful way to test 
- A useful way to test the effectiveness of your segmentation is to ensure that your network segments are
+the effectiveness of your segmentation is to ensure that your network segments are properly separated, e,g, your 
- properly separated, e,g, your Development is separated from your Production, your applications are separated from one
+Development is separated from your Production, your applications are separated from one another etc. Use the 
- another etc. To security test is to verify that your network segmentation is configured properly. This way you make
+Infection Monkey to verify that your network segmentation is configured properly. This way you make sure that 
- sure that even if a certain attacker has breached your defenses, it can’t move laterally from point A to point B.
+even if a certain attacker has breached your defenses, it 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 
@@ -21,8 +21,6 @@ its cross-segment traffic testing feature.
 
 ## Configuration
 
-#### Important configuration values:
-
 - **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.
@@ -32,9 +30,9 @@ its cross-segment traffic testing feature.
 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.
 
-Execute Monkeys on machines in different subnetworks manually, by choosing “**1. Run Monkey**” from the left sidebar menu
+## Suggested run mode
- and clicking on “**Run on machine of your choice**”. 
+
- Alternatively, you could provide valid credentials and allow Monkey to propagate to relevant subnetworks by itself. 
+Execute Monkeys 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.

docs/content/usage/use-cases/other.md

@@ -2,7 +2,7 @@
 title: "Other"
 date: 2020-08-12T13:07:55+03:00
 draft: false
-description: "Tips and tricks about configuring monkey for your needs."
+description: "Tips and tricks about configuring Monkeys for your needs."
 weight: 100
 ---
 
@@ -10,33 +10,52 @@ weight: 100
 
 This page provides additional information about configuring monkeys, tips and tricks and creative usage scenarios.
 
-## ATT&CK & Zero Trust scanning
+## Custom behaviour
 
-You can use **ATT&CK** configuration section to select which techniques you want to scan. Keep in mind that ATT&CK
+If you want Monkey to run some kind of script or a tool after it breaches a machine, you can configure it in 
- matrix configuration just changes the overall configuration by modifying related fields, thus you should start by
+**Configuration -> Monkey -> Post breach**. Just input commands you want executed in the corresponding fields. 
- modifying and saving the matrix. After that you can change credentials and scope of the scan, but exploiters,
+You can also upload files and call them through commands you entered in command fields.
- post breach actions and other configuration values will be already chosen based on ATT&CK matrix and shouldn't be
- modified.
 
-There's currently no way to configure monkey using Zero Trust framework, but regardless of configuration options,
+## Accelerate the test
- you'll always be able to see ATT&CK and Zero Trust reports.
 
-## Tips and tricks
+To improve scanning speed you could **specify a subnet instead of scanning all of the local network**. 
 
-- Use **Monkey -> Persistent scanning** configuration section to either have periodic scans or to increase
+The following configuration values also have an impact on scanning speed:
- reliability of exploitations.
+- **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 
+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.
 
-- To increase propagation run monkey as root/administrator. This will ensure that monkey will gather credentials
+## Combining different scenarios
- on current system and use them to move laterally.
 
-- 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:
+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!
+
+## 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.
+
+## 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:
 
 ![Exploit password and user lists](/images/usage/scenarios/user-password-lists.png "Exploit password and user lists")
 
-- 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:
+## 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:
 
 ![How to configure post breach commands](/images/usage/scenarios/pba-example.png "How to configure post breach commands.")
-
-- If you're scanning a large network, consider narrowing the scope and scanning it bit by bit if scan times become too
- long. Lowering the amount of credentials, exploiters or post breach actions can also help to lower scanning times.
-

docs/content/usage/use-cases/zero-trust.md

@@ -0,0 +1,42 @@
+---
+title: "Zero Trust assessment"
+date: 2020-10-22T16:58:09+03:00
+draft: false
+description: "See where you stand in your Zero Trust journey."
+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 
+[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”.
+- **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.
+
+![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. 
+
+## 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.
+

docs/themes/learn

@@ -1 +1 @@
-Subproject commit 4fdb70e3639143076ce2cd7d5a69cc1df8e78caf
+Subproject commit 045d78bc98540c9b96518df73c05fdb9d16507ba

monkey/monkey_island/requirements.txt

@@ -10,7 +10,7 @@ dpath>=2.0
 flask>=1.1
 ipaddress>=1.0.23
 jsonschema==3.2.0
-mongoengine>=0.20
+mongoengine==0.20
 mongomock==3.19.0
 netifaces>=0.10.9
 pycryptodome==3.9.8