Migrated and updated docs from our wiki to the new docs site

Added tags to pages

docs/content/development/add-zero-trust-test.md

@@ -0,0 +1,26 @@
+---
+title: "Adding Zero Trust Tests"
+date: 2020-07-14T10:19:08+03:00
+draft: false
+weight: 100
+---
+
+## How to 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.
+
+### `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.
+
+### `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.
+
+## How to 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.

docs/content/development/adding-exploits.md

@@ -2,4 +2,6 @@
 title: "Adding Exploits"
 date: 2020-06-08T19:53:00+03:00
 draft: true
+tags: ["contribute"]
+weight: 50
 ---

docs/content/development/adding-post-breach-actions.md

@@ -1,6 +1,76 @@
 ---
 title: "Adding Post Breach Actions"
 date: 2020-06-08T19:53:13+03:00
-draft: true
+draft: false
+tags: ["contribute"]
+weight: 90
 ---
 
+## What's this?
+
+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.
+
+## 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.
+
+## How to add a new PBA
+
+### Monkey side
+
+#### Framework
+
+1. Create your new action in the following directory: `monkey/infection_monkey/post_breach/actions` by first creating a new file with the name of your action.
+2. In that file, create a class that inherits from the `PBA` class:
+
+```python
+from infection_monkey.post_breach.pba import PBA
+
+class MyNewPba(PBA):
+```
+
+3. Set the action name in the C'tor, like so:
+
+```python
+class MyNewPba(PBA):
+    def __init__(self):
+        super(MyNewPba, self).__init__(name="MyNewPba")
+```
+
+#### Implementation
+
+If your PBA consists only of simple shell commands, you can reuse the generic PBA by passing the commands into the constructor. See the `add_user.py` PBA for reference.
+
+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
+
+#### Configuration
+
+You'll need to add your PBA to the `config_schema.py` file, under `post_breach_acts`, like so:
+
+```json
+"post_breach_acts": {
+            "title": "Post breach actions",
+            "type": "string",
+            "anyOf": [
+                # ...
+                {
+                    "type": "string",
+                    "enum": [
+                        "MyNewPba"
+                    ],
+                    "title": "My new PBA",
+                    "attack_techniques": []
+                },
+            ],
+        },
+```
+
+Now you can choose your PBA when configuring the 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.

docs/content/development/adding-system-info-collectors.md

@@ -1,6 +1,105 @@
 ---
 title: "Adding System Info Collectors"
 date: 2020-06-09T11:03:42+03:00
-draft: true
+draft: false
+tags: ["contribute"]
+weight: 80
 ---
 
+## What's this?
+
+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.
+
+### Do I need a new System Info Controller?
+
+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.
+
+## How to add a new System Info Collector
+
+### Monkey 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.
+2. In that file, create a class that inherits from the `SystemInfoCollector` class:
+
+```py
+from infection_monkey.system_info.system_info_collector import SystemInfoCollector
+
+class MyNewCollector(SystemInfoCollector):
+```
+
+3. Set the Collector name in the C'tor, like so:
+
+```py
+class MyNewCollector(SystemInfoCollector):
+    def __init__(self):
+        super(MyNewCollector, self).__init__(name="MyNewCollector")
+```
+
+#### Implementation
+
+Override the `collect` method with your own implementation. See the `EnvironmentCollector.py` Collector for reference. You can log during collection as well.
+
+#### Configuration
+
+Add the new collector to `infection_monkey/config.py`
+
+### Island side
+
+#### Configuration
+
+##### `definitions`
+
+You'll need to add your Collector to the `config_schema.py` file, under `definitions/system_info_collectors_classes/anyOf`, like so:
+
+```json
+"system_info_collectors_classes": {
+    "title": "System Information Collectors",
+    "type": "string",
+    "anyOf": [
+        {
+            "type": "string",
+            "enum": [
+                "EnvironmentCollector"
+            ],
+            "title": "Which Environment this machine is on (on prem/cloud)",
+            "attack_techniques": []
+        },
+        {                               <=================================
+            "type": "string",           <=================================
+            "enum": [                   <=================================
+                "MyNewCollector"        <=================================
+            ],                          <=================================
+            "title": "My new title",    <=================================
+            "attack_techniques": []     <=================================
+        },
+    ],
+},
+```
+
+##### `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`:
+
+```json
+"system_info_collectors_classes": {
+    "title": "System info collectors",
+    "type": "array",
+    "uniqueItems": True,
+    "items": {
+        "$ref": "#/definitions/system_info_collectors_classes"
+    },
+    "default": [
+        "EnvironmentCollector",
+        "MyNewCollector"    <=================================
+    ],
+    "description": "Determines which system information collectors will collect information."
+},
+```
+
+#### 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.
+
+2. Add that function to the dispatcher - `monkey_island/cc/services/telemetry/processing/system_info_collectors/system_info_telemetry_dispatcher.py`.

docs/content/development/contribute-documentation.md

@@ -2,6 +2,7 @@
 title: "Contribute Documentation"
 date: 2020-06-17T17:31:54+03:00
 draft: false
+weight: 1
 tags: ["contribute"]
 ---
 

docs/content/development/setup-development-environment.md

@@ -1,7 +1,8 @@
 ---
-title: "Setting up a development environment"
+title: "Development setup"
 date: 2020-06-08T19:53:00+03:00
 draft: false
+weight: 5
 tags: ["contribute"]
 ---
 

docs/content/reference/_index.md

@@ -0,0 +1,14 @@
++++
+title = "Reference"
+date = 2020-05-26T20:55:04+03:00
+weight = 30
+chapter = true
+pre = '<i class="fas fa-layer-group"></i> '
+tags = ["reference"] 
++++
+
+# Reference
+
+Your source of all Monkey information.
+
+{{% children %}}

docs/content/reference/exploiters/ElasticGroovy.md

@@ -0,0 +1,12 @@
+---
+title: "ElasticGroovy"
+date: 2020-07-14T08:41:40+03:00
+draft: false
+tags: ["exploit", "windows", "linux"]
+---
+
+CVE-2015-1427.
+
+> The Groovy scripting engine in Elasticsearch before 1.3.8 and 1.4.x before 1.4.3 allows remote attackers to bypass the sandbox protection mechanism and execute arbitrary shell commands via a crafted script.
+
+Logic is based on [Metasploit module](https://github.com/rapid7/metasploit-framework/blob/12198a088132f047e0a86724bc5ebba92a73ac66/modules/exploits/multi/elasticsearch/search_groovy_script.rb).

docs/content/reference/exploiters/Hadoop.md

@@ -0,0 +1,8 @@
+---
+title: "Hadoop"
+date: 2020-07-14T08:41:49+03:00
+draft: false
+tags: ["exploit", "linux", "windows"]
+---
+
+Remote code execution on HADOOP server with YARN and default settings. Logic based on [this vulhub module](https://github.com/vulhub/vulhub/tree/master/hadoop/unauthorized-yarn).

docs/content/reference/exploiters/MS08-067.md

@@ -0,0 +1,10 @@
+---
+title: "MS08 067"
+date: 2020-07-14T08:42:54+03:00
+draft: false
+tags: ["exploit", "windows"]
+---
+
+[MS08-067](https://docs.microsoft.com/en-us/security-updates/securitybulletins/2008/ms08-067) is a remote code execution vulnerability.
+
+This exploiter is unsafe. If an exploit attempt fails, this could also lead to a crash in Svchost.exe. If the crash in Svchost.exe occurs, the Server service will be affected. That might cause system crash due to the use of buffer overflow. It's therefore **not** enabled by default.

docs/content/reference/exploiters/MsSQL.md

@@ -0,0 +1,8 @@
+---
+title: "MsSQL"
+date: 2020-07-14T08:41:56+03:00
+draft: false
+tags: ["exploit", "windows"]
+---
+
+The Monkey will try to brute force into MsSQL server and uses insecure configuration to execute commands on server.

docs/content/reference/exploiters/SMBExec.md

@@ -0,0 +1,8 @@
+---
+title: "SMBExec"
+date: 2020-07-14T08:42:16+03:00
+draft: false
+tags: ["exploit", "windows"]
+---
+
+Brute forces using credentials provided by user (see ["Configuration"](../usage/configuration)) and hashes gathered by Mimikatz.

docs/content/reference/exploiters/SSHExec.md

@@ -0,0 +1,8 @@
+---
+title: "SSHExec"
+date: 2020-07-14T08:42:21+03:00
+draft: false
+tags: ["exploit", "linux"]
+---
+
+Brute forces using credentials provided by user (see ["Configuration"](../usage/configuration))and SSH keys gathered from systems.

docs/content/reference/exploiters/Sambacry.md

@@ -0,0 +1,8 @@
+---
+title: "Sambacry"
+date: 2020-07-14T08:42:02+03:00
+draft: false
+tags: ["exploit", "linux"]
+---
+
+Bruteforces and searches for anonymous shares. Partially based on [the following implementation](https://github.com/CoreSecurity/impacket/blob/master/examples/sambaPipe.py) by CORE Security Technologies' impacket.

docs/content/reference/exploiters/Struts2.md

@@ -0,0 +1,8 @@
+---
+title: "Struts2"
+date: 2020-07-14T08:42:30+03:00
+draft: false
+tags: ["exploit", "linux", "windows"]
+---
+
+Exploits struts2 java web framework. CVE-2017-5638. Logic based on [VEX WOO's PoC](https://www.exploit-db.com/exploits/41570).

docs/content/reference/exploiters/VSFTPD.md

@@ -0,0 +1,8 @@
+---
+title: "VSFTPD"
+date: 2020-07-14T08:42:39+03:00
+draft: false
+tags: ["exploit", "linux"]
+---
+
+Exploits a malicious backdoor that was added to the VSFTPD download archive. Logic based on [this MetaSploit module](https://github.com/rapid7/metasploit-framework/blob/master/modules/exploits/unix/ftp/vsftpd_234_backdoor.rb).

docs/content/reference/exploiters/WMIExec.md

@@ -0,0 +1,8 @@
+---
+title: "WMIExec"
+date: 2020-07-14T08:43:12+03:00
+draft: false
+tags: ["exploit", "windows"]
+---
+
+Brute forces WMI (Windows Management Instrumentation) using credentials provided by user ((see ["Configuration"](../usage/configuration))) and hashes gathered by mimikatz.

docs/content/reference/exploiters/WebLogic.md

@@ -0,0 +1,8 @@
+---
+title: "WebLogic"
+date: 2020-07-14T08:42:46+03:00
+draft: false
+tags: ["exploit", "linux", "windows"]
+---
+
+Exploits CVE-2017-10271 and CVE-2019-2725 vulnerabilities on a vulnerable WebLogic server.

docs/content/reference/exploiters/_index.md

@@ -0,0 +1,16 @@
++++
+title = "Exploiters"
+date = 2020-05-26T20:55:04+03:00
+weight = 100
+chapter = true
+pre = '<i class="fas fa-ethernet"></i> '
+tags = ["reference", "exploit"]
++++
+
+# Exploiters
+
+Infection Monkey uses various RCE exploiters. Most of these, in our knowledge, pose no risk to performance or services on victim machines. This documentation serves as a quick introduction to the exploiters currently implemented and vulnerabilities used by them.
+
+{{% children %}}
+
+You can check out the Exploiters' implementation yourself [in the Monkey's GitHub repository](https://github.com/guardicore/monkey/tree/develop/monkey/infection_monkey/exploit).

docs/content/reference/exploiters/shellshock.md

@@ -0,0 +1,10 @@
+---
+title: "ShellShock"
+date: 2020-07-14T08:41:32+03:00
+draft: false
+tags: ["exploit", "linux"]
+---
+
+CVE-2014-6271, based on [logic in NCC group's GitHub](https://github.com/nccgroup/shocker/blob/master/shocker.py).
+
+> GNU Bash through 4.3 processes trailing strings after function definitions in the values of environment variables, which allows remote attackers to execute arbitrary code via a crafted environment, as demonstrated by vectors involving the ForceCommand feature in OpenSSH sshd, the mod_cgi and mod_cgid modules in the Apache HTTP Server, scripts executed by unspecified DHCP clients, and other situations in which setting the environment occurs across a privilege boundary from Bash execution, aka "ShellShock."

docs/content/reference/operating_systems_support.md

@@ -0,0 +1,64 @@
+---
+title: "Operating systems"
+date: 2020-07-14T08:09:53+03:00
+draft: false
+pre: '<i class="fas fa-laptop"></i> '
+weight: 10
+tags: ["setup", "reference", "windows", "linux"] 
+---
+
+The Infection Monkey project supports many popular OSes (but we can always do more).
+
+The Monkey itself (the agent) has been tested to run on the following operating systems (on x64 architecture)
+
+### Monkey support
+
+#### Linux
+
+Compatibility depends on GLIBC version (2.14+)[^1]. By default these distributions are supported:
+
+- Centos 7+
+- Debian 7+
+- Kali 2019+
+- Oracle 7+
+- Rhel 7+
+- Suse 12+
+- Ubuntu 14+
+
+#### Windows
+
+- Windows 2012+
+- Windows 2012_R2+
+- Windows 7/Server 2008_R2 if [KB2999226](https://support.microsoft.com/en-us/help/2999226/update-for-universal-c-runtime-in-windows) is installed.
+- Windows vista/Server 2008 should also work if the same update is installed, but this wasn't tested.
+
+### Island support
+
+**The Monkey Island (control server)** runs out of the box on:
+
+- Ubuntu 18.04
+- Debian 9
+- Windows Server 2012
+- Windows Server 2012 R2
+- Windows Server 2016
+
+We provide a dockerfile from our [website](http://infectionmonkey.com/) that lets the Monkey Island run inside a container.
+
+### Old machine bootloader
+
+Some **Older machines** still get a partial compatibility as in they get exploited and reported, but monkey can't run on them. So instead of monkey, old machine bootloader(small c program) is ran, which reports some minor info like network interface configuration, GLIBC version, OS and so on.
+
+**Old machine bootloader** also has a GLIBC 2.14+ requirement for linux, because bootloader is included into pyinstaller bootloader which uses python3.7, which in turn requires GLIBC 2.14+. If you think partial support for older machines is important, don't hesitate to open a new issue about it.
+
+**Old machine bootloader** runs on machines with:
+
+- Centos 7+
+- Debian 7+
+- Kali 2019+
+- Oracle 7+
+- Rhel 7+
+- Suse 12+
+- Ubuntu 14+
+- **Windows XP/Server 2003+**
+
+[^1]: GLIBC >= 2.14 requirement comes from the fact that monkey is built using this GLIBC version and GLIBC is not backwards compatible. We are also limited to the oldest GLIBC version compatible with ptyhon3.7

docs/content/reference/scanners/_index.md

@@ -0,0 +1,51 @@
+---
+title: "Scanners"
+date: 2020-07-14T08:43:12+03:00
+draft: false
+weight: 20
+pre: '<i class="fas fa-network-wired"></i> '
+tags: ["reference"]
+---
+
+The Infection Monkey agent has two steps before attempting to exploit a victim, scanning and fingerprinting, it's possible to customize both steps in the configuration files.
+
+## Scanning
+
+Currently there are two scanners, [`PingScanner`][ping-scanner] and [`TcpScanner`][tcp-scanner] both inheriting from [`HostScanner`][host-scanner].
+
+The sole interface required is the `is_host_alive` interface, which needs to return True/False.
+
+[`TcpScanner`][tcp-scanner] is the default scanner and it checks for open ports based on the `tcp_target_ports` configuration setting.
+
+[`PingScanner`][ping-scanner] sends a ping message using the host OS utility `ping`.
+
+## Fingerprinting
+
+Fingerprinters are modules that collect server information from a specific victim. They inherit from the [`HostFinger`][host-finger] class and are listed under `finger_classes` configuration option.
+
+Currently implemented Fingerprint modules are:
+
+1. [`SMBFinger`][smb-finger] - Fingerprints target machines over SMB. Extracts computer name and OS version.
+2. [`SSHFinger`][ssh-finger] - Fingerprints target machines over SSH (port 22). Extracts the computer version and SSH banner.
+3. [`PingScanner`][ping-scanner] - Fingerprints using the machines TTL, to differentiate between Linux and Windows hosts.
+4. [`HTTPFinger`][http-finger] - Fingerprints over HTTP/HTTPS, using the ports listed in `HTTP_PORTS` in the configuration. Returns the server type and if it supports SSL.
+5. [`MySQLFinger`][mysql-finger] - Fingerprints over MySQL (port 3306). Extracts MySQL banner info - Version, Major/Minor/Build and capabilities.
+6. [`ElasticFinger`][elastic-finger] - Fingerprints over ElasticSearch (port 9200). Extracts the cluster name, node name and node version.
+
+## Adding a scanner/fingerprinter
+
+To add a new scanner/fingerprinter, create a new class that inherits from [`HostScanner`][host-scanner] or [`HostFinger`][host-finger] (depending on the interface). The class should be under the network module and should be imported under [`network/__init__.py`](https://github.com/guardicore/monkey/blob/master/monkey/infection_monkey/network/__init__.py).
+
+To be used by default, two files need to be changed - [`config.py`](https://github.com/guardicore/monkey/blob/master/monkey/infection_monkey/config.py) and [`example.conf`](https://github.com/guardicore/monkey/blob/master/monkey/infection_monkey/example.conf) to add references to the new class.
+
+At this point, the Monkey knows how to use the new scanner/fingerprinter but to make it easy to use, the UI needs to be updated. The relevant UI file is [`config.py`](https://github.com/guardicore/monkey/blob/master/monkey/monkey_island/cc/services/config.py) (not to be confused with the prior `config.py`).
+
+ [elastic-finger]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/elasticfinger.py
+ [http-finger]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/httpfinger.py
+ [host-finger]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/__init__.py
+ [host-scanner]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/__init__.py
+ [mysql-finger]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/mysqlfinger.py
+ [ping-scanner]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/ping_scanner.py
+ [smb-finger]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/smbfinger.py
+ [ssh-finger]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/sshfinger.py
+ [tcp-scanner]: https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/network/tcp_scanner.py

docs/content/setup/debian.md

@@ -5,7 +5,7 @@ draft: false
 pre: '<i class="fab fa-linux"></i> '
 weight: 1
 disableToc: false
-tags: ["setup", "debian"] 
+tags: ["setup", "debian", "linux"]
 ---
 
 ## Deployment

docs/content/setup/docker.md

@@ -4,7 +4,7 @@ date: 2020-05-26T20:57:28+03:00
 draft: false
 pre: '<i class="fab fa-docker"></i> '
 weight: 4
-tags: ["setup", "docker"] 
+tags: ["setup", "docker", "linux", "windows"] 
 ---
 
 ## Deployment