cpanel-malware-scanner - Defensive malware scanning tool for cPanel/shared

项目说明

<di="center">

🛡️ Remote cPanel Malware Engine

A decoupled, remote-controlled malware scanning engine built for restricted shared-hosting en.

!Python
!Streamlit
!Platform
!License
!Status

</div>

---

📚 Table of Contents

---

📖 O

Traditional malware scanners often fail on shared servers due to strict CPU limits, process timeouts, and massive file structures. This project solves that by splitting the application into two layers:

| Layer | Role |
|---|---|
| 🖥️ Backend (security-engine.py) | A lightweight, stateful CGI script that lives on the server and does the actual scanning |
| 📊 Frontend (dashboard.py) | A real-time Streamlit dashboard that runs locally and drives the engine over HTTP |

---

✨ Core Architecture & Features

<details>
<summary><strong>🔹 Micro-Batch Processing</strong></summary>
<br>

The backend engine reads ser in dynamically controlled chunks (e.g. 200 files per request), pre Apache from crashing or throwing 500 Internal Sers due to RAM exhaustion.
</details>

<details>
<summary><strong>🔹 Stateful Memory</strong></summary>
<br>

A local state tracker on the ser the last scanned index, so the engine can resume seamlessly after a network drop.
</details>

<details>
<summary><strong>🔹 Resilient Networking</strong></summary>
<br>

The local frontend sets standard browser-like request headers so scans aren't disrupted by hosting-provider firewalls (e.g. Imunify360, Cloudflare) misclassifying legitimate, self-initiated traffic as bot activity. Only use this against infrastructure you own or are authorized to test.
</details>

<details>
<summary><strong>🔹 Dynamic Path Mapping</strong></summary>
<br>

Outputs the absolute ser of detected malicious signatures into a structured Pandas dataframe for immediate remediation.
</details>

---

🛠️ Tech Stack

<di="center">

| Frontend Controller | Backend Engine | Target En |
|:---:|:---:|:---:|
| Python · Streamlit · Pandas · Requests | Python · Apache CGI · Regex · JSON | Linux · cPanel · Shared Hosting |

</div>

---

🚀 How It Works

1. The Bridge — The dashboard authenticates with the remote ser a secret token (kept out of source control — see .gitignore).
2. The Scan — The ser the target directory, scans a chunk of files against known malware regex patterns (hidden base64_decode, rogue shell_exec, etc.), updates its state file, and returns JSON telemetry.
3. The Loop — The frontend reads the JSON, updates the li bar, and automatically triggers the next chunk until the whole directory tree is mapped.

---

⚡ Quick Start

---

1️⃣ Ser Deployment (cPanel)

1. Upload security-engine.py to your server's public_html directory (or the target folder).
2. Set file permissions to 755 (executable).
3. Add the first line of the script as a valid shebang, e.g. #!/usr/bin/python3.
4. Configure .htaccess as described below.

2️⃣ Client-Side Deployment (local machine)

Then open the local URL Streamlit prints (usually ).

---

🔧 .htaccess Configuration

By default, Apache doesn't know how to execute a .py file — it will either display the raw source or force a download. To run your script as a live CGI application, add this to the .htaccess file in the same folder as security-engine.py:

| Directive | What it does |
|---|---|
| Options +ExecCGI | Tells Apache to allow executable scripts to run in this folder |
| AddHandler cgi-script .py | Tells Apache to *execute* .py files instead of serving their raw source |

> Note: The script must be chmod 755 and start with a valid shebang (#!/usr/bin/python3 or #!/usr/bin/en) for the handler to work.

<details>
<summary>🔍 How to enable hidden files in cPanel File Manager</summary>
<br>

1. Open cPanel → File Manager.
2. Click Settings (top right).
3. Check Show Hidden Files (dotfiles).
4. Click Save.
</details>

---

📁 Project Structure

---

❓ FAQ / Troubleshooting

<details>
<summary><strong>The ser raw Python code instead of running it</strong></summary>
<br>

Your .htaccess isn't being applied. Double-check it's in the correct directory and that your hosting plan allows AddHandler o (some cPanel configurations restrict this — check with your host if it still fails).
</details>

<details>
<summary><strong>I'm getting a 500 Internal Ser</strong></summary>
<br>

Usually a permissions or shebang issue. Confirm the script is chmod 755 and the first line points to a valid Python interpreter path on the server (which python3 via SSH, if a).
</details>

<details>
<summary><strong>The dashboard can't connect to the engine</strong></summary>
<br>

the secret token matches on both sides, and that the server URL in dashboard.py points to the correct path to security-engine.py.
</details>

---

👤 Author

Hasnain Khan
*Focus: Data Science, Predicti & AI Automation*

项目信息

开发语言：Python

Star 数：3

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Defensive malware scanning tool for cPanel/shared hosting environments. Scans for webshells and suspicious files on servers you own or manage展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。