MalwareGraph

UNDER CONSTRUCTION: MalwareGraph is under active development. Treat static analysis, decompilation, runtime-debug, IOC, TTP, and attribution output as experimental analyst-assistance data. Validate every finding before operational, legal, incident-response, or production use.

Safe, graph-native malware analysis for AdversaryGraph.

MalwareGraph is an isolated malware-analysis service that can run as an independent Docker Compose tool or as a fully integrated AdversaryGraph module. Its primary output is clickable, graph-ready intelligence: hashes, IPs, domains, URLs, file paths, registry keys, mutexes, strings, behaviors, ATT&CK technique candidates, detections, evidence, and similarity leads.

Current Status

This repository starts with a safe static-analysis MVP:

• password-protected ZIP and raw sample intake;
• archive safety checks before extraction;
• no sample execution;
• SHA-256/SHA-1/MD5 hashing;
• printable string extraction;
• IOC extraction for IPs, domains, URLs, emails, registry paths, and Windows paths;
• graph-ready analysis.json;
• FastAPI endpoints;
• persistent local job index;
• multi-file bundle graph generation;
• dynamic function graph endpoint for PE code functions, direct calls, imports, and runtime trace artifacts when available;
• Android APK fallback static analysis;
• unpacking detection for UPX, ASPack, VMProtect, Themida, MPRESS, and high-entropy samples;
• safe static UPX decompression with persisted unpacked-file re-analysis when the upx tool is available;
• opt-in dynamic-analysis workflow request with static decompilation artifacts and runtime-debug session orchestration;
• AIDebug-style step-debug session plans with dynamic execution disabled by default;
• LLM provider status using the same provider names and environment variables as AdversaryGraph;
• CLI analysis mode;
• Docker Compose deployment;
• AdversaryGraph integration contract.

Dynamic execution and memory-unpacking remain disabled in the default profile and must be implemented only through disposable VM or microVM sandbox profiles. The dynamic_analysis=true request records analyst intent, generates safe decompilation artifacts, and prepares blocked/ready runtime-debug steps based on the configured sandbox profile.

The /api/v1/analyses/{job_id}/unpack endpoint now performs deterministic UPX decompression (upx -d) without executing the sample, validates the output, and persists the unpacked file back into the analysis graph. ASPack, Themida, VMProtect, and unknown high-entropy layers are reported as manual-review unless an isolated emulator/unpacker profile is explicitly added.

Safety Baseline

MalwareGraph does not execute samples in the default profile.

Required operating rules:

• Do not mount the Docker socket.
• Do not mount host directories containing sensitive data.
• Keep analysis workers network-isolated by default.
• Treat every uploaded archive, extracted file, and artifact as hostile.
• Submit hashes and extracted IOCs to external sources by default, not binaries.
• Use a disposable sandbox boundary for any future dynamic analysis.

Quick Start

cp .env.example .env
docker compose up -d --build

Open:

• Standalone UI: http://localhost:8100/
• Malware Analysis: http://localhost:8100/malware-analysis
• String Analyzer: http://localhost:8100/string-analyzer
• API health: http://localhost:8100/api/health
• API docs: http://localhost:8100/docs

Analyze a password-protected ZIP:

curl -F "file=@sample.zip" \
  -F "password=infected" \
  http://localhost:8100/api/v1/analyses

Analyze a raw sample without wrapping it in a ZIP:

curl -F "file=@sample.exe" \
  http://localhost:8100/api/v1/analyses

For team deployments, set MALWAREGRAPH_API_KEY in .env and send X-API-Key on all /api/v1/* requests.

CLI mode:

python -m malwaregraph.cli analyze sample.zip --password infected --output reports
python -m malwaregraph.cli analyze sample.exe --output reports

AdversaryGraph Integration

MalwareGraph is designed to be embedded into AdversaryGraph as a native dashboard. The service returns stable graph entities and relationships so AdversaryGraph can render every extraction as clickable data:

• hashes -> IOC/hash detail and enrichment;
• IPs/domains/URLs -> IOC Intelligence;
• ATT&CK candidates -> Navigator and mapping review;
• behaviors -> evidence and artifact views;
• detections -> Detection Studio;
• family/actor leads -> Compare Groups and attribution review.

See docs/adversarygraph-integration.md.

UX/UI Parity

The standalone MalwareGraph UI and the AdversaryGraph Malware Analysis module share the same analyst workflow and visual structure:

• safe ZIP or raw-sample intake with the same dynamic-analysis disclaimer;
• first-analysis cards for type, magic bytes, entropy, packer, obfuscation, entropy graph, and PE headers;
• graphical function graph, decompilation, unpack planning, runtime-debug plan, and blocked runtime-debug session views;
• separate String Analyzer page with all-string, smart extraction, and AI analysis modes;
• clickable IOC/TTP routes matching the AdversaryGraph route contract.

Standalone MalwareGraph preserves AdversaryGraph route links as preview pages. Open the same links inside AdversaryGraph to resolve them against the platform graph, IOC library, investigations, Navigator, and enrichment views.

API

Method	Path	Purpose
GET	/api/health	Service health
POST	/api/v1/analyses	Upload ZIP or raw sample and run safe analysis; dynamic_analysis=true also requests decompilation/runtime-debug workflow artifacts
GET	/api/v1/analyses	List persisted analysis jobs
GET	/api/v1/analyses/{job_id}	Return analysis.json
GET	/api/v1/analyses/{job_id}/workflow-graph	Return dynamic function graph nodes and edges; endpoint name is kept for compatibility
POST	/api/v1/analyses/{job_id}/debug-sessions	Create a safe step-debug plan for a sample
POST	/api/v1/analyses/{job_id}/decompilation	Generate a safe static decompilation artifact for a sample
POST	/api/v1/analyses/{job_id}/unpack	Attempt safe static UPX unpacking, validate output, and persist unpacked-file analysis
GET	/api/llm/providers	Show Claude/OpenAI/Gemini/local provider configuration status
POST	/api/v1/maintenance/purge-retention	Remove jobs/artifacts older than retention policy

Production Profile

The current production-supported profile is safe static analysis plus opt-in decompilation/runtime-debug workflow preparation. Malware execution and detonation remain blocked until a disposable VM/microVM sandbox is implemented and reviewed.

See docs/production-runbook.md.

Project Layout

malwaregraph/
  api/              FastAPI routes
  core/             Settings, safety limits, models
  services/         Archive, static, IOC, graph result builders
  schemas/          JSON schema for AdversaryGraph result import
  workers/          Worker orchestration
docs/               Architecture and integration docs
tests/              Inert static-analysis tests
ui/                 Standalone React UI mirroring AdversaryGraph UX

License

Personal use only unless a separate license is granted.