zaidxahmed-cyber/Spectra

# SPECTRA A Windows desktop application for detecting fileless malware through live memory forensics and AI-driven analysis. SPECTRA combines Volatility3 with a two-agent LLM pipeline (Claude + GPT-4o) to capture, triage, and deliver verdicts on suspicious Windows processes in real time. Developed as a Final Year Project at FAST NUCES Islamabad. ## Table of Contents - [Project Overview](#project-overview) - [Live Demo Features](#live-demo-features) - [Tech Stack](#tech-stack) - [Folder Structure](#folder-structure) - [Detection Capabilities](#detection-capabilities) - [Prerequisites](#prerequisites) - [Installation](#installation) - [Getting API Keys](#getting-api-keys) - [Running the Project](#running-the-project) - [Building the Standalone Executable](#building-the-standalone-executable) - [Usage Guide](#usage-guide) - [Demo Malware Simulators](#demo-malware-simulators) - [Environment Variables](#environment-variables) - [Academic Context](#academic-context) - [License](#license) - [Acknowledgments](#acknowledgments) - [Team](#team) ## Project Overview SPECTRA demonstrates a production-quality forensic analysis pipeline for fileless malware detection: - Monitors all running Windows processes in real time using `psutil` and `WMI` - Captures full memory dumps of selected processes using `ProcDump64` - Runs a suite of custom Volatility3 plugins against each dump to extract forensic indicators - Streams plugin output to an AI DFIR agent (Claude Sonnet primary, GPT-4o fallback) for structured analysis - Maps detected behaviors to the MITRE ATT&CK framework - Produces a final verdict: `BENIGN`, `SUSPICIOUS`, or `FILELESS MALWARE CONFIRMED` - Renders everything in a frosted-glass React desktop UI delivered via pywebview Fileless malware represents the most evasive category of modern threats — it executes entirely in memory, leaves no files on disk, and bypasses signature-based antivirus. SPECTRA addresses this gap by automating the full forensic workflow from process capture to AI-driven verdict. ## Live Demo Features | Feature | Description | |---------|-------------| | Process Monitoring | Live table of every running process (PID, PPID, owner, path, CPU, memory) refreshed every 60 seconds | | Memory Dump Capture | Searchable typeahead — pick any process and capture a full memory dump with one click via ProcDump64 | | DFIR Agent | Streams a structured forensic report covering parent-child relationships, execution paths, registry persistence, code injection, process hollowing, and network activity | | Verdict Engine | Final judgment with confidence score, full IOC list, and MITRE ATT&CK technique mappings, saved as JSON | | MITRE ATT&CK Mapping | Automatic mapping to tactics and techniques (e.g. T1055 Process Injection, T1547 Boot Autostart, T1071 Application Layer Protocol) | | YARA Detection | Scans process memory for shellcode patterns, PE headers in unexpected regions, and known family signatures | | Glass UI | Apple-style frosted glass theme, built with React + Tailwind, delivered as a native-feeling desktop window | ## Tech Stack **Desktop Shell** - pywebview 4.x (Chromium WebView2) - PyInstaller 6 (single-exe bundle) **Backend** - Python 3.12 - Flask 3 + Flask-SocketIO - Volatility3 2.26 with custom plugins - ProcDump64, psutil, WMI - YARA 4.5, pefile, capstone **AI Agents** - Anthropic Claude (primary DFIR agent) - OpenAI GPT-4o (fallback) **Frontend** - React 18 + TypeScript 5 + Vite 5 - Tailwind CSS 3 + custom glass theme ## Folder Structure Spectra/ ├── client/ # React + TypeScript frontend │ ├── pages/ # Dashboard, Monitoring, Dumps, DFIR, Verdict │ ├── lib/ # Shared hooks and context (ScanContext, etc.) │ └── global.css # Glass theme variables │ ├── server/ # Flask backend │ ├── api_server.py # All REST and SSE endpoints │ ├── config.py # Paths, ports, env loading │ ├── spectra_engine.py # Core analysis orchestration │ ├── volatility_executor.py # Volatility3 subprocess wrapper │ ├── dfir_triage.py # DFIR Agent 1 prompt and streaming logic │ ├── mitre_detection.py # MITRE ATT&CK technique mapper │ ├── detection_utils.py # YARA and pattern matching helpers │ └── agents/ # LLM agent wrappers (Claude, GPT-4o) │ ├── custom plugins/ # Custom Volatility3 plugins │ └── spectra_live.py # parentchild, execpath, persistence, injection, hollowing, network │ ├── Malwares/ # Demo malware simulators (non-destructive) │ ├── FilelessSimulator_Poweliks.exe │ └── ProcessHollowingSimulator.exe │ ├── SpectraAnalysis/ # Runtime output (auto-created, gitignored) │ ├── Processes/ # Process snapshot JSONs │ ├── Dumps/ # Memory dump files (.dmp) │ ├── Results/ # Verdict JSONs │ └── MemoryImages/ # Full memory images │ ├── desktop_app.py # Entry point: starts Flask, opens pywebview ├── spectra.spec # PyInstaller spec ├── BUILD.bat # One-click build script ├── requirements.txt ├── package.json └── README.md ## Detection Capabilities SPECTRA's six custom Volatility3 plugins extract the following indicators from every memory dump: | Plugin Category | Detection Focus | |-----------------|-----------------| | Parent-Child Relationships | Anomalous spawn chains, masquerading processes | | Execution Path Analysis | Binaries running from suspicious locations (Temp, AppData, etc.) | | Registry Persistence | Run keys, IFEO Debuggers, COM CLSID hijacks | | Code Injection | RWX memory regions, foreign module loads | | Process Hollowing | PE headers in unexpected memory regions, mismatched section data | | Network Activity | Suspicious outbound beacons, unusual ports, C2-like patterns | ## Prerequisites - Windows 10 or 11 (64-bit) - Python 3.12 — https://python.org/downloads - Node.js 20 LTS — https://nodejs.org - Git — https://git-scm.com - ProcDump64 from Sysinternals — place `procdump64.exe` on your PATH or in the project root - Volatility3 — installed via pip (included in `requirements.txt`) - An Anthropic API key and/or an OpenAI API key ## Installation ### 1. Clone the repository git clone https://github.com/zaidxahmed-cyber/Spectra.git cd Spectra ### 2. Create a Python virtual environment python -m venv .venv .venv\Scripts\activate ### 3. Install Python dependencies pip install -r requirements.txt ### 4. Install Node dependencies npm install ### 5. Configure your API keys Create a `.env` file in the project root: OPENAI_API_KEY=your-openai-api-key-here ANTHROPIC_API_KEY=your-anthropic-api-key-here ## Getting API Keys ### Anthropic Claude (primary agent) 1. Go to https://console.anthropic.com/ 2. Sign in or create an account 3. Navigate to **Settings → API Keys** 4. Click **Create Key**, copy the value, and paste it into `.env` as `ANTHROPIC_API_KEY` ### OpenAI GPT-4o (fallback agent) 1. Go to https://platform.openai.com/api-keys 2. Sign in or create an account 3. Click **Create new secret key** 4. Copy the value and paste it into `.env` as `OPENAI_API_KEY` You only need one key to run SPECTRA, but having both enables automatic fallback if one provider is unavailable. ## Running the Project You need two terminals running simultaneously in development mode. ### Terminal 1 — Start the Backend python desktop_app.py You should see: INFO — Flask backend running on http://127.0.0.1:5001 INFO — pywebview window opened ### Terminal 2 — Frontend (optional, for hot reload) npm run dev The pywebview window opens automatically. For end users, the standalone `.exe` build below combines both into a single executable. ## Building the Standalone Executable SPECTRA ships as a single `.exe` that bundles the Python backend and compiled React frontend. From the project root: BUILD.bat The output is placed in `dist/spectra.exe`. Run it directly — no Python or Node installation required on the target machine. ## Usage Guide ### Step 1 — Start SPECTRA Launch `python desktop_app.py` in development, or run `dist/spectra.exe` for the standalone build. The main window opens with the Dashboard. ### Step 2 — Monitor processes Click **Monitoring** in the sidebar. SPECTRA lists all running processes. Look for suspicious entries: unusual names, unknown paths, or processes masquerading as system executables. ### Step 3 — Collect a memory dump Click **Dumps Collected** in the sidebar. Type the name or PID of your target in the search box, then click **Take Dump**. SPECTRA invokes ProcDump64, stores the `.dmp` file in `SpectraAnalysis/Dumps/`, and adds it to the dump list. ### Step 4 — Run DFIR analysis Click **DFIR Agent** in the sidebar. Select your dump from the panel, then click **Memory Capture**. SPECTRA streams the forensic report plugin by plugin. When all six plugins finish, the full report is displayed with case summary, observed facts, suspicious indicators, and per-plugin output. ### Step 5 — Get a verdict Click **Verdict Agent** in the sidebar. Select the same dump. SPECTRA sends the aggregated plugin output to the verdict AI and streams the final judgment, confidence score, IOC list, and MITRE ATT&CK mappings. The verdict is saved as JSON to `SpectraAnalysis/Results/`. ## Demo Malware Simulators The `Malwares/` folder contains two educational .NET simulators that reproduce real fileless malware behaviors safely. All registry modifications are removed automatically on exit, and no payload is executed. ### FilelessSimulator_Poweliks.exe Simulates Poweliks-style fileless persistence: - Allocates a 64 KB RWX memory region filled with shellcode-shaped bytes - Embeds YARA-triggering API name strings - Writes registry Run key and COM CLSID hijack persistence entries - Spawns `mshta.exe` as an anomalous child process ### ProcessHollowingSimulator.exe Simulates a process hollowing carrier masquerading as `svchost.exe`: - Allocates two RWX regions (one with a fake MZ/PE header) - Embeds hollowing-specific strings - Writes a Run key and IFEO Debugger backdoor - Beacons to `localhost:4444` on a 5-second loop ### End-to-end test 1. Run either simulator from the `Malwares/` folder 2. Open SPECTRA and go to **Monitoring** to find the process 3. Dump it from the **Dumps Collected** page 4. Run **DFIR Agent** and then **Verdict Agent** on the dump 5. SPECTRA detects RWX injection regions, registry persistence, anomalous parent-child relationships, and YARA matches, and returns a `FILELESS MALWARE CONFIRMED` verdict with full MITRE ATT&CK mapping ## Environment Variables | Variable | Required | Description | |----------|----------|-------------| | `ANTHROPIC_API_KEY` | Yes (if using Claude) | Anthropic API key for the primary DFIR agent | | `OPENAI_API_KEY` | Yes (if using GPT-4o) | OpenAI API key for the fallback LLM agent | | `API_PORT` | No (default: `5001`) | Port for the Flask backend | | `VOLATILITY_PATH` | No (default: `volatility3`) | Path to the Volatility3 executable | | `PROCDUMP_PATH` | No (default: `procdump64.exe`) | Path to ProcDump64 | ## Academic Context SPECTRA was developed as a Bachelor of Science Final Year Project at **FAST National University of Computer and Emerging Sciences (FAST NUCES), Islamabad**. The project addresses a real gap in endpoint security tooling: most open-source memory forensics tools require deep expertise and a manual workflow. SPECTRA automates the entire pipeline from process capture through AI-driven verdict, making advanced forensic analysis accessible to security analysts at any skill level. The approach is grounded in academic research on fileless malware detection, process injection techniques (T1055), and the application of large language models to structured forensic reasoning. The architecture is inspired by the Argus framework for automated memory forensics and extends it with a modern graphical interface, multi-LLM reasoning, MITRE ATT&CK mapping, and YARA-based pattern detection. ## License This project is released for academic and educational purposes. The demo malware simulators are non-destructive and self-cleaning. **Do not use any part of this project against systems you do not own or have explicit permission to test.** ## Acknowledgments - The Volatility Foundation for Volatility3 - Sysinternals (Microsoft) for ProcDump - MITRE ATT&CK for the threat intelligence framework - Anthropic and OpenAI for the LLM APIs - The FAST NUCES Islamabad faculty and supervisors who guided this project ## Team **Zaid Ahmed** — Email: zaidahmed78654@gmail.com **Moaaz Nadeem** — Email: muhammadmoaaz000@gmail.com **Institution:** FAST National University of Computer and Emerging Sciences, Islamabad **Program:** Bachelor of Science in Cyber Security **Batch:** 2022

标签：后端开发