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