# u7dani/phishscope architecture

> Architecture diagram of the GitHub repository u7dani/phishscope, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/u7dani/phishscope
- Repository: https://github.com/u7dani/phishscope

## Overview

##### Project type and purpose
- PhishScope is a standalone, OSINT-defensive, batch-processing tool written in Python.

##### File structure
- Top-level files:
- phiscope_batch.py – the main entry point and orchestrator of the analysis pipeline
- requirements_linux.txt / requirements_windows.txt – dependency lists for each OS
- README.md, LICENSE, .gitignore – project metadata
- Implicit subfolder (per README):
- email/ – directory where `.eml` files are placed
- resultados_phishscope.xlsx – the generated output

##### README for architectural insights
- The tool is linear and batch-oriented: read emails → run analyzers → aggregate scores → output Excel.
- External interactions: DNS queries (SPF/DKIM/DMARC), HTTP HEAD requests (URL resolution).
- Core technologies: Python 3.9+, NLP embeddings library, openpyxl (or similar) for Excel.

##### Main components and interactions
a. Input Component
- Email Loader: scans `email/` directory for `.eml` files
b. Processing Components (each can be a sub-module or class within phiscope_batch.py)
1. Email Parser – extracts headers, body, attachments
2. NLP Analyzer – computes semantic embeddings and urgency patterns
3. URL Resolver – extracts URLs, follows redirects via HTTP HEAD
4. Authenticator – performs DNS-based SPF, DKIM, DMARC checks
5. Attachment Scanner – hashes attachments, flags suspicious types
6. Scoring Engine – weights and aggregates all signals into PhishScore
c. Output Component
d. External Services
- DNS Servers – for SPF/DKIM/DMARC lookups
- Remote HTTP Servers – for URL redirections

##### Architectural patterns and design principles
- Pipeline pattern: each email flows through a fixed sequence of analyzers.
- Single process, modular components – easy to extend by adding new analyzers.
- Configuration via requirements files and optional PhishScore weight adjustments.
- CLI-driven with no persistent server or database.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Entry and Metadata
    phiscope_entry["phiscope_batch.py"]:::metadata
    req_linux["requirements_linux.txt"]:::metadata
    req_win["requirements_windows.txt"]:::metadata
    readme["README.md"]:::metadata
    license["LICENSE"]:::metadata
    gitignore[".gitignore"]:::metadata

    subgraph "Metadata & Config"
        phiscope_entry
        req_linux
        req_win
        readme
        license
        gitignore
    end

    %% Input
    email_dir["email/"]:::input
    email_loader["Email Loader"]:::input

    %% Processing Pipeline
    subgraph "Processing Pipeline"
        parser["Email Parser"]:::processing
        nlp["NLP Analyzer"]:::processing
        url_resolver["URL Resolver"]:::processing
        authenticator["Authenticator"]:::processing
        attachment_scanner["Attachment Scanner"]:::processing
    end

    scoring["Scoring Engine"]:::processing
    excel_exporter["Excel Exporter"]:::output

    %% External Services
    dns["DNS Servers"]:::external
    http["Remote HTTP Servers"]:::external

    %% Connections
    phiscope_entry -->|"orchestrates"| email_loader
    email_dir -->|"directory scan"| email_loader
    email_loader -->|".eml content"| parser
    parser -->|"parsed headers & body"| nlp
    nlp -->|"embeddings & patterns"| url_resolver
    url_resolver -->|"resolved URLs"| authenticator
    authenticator -->|"auth results"| attachment_scanner
    attachment_scanner -->|"attachment hashes"| scoring
    scoring -->|"PhishScore"| excel_exporter

    url_resolver -->|"HTTP HEAD"| http
    authenticator -->|"DNS lookup"| dns

    %% Click Events
    click phiscope_entry "https://github.com/u7dani/phishscope/blob/main/phiscope_batch.py"
    click req_linux "https://github.com/u7dani/phishscope/blob/main/requirements_linux.txt"
    click req_win "https://github.com/u7dani/phishscope/blob/main/requirements_windows.txt"
    click readme "https://github.com/u7dani/phishscope/blob/main/README.md"
    click license "https://github.com/u7dani/phishscope/tree/main/LICENSE"
    click gitignore "https://github.com/u7dani/phishscope/blob/main/.gitignore"
    click email_dir "https://github.com/u7dani/phishscope/tree/main/email/"
    click excel_exporter "https://github.com/u7dani/phishscope/blob/main/resultados_phishscope.xlsx"

    %% Styles
    classDef input fill:#blue,stroke:#333,stroke-width:1px;
    classDef processing fill:#8fbc8f,stroke:#333,stroke-width:1px;
    classDef output fill:#ffa500,stroke:#333,stroke-width:1px;
    classDef external fill:#ccc,stroke:#333,stroke-width:1px;
    classDef metadata fill:#f5f5f5,stroke:#333,stroke-width:1px;
```
