Write modules for emp3r0r

How modules work

Vaccine

Perhaps you have already noticed a module called vaccine in emp3r0r, vaccine serves a special purpose, which is providing statically-linked binaries for emp3r0r agents.

You don't need to do anything specific, when emp3r0r C2 starts, it automatically packs whatever in vaccine and hosts it for agents to download. Once installed on a target host, you can run the binaries (or scripts, as long as they run) in interactive_shell, as if they were installed via normal means.

Also, I have implemented a compressed static bash binary in emp3r0r agents, it's embedded in agent binary and is extracted in runtime. This Bash shell is pre-configured, and is fully capable of doing anything that your system Bash can do. You can use the Bash shell after selecting a target.

It's suggested that you add common system utilities to vaccine, such as cat, ls, in case you need them on the target host that you are working on.

Custom modules

Intro

This is intended for extending the functionality of emp3r0r, and these modules will run on target hosts instead of C2 side, since I am not writing another Metasploit Framework.

Use cases including:

• Run additional exploits against other machines in target network, they will be removed after being run. And of course you can launch your attack from C2 side, with the help from port mapping
• Run third-party tools such as bettercap
• Local privilege escalation exploits
• Other local jobs such as credential collecting and data exfiltration

First

The first thing to do is, of course, to get your executable(s) to run on target hosts without error. If you have ever peeked into Metasploit Framework's code, you would notice that their "local exploits" are either compiled on target host or locally, both are tricky if you decide to write your own modules.

The reasons?

Dependencies! No matter if you use pure binaries or scripts, they all have their dependencies. For the very start, bash scripts needs at least bash itself (which is covered by emp3r0r), and python scripts needs python interpreter along with a bunch of runtime libraries and even third party Pypi packages (can you imagine that?!)

Oh of course you would say, let's use pyinstaller, but unfortunately python itself is linked against Glibc, which, with all due respect, is absolutely a nightmare for portable programs, at the very least, it picks kernels! Therefore, even if you packed everything including the Glibc with pyinstaller and staticx, it's not guaranteed to work!

So it's already very hard to run pre-compiled programs on target hosts, unless your modules uses only the most basic APIs and you know what you are doing.

What about compiling on target hosts? Seriously, don't do that shit, you are an attacker, not a fucking system admin! Even if there's gcc on target hosts, you will probably need some libraries other than standard ones!

Prepare your modules

Here are some suggestions, depending on what language you choose to write your modules.

Python

You have two options, one is to use pyinstaller, the other is to use the built-in python3.9 environment

For details, see Write modules in python3.9

Bash

It works unless your modules require additional utilities, such as jq, nmap, nc, anyway, make sure they exist, if not, consider adding them to vaccine module

Go

Turn off CGO unless you know what you are doing

Rust, C, CPP

Compile with musl libc, make it fully static

Compress

You can always use upx to compress your binaries, but remember to strip it first!

Meta data

{
    "name": "bettercap",
    "exec": "bettercap",
    "platform": "Linux",
    "interactive": true,
    "author": "jm33-ng",
    "date": "2022-03-09",
    "comment": "Run bettercap as an interactive shell",
    "options": {
        "args": ["--", "run bettercap with this commandline arg"]
    }
}

This is an example, you can view it here

Internally, it's parsed as this

type ModConfig struct {
    Name          string `json:"name"`        // Display as this name
    Exec          string `json:"exec"`        // Run this executable file
    Platform      string `json:"platform"`    // targeting which OS? Linux/Windows
    IsInteractive bool   `json:"interactive"` // whether run as a shell or not, eg. python, bettercap
    Author        string `json:"author"`      // by whom
    Date          string `json:"date"`        // when did you write it
    Comment       string `json:"comment"`     // describe your module in one line

    // option: [value, help]
    // eg.
    // "option you see in emp3r0r console": ["a parameter of your module", "describe how to use this parameter"]
    Options map[string][]string `json:"options"`
}

interactive means your module is supposed to provide a terminal UI, such as bash, htop, bettercap

To load a module, you need to create a directory under ~/.emp3r0r/modules, and put config.json there. When emp3r0r C2 starts, it automatically searches config.json and loads the modules

Use your module

In emp3r0r console, type search <query> to find the module you need, then use <module_name> to get started

If your module has configurable options (like Metasploit modules), you can use set option value to set them, all these options will be passed to your executable as environment variables, be sure to receive them!