A Python script to automatically search GitHub for .exe, .com, .pif, .msi, .scr, .bat, .cmd, .dll, .sys, .drv, .ocx, .vbs, .js, .ps1, .hta, .wsf, .lnk, .sh, .py, .zip, .rar, .7z, .tar, .gz, .iso, .docm, .xlsm, .pptm, .apk, .jar files, download them, and scan them for malware using ClamAV and VirusTotal. Results are logged and malicious files are saved for further analysis.
What malscan looks like while running with verbose:
What the folder output will look like:
What the Malware Log will look like:
- Searches GitHub repositories for
.exe, .com, .pif, .msi, .scr, .bat, .cmd, .dll, .sys, .drv, .ocx, .vbs, .js, .ps1, .hta, .wsf, .lnk, .sh, .py, .zip, .rar, .7z, .tar, .gz, .iso, .docm, .xlsm, .pptm, .apk, .jarfiles using the GitHub API. - Should Comply with API Limits for Virus Total.
- Downloads and scans each file with ClamAV.
- Then scans files with VirusTotal (API key required, respects rate limits).
- Maintains blocklists to avoid reprocessing the same files or repositories.
- Has extensive verbose mode, can choose wether you want to see the verbose when starting a scan.
- Allows for setting recursive search depth
- You can specify up to 30-100 for search query at the moment, however this searches three filters so you'll likely get around 300 repos to search
- Allows for setting a keyword to search for, IE: Roblox Hacks, and it will filter only from this topic
- Designed for use on a Raspberry Pi or Linux system with SSD storage.
- Automatically installs missing Python dependencies.
- Automatically logs the source address to a file inside a folder containing the binary, allows for easier reporting.
- Python 3.7+
- ClamAV installed and available in your PATH
- A GitHub Personal Access Token with
repoaccess - A VirusTotal API key (optional, but recommended)
- Linux system (uses
/mnt/ssdandnicecommand; adjust for other OSes as needed)
-
Clone this repository or download the script:
git clone https://github.com/Net-Zer0/MalScan.git cd malscan.py -
Install ClamAV: -If you are using V3.1VT, you may skip this step!
sudo apt update sudo apt install clamav
-
Edit the script:
- Replace the
GITHUB_TOKENandVT_API_KEYvariables at the top of the script with your own keys. - You can create a token in the developer section of Githubs settings for your account, create a new personal one and copy that and use it in the script, However I must empathize you must never share this!!!
- Replace the
-
(Optional) Adjust directories:
- By default, the script uses
/mnt/ssdfor storage and/tmp/git_scanfor temporary files. Change these if needed.
- By default, the script uses
-
(Non Optional) Adjustment to directories:
- ALSO more importantly change the def mount portion
def mount_ssd():where/dev/sda3is defined, this needs to be set to your drive to work, IE: SSD or USB etc. using lsblk can find your mount point! - THIS STEP IS CRUCIAL TO THE SCRIPT WORKING AND REQUIRES SOME KNOWLEDGE OF PYTHON!!!
- ALSO more importantly change the def mount portion
-
(Optional) Adjust the search query to include other file types
SEARCH_QUERY = "extension:exe OR extension:dll OR extension:scr OR extension:bat OR extension:cmd OR extension:js OR extension:vbs OR extension:ps1 OR extension:msi OR extension:com OR extension:jar" SEARCHES = [ {"desc": "fewest stars", "sort": "stars", "order": "asc"}, {"desc": "newly indexed", "sort": "indexed", "order": "desc"}, {"desc": "recently updated", "sort": "updated", "order": "desc"}, ]
- you can pretty much change or add any scannable file type to
extensions:X OR extension:Xmeaning you can easily add more to the scope by tweaking it until I add more to the base script!
Run the script with Python 3:
sudo python3 MalScanV4.py or MalScan4VT.pyI would recommend if you are using Raspbian to use the 64bit version and run it in lite as we will be using the command line exclusively. I would also recommend if you want to run it for long periods of time to use tmux new -s scan or some other alternative like screen to keep the process running if you are using SSH, this will allow you to come back and reattach to the program when leaving it unattended if you do not have a monitor and keyboard to run it as it's own workstation. among other things I am investigating freezing issues with ClamAV on my 3B+, however I'm fairly certain this is due to undervoltage on my part. when I figure that out I may make ClamAV scan with more vigor, It will likely also work better on hardware that is not from 2018. At some point I will be upgrading to a RPI 5 to see if it runs better, If you are getting freezing issues I would recommend only running the VT only version for now.
- To Be Determined!!!
- Will add more features and functions to do with detection or extensions upon majority request!
- V1 - inital iteration of MalScan
- V2 & V2VT - added folders and sorting methods, new VT version for exclusively using virus totals API for slower hardware.
- V3 & V3VT - added other extension to the scope of the search, ones commonly associated with malware.
- V3.1 & V3.1VT - removed unused function for optimization and added more API error handling
- V4 & V4VT -
.pif, .drv, .ocx, .sys, .hta, .wsf, .lnk, .sh, .py, .zip, .rar, .7z, .tar, .gz, .iso, .docm, .xlsm, .pptm, .apkadded to scan list
Git-MalScan is provided for research and cybersecurity awareness purposes only. The authors and contributors are not responsible for any potential harm, system damage, data loss, or security breaches that may result from running this tool.
- Users must exercise caution when scanning and handling binaries, as malware can pose significant risks.
- Running Git-MalScan requires proper security measures, such as isolated environments, virtual machines, or dedicated analysis setups.
- This tool does not guarantee complete or perfect malware detection and should not replace professional cybersecurity solutions. By using Git-MalScan, you acknowledge and accept these risks and take full responsibility for its usage.