MalGuiser

MalGuiser: Hard-Label Adversarial Attack Against Machine Learning-Based Malicious Package Detectors

A full-stack research platform with a Vue 3 web interface for managing detectors, generating adversarial samples, clustering analysis, functionality verification, and semantic repair of Python packages.

📋 Prerequisites

• Python: Python 3.8+
• Node.js: 18+ (for frontend)
• Operating System: Linux or Windows
• Software Dependencies:
  • pip (Python package manager)
  • npm (Node.js package manager)
  • Git (for cloning the repository)
  • Access to LLM APIs (OpenAI GPT-4, DeepSeek, etc.)

📊 Dataset

This project works with Python package datasets for malware detection research. Download malicious and benign packages from the following sources:

Malicious Packages

• PyPI Malregistry: https://github.com/lxyeternal/pypi_malregistry
• DataDog Dataset: https://github.com/DataDog/malicious-software-packages-dataset
• OSS-MPAW: https://github.com/Rebecia/OSS-MPAW
• MALOSS: https://github.com/osssanitizer/maloss

Benign Packages

• MalGuard Dataset: https://zenodo.org/doi/10.5281/zenodo.15545824

Dataset Structure

dataset/
├── malicious_packages/      # Malicious packages (original)
│   ├── package-a-1.0.0/
│   └── ...
├── benign/                  # Benign packages
└── test/                    # Test samples

Note: Due to ethical and legal considerations, datasets are not included in this repository. Use publicly available malware research datasets or create your own in accordance with applicable laws.

🎯 Target Detector

MalGuiser supports testing against various malware detection systems, including ML-based detectors and real-world security tools.

ML Detectors

1. MalGuard: CNN-based PE file analysis (Zenodo)
2. SAP: Cross-language ensemble detector (GitHub)
3. MalDet: Ensemble detector v3.0 (Zenodo)

Real-world Detectors

4. VirusTotal: https://www.virustotal.com
5. OSSGadget: https://github.com/microsoft/OSSGadget
6. Bandit4mal: https://github.com/lyvd/bandit4mal
7. Aura: https://github.com/SourceCode-AI/aura

📁 Project Structure

MalGuiser/
│
├── backend/                     # FastAPI backend
│   ├── app/
│   │   ├── main.py              # FastAPI entry, route registration
│   │   ├── config.py            # Detector paths, CORS, LLM config
│   │   ├── api/                 # REST API route handlers
│   │   │   ├── adversarial.py   # Adversarial attack endpoints
│   │   │   ├── cluster.py       # Clustering endpoints
│   │   │   ├── detector.py      # Detector management
│   │   │   ├── repair.py        # Verification & repair endpoints
│   │   │   ├── samples.py       # Sample & report management
│   │   │   └── statistics.py    # Dashboard statistics
│   │   ├── core/
│   │   │   └── detector_manager.py  # Detector lifecycle orchestration
│   │   ├── models/
│   │   │   └── schemas.py       # Pydantic request/response models
│   │   └── services/            # Service layer
│   └── requirements.txt         # Backend Python dependencies
│
├── frontend/                    # Vue 3 + Vite + TypeScript frontend
│   ├── src/
│   │   ├── App.vue              # Root component
│   │   ├── main.ts              # App entry point
│   │   ├── api/                 # Axios API client layer
│   │   │   ├── adversarial.ts
│   │   │   ├── cluster.ts
│   │   │   ├── detector.ts
│   │   │   ├── repair.ts
│   │   │   ├── request.ts       # Base Axios instance (auto Content-Type)
│   │   │   ├── sample.ts
│   │   │   └── statistics.ts
│   │   ├── components/
│   │   │   └── common/          # LogViewer, MainLayout, StatusPanel
│   │   ├── router/              # Vue Router (SPA)
│   │   ├── stores/              # Pinia state management
│   │   ├── types/               # TypeScript interfaces
│   │   ├── utils/               # Constants, WebSocket client
│   │   └── views/
│   │       ├── DashboardView.vue
│   │       ├── DetectorView.vue
│   │       └── tabs/
│   │           ├── AdversarialTab.vue   # Adversarial sample generation
│   │           ├── ClusterTab.vue       # Cluster analysis
│   │           ├── RepairTab.vue        # Function verification & repair
│   │           └── SampleReportTab.vue  # Sample & report management
│   ├── public/
│   │   └── verification-repair.html     # Standalone verification-repair UI
│   ├── package.json
│   └── vite.config.ts
│
├── adversarial_attack/          # Adversarial attack modules
│   └── evasion/
│       ├── injection.py         # Dead code injection techniques
│       ├── modify_metadata.py   # Metadata modification
│       ├── obfuscation.py       # Code obfuscation methods
│       └── anti_analysis.py     # Anti-debugging techniques
│
├── embedding_cluster/           # Embedding and clustering modules
│   ├── embedding.py             # Feature embedding generation
│   └── cluster.py               # Clustering algorithms
│
├── functionality_verification_repair/  # Post-attack verification
│   ├── llm_for_fix_with_tokenv2.py     # LLM-based package repair
│   ├── validate_functionality.py       # Semantic validation
│   └── validate_syntax_compilation.py  # Syntax & compilation check
│
├── ml_detector/                 # ML detector implementations
│   ├── sap/                     # SAP detector
│   ├── malguard.py              # MalGuard detector
│   └── maldet.py                # MalDet detector
│
├── realwrod_detector/           # Real-world detector interfaces
│   ├── aura_wrapper.py
│   └── oss_gadget.py
│
├── dataset/                     # Dataset directory
│   ├── malicious_packages/      # Original malicious samples
│   ├── benign/                  # Benign samples
│   └── test/                    # Test samples
│
├── results/                     # Attack run outputs
│
├── main.py                      # CLI adversarial attack engine (MAB)
├── start.bat                    # Windows one-click launcher
├── requirements.txt             # Root Python dependencies
└── README.md                    # This file

🔧 Install

1. Clone the Repository

git clone https://anonymous.4open.science/r/MalGuiser-3F5E.git
cd MalGuiser

2. Create Virtual Environment & Install Dependencies

# Using venv
python -m venv venv

# Windows
venv\Scripts\activate

# Linux/macOS
source venv/bin/activate

# Install root dependencies (adversarial attack pipeline)
pip install -r requirements.txt

# Install backend dependencies
pip install -r backend/requirements.txt

3. Install Frontend Dependencies

cd frontend
npm install
cd ..

🚀 How to Run

Web Application (Recommended)

Launch both backend and frontend with one click on Windows:

start.bat

Or start them manually:

Backend (terminal 1):

# Windows
venv\Scripts\activate
cd backend
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# Linux/macOS
source venv/bin/activate
cd backend
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

API docs available at: http://localhost:8000/docs

Frontend (terminal 2):

cd frontend
npm run dev

App available at: http://localhost:3000

Web App Modules

Module	Route	Function
Data Overview	/dashboard	Dashboard, statistics, recent activity
Adversarial Generation	/adversarial	Run adversarial attacks, view per-package results
Cluster Analysis	/cluster	Generate embeddings, cluster packages, visualize
Verification & Repair	/repair	Syntax check, LLM-based repair, semantic validation
Detector Management	/detector	View/manage ML and real-world detectors
Sample & Report Mgmt	/samples	Upload/download samples, manage reports

CLI Adversarial Attack (Standalone)

Run the attack engine directly without the web UI:

# Activate venv first
python main.py

This uses a Multi-Armed Bandit (UCB1) algorithm to iteratively apply obfuscation techniques against detectors. Edit main.py to configure:

• base_dir — path to malicious packages
• max_attempts — query budget per package

Standalone Scripts

Embedding & Clustering:

python embedding_cluster/embedding.py
python embedding_cluster/cluster.py

Functionality Verification & Repair:

cd functionality_verification_repair

# Syntax & compilation check
python validate_syntax_compilation.py

# LLM-based fix
python llm_for_fix_with_tokenv2.py

# Semantic validation
python validate_functionality.py

Adversarial Attack Methods

The engine supports 17 attack methods across 4 categories:

Category	Methods
Injection	insert_dead_code, insert_spaces, inject_benign_files, code_splitting
Obfuscation	variable_rename, string_splitting, base64_encoding, aes_encryption, homoglyph_substitution, binary_conversion, gzip_compression, pyc_compilation
Metadata	modify_metadata, version_rollback, dependency_shuffling
Anti-analysis	anti_debug, control_flow_flattening

---

⚠️ Ethical Guidelines

• Use this tool only on packages you own or have explicit permission to test
• Do not upload malicious packages to public repositories
• Follow responsible disclosure practices
• Respect all applicable laws and regulations

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📧 Contact

For questions or support, please open an issue on GitHub.

---

Disclaimer: This tool is intended for research and educational purposes only. The authors do not condone or support the use of this software for malicious purposes. Users are responsible for complying with all applicable laws and regulations. Misuse of this software may result in criminal charges.