Write modules for emp3r0r

Vaccine

The vaccine module in emp3r0r is designed to provide statically-linked binaries for emp3r0r agents. When the emp3r0r C2 server starts, it automatically packages whatever is in the vaccine directory and makes it available for agents to download. This means you can use these tools on a target host through the interactive_shell without worrying about compatibility issues.

Key Features:

• Static Bash Shell: emp3r0r agents come with a compressed static bash binary. This shell is embedded in the agent and extracted at runtime. It’s fully capable, like the system's native Bash.
• Adding Utilities: It’s a good idea to include common system utilities like cat, ls, or any tool you might need, to ensure functionality on the target host.

Custom Modules

Overview

Custom modules let you extend emp3r0r's functionality. Unlike the Metasploit Framework, these modules run on target hosts, not on the C2 server.

Use Cases:

• Launching attacks from a compromised machine (e.g., lateral movement).
• Running third-party tools.
• Local privilege escalation exploits.
• Credential collection and data exfiltration.

Creating Your First Module

Challenges:

1. Dependencies: Many scripts and binaries rely on dependencies. Python, for example, requires a compatible interpreter and libraries.
2. Compatibility: Pre-compiled binaries may not run on all targets due to differences in libraries (e.g., Glibc compatibility issues).
3. On-Target Compilation: Avoid compiling on target machines—it’s unreliable and can be noisy.

Preparing Your Module

General Tips

• Choose a language and make sure your executables run without errors on target hosts.
• Minimize dependencies, focusing on portability and basic APIs.
• Consider static compilation when possible to reduce compatibility issues.

Language-Specific Advice

Python

• Use pyinstaller to create standalone binaries.
• Alternatively, use the built-in python3.9 environment. More details here.

Bash

• Ensure any additional utilities your script requires are present (e.g., jq, nmap). If not, add them to the vaccine module.

Go

• Disable CGO unless you are sure about the target environment.

Rust, C, C++

• Use musl libc for static compilation.

Compression

• UPX: Compress binaries with UPX, but remember to strip them first for smaller sizes.

Module Metadata

Every module requires a config.json file with the following structure:

{
    "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"]
    }
}

Fields Description:

• name: The name displayed for the module.
• exec: The executable file name.
• platform: Target OS (e.g., Linux, Windows).
• interactive: Indicates if the module has a terminal interface (e.g., bash, htop).
• author: Creator’s name.
• date: Creation date.
• comment: A brief description.
• options: A dictionary of parameters with descriptions.

Example in Go:

type ModConfig struct {
    Name          string `json:"name"`        // Module name
    Exec          string `json:"exec"`        // Executable to run
    Platform      string `json:"platform"`    // Target OS
    IsInteractive bool   `json:"interactive"` // True if the module is a shell-like interface
    Author        string `json:"author"`      // Author name
    Date          string `json:"date"`        // Creation date
    Comment       string `json:"comment"`     // Brief description
    Options       map[string][]string `json:"options"` // Parameters: [value, description]
}

Loading and Using Modules

1. Load: Create a directory under ~/.emp3r0r/modules and place the config.json there.
2. Use:
   • Use the search <query> command in the emp3r0r console to locate your module.
   • use <module_name> to select it.
   • If your module has configurable options, set them with set option value. These values will be passed as environment variables to your executable.

Note:

Make sure your module’s options are handled correctly by reading the environment variables.