Skip to content

TECHNICAL_DETAILS.md

Latest commit

 

History

History
225 lines (161 loc) · 3.56 KB

TECHNICAL_DETAILS.md

File metadata and controls

225 lines (161 loc) · 3.56 KB
Raw

Technical Details

Overview

PhishSentinel is a modular, rule-based phishing detection toolkit developed in Python. It analyzes URLs, websites, emails, domains, and files using defensive security techniques without relying on machine learning or external threat intelligence services.

The project follows a modular architecture where each scanner is responsible for analyzing a specific type of input.

Architecture

                 +----------------------+
                 |      main.py         |
                 +----------+-----------+
                            |
                            |
            +---------------+----------------+
            |                                |
     CLI Utilities                    Logger Utilities
            |                                |
            +---------------+----------------+
                            |
                    Scanner Framework
                            |
     -------------------------------------------------
     |        |         |         |                 |
 URL      Website     Email    Domain            File
Scanner    Scanner    Scanner   Scanner         Scanner

Scanners

URL Scanner

Performs rule-based phishing analysis on URLs.

Detection includes:

  • HTTPS verification
  • IP address detection
  • Long URL detection
  • URL shortener detection
  • Suspicious keyword detection
  • Suspicious TLD detection
  • Brand impersonation detection

Website Scanner

Downloads and analyzes webpage HTML.

Checks include:

  • Login forms
  • Password fields
  • Hidden iframes
  • JavaScript redirects
  • External JavaScript
  • Suspicious HTML elements

Email Scanner

Parses .eml email files.

Analysis includes:

  • Email headers
  • Subject inspection
  • URL extraction
  • SPF header presence
  • DKIM signature presence
  • DMARC(Authentication-Results) header presence
  • Suspicious keywords
  • Suspicious attachments

Domain Scanner

Collects domain intelligence.

Checks include:

  • WHOIS lookup
  • Registrar information
  • Domain age
  • Expiration analysis
  • DNS records
  • MX records
  • SSL certificate validation

File Scanner

Analyzes local files.

Checks include:

  • SHA-256 hashing
  • MD5 hashing
  • Double extensions
  • Executable files
  • Macro-enabled Office documents
  • Suspicious filenames

Risk Engine

Each scanner generates findings.

Every finding has:

  • Category
  • Severity
  • Description
  • Risk weight

The total risk score is calculated by summing the configured weights.

Example:

HTTP                15
IP Address          20
Brand Detection     30

Total Score         65

Risk levels:

Score Level
0–24 Low
25–49 Medium
50–74 High
75+ Critical

Project Structure

PhishSentinel/
│
├── scanners/
├── utils/
├── models/
├── samples/
├── logs/
│
├── config.py
├── main.py
└── requirements.txt

Design Principles

The project follows:

  • Modular architecture
  • Single Responsibility Principle (SRP)
  • Rule-based detection
  • Code reusability
  • Separation of concerns
  • Readable and maintainable code

Technologies

Language

  • Python 3.12+

Libraries

  • requests
  • beautifulsoup4
  • validators
  • tldextract
  • dnspython
  • python-whois
  • colorama

Standard Library

  • hashlib
  • ssl
  • socket
  • email
  • logging
  • pathlib
  • ipaddress
  • urllib.parse

Logging

Application activity is recorded in:

logs/phishsentinel.log

Each log entry includes:

  • Scanner
  • Target
  • Risk score
  • Risk level
  • Findings count
  • Timestamp