From 170999e9ed745455751ef6f26de36b5d2f820513 Mon Sep 17 00:00:00 2001 From: Shreya Malviya Date: Tue, 3 Aug 2021 15:30:37 +0530 Subject: [PATCH 1/6] docs: Fix heading in 'Adding System Info Collectors' --- docs/content/development/adding-system-info-collectors.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/content/development/adding-system-info-collectors.md b/docs/content/development/adding-system-info-collectors.md index 5a7aadd94..7a50f32b5 100644 --- a/docs/content/development/adding-system-info-collectors.md +++ b/docs/content/development/adding-system-info-collectors.md @@ -14,9 +14,9 @@ This guide will show you how to create a new _System Info Collector_ for the Inf 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 -### From the Monkey Island Side +### From the Infection Monkey Side #### Framework From e7375c0d940645d36f8132e06d0effca43b3213f Mon Sep 17 00:00:00 2001 From: Shreya Malviya Date: Tue, 3 Aug 2021 15:31:57 +0530 Subject: [PATCH 2/6] docs: Add 'Adding Exploits' page --- docs/content/development/adding-exploits.md | 103 ++++++++++++++++++++ 1 file changed, 103 insertions(+) diff --git a/docs/content/development/adding-exploits.md b/docs/content/development/adding-exploits.md index d6af6814c..6e3fed9e8 100644 --- a/docs/content/development/adding-exploits.md +++ b/docs/content/development/adding-exploits.md @@ -5,3 +5,106 @@ draft: true tags: ["contribute"] weight: 50 --- + +## What does this guide cover? + +This guide will show you how to add a new _Exploit_ to the Infection Monkey. + +An exploit is a sequence of commands which takes advantage of a security vulnerability to gain unauthorised access to a system on your network. If successful, a Monkey agent is released on the exploited system. The result of an attempted exploit is sent back to the Monkey Island as part of the telemetry. + +### Do I need a new Exploit? + +If all you want to do is execute a shell command, configure the required commands in the Monkey Island's configuration's post-breach action (PBA) section or [add a new PBA](../adding-post-breach-actions/). If you would like the Monkey agent to collect specific information, [add a new System Info Collector](../adding-system-info-collectors/). + +However, if you have your eyes on an interesting CVE that you would like the Monkey to support, you must add a new exploit. Keep reading to learn the steps of adding an exploit. + + +## How to add a new Exploit + +### From the Infection Monkey Side + +The Infection Monkey exploiters are all built in a similar way. Each exploiter class inherits from the [`HostExploiter`](https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/exploit/HostExploiter.py) class which exposes two interface functions: + +* `is_os_supported` - Returns a boolean value denoting whether the victim machine is supported by the exploiter (for example, returns `False` on Windows victim machines for the `SSHExploiter`). This can be used to thoroughly inspect a potential victim machine and decide whether to attempt the exploit on that particular machine (for example, by checking for open services matching specific versions). +* `exploit_host` - Exploits the host and returns a boolean value indicating whether the exploit was successful or not. + +#### Adding a new exploiter + +In the [Infection Monkey's exploit directory](https://github.com/guardicore/monkey/tree/develop/monkey/infection_monkey/exploit), add the **exploit's logic** by defining a new class inheriting [`HostExploiter`](https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/exploit/HostExploiter.py), or if your new exploit is a web RCE (remote code execution) exploit, inheriting [`WebRCE`](https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/exploit/web_rce.py). + +```py +from infection_monkey.exploit.HostExploiter import HostExploiter + +class MyNewExploiter(HostExploiter): + ... +``` + +A good example of an exploiter class in the Monkey is the [`SSHExploiter`](https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/exploit/sshexec.py). The [Drupal exploiter is a recently added web RCE exploit](https://github.com/guardicore/monkey/pull/808) that is a good reference as well. + + +### From the Monkey Island Side + +#### Configuration + +1. Add your **exploiter's description** to the [configuration schema](https://github.com/guardicore/monkey/blob/develop/monkey/monkey_island/cc/services/config_schema/definitions/exploiter_classes.py). + +```py +... + { + "type": "string", + "enum": ["SmbExploiter"], + "title": "SMB Exploiter", + "safe": True, + "attack_techniques": ["T1110", "T1075", "T1035"], + "info": "Brute forces using credentials provided by user and hashes gathered by mimikatz.", + "link": "https://www.guardicore.com/infectionmonkey/docs/reference/exploiters/smbexec/", + }, + { + "type": "string", <================================= + "enum": ["MyNewExploiter"], <================================= + "title": "My New Exploiter", <================================= + "safe": True, <================================= + "attack_techniques": [], <================================= + "info": "Information about your new exploiter.", <================================= + "link": "Link to the documentation page explaining your new exploiter.", <================================= + }, +... +``` + +2. Update the default **list of exploiters** in the [configuration schema](https://github.com/guardicore/monkey/blob/develop/monkey/monkey_island/cc/services/config_schema/basic.py) by adding your new exploiter's class name. + +```py +... + "exploiter_classes": { + "title": "Exploiters", + "type": "array", + "uniqueItems": True, + "items": {"$ref": "#/definitions/exploiter_classes"}, + "default": [ + "SmbExploiter", + ... + "DrupalExploiter", + "MyNewExploiter", <================================= + ], + } +... +``` + +#### Reporting + +1. In the [report generation pipeline](https://github.com/guardicore/monkey/blob/develop/monkey/monkey_island/cc/services/reporting/issue_processing/exploit_processing/exploiter_descriptor_enum.py), define how your **exploiter's data** should be processed and displayed in the report. Use the default `ExploitProcessor` or create a custom exploit processor if needed. + +```py +class ExploiterDescriptorEnum(Enum): + SMB = ExploiterDescriptor("SmbExploiter", "SMB Exploiter", CredExploitProcessor) + ... + ZEROLOGON = ExploiterDescriptor("ZerologonExploiter", "Zerologon Exploiter", ZerologonExploitProcessor) + MYNEWEXPLOITER = ExploitDescriptor("MyNewExploiter", "My New Eexploiter", ExploitProcessor) <================================= +``` + +2. Describe how the Monkey Island should **display your exploiter's results** by defining the UI contents in the [security report](https://github.com/guardicore/monkey/blob/develop/monkey/monkey_island/cc/ui/src/components/report-components/SecurityReport.js). + + +### Documentation + +**Update the documentation** to explain what your exploiter does in the [documentation framework](https://github.com/guardicore/monkey/blob/develop/docs/content/reference/exploiters/). From b5db42d829606ccdb67fe4ce1f162681e8b17350 Mon Sep 17 00:00:00 2001 From: Shreya Malviya Date: Tue, 3 Aug 2021 15:32:33 +0530 Subject: [PATCH 3/6] docs: Mark 'Adding Exploits' as not draft --- docs/content/development/adding-exploits.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/development/adding-exploits.md b/docs/content/development/adding-exploits.md index 6e3fed9e8..af707fcc8 100644 --- a/docs/content/development/adding-exploits.md +++ b/docs/content/development/adding-exploits.md @@ -1,7 +1,7 @@ --- title: "Adding Exploits" date: 2020-06-08T19:53:00+03:00 -draft: true +draft: false tags: ["contribute"] weight: 50 --- From 94ddd7c760f786ced24dbe529610fd84b8cc9051 Mon Sep 17 00:00:00 2001 From: Shreya Malviya Date: Tue, 3 Aug 2021 15:35:03 +0530 Subject: [PATCH 4/6] docs: Update link to contributing exploits' documentation on 'Contribute' page --- docs/content/development/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/content/development/_index.md b/docs/content/development/_index.md index 91c5e7855..37a5978e7 100644 --- a/docs/content/development/_index.md +++ b/docs/content/development/_index.md @@ -24,7 +24,7 @@ You can take a look at [our roadmap](https://github.com/guardicore/monkey/projec ### More 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. +The best way to find weak spots in a network is by attacking it. The [*Adding Exploits*](./adding-exploits/) page will help you add exploits. 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. From f55b34829117c690fdc47b5b3c2d3bd5942480a5 Mon Sep 17 00:00:00 2001 From: Shreya Malviya Date: Tue, 3 Aug 2021 19:22:54 +0530 Subject: [PATCH 5/6] docs: Minor rewording in 'Adding Exploits' page based on review --- docs/content/development/adding-exploits.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/docs/content/development/adding-exploits.md b/docs/content/development/adding-exploits.md index af707fcc8..1f4698820 100644 --- a/docs/content/development/adding-exploits.md +++ b/docs/content/development/adding-exploits.md @@ -10,27 +10,27 @@ weight: 50 This guide will show you how to add a new _Exploit_ to the Infection Monkey. -An exploit is a sequence of commands which takes advantage of a security vulnerability to gain unauthorised access to a system on your network. If successful, a Monkey agent is released on the exploited system. The result of an attempted exploit is sent back to the Monkey Island as part of the telemetry. +An exploit is a sequence of commands that takes advantage of a security vulnerability to gain unauthorized access to a system on your network. If successful, an Infection Monkey agent is released on the exploited system. The result of an attempted exploit is sent back to the Monkey Island as part of the telemetry. ### Do I need a new Exploit? -If all you want to do is execute a shell command, configure the required commands in the Monkey Island's configuration's post-breach action (PBA) section or [add a new PBA](../adding-post-breach-actions/). If you would like the Monkey agent to collect specific information, [add a new System Info Collector](../adding-system-info-collectors/). +If all you want to do is execute a shell command, configure the required commands in the Monkey Island's post-breach action (PBA) configuration section or [add a new PBA](../adding-post-breach-actions/). If you would like the Infection Monkey agent to collect specific information, [add a new System Info Collector](../adding-system-info-collectors/). -However, if you have your eyes on an interesting CVE that you would like the Monkey to support, you must add a new exploit. Keep reading to learn the steps of adding an exploit. +However, if you have your eye on an interesting CVE that you would like the Infection Monkey to support, you must add a new exploit. Keep reading to learn how to add a new exploit. ## How to add a new Exploit -### From the Infection Monkey Side +### Modify the Infection Monkey Agent -The Infection Monkey exploiters are all built in a similar way. Each exploiter class inherits from the [`HostExploiter`](https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/exploit/HostExploiter.py) class which exposes two interface functions: +The Infection Monkey exploiters are all built in a similar way. Each exploiter class inherits from the [`HostExploiter`](https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/exploit/HostExploiter.py) class, which exposes two interface functions: * `is_os_supported` - Returns a boolean value denoting whether the victim machine is supported by the exploiter (for example, returns `False` on Windows victim machines for the `SSHExploiter`). This can be used to thoroughly inspect a potential victim machine and decide whether to attempt the exploit on that particular machine (for example, by checking for open services matching specific versions). -* `exploit_host` - Exploits the host and returns a boolean value indicating whether the exploit was successful or not. +* `exploit_host` - Exploits the host and returns a boolean value indicating whether or not the exploit was successful. #### Adding a new exploiter -In the [Infection Monkey's exploit directory](https://github.com/guardicore/monkey/tree/develop/monkey/infection_monkey/exploit), add the **exploit's logic** by defining a new class inheriting [`HostExploiter`](https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/exploit/HostExploiter.py), or if your new exploit is a web RCE (remote code execution) exploit, inheriting [`WebRCE`](https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/exploit/web_rce.py). +In the [Infection Monkey's exploit directory](https://github.com/guardicore/monkey/tree/develop/monkey/infection_monkey/exploit), add the **exploit's logic** by defining a new class that inherits from [`HostExploiter`](https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/exploit/HostExploiter.py). If your new exploit is a web RCE (remote code execution) exploit, inherit from [`WebRCE`](https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/exploit/web_rce.py). ```py from infection_monkey.exploit.HostExploiter import HostExploiter @@ -39,10 +39,10 @@ class MyNewExploiter(HostExploiter): ... ``` -A good example of an exploiter class in the Monkey is the [`SSHExploiter`](https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/exploit/sshexec.py). The [Drupal exploiter is a recently added web RCE exploit](https://github.com/guardicore/monkey/pull/808) that is a good reference as well. +A good example of an exploiter class is the [`SSHExploiter`](https://github.com/guardicore/monkey/blob/develop/monkey/infection_monkey/exploit/sshexec.py). The [Drupal exploiter is a recently added web RCE exploit](https://github.com/guardicore/monkey/pull/808) that is a good reference as well. -### From the Monkey Island Side +### Modify the Monkey Island #### Configuration From 7252ff97b6f089e68abe54d419a7bcbad7605075 Mon Sep 17 00:00:00 2001 From: Shreya Malviya Date: Tue, 3 Aug 2021 19:28:43 +0530 Subject: [PATCH 6/6] docs: Reword sub-headings in pages in contribution section --- docs/content/development/adding-post-breach-actions.md | 4 ++-- docs/content/development/adding-system-info-collectors.md | 4 ++-- docs/content/development/setup-development-environment.md | 2 +- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/content/development/adding-post-breach-actions.md b/docs/content/development/adding-post-breach-actions.md index 033a6118c..659bb9473 100644 --- a/docs/content/development/adding-post-breach-actions.md +++ b/docs/content/development/adding-post-breach-actions.md @@ -16,7 +16,7 @@ If all you want to do is execute shell commands, then there's no need to add a n ## How to add a new PBA -### From the Infection Monkey Side +### Modify the Infection Monkey Agent #### 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. -### From the Monkey Island Side +### Modify the Monkey Island #### Configuration diff --git a/docs/content/development/adding-system-info-collectors.md b/docs/content/development/adding-system-info-collectors.md index 7a50f32b5..71cea6000 100644 --- a/docs/content/development/adding-system-info-collectors.md +++ b/docs/content/development/adding-system-info-collectors.md @@ -16,7 +16,7 @@ If all you want to do is execute a shell command, then there's no need to add a ## How to add a new System Info Collector -### From the Infection Monkey Side +### Modify the Infection Monkey Agent #### Framework @@ -41,7 +41,7 @@ class MyNewCollector(SystemInfoCollector): Override the `collect` method with your own implementation. See the `EnvironmentCollector.py` System Info Collector for reference. You can log during collection as well. -### From the Monkey Island Side +### Modify the Monkey Island #### Configuration diff --git a/docs/content/development/setup-development-environment.md b/docs/content/development/setup-development-environment.md index ad9a4675b..f2e739f3a 100644 --- a/docs/content/development/setup-development-environment.md +++ b/docs/content/development/setup-development-environment.md @@ -10,7 +10,7 @@ tags: ["contribute"] 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 Infection Monkey Agent 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.