{"id":37078142,"url":"https://github.com/0xlam/phishsage","last_synced_at":"2026-05-30T01:02:49.838Z","repository":{"id":325511392,"uuid":"1096884922","full_name":"0xlam/PhishSage","owner":"0xlam","description":"PhishSage is a lightweight email triage and phishing-analysis toolkit. Extracts headers, attachments, and links, applies heuristic checks, and produces structured insights.","archived":false,"fork":false,"pushed_at":"2026-02-13T08:05:57.000Z","size":184,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-13T19:57:30.460Z","etag":null,"topics":["cybersecurity","email-analysis","email-security","incident-response","malware-analysis","phishing","python3","security-tools","soc"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/0xlam.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-15T05:47:49.000Z","updated_at":"2026-02-13T08:03:00.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/0xlam/PhishSage","commit_stats":null,"previous_names":["0xlam/phishsage"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/0xlam/PhishSage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xlam%2FPhishSage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xlam%2FPhishSage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xlam%2FPhishSage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xlam%2FPhishSage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/0xlam","download_url":"https://codeload.github.com/0xlam/PhishSage/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/0xlam%2FPhishSage/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31371648,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-03T17:53:18.093Z","status":"ssl_error","status_checked_at":"2026-04-03T17:53:17.617Z","response_time":107,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cybersecurity","email-analysis","email-security","incident-response","malware-analysis","phishing","python3","security-tools","soc"],"created_at":"2026-01-14T09:03:53.375Z","updated_at":"2026-05-30T01:02:49.824Z","avatar_url":"https://github.com/0xlam.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PhishSage\n\nPhishSage is a lightweight phishing-analysis toolkit that parses raw emails, inspects headers, analyzes links and domains with multi-layer heuristics, and outputs structured JSON findings for fast, automated investigation\n\n\u003c!-- Badges go here --\u003e\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)]()\n[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)]()\n[![Status: Active](https://img.shields.io/badge/Project%20Status-Active-brightgreen.svg)]()\n\n\n## 1. Core functionality\n\nPhishSage is intentionally minimal and concentrates on these essential capabilities:\n\n* **Header analysis**\n\n  * Extracts normalized sender-related headers (From, Reply-To, Return-Path, Message-ID)\n  * Parses SPF, DKIM, and DMARC results from Authentication-Results\n  * Performs alignment checks across From, Reply-To, and Return-Path\n  * Validates Message-ID domain consistency\n  * Detects use of free email providers in Reply-To and Return-Path headers\n  * Checks timestamp sanity by comparing the Date header with the first Received hop\n  * Looks up WHOIS domain age and flags newly registered or soon-to-expire domains\n  * Validates MX records for sender-related domains\n  * Queries Spamhaus DBL for sender-related domains\n  * Aggregates all findings into structured JSON with merged alerts\n\n\n* **Attachment processing**\n\n  * List attachments with MIME and size\n  * Extract attachments safely (avoid overwrites)\n  * Compute hashes (MD5, SHA1, SHA256)\n  * Optional VirusTotal scan by SHA256\n  * Scan attachments with YARA rules (single files, multiple files, or directories; recursive and filtered for valid .yar/.yara files)\n  * Verbose mode shows matched strings with offsets and hex data\n\n\n* **Link / URL analysis**\n\n  * Extracts URLs from email bodies or headers\n  * Detects URLs using raw IP addresses instead of domains\n  * Flags suspicious or uncommon top-level domains (TLDs)\n  * Identifies excessive or nested subdomains, ignoring trivial ones (e.g., \"www\")\n  * Recognizes shortened URLs (bit.ly, tinyurl.com, etc.)\n  * Calculates Shannon entropy for domain and subdomain to spot obfuscation\n  * Performs SSL/TLS certificate inspection (issuer, validity, domain match, expiration)\n  * Looks up domain age via WHOIS and flags newly registered or expiring domains\n  * VirusTotal URL lookup for threat intelligence\n  * Optional redirect-chain tracing to uncover hidden destinations\n  * Checks for numeric-only registrable domains\n  * Detects URLs using commonly abused web platforms and services\n  * Flags URLs with excessively deep paths\n\n\n## 2. Installation\n\n### Base Install\n\nInstalls core functionality: header analysis and basic email parsing.\n```bash\n# From PyPI\npip install phishsage\n\n# From GitHub\ngit clone https://github.com/0xlam/PhishSage.git\ncd PhishSage\npython3 -m venv venv\n\n# Linux / macOS\nsource venv/bin/activate\n\n# Windows (PowerShell)\nvenv\\Scripts\\Activate.ps1\n\npip install -e .\n```\n\n---\n\n### Optional Extras\n\nInstall only what you need:\n```bash\n# Attachment analysis (YARA scanning, MIME detection)\npip install \"phishsage[attachments]\"\n\n# Link / URL analysis\npip install \"phishsage[links]\"\n\n# Everything\npip install \"phishsage[all]\"\n```\n\n---\n\n### VirusTotal API Key\n\nRequired if using `--vt-scan` in any mode.\n```bash\n# Linux / macOS\nexport VIRUSTOTAL_API_KEY=\"your_virustotal_api_key\"\n\n# Windows (PowerShell)\nsetx VIRUSTOTAL_API_KEY \"your_virustotal_api_key\"\n```\n\n\n## 3. CLI Usage\n\nPhishSage provides a command-line interface with three main modes: `headers`, `attachments`, and `links`. The `headers` and `links` modes output results in JSON format, while the `attachments` mode produces human-readable summaries only.\n\n\n### Main Help\n\n```bash\nphishsage -h\n```\n\n**Output:**\n\n```\nusage: phishsage [-h] {headers,attachments,links} ...\n\nPhishSage\n\npositional arguments:\n  {headers,attachments,links}\n    headers             Analyze email headers for anomalies or indicators\n    attachments         Analyze or extract attachments\n    links               Analyze links in email content\n\noptions:\n  -h, --help            show this help message and exit\n```\n\n---\n\n### Header Analysis\n\n```bash\nphishsage headers -h\n```\n\n**Options:**\n\n```\nusage: phishsage headers [-h] -f FILE [-o FILE] [--heuristics] [--enrich [{mx,spamhaus,domain_age,all} ...]] [--json]\n\noptions:\n  -h, --help            show this help message and exit\n  -f, --file FILE       Email file to analyze (.eml)\n  -o, --output FILE     Save JSON results to file (use with --json)\n  --heuristics          Analyze headers for suspicious patterns and anomalies\n  --enrich [{mx,spamhaus,domain_age,all} ...]\n                        Add threat-intel enrichment to header analysis (mx, spamhaus, domain_age). Requires --heuristics.\n  --json                Output full details in JSON format\n```\n\n---\n\n### Attachment Processing\n\n```bash\nphishsage attachments -h\n```\n\n**Options:**\n\n```\nusage: phishsage attachments [-h] -f FILE [-o FILE] [--list] [--extract DIR] [--hash] [--vt-scan] [--yara PATH [PATH ...]] [--yara-verbose] [--json]\n\noptions:\n  -h, --help            show this help message and exit\n  -f, --file FILE       Email file to analyze (.eml)\n  -o, --output FILE     Save JSON results to file (use with --json)\n  --list                List attachments only\n  --extract DIR         Extract attachments to specified directory\n  --hash                Compute hashes (MD5, SHA1, SHA256) for each attachment\n  --vt-scan             Check attachments against VirusTotal by SHA256\n  --yara PATH [PATH ...]\n                        Scan attachments with YARA rules. Paths can be files or directories; directories are scanned recursively for .yar/.yara\n                        files.\n  --yara-verbose        Show detailed string matches and offsets when YARA rules hit\n  --json                Output full details in JSON format\n```\n\n---\n\n### Link / URL Analysis\n\n```bash\nphishsage links -h\n```\n\n**Options:**\n\n```\nusage: phishsage links [-h] -f FILE [-o FILE] [--extract] [--vt-scan] [--check-redirects] [--heuristics]\n                       [--enrich [{all,domain_age,certificate,virustotal,redirects} ...]] [--json]\n\noptions:\n  -h, --help            show this help message and exit\n  -f, --file FILE       Email file to analyze (.eml)\n  -o, --output FILE     Save JSON results to file (use with --json)\n  --extract             Extract URLs from the email body\n  --vt-scan             Query VirusTotal for URL reputation\n  --check-redirects     Follow HTTP redirects and show chain\n  --heuristics          Run phishing detection heuristics (use --enrich to add extra data)\n  --enrich [{all,domain_age,certificate,virustotal,redirects} ...]\n                        Add extra analysis to heuristics (requires --heuristics)\n  --json                Output full details in JSON format\n```\n\n---\n\n## 4. Configuration\n\nPhishSage stores configuration values in the project config (`config.toml`) or environment variables. The main items you may safely adjust are:\n\n  * `VIRUSTOTAL_API_KEY` — API key for VirusTotal scans.\n  * `MAX_REDIRECTS` — Maximum number of redirects to follow when checking redirect chains.\n  * `THRESHOLD_YOUNG`, `THRESHOLD_EXPIRING` — Domain age/expiry thresholds (in days). Domains younger than `THRESHOLD_YOUNG` or expiring within `THRESHOLD_EXPIRING` days are flagged as potentially suspicious.\n  * `ABUSABLE_PLATFORM_DOMAINS`, `SUSPICIOUS_TLDS`, `SHORTENERS` — Heuristic lists used in URL/link analysis.\n  * `SUBDOMAIN_THRESHOLD`, `TRIVIAL_SUBDOMAINS` — Used for subdomain heuristics to identify excessive or meaningful subdomains.\n  * `FREE_EMAIL_DOMAINS` — Free email providers that may indicate disposable or less-trusted addresses.\n  * `DATE_RECEIVED_DRIFT_MINUTES` — Maximum allowed difference between the `Date` header and the first `Received` hop in email headers.\n\n *Note: Only modify thresholds or heuristic lists if you understand the potential impact on false positives and overall detection accuracy.*\n\n\n---\n\n## 5. Scope \u0026 Limitations\n\n  * **Focused functionality:** PhishSage is not a full mail forensic suite. It prioritizes heuristics, quick triage, and enrichment over deep forensic analysis.\n  * **Network-dependent checks:** WHOIS, VirusTotal, MX, and SSL inspections rely on external services; results may vary or fail due to connectivity issues or API limits.\n  * **Attachment processing:** Currently limited to listing, extraction, hashing, and optional VirusTotal scans. Full heuristic attachment analysis will be introduced in a future release.\n  * **Output formats:** Human‑readable pretty output is the default. Use `--json` to obtain detailed structured data for all modes.\n  * **Intended use:** Designed for investigative support and enrichment. Not intended for automated blocking or enforcement in production email systems.\n  * **Evolving coverage:** Current checks under each section are limited; additional heuristics and enhanced analyses will be added in future releases.\n\n\n---\n\n## 6. Contributing\n\nContributions to PhishSage are welcome! You can help improve the project by:\n\n* Adding or refining heuristic checks for headers, attachments, and links.\n* Expanding the lists in `config.toml`.\n* Improving parsing, normalization, or output handling.\n* Reporting bugs or suggesting enhancements.\n\nBefore submitting changes, please ensure they are well-tested and maintain the code’s clarity, security, and reliability. Contributions that enhance detection coverage, reduce false positives, or improve usability are particularly appreciated.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xlam%2Fphishsage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F0xlam%2Fphishsage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F0xlam%2Fphishsage/lists"}