🔬 API Overview

MalwareForge is a powerful malware analysis API that performs static analysis on suspicious files and hashes. Get instant threat intelligence including risk scoring, file type detection, entropy analysis, and malicious pattern identification.

✨ Key Features

File Analysis - Upload files (base64 encoded) for comprehensive static analysis
Hash Lookup - Query existing analyses by SHA256 hash
Risk Scoring - 0-100 risk score with severity levels (none, low, medium, high, critical)
Pattern Detection - Identifies suspicious strings, packers, macros, and malicious indicators
Entropy Analysis - Detects packed/encrypted content
Smart Caching - Previously analyzed files return instant results

💎 Subscription Tiers

Plan	Monthly Analyses	Max File Size	Data Retention	Best For
Free	20	5 MB	7 days	Testing & Evaluation
Starter	2,000	20 MB	30 days	Individual Researchers
Pro	10,000	50 MB	90 days	Security Teams
Business	50,000	100 MB	180 days	Enterprise Security
Enterprise	250,000	250 MB	365 days	Large Organizations

📡 Endpoints

1. Health Check

GET /health

Check API availability and status. No authentication required.

Example Response:

{
  "status": "healthy",
  "timestamp": "2026-02-03T20:00:00.000Z",
  "version": "1.0.0"
}

2. Analyze File

POST /analyze-file

Upload a file for comprehensive static malware analysis.

Request Body:

Field	Type	Required	Description
filename	string	Yes	Name of the file being analyzed
fileData	string	Yes	Base64-encoded file content

Example Request - Simple Text File (Low Risk):

{
  "filename": "readme.txt",
  "fileData": "SGVsbG8gV29ybGQhIFRoaXMgaXMgYSB0ZXN0IGZpbGUu"
}

Decodes to: "Hello World! This is a test file."

Example Request - Suspicious Script (Medium Risk):

{
  "filename": "script.bat",
  "fileData": "QGVjaG8gb2ZmDQpjbWQuZXhlIC9jIHBvd2Vyc2hlbGwgLUV4ZWN1dGlvblBvbGljeSBCeXBhc3MNCmV4aXQ="
}

Decodes to: "@echo off\r\ncmd.exe /c powershell -ExecutionPolicy Bypass\r\nexit"

Example Request - PE Executable Header (High Risk):

{
  "filename": "sample.exe",
  "fileData": "TVqQAAMAAAAEAAAA//8AALgAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgAAAAA4fug4AtAnNIbgBTM0hVGhpcyBwcm9ncmFtIGNhbm5vdCBiZSBydW4gaW4gRE9TIG1vZGUuDQ0KJA=="
}

Valid PE/MZ header - will be detected as "PE executable"

Example Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "filename": "sample.exe",
  "sha256": "a1b2c3d4e5f6...",
  "md5": "d41d8cd98f00b204...",
  "fileType": "PE executable",
  "fileSize": 1024,
  "riskScore": 45,
  "riskLevel": "medium",
  "summary": "PE executable file analyzed. Some suspicious indicators found.",
  "staticReport": {
    "entropy": 5.2,
    "strings": ["cmd.exe", "powershell", "..."],
    "indicators": [
      {"name": "Command Execution", "weight": 10, "detected": true}
    ],
    "hasMacros": false,
    "packers": []
  }
}

3. Lookup Hash

GET /analyze-hash?sha256={hash}

Check if a file has been previously analyzed by its SHA256 hash.

Query Parameters:

Parameter	Type	Required	Description
sha256	string	Yes	SHA256 hash of the file (64 hex characters)

Example Request:

GET /analyze-hash?sha256=e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Example Response (Found):

{
  "found": true,
  "analysis": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "completed",
    "filename": "sample.exe",
    "riskScore": 45,
    "riskLevel": "medium",
    "summary": "PE executable file analyzed..."
  }
}

Example Response (Not Found):

{
  "found": false,
  "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "message": "No analysis found for this hash"
}

4. Get Analysis

GET /analysis/{id}

Retrieve a specific analysis by its unique ID.

Path Parameters:

Parameter	Type	Required	Description
id	string	Yes	Analysis UUID returned from analyze-file

Example Request:

GET /analysis/550e8400-e29b-41d4-a716-446655440000

Example Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "filename": "sample.exe",
  "sha256": "a1b2c3d4e5f6...",
  "md5": "d41d8cd98f00b204...",
  "fileType": "PE executable",
  "fileSize": 1024,
  "riskScore": 45,
  "riskLevel": "medium",
  "summary": "PE executable file analyzed. Some suspicious indicators found.",
  "createdAt": "2026-02-03T20:00:00.000Z",
  "expiresAt": "2026-02-10T20:00:00.000Z"
}

5. Get Full Report

GET /analysis/{id}/report

Retrieve the complete static analysis report including all detected indicators, extracted strings, and detailed findings.

Example Request:

GET /analysis/550e8400-e29b-41d4-a716-446655440000/report

Example Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "filename": "sample.exe",
  "sha256": "a1b2c3d4e5f6...",
  "riskScore": 45,
  "riskLevel": "medium",
  "staticReport": {
    "entropy": 5.2,
    "fileType": "PE executable",
    "hasMacros": false,
    "packers": [],
    "strings": [
      "cmd.exe",
      "powershell",
      "CreateRemoteThread",
      "VirtualAlloc"
    ],
    "indicators": [
      {"name": "Command Execution", "weight": 10, "detected": true, "evidence": "cmd.exe"},
      {"name": "Memory Manipulation", "weight": 15, "detected": true, "evidence": "VirtualAlloc"},
      {"name": "Process Injection", "weight": 20, "detected": true, "evidence": "CreateRemoteThread"}
    ]
  }
}

6. Delete Analysis

DELETE /analysis/{id}/delete

Permanently delete an analysis and its associated data.

Example Request:

DELETE /analysis/550e8400-e29b-41d4-a716-446655440000/delete

Example Response:

{
  "success": true,
  "message": "Analysis deleted successfully",
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

🎯 Risk Levels Explained

Level	Score Range	Description
🟢 None	0	No suspicious indicators detected
🟡 Low	1-25	Minor suspicious patterns, likely benign
🟠 Medium	26-50	Notable suspicious indicators present
🔴 High	51-75	Multiple malicious indicators detected
⚫ Critical	76-100	Strong evidence of malicious intent

🔍 Detection Capabilities

File Types Detected:

PE Executables (.exe, .dll)
Office Documents (.docx, .xlsx, .pptx)
PDF Documents
Archives (.zip, .rar, .gzip)
ELF Binaries (Linux)
Images (PNG, JPEG, GIF)

Threat Indicators:

Suspicious URLs and download links
PowerShell encoded commands
Command execution patterns
Registry modifications
Memory manipulation (VirtualAlloc, VirtualProtect)
Process injection techniques
Anti-debugging checks
Credential harvesting keywords
VBA macros in Office documents
Packer detection (UPX, ASPack, Themida, VMProtect)

📊 Rate Limit Headers

All responses include rate limit information:

X-RateLimit-Requests-Limit - Your monthly limit
X-RateLimit-Requests-Remaining - Remaining requests this month
X-RateLimit-Requests-Reset - Seconds until limit resets

🚀 Quick Start

Subscribe to a plan that fits your needs
Test connectivity with GET /health
Analyze your first file with POST /analyze-file
Retrieve results anytime with GET /analysis/{id}

⚠️ Error Codes

Code	Description
400	Bad Request - Missing or invalid parameters
404	Not Found - Analysis ID or hash not found
413	Payload Too Large - File exceeds plan size limit
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error - Please retry or contact support

📧 Support

For technical support or enterprise inquiries: malwareforge@protonmail.com