monkey/docs/content/development/adding-exploits.md

title	date	draft	tags	weight
Adding Exploits	2020-06-08T19:53:00+03:00	false	contribute	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 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 post-breach action (PBA) configuration section or add a new PBA.

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

Modify the Infection Monkey Agent

The Infection Monkey exploiters are all built in a similar way. Each exploiter class inherits from the HostExploiter 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 or not the exploit was successful.

Adding a new exploiter

In the Infection Monkey's exploit directory, add the exploit's logic by defining a new class that inherits from HostExploiter. If your new exploit is a web RCE (remote code execution) exploit, inherit from WebRCE.

from infection_monkey.exploit.HostExploiter import HostExploiter

class MyNewExploiter(HostExploiter):
    ...

A good example of an exploiter class is the SSHExploiter. The Log4Shell exploiter is a recently added web RCE exploit that is a good reference as well.

Modify the Monkey Island

Configuration

1. Add your exploiter's description to the configuration schema.

...
    {
        "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 by adding your new exploiter's class name.

...
    "exploiter_classes": {
        "title": "Exploiters",
        "type": "array",
        "uniqueItems": True,
        "items": {"$ref": "#/definitions/exploiter_classes"},
        "default": [
            "SmbExploiter",
            ...
            "Log4ShellExploiter",
            "MyNewExploiter",    <=================================
        ],
    }
...

Reporting

1. In the report generation pipeline, 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.

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.

Documentation

Update the documentation to explain what your exploiter does in the documentation framework.