ZeroPulse

---

📋 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

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

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