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