PyPScan: Python Process Scanner with VirusTotal Integration

A Python-based process scanner that uses the VirusTotal API to analyze running processes on a Windows machine. The scanner calculates a SHA-256 hash for each process's executable, queries VirusTotal for threat reports, and caches the results locally to avoid duplicate API calls. It features dynamic time estimation, a live progress display, and incremental cache updates to ensure that progress is not lost between runs.

Features

• Process Retrieval: Uses Windows Management Instrumentation (WMI) to retrieve all running processes with valid executable paths.
• File Hashing: Computes a SHA-256 hash for each executable to uniquely identify the file.
• VirusTotal Integration: Queries the VirusTotal API for each file hash not already cached, retrieving the number of malicious and total reports.
• Incremental Caching: Stores query results in a JSON cache (vt_cache.json) immediately after each API call so that progress is preserved between runs.
• Dynamic Progress Display: Shows the number of API queries completed, the estimated remaining time (based on pending API calls), and the counts of processes flagged as threats versus clean.
• Configurable Thresholds: Easily adjust the threshold for marking a process as potentially malicious.
• Graceful Error Handling: Exits with an informative message if the API key is invalid (HTTP 401).

Prerequisites

• Python 3.6+
• Windows operating system
• VirusTotal API Key (A free API key is required for non-commercial use)

Python Dependencies

Install the required Python packages using pip:

pip install wmi requests

Setup

1. Clone the Repository:

   git clone https://github.com/kw-soft/pypscan.git
   cd your-repo-name

2. Create the Configuration File:

   A config.json file is included in the repository. You must edit this file and replace the placeholder with your VirusTotal API key:

   {
       "API_KEY": "YOUR_VIRUSTOTAL_API_KEY"
   }

   Note:
   Ensure that you add config.json to your .gitignore so that your API key is not accidentally published.

Usage

Run the script using Python:

python main.py

The script will:

• Retrieve all running processes with executables.
• Calculate a SHA-256 hash for each process.
• Query VirusTotal for any hash that isn’t already cached (with a 15-second delay between API calls to respect rate limits).
• Display a dynamic progress summary in the console.
• Output a detailed list of processes that are potentially malicious once the scan is complete.

How It Works

1. Configuration Loading:
   The script reads the API key from config.json.

2. Process Retrieval & Hashing:
   It uses the WMI interface to list running processes and calculates a unique SHA-256 hash for each executable.

3. VirusTotal Query & Caching:
   For each hash not found in the local cache (vt_cache.json), the script queries the VirusTotal API. The result (number of malicious reports and total reports) is then immediately saved to the cache.

4. Progress Display & Time Estimation:
   The console shows a live progress update with the number of API calls completed (out of the total required), an estimated remaining time (based on pending queries), and the current counts of flagged threats versus clean processes.

5. Final Report:
   After scanning, a summary is printed along with a detailed list of any processes deemed potentially malicious.

Disclaimer

This tool is provided for educational and research purposes only. It is not intended for production use or commercial purposes. Use it at your own risk. Make sure to comply with the VirusTotal API usage policies and rate limits.

License

This project is licensed under the MIT License.