ZeroPulse

<div align="center"> <img src="docs/images/favicon.png" alt="favicon.png" width="300"/>

A Modern Command & Control (C2) Platform with Cloudflare Tunnel Integration

</div>

---

📋 Table of Contents

• Overview
• Features
• Architecture
• Prerequisites
• Installation
• Configuration
• Usage
• API Documentation
• Security
• Project Structure
• Development
• Contributing
• License
• Acknowledgments
• Support

🎯 Overview

ZeroPulse is a comprehensive Command & Control (C2) platform designed for secure remote management and monitoring. It leverages Cloudflare Tunnel technology to provide secure, encrypted connections without exposing your infrastructure to the public internet.

⚠️ Development Status: This project is currently in active development. This version is a demo/alpha release and some features may be:

• Unstable or subject to breaking changes
• Incomplete or partially implemented
• Under active development with frequent updates

We recommend using this software for testing and evaluation purposes only. For production use, please wait for a stable release or use at your own risk.

Key Highlights

• 🔒 Secure by Default: Built-in authentication, session management, and API token system
• 🌐 Cloudflare Integration: Seamless DNS and tunnel management via Cloudflare API
• 🖥️ Remote Management: WinRM and SSH support with evil-winrm integration for interactive shells
• 📊 Modern UI: Beautiful, responsive React interface with real-time terminal integration
• 🚀 Performance Optimized: Non-blocking I/O, optimized database queries, and memory leak prevention
• 🖥️ Local Shell Access: Interactive local shell via WebSocket with real-time terminal emulation

✨ Features

<div align="center"> <img src="docs/images/agents.png?raw=true" alt="favicon.png" /> <p><em>ZeroPulse Dashboard - Overview of all tunnels and system status</em></p> </div>

Core Capabilities

• Tunnel Management

  • Create and manage Cloudflare Tunnels
  • Configure ingress rules (HTTP, HTTPS, TCP)
  • Automatic DNS record management
  • Route proxy management

• Remote Command Execution

  • Execute commands on remote Windows systems via WinRM
  • Interactive shell with evil-winrm integration (Password & NTLM Hash authentication)
  • SSH command execution and interactive sessions
  • PowerShell script execution
  • Command history tracking
  • Real-time output streaming
  • Module Control Panel with dynamic module execution

• Remote Desktop

  • VNC server detection and management
  • noVNC web-based remote desktop client
  • Support for Windows and Linux systems
  • Secure tunnel-based connections

• Session & Security

  • JWT-based authentication
  • Active session management
  • API token system with granular permissions
  • Token blacklisting and revocation
  • Role-based access control (RBAC)

• DNS Management

  • Automatic DNS record creation/updates
  • Support for CNAME, A, AAAA records
  • Cloudflare proxy configuration
  • Conflict resolution

• Local Shell Access

  • Interactive local shell via WebSocket
  • Real-time terminal emulation with xterm.js
  • Standalone window support
  • Non-blocking I/O for optimal performance

• Module Control System

  • Dynamic module loading from database
  • Hierarchical structure (Categories → Sections → Items)
  • Template engine with variable substitution
  • Interactive terminal integration
  • Command execution history

⚙️ Technology Stack

| Layer | Technology | Purpose | |-------|-----------|---------| | Frontend | React 19, Redux Toolkit, React Router, TailwindCSS, xterm.js | User interface | | Backend | FastAPI, Uvicorn | API server | | Database | SQLite (with optimized queries and indexes) | Data persistence | | Authentication | JWT, python-jose | Token-based auth | | Remote Execution | pywinrm, paramiko, evil-winrm | WinRM & SSH integration | | Terminal | xterm.js, WebSocket | Interactive terminal | | External APIs | requests, cloudflare | Service integration | | Process Management | subprocess, asyncio, threading | Background tasks |

📦 Prerequisites

System Requirements

• OS: Linux (Ubuntu 20.04+, Debian 11+, or any modern Linux distribution)
• Python: 3.8 or higher
• Node.js: 20.19.0+ or 22.12.0+ (see .nvmrc in frontend directory)
• npm: Comes with Node.js
• Cloudflare Account: With API token and account ID
• Ruby (optional): For evil-winrm support (gem install evil-winrm)

Required Software

# Ubuntu/Debian
sudo apt update
sudo apt install -y python3 python3-pip python3-venv git curl

# Install Node.js 20+ (using nvm recommended)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
source ~/.bashrc
nvm install 20.19.0
nvm use 20.19.0

# Optional: Install Ruby for evil-winrm
sudo snap install ruby --classic
gem install evil-winrm

# Verify versions
python3 --version  # Should be 3.8+
node --version      # Should be 20.19.0+ or 22.12.0+
npm --version

🚀 Installation

<div align="center"> <img src="docs/images/system-setup.png?raw=true" alt="Installation Setup" /> <p><em>Installation Process - Setting up ZeroPulse on a new system</em></p> </div>

1. Clone the Repository

git clone https://github.com/yourusername/zeropulse.git
cd zeropulse

2. Backend Setup

# Create virtual environment
python3 -m venv venv

# Activate virtual environment
source venv/bin/activate

# Upgrade pip
pip install --upgrade pip

# Install dependencies
pip install -r requirements.txt

3. Frontend Setup

cd frontend

# Check Node.js version (should be 20.19.0+ or 22.12.0+)
node --version

# If using nvm, switch to required version
nvm use  # Automatically uses version from .nvmrc

# Install dependencies
npm install

# Build frontend
npm run build

cd ..

4. Configure Environment Variables

Create a .env file in the project root:

cat > .env << EOF
# Authentication Settings
ADMIN_USERNAME=admin
ADMIN_PASSWORD=your-secure-password-here
JWT_SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")
JWT_ALGORITHM=HS256
JWT_EXPIRATION_HOURS=24

# Cloudflare Settings
CLOUDFLARE_API_TOKEN=your-cloudflare-api-token-here
CLOUDFLARE_ACCOUNT_ID=your-cloudflare-account-id-here
CLOUDFLARE_DOMAIN=your-domain.com

# WinRM Settings (optional)
WINRM_USERNAME=WinRMUser
WINRM_PASSWORD=your-secure-password-here

# SSH Settings (optional)
SSH_KEY_PATH=/path/to/ssh/key
SSH_USERNAME=ssh_user

# C2 Server Settings
C2_SERVER_HOST=0.0.0.0
C2_SERVER_PORT=8000
ENVIRONMENT=production

# Database Settings
DATABASE_PATH=data/database.db
EOF

# Set permissions
chmod 600 .env

5. Start the Server

# Ensure virtual environment is active
source venv/bin/activate

# Start the server
python3 run_server.py

The server will be accessible at http://localhost:8000

⚙️ Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | ADMIN_USERNAME | Admin username | admin | | ADMIN_PASSWORD | Admin password | - | | JWT_SECRET_KEY | JWT signing key | - | | JWT_EXPIRATION_HOURS | Token expiration time | 24 | | CLOUDFLARE_API_TOKEN | Cloudflare API token | - | | CLOUDFLARE_ACCOUNT_ID | Cloudflare account ID | - | | CLOUDFLARE_DOMAIN | Your domain | - | | WINRM_USERNAME | WinRM username | WinRMUser | | WINRM_PASSWORD | WinRM password | - | | SSH_KEY_PATH | SSH private key path | - | | SSH_USERNAME | SSH username | - | | C2_SERVER_HOST | Server host | 0.0.0.0 | | C2_SERVER_PORT | Server port | 8000 | | ENVIRONMENT | Environment mode | development | | DATABASE_PATH | Database file path | data/database.db |

Cloudflare API Token Permissions

Your Cloudflare API token needs the following permissions:

• Zone: Zone:Read, DNS:Edit
• Account: Cloudflare Tunnel:Edit
• Zone Resources: Include your domain zone

Managing Tunnels

<div align="center"> <img src="docs/images/managing-tunnels.png?raw=true" alt="Tunnel List" width="800"/> <p><em>Tunnel List - View all tunnels with status, health indicators, and quick actions</em></p> </div>

Features

• Dynamic Port Mapping: Map local ports to tunnel routes
• Service Proxying: Proxy HTTP, HTTPS, and TCP services
• Automatic Management: Start, stop, and monitor proxy processes
• Port Discovery: Automatically find available ports
• Status Monitoring: Real-time status of all active proxies

1. Create a Tunnel: Navigate to Dashboard → Create Tunnel
2. Configure Routes: Set ingress rules for HTTP, HTTPS, or TCP services
3. Manage DNS: Automatic DNS record creation/updates
4. Monitor Status: View tunnel health and connection status

<div align="center"> <img src="docs/images/ingress-rules.png?raw=true" alt="Tunnel Routes Configuration" width="800"/> <p><em>Tunnel Routes Configuration - Configure ingress rules and DNS records</em></p> </div>

Remote Command Execution

<div align="center"> <img src="docs/images/rce.png?raw=true" alt="Command Execution" width="800"/> <p><em>Command Execution Inter