p20319658
/
monkey
forked from p34709852/monkey
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

docs: Add 'Adding Exploits' page

This commit is contained in:
Shreya Malviya 2021-08-03 15:31:57 +05:30
parent 170999e9ed
commit e7375c0d94
1 changed files with 103 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

103
docs/content/development/adding-exploits.md
View File

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