HeaderHawk 🦅

An advanced email security analysis MCP (Model Context Protocol) server that provides real-time phishing detection, threat intelligence integration, and comprehensive email header analysis.

Overview

HeaderHawk is a specialized MCP server designed to help security analysts, cybersecurity professionals, and organizations detect and analyze phishing attempts, malicious emails, and security threats through deep email header analysis and threat intelligence integration.

Key Features:

• 📧 Comprehensive email header parsing and analysis
• 🎯 Phishing indicator detection with confidence scoring
• 🔍 Indicators of Compromise (IoCs) extraction
• 🛡️ VirusTotal threat intelligence integration
• 🔐 DKIM/SPF/DMARC authentication validation
• 🌐 Domain reputation analysis
• ⚡ Real-time threat assessment
• 🦠 Malware detection and payload analysis
• 📊 Business Email Compromise (BEC) pattern detection
• 🔬 Social engineering tactic identification

<img width="772" height="993" alt="image" src="https://github.com/user-attachments/assets/a51373b7-4f6e-46dd-b919-33d1dce93c2d" />

Installation

Prerequisites

• Python 3.8+
• pip (Python package manager)
• VirusTotal API key (for threat scanning features)

From PyPI (Recommended)

pip install headerhawk

From Source

git clone https://github.com/nervpeng/headerhawk.git
cd headerhawk
pip install -e .

Quick Start

Basic Usage with Claude Desktop

1. Install HeaderHawk:

   pip install headerhawk
   

2. Configure Claude Desktop (claude_desktop_config.json):

   {
     "mcpServers": {
       "headerhawk": {
         "command": "headerhawk-mcp",
         "env": {
           "VIRUSTOTAL_API_KEY": "your_virustotal_api_key_here"
         }
       }
     }
   }
   

3. Restart Claude Desktop and start analyzing emails!

Command Line Usage

# Analyze an email for phishing indicators
headerhawk analyze /path/to/email.eml

# Extract IoCs from an email
headerhawk extract-iocs /path/to/email.eml

# Scan extracted indicators with VirusTotal
headerhawk scan-virustotal /path/to/email.eml

Available Functions

1. analyze_email(file_path: str)

Performs comprehensive phishing analysis on an email file.

Input:

• file_path: Path to .eml file

Returns:

• Email header metadata (From, To, Date, Message-ID)
• Authentication results (DKIM, SPF, DMARC status)
• Phishing indicators with confidence scores
• Risk assessment summary
• Detailed analysis recommendations
• Malware/payload detection results

Example:

from headerhawk import analyze_email

result = analyze_email("suspicious_email.eml")
print(f"Risk Level: {result['risk_level']}")
print(f"Indicators Found: {result['phishing_indicators']}")
print(f"Malware Detected: {result.get('malware_indicators', [])}")

Real-World Example Output:

Risk Level: CRITICAL
Verdict: MALICIOUS - Business Email Compromise with Malware

Phishing Indicators Found:
1. Spoofed Domain Authority (morecft.shop) - CRITICAL
2. Generic Business Greeting ("Good day") - HIGH
3. Urgency Pattern (RFQ Request) - MEDIUM
4. Suspicious Attachment Format (.7z archive) - CRITICAL
5. Base64-Encoded Payload - CRITICAL

Authentication:
- DKIM: PASS (but domain is malicious)
- SPF: PASS (but sender is spoofed)
- DMARC: PASS (policy bypass)

Malware Indicators:
- .7z compressed archive containing VBS script
- File: Invoice.vbs
- Payload: Base64-encoded executable
- Likely Attack: Ransomware/Trojan deployment

Recommended Action: QUARANTINE & DELETE

2. extract_iocs(file_path: str)

Extracts Indicators of Compromise from email content and headers.

Input:

• file_path: Path to .eml file

Returns:

• URLs found in email
• IP addresses detected
• Domains referenced
• Email addresses extracted
• File hashes (if present)
• Attachment metadata
• Classification by type and risk level

Example:

from headerhawk import extract_iocs

iocs = extract_iocs("email.eml")
print(f"URLs: {iocs['urls']}")
print(f"Domains: {iocs['domains']}")
print(f"IPs: {iocs['ips']}")
print(f"Attachments: {iocs.get('attachments', [])}")

Real-World Example Output:

{
  "domains": ["[redacted].shop"],
  "ips": ["[redacted]"],
  "emails": ["postmaster@[redacted].shop", "Mr. Andy <postmaster@[redacted].shop>"],
  "attachments": [
    {
      "filename": "Request for Quotation (RFQ) - 3949483.7z",
      "type": ".7z",
      "risk": "CRITICAL",
      "encoding": "base64",
      "size_kb": "~100"
    }
  ],
  "mail_server": "[redacted].[redacted].shop",
  "sender_ip": "[redacted]"
}

3. scan_with_virustotal(file_path: str)

Scans extracted IoCs against VirusTotal threat intelligence database.

Input:

• file_path: Path to .eml file
• Environment variable: VIRUSTOTAL_API_KEY

Returns:

• VirusTotal scan results for each IoC
• Detection ratios (e.g., "5/72")
• Last analysis dates
• Verdict summary
• Detailed threat classifications
• Campaign correlation (if available)

Example:

from headerhawk import scan_with_virustotal

results = scan_with_virustotal("email.eml")
for ioc, verdict in results.items():
    print(f"{ioc}: {verdict['detection_ratio']}")
    print(f"  Verdict: {verdict['verdict']}")
    print(f"  Categories: {verdict.get('categories', [])}")

Phishing Indicators Detected

HeaderHawk analyzes emails for 25+ phishing and malware indicators including:

• Authentication Failures

  • DKIM signature failures
  • SPF policy misalignment
  • DMARC failures
  • Missing authentication headers
  • Deprecated signing algorithms (RSA-SHA1)
  • Authentication bypass attempts

• Header Anomalies

  • Spoofed sender domains
  • Mismatched Reply-To addresses
  • Suspicious X-headers
  • Mail forwarding inconsistencies
  • X-Recommended-Action flags
  • Spoofed corporate identity headers

• Content Analysis

  • Urgency language patterns
  • Authority impersonation attempts
  • Suspicious URL patterns
  • Known phishing keywords
  • Business Email Compromise (BEC) patterns
  • Social engineering tactics
  • Generic greetings ("Good day", "Dear Sir/Madam")
  • Fake business requests

• Infrastructure Indicators

  • Suspicious mail servers
  • Blacklisted IP addresses
  • Generic/free email providers for business
  • Impossible travel patterns
  • Bulletproof hosting providers
  • Newly registered malicious domains
  • Domain registration age analysis

• Technical Indicators

  • Return-Path misalignment
  • Multiple forwarding hops
  • Encoding anomalies
  • Obfuscated content
  • Suspicious attachment formats (.7z, .scr, .vbs, .exe)
  • Base64-encoded executable payloads
  • Archive bombs or compressed payloads

• Malware Detection

  • Archive files (.7z, .rar, .zip) containing executables
  • Visual Basic Script (.vbs) payloads
  • Executable masquerading as documents
  • Ransomware/trojan attack chains
  • Known malware signatures
  • Payload obfuscation techniques

Real-World Usage Examples

Example 1: Legitimate Marketing Email

✅ Risk Level: LOW
Verdict: LEGITIMATE

Indicators:
- Valid DKIM/SPF/DMARC: ✓
- Known sender domain: [redacted].com
- Legitimate business (Music Festival)
- Clear unsubscribe mechanism
- Standard Mailchimp template
- No suspicious attachments

Example 2: Malicious RFQ Phishing Email

🚨 Risk Level: CRITICAL
Verdict: MALICIOUS - BEC with Malware

Indicators:
- Spoofed domain: [redacted].shop (newly registered)
- Generic greeting: "Good day"
- Business request (RFQ) for credibility
- Urgent tone: "awaiting your esteemed offer"
- .7z attachment with VBS payload
- Base64-encoded malware
- Bulletproof hosting IP: [redacted]
- Deprecated DKIM algorithm (RSA-SHA1)

Recommended Action: QUARANTINE & DELETE

MCP Integration

With Claude (claude.ai or Claude Desktop)

User: "Analyze this suspicious email for me"
Claude: Uses HeaderHawk to extract IoCs and phishing indicators
Claude: "I found X phishing indicators including: [list]"
Claude: "Risk Level: [CRITICAL/HIGH/MEDIUM/LOW]"
Claude: "Recommended Action: [QUARANTINE/DELETE/REVIEW/SAFE]"

Available MCP Tools

When used with Claude or other MCP-compatible clients:

1. say_hello - Test connection status
2. analyze_email - Full phishing analysis with malware detection
3. extract_iocs - Extract indicators of compromise
4. scan_with_virustotal - Threat intelligence lookup

Configuration

Environment Variables

# VirusTotal API Key (required for threat scanning)
export VIRUSTOTAL_API_KEY="your_api_key_here"

# Optional: API rate limiting
export VIRUSTOTAL_RATE_LIMIT="4"  # requests per minute

# Optional: Output format
export OUTPUT_FORMAT="json"  # or "text" (default)

# Optional: Threat level thresholds
export CRITICAL_THRESHOLD="0.8"
export HIGH_THRESHOLD="0.6"

Configuration File

Create ~/.headerhawk/config.json:

{
  "virustotal": {
    "api_key": "your_api_key",
    "rate_limit": 4,
    "timeout": 30
  },
  "analysis": {
    "check_authentication": true,
    "extract_urls": true,
    "check_phishing_keywords": true,
    "detect_malware": true,
    "check_attachment_types": true
  },
  "threat_levels": {
    "critical_threshold": 0.8,
    "high_threshold": 0.6,
    "medium_threshold": 0.4
  }
}

Output Format

Email Analysis Output

{
  "email_metadata": {
    "from": "sender@example.com",
    "to": ["recipient@company.com"],
    "date": "2026-01-08T13:30:49Z",
    "subject": "[Important] Invoice (Due: TODAY at 10pm ET)"
  },
  "authentication": {
    "dkim": "PASS",
    "spf": "PASS",
    "dmarc": "PASS",
    "dkim_algorithm": "rsa-sha256"
  },
  "phishing_indicators": [
    {
      "indicator": "valid_dkim",
      "severity": "low",
      "description": "DKIM signature verified successfully",
      "confidence": 0.95
    }
  ],
  "malware_indicators": [
    {
      "type": "suspicious_attachment",
      "description": ".7z archive with VBS payload",
      "severity": "critical",
      "filename": "Document_Invoice.7z",
      "payload_type": "VBS script"
    }
  ],
  "risk_level": "CRITICAL",
  "verdict": "MALICIOUS"
}

IoCs Extraction Output

{
  "urls": [
    "https://www.[target1].com/...",
    "https://www.[target2].net/..."
  ],
  "domains": [
    "[target1].com",
    "[target2].com"
  ],
  "ips": [
    "[redacted]"
  ],
  "emails": [
    "info@[target1].com"
  ],
  "attachments": [
    {
      "filename": "document.7z",
      "type": "archive",
      "risk_level": "high",
      "encoding": "base64"
    }
  ]
}

Use Cases

1. Security Analysts

Quickly triage and analyze suspicious emails in bulk with confidence scoring and automated threat intelligence lookup. Identify malware campaigns and BEC attempts in seconds.

2. IT Security Teams

Integrate HeaderHawk into security information and event management (SIEM) systems for automated email threat detection and alerting.

3. Cybersecurity Researchers

Extract and analyze phishing campaigns with comprehensive IoC extraction, malware payload detection, and threat intelligence correlation.

4. Email Gateway Administrators

Deploy HeaderHawk as part of email gateway solutions for real-time phishing detection, malware scanning, and automated quarantine.

5. Incident Response Teams

Rapidly analyze emails during security incidents with detailed forensic information, malware analysis, and threat assessment for faster response.

6. Managed Security Service Providers (MSSPs)

Offer HeaderHawk as part of email security services for clients, with automated reports and threat summaries.

Deployment Strategies

PyPI Package Distribution

# Package and upload to PyPI
python -m pip install --upgrade build twine
python -m build
twine upload dist/*

MCP Registry Submission

HeaderHawk is available for submission to the official MCP Registry at mcp-registry.anthropic.com.

To register:

1. Format project following MCP standards
2. Submit to registry with documentation
3. Enable discovery for Claude users globally

Docker Deployment

FROM python:3.11-slim
RUN pip install headerhawk
ENV VIRUSTOTAL_API_KEY=your_key
CMD ["headerhawk-mcp"]

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: headerhawk-mcp
spec:
  replicas: 3
  template:
    spec:
      containers:
      - name: headerhawk
        image: headerhawk:latest
        env:
        - name: VIRUSTOTAL_API_KEY
          valueFrom:
            secretKeyRef:
              name: headerhawk-secrets
              key: api-key

API Reference

analyze_email()

def analyze_email(file_path: str) -> Dict[str, Any]:
    """
    Analyze email for phishing indicators and malware.
    
    Args:
        file_path: Path to .eml file
        
    Returns:
        Dictionary with analysis results including:
        - email_metadata
        - authentication (DKIM/SPF/DMARC)
        - phishing_indicators
        - malware_indicators
        - risk_level
        - verdict
    """

extract_iocs()

def extract_iocs(file_path: str) -> Dict[str, List[str]]:
    """
    Extract Indicators of Compromise from email.
    
    Args:
        file_path: Path to .eml file
        
    Returns:
        Dictionary containing:
        - urls: List of URLs
        - domains: List of domains
        - ips: List of IP addresses
        - emails: List of email addresses
        - attachments: List of attachment metadata
        - hashes: List of file hashes
    """

scan_with_virustotal()

def scan_with_virustotal(file_path: str) -> Dict[str, Dict[str, Any]]:
    """
    Scan IoCs against VirusTotal threat intelligence.
    
    Args:
        file_path: Path to .eml file
        
    Returns:
        Dictionary with VirusTotal results for each IoC:
        - detection_ratio: e.g., "5/72"
        - last_analysis_date
        - verdict
        - categories
        - malware_type
    """

Performance Characteristics

Operation	Typical Time	Notes
Email Analysis	50-200ms	Local processing only
IoCs Extraction	30-100ms	Includes regex parsing + attachment analysis
VirusTotal Scan	1-5s per IoC	Depends on API rate limits
Malware Detection	100-300ms	Payload analysis and pattern matching
Full Pipeline	2-10s	Complete analysis with threats + VT lookup

Limitations & Considerations

• File Size: Works best with emails < 50MB
• Encoding: Handles UTF-8, ASCII, and common encodings
• VirusTotal API: Requires API key for threat scanning (free tier: 4 requests/minute)
• False Positives: Machine learning-based detection may have edge cases
• Zero-Days: Cannot detect previously unknown threat patterns
• Language: Phishing keyword detection optimized for English
• Payload Analysis: Limited to email-embedded payloads; does not execute malware

Troubleshooting

VirusTotal API Issues

Error: "API key invalid or rate limit exceeded"
Solution: Check VIRUSTOTAL_API_KEY environment variable and request limits

File Not Found

Error: "File not found at path"
Solution: Ensure .eml file exists and path is absolute or relative from current directory

Encoding Issues

Error: "Unable to parse email"
Solution: Verify file is valid .eml format (SMTP mail with CRLF line terminators)

Malware Detection Not Working

Error: "Payload analysis incomplete"
Solution: Ensure email includes attachments and they are properly encoded (base64/quoted-printable)

Contributing

Contributions are welcome! Areas for improvement:

• Additional phishing detection heuristics
• Support for more email formats (.msg, .pst)
• Enhanced machine learning models
• Additional threat intelligence integrations
• Payload detonation sandbox integration
• Performance optimizations
• Multi-language support

Development

Setup Development Environment

git clone https://github.com/nervpeng/headerhawk.git
cd headerhawk
pip install -e ".[dev]"
pytest  # Run tests

Running Tests

pytest tests/ -v
pytest tests/ --cov=headerhawk  # With coverage
pytest tests/test_malware_detection.py -v  # Malware detection tests

Security Considerations

• API Keys: Never commit API keys to version control
• Email Data: Use in compliance with your organization's data retention policies
• Rate Limiting: Respect VirusTotal API rate limits to avoid blocking
• Threat Intelligence: VirusTotal results reflect community detections, not absolute truth
• Payload Safety: Extracted payloads are not executed; analysis is performed on file metadata
• Data Privacy: Emails are analyzed locally unless using VirusTotal scanning

License

MIT License - See LICENSE file for details

Support & Community

• GitHub Issues: Report bugs and request features
• MCP Specification: Model Context Protocol Documentation
• VirusTotal API: VirusTotal Developers

Acknowledgments

• Built on the Model Context Protocol (MCP) specification
• Threat intelligence powered by VirusTotal
• Email parsing utilizing industry-standard libraries
• Inspired by security research in phishing detection and malware analysis

Changelog

v0.0.1 (Initial)

• Core email analysis functionality
• IoC extraction
• VirusTotal integration
• MCP server implementation

Roadmap

• v0.1.0: Spam/Ham scoring and detection logic improvements
• v0.2.0: Sandbox payload detonation integration
• v0.3.0: Additional threat intelligence integrations (AlienVault OTX, URLhaus)
• v0.4.0: Multi-language phishing keyword support
• v1.0.0: Production-ready with comprehensive documentation

---

Made with 🦅 for cybersecurity professionals

For questions or support, reach out through GitHub Issues or community channels.