A local Python-based graphical user interface to scan files using the free VirusTotal Public API v3. The app shows scan results, hash values, and detection details in a clear, easy-to-read layout. Built with Tkinter for a lightweight, responsive experience on Windows, macOS, and Linux.
Table of Contents
- Overview
- What this project is for
- Key features
- How it works
- Architecture and tech stack
- Getting started
- Prerequisites
- End-user installation (from releases)
- Development setup (from source)
- How to use the app
- Preparing your VirusTotal API key
- Scanning a file
- Understanding the results
- Hashing and provenance
- Security, privacy, and data handling
- Performance and reliability
- Customization and extension
- UI tour and design notes
- Troubleshooting
- Testing and quality assurance
- Release management
- Roadmap
- Contributing
- License
- Acknowledgments
Overview This project delivers a local, Python-based GUI tool that enables file scanning through the VirusTotal Public API v3. It does not require you to push files to any external server beyond what VirusTotal already processes. The interface presents the file hash values (MD5, SHA-1, SHA-256), the VT scan verdicts, and detection details in a user-friendly window. The goal is to provide researchers, incident responders, and security-minded users with a straightforward way to inspect files with the VirusTotal API on their own machine.
What this project is for
- Quick, local analysis of files using VirusTotal data, without sending raw data to a dedicated server you control.
- A learning tool for developers and security practitioners to understand how to couple a GUI with a public API.
- A reference implementation for Python-based security tooling that uses public API endpoints in a safe, user-controlled environment.
Key features
- Local GUI with Tkinter: straightforward, responsive, keyboard-accessible controls.
- VT Public API v3 integration: fetch scan results, per-file verdicts, and detailed detections.
- Hash calculation and display: MD5, SHA-1, and SHA-256 for each file.
- Clear result visualization: color-coded verdicts, threat names, and tolerance notes.
- API key management: store securely (in memory for session, with prompts to protect keys).
- Lightweight and dependency-light: designed to run on modest hardware.
- Portable packaging: ready-to-run packages for major platforms via the Releases section.
- Extensible design: clean separation between UI, API calls, and data handling.
How it works
- The app accepts a file, computes standard cryptographic hashes, and sends a request to VirusTotal Public API v3 with your API key.
- The API returns a scan id and a verdict; the app then fetches detailed analysis data for the file.
- The user interface renders the results, including detection details, engine names, and categories.
- All results are presented locally in the GUI; sensitive input stays on your device.
Architecture and tech stack
- Language: Python 3.x
- GUI toolkit: Tkinter
- Networking: requests (HTTP) for VirusTotal API calls
- Hashing: hashlib for MD5, SHA-1, SHA-256
- Packaging: optional virtual environment, with a release package for end users
- Cross-platform support: Windows, macOS, Linux (subject to platform-specific packaging)
Getting started Prerequisites
- Python 3.8 or newer
- A VirusTotal Public API v3 key (free tier available)
- Basic familiarity with running Python code or executable installers
- Administrative/root access may be required on some systems for installing dependencies
End-user installation (from releases)
- The latest release package exists in the Releases section of this repository.
- The release page is available at https://github.com/hieumaster05/VirusTotal-File-Scanner/releases.
- From that page, download the release package (the page contains assets in ZIP or executable form). The download file is typically named something like VirusTotal-File-Scanner-.zip or VirusTotal-File-Scanner-.exe.
- Run or extract the downloaded package:
- If you downloaded an executable, run the installer/launcher directly.
- If you downloaded a ZIP, extract it and run the launcher inside (for example, VirusTotal-File-Scanner-/VTFileScanner.exe or VTFileScanner.py, depending on packaging choices).
- The installer or launcher will guide you through configuration, including entering your VirusTotal API key and choosing a default scan directory if supported.
Development setup (from source)
- Clone the repository: git clone https://github.com/hieumaster05/VirusTotal-File-Scanner.git
- Create a virtual environment:
- python3 -m venv venv
- source venv/bin/activate (Linux/macOS) or venv\Scripts\activate (Windows)
- Install dependencies:
- pip install -r requirements.txt
- If a requirements.txt is not present, install core libs:
- requests
- tkinter (usually included with Python)
- Run the app:
- python VTFileScanner.py
- Or use the launcher script provided in the repo
- For developers who want to package the app for distribution, follow the packaging guide in the Contributing or Build section below.
How to use the app Preparing your VirusTotal API key
- Sign up for a free VirusTotal account if you don’t have one.
- Generate an API key from your account dashboard.
- Copy the API key and store it securely in your environment or in the app’s settings as directed by the UI.
Scanning a file
- Launch the app from the installed launcher or from the development entry point.
- In the file picker, select the file you want to scan.
- The app calculates the file’s MD5, SHA-1, and SHA-256 hashes and displays them in the UI.
- The app sends a scan request to VirusTotal Public API v3, using your API key.
- A scan id is returned; the app fetches the analysis results associated with that id.
- The results appear in a dedicated pane, showing:
- Overall verdict (malicious, harmless, or undetected)
- Detected engines and their classifications
- File metadata and hashes
- URL and reference pointers for evidence
- Timestamp and scan details
Understanding the results
- VT analysis returns a set of engine verdicts. You may see multiple detections, each with a engine name, category, and result.
- The UI highlights any engines that labeled the file as malicious, as well as engines that returned clean or inconclusive results.
- Hash values provide a stable fingerprint for the file. Use them to cross-check with other tools or to verify file provenance.
- If the scan is pending, the UI will show a progress indicator and refresh until results are available. In some cases, results may require additional processing time on VirusTotal servers.
Hashing and provenance
- Hash values are calculated locally as soon as a file is selected:
- MD5
- SHA-1
- SHA-256
- These hashes help you confirm file identity and trace provenance in incident response workflows.
- The app stores a minimal in-memory record of the file metadata for the current session. No data is sent back to the app’s servers without your explicit action.
Security, privacy, and data handling
- The tool is designed for local use. Files are sent to VirusTotal only if you approve the scan action and provide your API key.
- Use a dedicated API key for testing and ensure you comply with VirusTotal’s terms of service.
- Do not scan sensitive data unless you are comfortable with the data sharing terms of VirusTotal’s API.
- The GUI is built to minimize exposure of logs that include sensitive file details. If you need more privacy, consider running the app in a sandboxed environment.
Performance and reliability
- Scans depend on VirusTotal API response times, which can vary with traffic and API key usage limits.
- The app gracefully handles rate limits and temporary errors by presenting clear messages and retry options.
- Local hashing is fast and scales with file size. Large files will take longer to hash, but the UI remains responsive.
Customization and extension
- The codebase is organized to separate UI, networking, and data handling. You can:
- Replace the UI with another toolkit if desired (Qt, Kivy, etc.)
- Extend API interaction to support additional VT endpoints (e.g., detailed per-engine reports)
- Add support for additional hash algorithms or metadata formats
- Create plugins to integrate with other security tools or SIEMs
- If you want to contribute, follow the guidelines in the Contributing section below.
UI tour and design notes
- The left pane lists the selected file and shows a quick summary of its hashes and status.
- The main pane shows the scan results and details in a structured, readable format:
- Verdict: color-coded for quick recognition
- Engines: list with engine name and result
- Detections: known malware families and families’ aliases
- Hashes: MD5, SHA-1, SHA-256
- Evidence: links and references to VirusTotal analysis
- The bottom bar presents actions such as “Scan another file,” “Save results,” and “Open help.”
- The UI emphasizes clarity and minimizes jargon. If a term is unfamiliar, hover tooltips or a help panel explains it in plain language.
Screenshots and visuals
- UI mockups and visuals help new users understand how the application looks and behaves.
- Visual placeholders are provided here for reference:
- Screenshots illustrate the flow from file selection to results presentation, including sample hash values and sample engine verdicts.
Troubleshooting
- If you cannot connect to VirusTotal:
- Verify your API key and ensure it is not expired or disabled.
- Check network connectivity and firewall rules that might block outbound HTTP requests.
- If the UI does not start:
- Confirm you are using a supported Python version.
- Ensure all dependencies are installed; re-run the dependency installation step.
- Check for missing resources or corrupted installation files; re-download from the official Releases page.
- If hash values differ from other tools:
- Confirm the file used for hashing is the same as the one being scanned.
- Recompute hashes manually and compare.
Testing and quality assurance
- Unit tests cover hashing routines and basic API request handling.
- Integration tests simulate VT API responses to validate UI behavior and error handling.
- Manual testing focuses on:
- File loading across common formats (bin, exe, dll, text, packaged archives)
- Large file performance
- API key boundary conditions (valid key, invalid key, rate limits)
- Continuous integration (CI) workflows run on push/pull requests to ensure code quality and test coverage.
Release management
- Releases are published to the Releases section, containing prebuilt packages and installers for convenient end-user deployment.
- The primary release page can be found at the link above. For a quick reference, you can use the same link again in the Releases section to verify the latest assets and release notes.
Roadmap
- Add multi-language UI translations
- Include offline analysis options with a locally stored hash database
- Support batch scanning of multiple files
- Introduce a richer results dashboard with charts and exports (CSV, JSON)
- Enhance security features with ephemeral keys and encrypted storage for API keys
- Improve accessibility with keyboard navigation, screen reader compatibility, and high-contrast themes
Contributing
- Welcome contributions from developers and researchers. If you want to contribute:
- Create a fork of the repository
- Implement features or fix issues
- Write tests for new functionality
- Submit a pull request with a clear description of changes
- Coding standards emphasize readability, clear error handling, and minimal dependencies.
- Please follow the project’s guidelines for issue reporting and feature requests.
License
- This project uses an open license suitable for educational and research purposes. See the LICENSE file in the repository for full terms and conditions.
Acknowledgments
- Thanks to the security community for inspiration and feedback
- Special thanks to VirusTotal for providing a public API that enables safe, educational experimentation
- Thanks to the contributors who tested and provided feedback to improve the tool
Releases: Quick reference
- The primary releases page you should check for the latest build is at https://github.com/hieumaster05/VirusTotal-File-Scanner/releases.
- Since this link includes a path, the release package you download from that page is the file you should run or unpack to get started. Typical assets include a zipped package or an executable launcher. The file to download and execute will be clearly labeled on the releases page, for example VirusTotal-File-Scanner-.zip or VirusTotal-File-Scanner-.exe. After downloading, run the contained launcher or installer to begin using the app.
Appendix: Design decisions and rationale
- Local-first philosophy: The tool prioritizes keeping data on your machine, with network access limited to the VirusTotal API when you opt to scan.
- Minimal dependencies: The goal is to keep installation straightforward, especially for users with limited system admin permissions.
- Cross-platform usability: Tkinter provides a consistent experience across Windows, macOS, and Linux without heavy platform-specific code.
- Clear, actionable results: Users should quickly determine whether a file is flagged by any engine and understand the nature of the detections.
Appendix: Frequently asked topics
- Do you need VirusTotal API access to use the app? Yes, to fetch scan results you must provide a valid VirusTotal Public API v3 key.
- Can I scan multiple files in one session? The core flow scans one file at a time. The architecture is ready for extension to batch operations in future versions.
- Is the app safe to use in a corporate environment? It is designed to be safe and locally executed. Ensure you comply with your organization’s policies regarding API usage and data handling.
Appendix: Documentation structure
- The README is organized to help both new users and maintainers. Quick-start sections help first-time users, while the architecture and developer notes support contributors and maintainers.
- All major features are documented with usage examples, expected behavior, and troubleshooting steps.
- Each section is crafted to be concise, yet informative, so you can quickly locate the information you need.
Appendix: Community and support
- If you run into issues, open an issue in the repository’s issue tracker with a clear description, steps to reproduce, and any console output you observed.
- For feature requests, propose a concrete plan with user stories and acceptance criteria.
- Community discussions are welcome; maintainers monitor issues and pull requests to ensure timely responses.
Appendix: Notes on safety and ethics
- The VirusTotal Public API is a valuable resource for threat research and incident response. Use it responsibly and in accordance with legal and organizational guidelines.
- Do not upload sensitive or confidential files to VirusTotal without proper authorization and understanding of data sharing terms.
- The local GUI helps minimize data exposure by processing and displaying results on the user’s machine, but the actual scan involves sending file data to VirusTotal as per API terms.
Appendix: How to stay up to date
- Check the Releases page regularly for new builds, bug fixes, and feature enhancements.
- Follow the repository for updates, patches, and community contributions.
- Update instructions are provided with each release to ensure a smooth upgrade path.
Appendix: Contact and feedback
- For questions, ideas, or feedback, use the repository’s issue tracker. The project maintainers welcome constructive feedback and collaborative testing.
Note: This README paraphrases and expands upon the provided information to create a thorough, user-friendly guide. It preserves the core concept of a local Python GUI tool that uses the VirusTotal Public API v3 to scan files and present results, while ensuring clarity, accessibility, and developer guidance.