blinkzero/pcap-replaya-backend repository overview

⁠PCAP Replaya

A modern web application for replaying network packet capture (PCAP) files using tcpreplay. Built with React frontend, Flask backend, and fully containerized with Docker.

⁠✨ Features

• 📁 File Upload: Drag-and-drop PCAP upload with validation (.pcap, .pcapng, .cap up to 1GB)
• 📊 PCAP Analysis: Automatic analysis showing packet count, duration, and protocols
• 🔄 Flexible Replay: Speed control with multiplier or PPS modes
• 🔁 Continuous Replay: Loop PCAP files continuously until manually stopped
• 📈 Real-time Monitoring: Live progress tracking with WebSocket updates
• 📋 Replay History: Persistent history with pagination, search, and filtering
• ⬇️ Download Feature: Download previously replayed PCAP files
• 🖥️ Interface Selection: Dynamic network interface detection
• 📱 Responsive UI: Modern Material-UI interface

⁠🚀 Quick Start

⁠One-Command Deployment (Recommended)

curl -sSL https://raw.githubusercontent.com/blink-zero/pcap-replaya/main/quick-deploy.sh | sudo bash

⁠Manual Deployment

# Download production configuration
curl -sSL https://raw.githubusercontent.com/blink-zero/pcap-replaya/main/docker-compose.prod.yml -o docker-compose.yml

# Start the application
sudo docker-compose up -d

⁠Access the Application

• Frontend: http://localhost⁠
• Backend API: http://localhost:5000/api⁠

⁠📋 Prerequisites

• Docker and Docker Compose
• Linux environment (for network interface access)
• Root/sudo privileges (required for tcpreplay network access)

⁠🔄 Updating

⁠Quick Update

cd pcap-replaya-deploy
curl -sSL https://raw.githubusercontent.com/blink-zero/pcap-replaya/main/update.sh | sudo bash

⁠Manual Update

sudo docker-compose pull
sudo docker-compose down
sudo docker-compose up -d

⁠📖 Usage

⁠1. Upload PCAP File

• Drag and drop or click to select a PCAP file
• Supported formats: .pcap, .pcapng, .cap
• Maximum size: 1GB

⁠2. Configure Replay

• Interface: Select network interface
• Speed: Choose multiplier (0.1x-100x) or PPS (1-1,000,000)
• Continuous: Enable for continuous looping
• Advanced: Loop count and preload options

⁠3. Monitor Progress

• Real-time progress updates
• Live packet and data transmission stats
• Stop replay at any time

⁠4. View History

• Browse all previous replays
• Search and filter by status
• Download original PCAP files
• Replay with same configuration

⁠🔌 API Documentation

⁠Base URL

http://localhost:5000/api

⁠Authentication

No authentication required for local deployment.

⁠Endpoints

⁠Health & System

⁠File Management

⁠Replay Control

⁠Packet Manipulation

⁠Logging

⁠Request Examples

⁠Start Replay

curl -X POST http://localhost:5000/api/replay/start \
  -H "Content-Type: application/json" \
  -d '{
    "file_id": "uuid-of-uploaded-file",
    "interface": "eth0",
    "speed": 2.0,
    "speed_unit": "multiplier",
    "continuous": false,
    "loop": 1,
    "preload_pcap": false
  }'

⁠Upload File

curl -X POST http://localhost:5000/api/upload \
  -F "[email protected]"

⁠Get Replay History

curl "http://localhost:5000/api/replay/history?limit=20&offset=0&search=test&status=completed"

⁠Response Examples

⁠Replay Status

{
  "replay_id": "uuid",
  "status": "running",
  "progress_percent": 45.2,
  "packets_sent": 1250,
  "bytes_sent": 892400,
  "elapsed_time": 12.5,
  "packets_per_second": 100.0,
  "continuous": false,
  "loop_count": 1
}

⁠Upload Response

{
  "message": "File uploaded successfully",
  "file_id": "uuid",
  "filename": "example.pcap",
  "file_size": 1048576,
  "pcap_info": {
    "packet_count": 1000,
    "duration": 30.5,
    "file_format": "pcap",
    "protocols": ["IP", "TCP", "UDP"]
  }
}

⁠History Response

{
  "history": [
    {
      "id": "uuid",
      "filename": "example.pcap",
      "file_id": "file-uuid",
      "status": "completed",
      "started_at": "2025-08-08T15:30:00Z",
      "duration": 25.3,
      "packets_sent": 1000,
      "config": {
        "interface": "eth0",
        "speed": 2.0,
        "speed_unit": "multiplier",
        "continuous": false
      }
    }
  ],
  "total_count": 50,
  "limit": 20,
  "offset": 0,
  "has_more": true
}

⁠WebSocket Events

Connect to: ws://localhost:5000

⁠⚙️ Configuration

⁠Environment Variables

⁠Docker Configuration

The application uses host networking and privileged containers for network interface access.

⁠🏗️ Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   React Frontend│◄──►│  Flask Backend  │◄──►│   tcpreplay     │
│                 │    │                 │    │                 │
│ • File Upload   │    │ • API Endpoints │    │ • Packet Replay │
│ • Config UI     │    │ • File Handling │    │ • Speed Control │
│ • Progress Mon. │    │ • WebSocket     │    │ • Interface Mgmt│
│ • History View  │    │ • Process Mgmt  │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘

⁠🛠️ Development

⁠Local Development

⁠Backend

cd backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python app.py

⁠Frontend

cd frontend
npm install
npm start

⁠Build from Source

git clone https://github.com/blink-zero/pcap-replaya.git
cd pcap-replaya
sudo docker-compose up --build

⁠🔧 Troubleshooting

⁠Common Issues

⁠Permission Denied

# Ensure Docker has necessary privileges
sudo docker-compose down
sudo docker-compose up --build

⁠tcpreplay Not Working

# Check tcpreplay in container
docker-compose exec backend tcpreplay --version

⁠File Upload Fails

• Check file size (max 1GB)
• Verify file format (.pcap, .pcapng, .cap)
• Ensure sufficient disk space

⁠Debug Commands

# View logs
docker-compose logs -f

# Check system status
docker-compose exec backend python -c "
import psutil
print(f'CPU: {psutil.cpu_percent()}%')
print(f'Memory: {psutil.virtual_memory().percent}%')
"

# Test tcpreplay
docker-compose exec backend tcpreplay --version

⁠📊 Technology Stack

⁠Backend

• Flask 2.3.3 - Web framework
• Flask-SocketIO 5.3.6 - WebSocket communication
• Scapy 2.5.0 - PCAP analysis
• psutil 5.9.5 - System monitoring
• tcpreplay - Packet replay

⁠Frontend

• React 18.2.0 - Frontend framework
• Material-UI 5.14.1 - UI components
• axios 1.4.0 - HTTP client
• socket.io-client 4.7.2 - WebSocket client

⁠Infrastructure

• Docker & Docker Compose - Containerization
• Nginx - Reverse proxy
• Python 3.11 - Backend runtime
• Node.js 18 - Frontend build

⁠📝 License

This project is licensed under the MIT License - see the LICENSE⁠ file for details.

⁠🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

⁠📞 Support

• Issues: GitHub Issues⁠
• Documentation: Check troubleshooting section above
• Logs: Use docker-compose logs -f for debugging

⁠🏷️ Version History

• v1.3.11 - Added GitHub link to UI and cleaned up interface
• v1.3.10 - Improved history details display for continuous replay mode
• v1.3.9 - Complete README overhaul and comprehensive API documentation
• v1.3.8 - Added PCAP download feature to replay history
• v1.3.7 - Fixed continuous mode display in history details
• v1.3.6 - Fixed speed unit display (PPS showing correctly)
• v1.3.5 - Fixed critical status override bug (stopped vs failed)
• v1.3.4 - Improved status handling for manually stopped replays
• v1.3.3 - Fixed critical validator bug for continuous parameter
• v1.3.2 - Fixed continuous replay frontend logic
• v1.3.1 - Fixed continuous replay process communication
• v1.3.0 - Added continuous replay feature
• v1.2.1 - Fixed Docker version display and search input focus
• v1.2.0 - Enhanced replay history with pagination and search
• v1.1.0 - Added pagination for replay history
• v1.0.0 - Initial release

⁠🙏 Acknowledgments

• tcpreplay⁠ - Network packet replay utility
• Scapy⁠ - Packet manipulation library
• React⁠ - Frontend framework
• Flask⁠ - Backend framework
• Material-UI⁠ - UI component library