Documentation
Everything you need to deploy, configure, and scale intelligence-driven malware analysis.
Installation
Local Development Setup
git clone https://github.com/forex911/Aegis.git
cd Aegis/backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000
Docker Compose
For a fully containerized development environment:
docker-compose up --build
This starts the Backend, Frontend, MongoDB, and Redis.
Configuration
Backend Environment (.env)
| Variable | Default | Description |
|---|
| MONGODB_URI | - | MongoDB connection string |
| REDIS_URI | - | Redis connection string |
| JWT_SECRET_KEY | - | Secret key for JWT token signing |
| SANDBOX_ENGINE | local_dev | Backend (local_dev, gvisor, firecracker) |
System Overview
AEGIS employs an event-driven architecture with isolated execution sandboxes and real-time telemetry extraction.
Component Flow
User -> API Gateway -> MongoDB / Redis -> Celery Worker Pool -> Air-Gapped Sandbox -> AI Threat Engine
Backend Structure
- app/api/: FastAPI routes (upload, analysis, websockets)
- app/services/: Core business logic (hash_analyzer, pe_analyzer, mitre_mapper, yara_service)
- app/analysis/: The Intelligence Layer
Intelligence Layer
Converts raw telemetry into actionable threat intelligence.
- capability_engine.py: Extracts attacker capabilities from static findings and runtime telemetry
- behavior_engine.py: Correlates capabilities into behavioral attack chains
- threat_classifier.py: Classifies payloads into malware families (e.g., Infostealer, Ransomware)
- risk_engine.py: Computes weighted risk score across 5 pillars
- report_generator.py: Compiles the structured AnalystReport using LLMs
Data Stores
- MongoDB: Stores job metadata, static results, full telemetry, MITRE mappings, and AI reports.
- Redis: PubSub bus for real-time WebSocket telemetry (`job_updates:{job_id}`) and caching layer.
- Neo4j: Graph database storing the attack representation (Files, Processes, NetworkConnections, IOCs).
Pipeline Workflow
The orchestrator manages the sandbox state machine: CREATED -> RUNNING -> COMPLETED.
Threat Intelligence Pipeline
Sandbox Worker -> Extractor (IPs, Hashes)
↓
Threat Intel Service (VirusTotal/AbuseIPDB) & YARA Scan
↓
Aggregate Final Report