docs: Add 'Adding Exploits' page

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/).