Skip to main content
Run this project only inside a controlled virtual machine or isolated lab network. It creates real reverse shells and persistence artifacts. Never install or run it on a production system or against any target you do not own.

​
Prerequisites

Before you begin, make sure the following are available on your system:
  • Python 3.8 or later — python.org/downloads
  • pip — bundled with Python 3.4+; verify with pip --version
  • Git — to clone the repository (or download the ZIP from GitHub)
  • Port 5050 open — required for the listener to accept remote connections
The game auto-detects whether pygame-ce is installed and offers to install it for you at startup via cyber_modules/dependency_checker.py. Manual installation is also supported.

​
Installation steps

1

Clone the repository

Download the source code to your local machine.
git clone https://github.com/cal250/Virus-Hunter-Code-Defender.git
cd Virus-Hunter-Code-Defender
Alternatively, download and extract the ZIP archive from the GitHub repository page, then open a terminal in the extracted folder.
2

Create a virtual environment (recommended)

Isolate the project dependencies from your system Python installation.
python3 -m venv .venv
source .venv/bin/activate
Using a virtual environment keeps pygame-ce scoped to this project and makes cleanup straightforward.
3

Install dependencies

The only required dependency is pygame-ce. Install it manually, or let the game install it automatically on first launch.Manual install:
pip3 install -r requirements.txt
Auto-install: Skip this step and run the game directly. cyber_modules/dependency_checker.py checks for pygame-ce at startup and prompts you to install it if it is missing.
4

Verify the installation

Confirm Python and pygame-ce are available:
python --version
python -c "import pygame; print(pygame.version.ver)"
You should see Python 3.8 or later and a pygame-ce version string.
5

Launch the game

Start the game from the repository root:
python game/main_game.py
See Optional flags below for windowed mode and custom host options.

​
Directory structure

Virus-Hunter-Code-Defender/
├── game/
│   └── main_game.py          # Main game entry point
├── cyber_modules/
│   ├── dependency_checker.py # Auto-installs pygame-ce if missing
│   ├── network_shell.py      # Reverse shell implementation
│   └── persistence.py        # Cross-platform persistence module
├── tools/
│   ├── listener.py           # TCP listener (run on the attacker/instructor machine)
│   └── cleanup_tool.py       # Removes all artifacts created during a session
├── requirements.txt          # Lists pygame-ce
├── VirusHunter.spec          # PyInstaller spec for standalone game executable
└── CleanupTool.spec          # PyInstaller spec for standalone cleanup executable

​
Optional flags

Pass flags to game/main_game.py to customize startup behavior:
FlagDescription
--windowedRun in a window instead of fullscreen
--host <IP>Override the default listener IP address
--bgStart the listener process in the background
Example: 
# Windowed mode with a custom listener IP
python game/main_game.py --windowed --host 192.168.1.100

​
Standalone executables

PyInstaller spec files are included if you need to distribute the game without requiring Python on the target machine. 
# Build the game executable
pyinstaller VirusHunter.spec

# Build the cleanup tool executable
pyinstaller CleanupTool.spec
Outputs are placed in the dist/ directory.

​
Platform notes

Windows

Fully supported. Persistence uses the Windows Registry (HKCU\Software\Microsoft\Windows\CurrentVersion\Run). Run PowerShell or Command Prompt as a standard user — no elevation required for the game itself.

Linux

Fully supported. Persistence uses a crontab entry. Ensure your user has write access to the crontab.

macOS

Fully supported. Persistence uses a LaunchAgent plist in ~/Library/LaunchAgents/.

​
Firewall and networking

The listener binds to 0.0.0.0:5050. For remote (two-PC) mode, port 5050 must be reachable from the game machine to the listener machine. 
# Allow inbound connections on port 5050
sudo ufw allow 5050/tcp
Only open port 5050 within an isolated lab network or virtual machine host-only adapter. Do not expose this port on an internet-connected or shared corporate network.

Build docs developers (and LLMs) love

Get started for freeTalk to us