PhishGuard

Command-line phishing email analysis for .eml files, with IOC extraction, authentication checks, URL inspection, risk scoring, YARA scanning, and STIX 2.1 export.

Overview

PhishGuard parses an RFC 5322 email and combines evidence from its headers, bodies, URLs, and attachments into an analyst-oriented terminal report. It can also extract indicators of compromise (IOCs), inspect a domain's SPF, DMARC, and commonly used DKIM selectors, and export analysis results as a STIX 2.1 bundle.

The project is intended for local security analysis and incident-response workflows. It does not replace a mail gateway, sandbox, or manual analyst review.

Features

• Parses message headers, plain-text and HTML bodies, attachments, and Received hops.
• Computes MD5, SHA-1, and SHA-256 hashes for attachments.
• Detects Reply-To, Return-Path, and display-name anomalies.
• Queries DNS for SPF, DMARC, and common DKIM selectors and parses Authentication-Results headers.
• Extracts and deduplicates IPv4, IPv6, domain, email, URL, and file-hash IOCs.
• Defangs URLs, domains, IP addresses, and email addresses for safer sharing.
• Flags URL shorteners, suspicious TLDs, IP-based URLs, homoglyphs, @ redirect tricks, non-standard ports, and long redirect chains.
• Scores authentication, URL, social-engineering, attachment, header, and IOC-density signals from Clean through Critical.
• Scans attachments with seven built-in YARA rules when the optional yara-python dependency is installed.
• Exports STIX 2.1 bundles containing indicators, relationships, identity, threat-actor, and report objects.
• Provides standalone Python clients for VirusTotal URL, hash, and domain lookups and AbuseIPDB IP lookups.

Architecture

                         +----------------+
                         |   .eml parser  |
                         +-------+--------+
                                 |
             +-------------------+-------------------+
             |                   |                   |
             v                   v                   v
      +-------------+     +-------------+     +-------------+
      | Auth checks |     | IOC + URL   |     | Attachments |
      | through DNS |     | analysis    |     | + YARA      |
      +------+------+     +------+------+     +------+------+
             |                   |                   |
             +-------------------+-------------------+
                                 |
                                 v
                    +--------------------------+
                    | Risk score + CLI report  |
                    +-------------+------------+
                                  |
                         optional STIX export
                                  |
                                  v
                    +--------------------------+
                    | STIX 2.1 JSON bundle     |
                    +--------------------------+

The VirusTotal and AbuseIPDB clients are available as Python APIs in phishguard.intel; the CLI does not call them automatically.

Requirements

• Python 3.11 or later
• Network access for email-authentication DNS checks and URL resolution/redirect tracing
• yara-python only if attachment content should be scanned with YARA

Installation

Clone the repository and install it in a virtual environment:

git clone https://github.com/trac3r00/phishing-analyzer.git
cd phishing-analyzer
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e .

On Windows PowerShell, activate the environment with .venv\Scripts\Activate.ps1.

To enable YARA attachment scanning:

python -m pip install -e '.[yara]'

Usage

Analyze an email

phishguard analyze samples/phish_paypal.eml

Analysis performs live email-authentication DNS queries and follows URLs with HTTP HEAD requests by default. Use both flags below when reviewing untrusted samples without redirect requests or authentication lookups:

phishguard analyze samples/phish_paypal.eml --no-dns --no-redirects

--no-dns skips SPF, DMARC, and DKIM checks. It does not disable the hostname resolution performed by URL analysis. --no-redirects disables HTTP redirect tracing.

Append a JSON representation of the score, signals, and IOCs to the terminal report:

phishguard analyze samples/phish_paypal.eml --no-dns --no-redirects --json

The --json option does not suppress the human-readable report; it prints a JSON document after that report.

Export the extracted indicators and analysis summary as STIX 2.1:

phishguard analyze samples/phish_paypal.eml --no-dns --no-redirects \
  --stix report.stix.json

Extract IOCs

phishguard ioc samples/phish_paypal.eml
phishguard ioc samples/phish_paypal.eml --defanged

The ioc command examines the message bodies. The full analyze command also extracts indicators from headers.

Check email authentication

phishguard auth-check example.com

This command performs live DNS queries for SPF and DMARC records and probes the common DKIM selectors defined by the project.

Run phishguard --help or phishguard <command> --help for the complete CLI syntax.

Configuration

The CLI has no configuration file. Its analysis behavior is controlled by command-line options.

The standalone threat-intelligence clients read the following environment variables when no API key is passed to their constructors:

Variable	Used by	Purpose
VT_API_KEY	phishguard.intel.VirusTotalClient	VirusTotal API v3 authentication
ABUSEIPDB_API_KEY	phishguard.intel.AbuseIPDBClient	AbuseIPDB API v2 authentication

These variables do not enable enrichment in phishguard analyze; the CLI currently does not invoke the clients.

Development

Install the development dependencies in an activated virtual environment:

python -m pip install -e '.[dev]'

Run the test suite:

python -m pytest

The test configuration in pyproject.toml discovers tests under tests/ and applies -ra -q by default.

Project Structure

phishguard/
├── cli.py                 # Command-line interface and analysis pipeline
├── core/
│   ├── __init__.py        # .eml parser and attachment hashing
│   ├── auth.py            # SPF, DMARC, DKIM, and Authentication-Results checks
│   ├── ioc.py             # IOC extraction and defanging
│   ├── scorer.py          # Multi-signal risk scoring
│   └── url_intel.py       # URL extraction, inspection, and redirect tracing
├── intel/__init__.py      # Standalone VirusTotal and AbuseIPDB clients
├── reports/__init__.py    # STIX 2.1 bundle creation
└── yara_rules/
    ├── __init__.py        # Optional YARA scanner
    └── phishing.yar       # Built-in phishing and attachment rules
samples/                   # Benign and phishing sample emails
tests/                     # Pytest suite

Security Considerations

• Treat email bodies and attachments as untrusted input. PhishGuard reads attachment bytes for hashing and optional YARA matching but does not intentionally execute attachments.
• Default URL analysis can contact URLs found in the message. Use --no-redirects when outbound requests are not appropriate for the analysis environment.
• DNS and URL requests can disclose the domains being investigated to network providers or remote systems.
• Do not publish reports containing personal data, confidential email content, or active indicators without reviewing and sanitizing them.
• A Clean or Low result is not proof that a message is safe; the score reflects only the implemented signals.

License

PhishGuard is available under the MIT License.