# shivansh4123/malware-slayer architecture

> Architecture diagram of the GitHub repository shivansh4123/malware-slayer, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shivansh4123/malware-slayer
- Repository: https://github.com/shivansh4123/malware-slayer

## Overview

##### Project Type and Purpose
- **Type**: Full-stack web application (monolithic service)
- **Purpose**: Static malware detection via file uploads, using YARA rules and PE analysis, with a responsive web UI for user interaction.

##### File Structure
- **app.py**
- Acts as the Flask web server, routing requests, orchestrating file storage, analysis, and response.
- **uploads/**
- Persistent storage for incoming user files (e.g., EXE, DOCX, PDF).
- **Rule directories** (all containing YARA rule files):
- **/malware/** – rules for executables & COM files
- **/maldocs/** – rules for document malware
- **/exploit_kits/** – rules for PDF exploit kits
- **/crypto/** – crypto-related signatures
- **/packers/** – packer/obfuscator signatures
- **Dependencies**: Flask (web framework), yara-python (rule engine), pefile (PE analysis).

##### README for Additional Insights
- Confirms drag-and-drop, multi-file upload UI (HTML5/JS/CSS).
- Custom verdicts based on static rule matches and entropy/section anomalies.
- Runs locally on port 5001.

##### Main Components
a. **Frontend (Browser/UI Layer)**
- HTML5 drag & drop area
- JavaScript uploads files via AJAX/HTTP POST
- Displays results (clean vs. malicious) in real time.
b. **Web Server (Flask Application)**
- HTTP routing: upload endpoint, results endpoint
- Stores files under /uploads
- Invokes analysis modules
c. **Storage**
- Local filesystem directory `/uploads/`
- Temp vs. long-term storage.
d. **Analysis Engine**
- **YARA Engine**: loads all rules from the five rule directories
- **PE Analysis Module**: uses pefile to compute entropy, check sections
- Decision logic: merges YARA hits + PE anomalies → verdict
e. **Rule Repository**
- The five rule directories serve as a “plugin” store of signatures.
f. **External Libraries/Services**
- yara-python library
- pefile library
- (In future: could integrate antivirus services, databases, or message queues.)

##### Relationships & Data Flows
- User drags file → Frontend
- Frontend sends HTTP POST → Flask upload endpoint
- Flask writes file → `/uploads/`
- Flask calls → YARA Engine & PE Analyzer
- Engines read file + rule files → return findings
- Flask applies verdict logic → sends JSON response
- Frontend updates UI with results

##### Architectural Patterns & Principles
- **Monolithic service**: single Flask process handling both API and analysis
- **Separation of concerns**: UI vs. HTTP/API vs. analysis logic vs. storage
- **Plugin-style rule loading**: dropping a rule file → immediate inclusion
- **Synchronous scanning**: simple request/response (could evolve to async tasks)

##### Technologies & Frameworks
- **Flask** for routing & templating
- **yara-python** for signature matching
- **pefile** for Windows PE analysis
- **HTML5/JS/CSS** for drag-and-drop UI
- **Python** standard libraries for filesystem I/O

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    Browser["User Browser\nDrag & Drop UI"]:::frontend
    Browser -->|POST /upload| FlaskUpload["Flask Upload Endpoint"]:::backend
    click Browser "https://github.com/shivansh4123/malware-slayer/blob/main/app.py"
    click FlaskUpload "https://github.com/shivansh4123/malware-slayer/blob/main/app.py"

    %% Storage Layer
    Uploads["/uploads/\n(File Storage)"]:::storage
    FlaskUpload -->|Write File| Uploads
    click Uploads "https://github.com/shivansh4123/malware-slayer/tree/main/uploads/"

    %% Analysis Subsystem
    subgraph "Analysis Engine"
        direction TB
        subgraph "YARA Engine"
            direction TB
            MalwareRules["malware/"]:::rules
            MaldocsRules["maldocs/"]:::rules
            ExploitKitsRules["exploit_kits/"]:::rules
            CryptoRules["crypto/"]:::rules
            PackersRules["packers/"]:::rules
        end
        PEAnalyzer["PE Analysis Module"]:::analysis
        VerdictLogic["Verdict Logic"]:::analysis
    end

    %% Analysis Flows
    FlaskUpload -->|Invoke YARA Scan| MalwareRules
    FlaskUpload -->|Invoke YARA Scan| MaldocsRules
    FlaskUpload -->|Invoke YARA Scan| ExploitKitsRules
    FlaskUpload -->|Invoke YARA Scan| CryptoRules
    FlaskUpload -->|Invoke YARA Scan| PackersRules
    FlaskUpload -->|Invoke PE Analysis| PEAnalyzer
    click MalwareRules "https://github.com/shivansh4123/malware-slayer/tree/main/malware/"
    click MaldocsRules "https://github.com/shivansh4123/malware-slayer/tree/main/maldocs/"
    click ExploitKitsRules "https://github.com/shivansh4123/malware-slayer/tree/main/exploit_kits/"
    click CryptoRules "https://github.com/shivansh4123/malware-slayer/tree/main/crypto/"
    click PackersRules "https://github.com/shivansh4123/malware-slayer/tree/main/packers/"
    click PEAnalyzer "https://github.com/shivansh4123/malware-slayer/blob/main/app.py"

    %% Verdict and Response
    MalwareRules -->|Rules Results| VerdictLogic
    MaldocsRules -->|Rules Results| VerdictLogic
    ExploitKitsRules -->|Rules Results| VerdictLogic
    CryptoRules -->|Rules Results| VerdictLogic
    PackersRules -->|Rules Results| VerdictLogic
    PEAnalyzer -->|Analysis Results| VerdictLogic
    VerdictLogic -->|JSON Response| Browser

    %% Styles
    classDef frontend fill:#D0E6FF,stroke:#0366d6,color:#000
    classDef backend fill:#D0FFD6,stroke:#028a0f,color:#000
    classDef analysis fill:#FFE3B3,stroke:#d97706,color:#000
    classDef storage fill:#E0E0E0,stroke:#555,color:#000
    classDef rules fill:#FFF0D0,stroke:#aa5500,color:#000
```
