Trace Hunter - A Ransomware Detection Tool

Trace Hunter is a real-time ransomware detection and monitoring system that uses Event Tracing for Windows (ETW) to detect suspicious file system operations, process activities, registry modifications, and network behaviors indicative of ransomware attacks.

Features

• Real-time Monitoring: File system, process, registry, network, and I/O monitoring
• Advanced Detection Engine: Rule-based detection with scoring system
• Process Whitelisting: Hash-based and signature verification for trusted processes
• Automated Response: Configurable actions (alert, isolate, terminate, quarantine)
• Web Dashboard: Real-time Angular frontend with live monitoring and alerts
• Event Architecture: Asynchronous event-driven system with Redis

Requirements

• Python: 3.10 and above
• Node.js: 14.x or higher (for frontend)
• Redis: 5.0 or higher (message broker)
• Operating System: Windows
• Administrator Privileges: Required for ETW provider access

Dependencies

Backend (Python)

The following Python packages lists some of the main dependencies used in the backend, but please refer to requirements.txt for the complete list.:

• Flask - Web framework
• Flask-SocketIO - WebSocket support
• Redis - Message broker
• Watchdog - File system monitoring
• psutil - System monitoring
• pywintrace - ETW (Event Tracing for Windows) support
• PyYAML - Configuration management

Frontend (Angular)

• Angular 20.x
• Socket.io-client - Real-time communication
• Chart.js - Data visualization
• Angular Material - UI components

Testing

• pytest - Testing framework
• pytest-cov - Coverage reporting
• pytest-html - HTML test reports
• pytest-xdist - Parallel test execution

Installation

1. Clone the Repository

git clone https://github.com/Viriliter/RansomwareDetector.git
cd RansomwareDetector

2. Set Up Project dependencies

Option A: Automated Installation (Recommended)

Note: For sysmon installation, you need to run the command prompt as Administrator or you can manually install sysmon later.

.\scripts\install_all.bat

This will:

• Install Python dependencies
• Install Node.js dependencies for frontend
• Install Redis server
• Install sysmon (requires administrator privileges)

Option B: Manual Installation

Install Python dependencies:

pip install -r requirements.txt

Install frontend dependencies:

cd frontend
npm install
cd ..

3. Set Up Redis

Redis is required as a message broker for the application.

Option 1: Using Docker

docker run -d -p 6379:6379 redis

Option 2: Using WSL

wsl redis-server

Option 3: Windows Native Download and install Redis for Windows from Microsoft Archive or use Memurai.

4. Configure the Application

Edit config.yaml to customize:

• Network ports (backend: 4100, frontend: 4200, redis: 6379)
• Logging levels and output
• Enable/disable specific monitors
• Detection rules and thresholds

Example configuration:

network:
  backend:
    host: 0.0.0.0
    port: 4100
  redis:
    host: localhost
    port: 6379
  frontend:
    host: localhost
    port: 4200

tasks:
  FilesystemMonitor:
    enabled: true
    priority: high
  ProcessMonitor:
    enabled: true
    priority: high

Note: To enable specific monitors, set enabled: true under the respective monitor section. By default, all monitors are disabled.

Running the Application

The application consists of a backend server (Flask) and a frontend server (Angular). Both need to be running for full functionality.

Start All Servers (Recommended)

.\scripts\start_servers.bat

This will:

• Check if Redis is running
• Start the backend server (Flask)
• Start the frontend server (Angular)

Start Backend Only

The application requires administrator privileges to access ETW providers. Without these privileges, some monitoring features will be limited. It is recommended to run the application in virtual environments.

To start the backend server with administrator privileges, open a command prompt as Administrator and run:

.venv\Scripts\activate
python run.py

Start Frontend Only

cd frontend
npm start

Accessing the Application

In any web browser, navigate to http://localhost:4200 to access the Trace Hunter dashboard.

Note: Default URLs and Ports for backend and frontend servers are listed and can be customized in config.yaml:

1. Backend API: http://localhost:4100
2. Frontend Dashboard: http://localhost:4200
3. Redis Server: localhost:6379

Project Structure

RansomwareDetector/
├── backend/          # Python backend
│   ├── controller/   # Business logic controllers
│   ├── core/         # Core system components
│   ├── executor/     # Automated response actions
│   ├── monitors/     # System monitors (ETW, filesystem, etc.)
│   ├── routes/       # API route handlers
│   └── utils/        # Utilities and helpers
├── docs/             # Documentation
├── frontend/         # Angular frontend
│   └── src/          # Frontend source code
│       └── app/          # Frontend source code
│       └── assets/       # Frontend assets
│       └── environments/ # Frontend environment configs
├── examples/         # Example python scripts
├── externals/        # External dependencies (e.g. sysmon)
├── scripts/          # Installation and startup scripts
├── tests/            # Test suite
├── tools/            # Test and simulation tool scripts 
├── logs/             # Application logs
├── quarantine/       # Quarantined files
├── reports/          # Test and coverage reports
└── config.yaml       # Main configuration file
└── README.md         # This file
└── LICENSE           # License information
└── run.py            # Backend application entry point
└── setup.py          # Setup script for packaging
└── system_index.json # Index of system files for monitoring

Configuration Files

• config.yaml: Main application configuration
• pytest.ini: Test framework configuration
• frontend/proxy.conf.json: Frontend proxy settings

Documentation

• docs/OVERVIEW.md - Describes system overview

Development

Simulation Tools:

Simulation scripts are available in the tools/simulations/ directory to generate test ransomware behaviors. There are two main scripts in this directory:

• simulate_ransomware.bat: Simulates ransomware-like file operations.
  • This script has two modes:
    • Start Simulation: Starts a simulation of ransomware activity by creating, modifying, and encrypting files in a specified directory.
    • Restore: Restores the encrypted files back to their original state.
• create_test_directory.bat: Creates a dummy test directory in a way that mimics usual user directory structures.

For detailed usage instructions, refer to the tools/simulation/README.md file.

Test Tools:

Test scripts are available in the tools/testing/ directory to facilitate running and managing tests. There are three main scripts in this directory:

• generate_coverage_report.bat: Generates coverage reports after tests have been run.
• run_tests.bat: Runs all unit and integration tests with coverage reporting.
• run_integration_tests.bat: Runs only the integration tests.
• run_unit_tests.bat: Runs only the unit tests.

Test Coverage

View coverage reports:

• HTML Report: reports/coverage/html/index.html
• Terminal: Displayed after test execution
• XML Report: reports/coverage/coverage.xml (for CI/CD)

Test Structure

tests/
├── unit/             # Unit tests
│   ├── controller/   # Controller tests
│   ├── core/         # Core module tests
│   ├── executor/     # Executor module tests
│   ├── monitors/     # Monitor tests
│   └── utils/        # Utility tests
└── integration/      # Integration tests

Contributing

N/A

License

See LICENSE file for details.

Security

This tool is designed for security research and system monitoring. Use responsibly and in accordance with applicable laws and regulations.

Support

For issues, questions, or contributions, please open an issue on GitHub.

Future Work

Planned enhancements include:

• Implementation of automated response actions
• Testing registry and network monitors
• Fine-tuning of detection rules and thresholds
• Effective usage of system indexing for improved monitoring
• Machine-learning-based anomaly detection
• Enhanced test coverage and CI/CD integration
• Testing the application with real-world ransomware samples in a controlled environment.

Screenshots

Figure 1: Trace Hunter Dashboard displaying real-time monitoring and alerts.

Figure 2: Alert notification for detected ransomware activity.

Figure 3: Monitoring configuration interface.

Figure 4: Detailed process tree activity view.

Figure 4: Settings panel for customizing detection rules and thresholds.