ZeroPulse

---

📋 목차

• 개요
• 기능
• 아키텍처
• 사전 요구사항
• 설치
• 구성
• 사용법
• API 문서
• 보안
• 프로젝트 구조
• 개발
• 기여
• 라이선스
• 감사의 말
• 지원

🎯 개요

ZeroPulse는 안전한 원격 관리 및 모니터링을 위해 설계된 종합적인 C2(Command & Control) 플랫폼입니다. Cloudflare Tunnel 기술을 활용하여 인프라를 공용 인터넷에 노출하지 않으면서도 안전하고 암호화된 연결을 제공합니다.

⚠️ 개발 상태: 이 프로젝트는 현재 활발히 개발 중입니다. 이 버전은 데모/알파 릴리스이며 일부 기능은 다음과 같을 수 있습니다:

• 불안정하거나 호환성을 깨뜨리는 변경이 있을 수 있음
• 불완전하거나 일부만 구현되었을 수 있음
• 빈번한 업데이트가 이루어지는 활발한 개발 중 상태

이 소프트웨어는 테스트 및 평가 목적으로만 사용할 것을 권장합니다. 프로덕션 환경에서는 안정적인 릴리스를 기다리거나 본인의 책임 하에 사용하십시오.

주요 특징

• 🔒 기본 보안 강화: 내장 인증, 세션 관리, API 토큰 시스템
• 🌐 Cloudflare 통합: Cloudflare API를 통한 원활한 DNS 및 터널 관리
• 🖥️ 원격 관리: 대화형 셸을 위한 evil-winrm 통합 및 WinRM/SSH 지원
• 📊 현대적인 UI: 실시간 터미널 통합을 갖춘 아름답고 반응형 React 인터페이스
• 🚀 성능 최적화: 비차단 I/O, 최적화된 데이터베이스 쿼리, 메모리 누수 방지
• 🖥️ 로컬 셸 접근: 실시간 터미널 에뮬레이션을 통한 WebSocket 기반 대화형 로컬 셸

✨ 기능

핵심 기능

• 터널 관리

  • Cloudflare 터널 생성 및 관리
  • 인그레스 규칙 구성 (HTTP, HTTPS, TCP)
  • 자동 DNS 레코드 관리
  • 경로 프록시 관리

• 원격 명령 실행

  • WinRM을 통해 원격 Windows 시스템에서 명령 실행
  • evil-winrm 통합 대화형 셸 (비밀번호 및 NTLM 해시 인증)
  • SSH 명령 실행 및 대화형 세션
  • PowerShell 스크립트 실행
  • 명령 기록 추적
  • 실시간 출력 스트리밍
  • 동적 모듈 실행이 가능한 모듈 제어판

• 원격 데스크톱

  • VNC 서버 탐지 및 관리
  • noVNC 웹 기반 원격 데스크톱 클라이언트
  • Windows 및 Linux 시스템 지원
  • 보안 터널 기반 연결

• 세션 및 보안

  • JWT 기반 인증
  • 활성 세션 관리
  • 세밀한 권한을 갖춘 API 토큰 시스템
  • 토큰 블랙리스트 및 폐기
  • 역할 기반 접근 제어 (RBAC)

• DNS 관리

  • 자동 DNS 레코드 생성/업데이트
  • CNAME, A, AAAA 레코드 지원
  • Cloudflare 프록시 구성
  • 충돌 해결

• 로컬 셸 접근

  • WebSocket 기반 대화형 로컬 셸
  • xterm.js를 사용한 실시간 터미널 에뮬레이션
  • 독립 실행 창 지원
  • 최적의 성능을 위한 비차단 I/O

• 모듈 제어 시스템

  • 데이터베이스에서 동적 모듈 로드
  • 계층적 구조 (카테고리 → 섹션 → 항목)
  • 변수 치환을 지원하는 템플릿 엔진
  • 대화형 터미널 통합
  • 명령 실행 기록

⚙️ 기술 스택

레이어	기술	용도
프론트엔드	React 19, Redux Toolkit, React Router, TailwindCSS, xterm.js	사용자 인터페이스
백엔드	FastAPI, Uvicorn	API 서버
데이터베이스	SQLite (with optimized queries and indexes)	데이터 저장
인증	JWT, python-jose	토큰 기반 인증
원격 실행	pywinrm, paramiko, evil-winrm	WinRM 및 SSH 통합
터미널	xterm.js, WebSocket	대화형 터미널
외부 API	requests, cloudflare	서비스 통합
프로세스 관리	subprocess, asyncio, threading	백그라운드 작업

📦 사전 요구사항

시스템 요구사항

• OS: Linux (Ubuntu 20.04+, Debian 11+ 또는 모든 최신 Linux 배포판)
• Python: 3.8 이상
• Node.js: 20.19.0+ 또는 22.12.0+ (frontend 디렉터리의 .nvmrc 참조)
• npm: Node.js에 포함됨
• Cloudflare 계정: API 토큰 및 계정 ID 보유
• Ruby (선택 사항): evil-winrm 지원용 (gem install evil-winrm)

필수 소프트웨어```bash

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

## 🚀 설치

<div align="center">
  <img src="https://assets.kitploit.com/production/public/readmes/7371/63f8299d6bb31aaa64c5e271f4e78bcb3ea94ef8ae7a2f1e2e3b6205552fb8b2.png" alt="설치 설정" />
  <p><em>설치 과정 - 새 시스템에 ZeroPulse 설정</em></p>
</div>

### 1. 저장소 복제```bash
git clone https://github.com/yourusername/zeropulse.git
cd zeropulse

2. 백엔드 설정```bash

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. 프론트엔드 설정```bash
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. 환경 변수 구성

프로젝트 루트에 .env 파일을 생성합니다:```bash 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. 서버 시작```bash
# 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

⚙️ 구성

환경 변수

변수	설명	기본값
ADMIN_USERNAME	관리자 사용자 이름	admin
ADMIN_PASSWORD	관리자 비밀번호	-
JWT_SECRET_KEY	JWT 서명 키	-
JWT_EXPIRATION_HOURS	토큰 만료 시간	24
CLOUDFLARE_API_TOKEN	Cloudflare API 토큰	-
CLOUDFLARE_ACCOUNT_ID	Cloudflare 계정 ID	-
CLOUDFLARE_DOMAIN	사용자 도메인	-
WINRM_USERNAME	WinRM 사용자 이름	WinRMUser
WINRM_PASSWORD	WinRM 비밀번호	-
SSH_KEY_PATH	SSH 개인 키 경로	-
SSH_USERNAME	SSH 사용자 이름	-
C2_SERVER_HOST	서버 호스트	0.0.0.0
C2_SERVER_PORT	서버 포트	8000
ENVIRONMENT	환경 모드	development
DATABASE_PATH	데이터베이스 파일 경로	data/database.db

Cloudflare API 토큰 권한

Cloudflare API 토큰에는 다음 권한이 필요합니다:

• Zone: Zone:Read, DNS:Edit
• 계정: Cloudflare Tunnel:Edit
• 영역 리소스: 도메인 영역 포함

터널 관리

기능

• 동적 포트 매핑: 로컬 포트를 터널 경로에 매핑
• 서비스 프록시: HTTP, HTTPS 및 TCP 서비스 프록시
• 자동 관리: 프록시 프로세스 시작, 중지 및 모니터링
• 포트 검색: 사용 가능한 포트 자동 검색
• 상태 모니터링: 모든 활성 프록시의 실시간 상태

1. 터널 생성: 대시보드 → 터널 생성으로 이동
2. 경로 구성: HTTP, HTTPS 또는 TCP 서비스에 대한 인그레스 규칙 설정
3. DNS 관리: DNS 레코드 자동 생성/업데이트
4. 상태 모니터링: 터널 상태 및 연결 상태 확인

원격 명령 실행