# harshil-2008/phisheye architecture

> Architecture diagram of the GitHub repository harshil-2008/phisheye, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harshil-2008/phisheye
- Repository: https://github.com/harshil-2008/phisheye

## Overview

PhishEye detects brand lookalikes in individual domains or new-domain feeds. The main workflow ingests a domain, screens its URL and registration age, then—when applicable—compares fetched page content and rendered appearance against brand snapshots. The scanner fuses available signals into a probability, verdict, and evidence; CLI/API entry points expose analysis and reporting. Training, brand snapshot refresh, and report generation are additional documented capabilities. Edges reflect the shown scanner orchestration, imports, or README; unsampled internals are represented only where documented.

Main entry points: [`phisheye/scanner.py`](https://github.com/harshil-2008/phisheye/blob/main/phisheye/scanner.py) (Scan orchestration), [`run.py`](https://github.com/harshil-2008/phisheye/blob/main/run.py) (CLI commands), [`phisheye/content/similarity.py`](https://github.com/harshil-2008/phisheye/blob/main/phisheye/content/similarity.py) (Page snapshots and similarity), [`phisheye/whois.py`](https://github.com/harshil-2008/phisheye/blob/main/phisheye/whois.py) (RDAP age lookup)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry points"]
  node_cli["CLI commands<br/>[run.py]"]
  node_api["REST API<br/>[api.py]"]
end

subgraph group_screen["Screening"]
  node_scanner["Scan orchestration<br/>[scanner.py]"]
  node_whois["RDAP age lookup<br/>[whois.py]"]
  node_urlfeatures["URL features<br/>[url_features.py]"]
  node_model["Screening classifier<br/>[model.py]"]
end

subgraph group_deep["Deep analysis"]
  node_content["Page snapshots and similarity<br/>[similarity.py]"]
  node_visual["Visual comparison<br/>[similarity.py]"]
  node_fusion["Score and verdict fusion<br/>[fusion.py]"]
end

subgraph group_support["Models and data"]
  node_whoiscache[("WHOIS cache<br/>[whois_cache.json]")]
  node_dataset["Synthetic training data<br/>[dataset.py]"]
  node_brands["Brand configuration<br/>[config.py]"]
  node_branddata["Brand definitions<br/>[brands.json]"]
  node_brandcache[("Brand snapshots")]
end

subgraph group_results["Results"]
  node_reports["JSON CSV HTML reports<br/>[report.py]"]
  node_reportfiles["Generated reports"]
end

node_operator(("Analyst or feed"))

node_operator -->|"runs commands"| node_cli
node_operator -->|"submits analysis"| node_api
node_cli -->|"checks or scans"| node_scanner
node_api -->|"routes analysis"| node_scanner
node_scanner -->|"extracts features"| node_urlfeatures
node_scanner -->|"gets screening score"| node_model
node_scanner -->|"looks up age"| node_whois
node_whois -->|"reads and writes"| node_whoiscache
node_whois -.->|"queries RDAP"| node_operator
node_model -->|"trains from"| node_dataset
node_dataset -->|"extracts features"| node_urlfeatures
node_scanner -->|"compares snapshots"| node_content
node_scanner -->|"renders candidate"| node_visual
node_content -->|"hashes favicons"| node_visual
node_scanner -->|"fuses signals"| node_fusion
node_urlfeatures -->|"loads brand tokens"| node_brands
node_content -->|"uses brand metadata"| node_brands
node_brands -->|"loads definitions"| node_branddata
node_scanner -->|"uses snapshots"| node_brandcache
node_cli -->|"refreshes snapshots"| node_content
node_cli -->|"trains classifier"| node_model
node_cli -->|"writes scan reports"| node_reports
node_reports -->|"writes outputs"| node_reportfiles

click node_cli "https://github.com/harshil-2008/phisheye/blob/main/run.py"
click node_api "https://github.com/harshil-2008/phisheye/blob/main/phisheye/api.py"
click node_scanner "https://github.com/harshil-2008/phisheye/blob/main/phisheye/scanner.py"
click node_whois "https://github.com/harshil-2008/phisheye/blob/main/phisheye/whois.py"
click node_whoiscache "https://github.com/harshil-2008/phisheye/blob/main/data/whois_cache.json"
click node_urlfeatures "https://github.com/harshil-2008/phisheye/blob/main/phisheye/features/url_features.py"
click node_model "https://github.com/harshil-2008/phisheye/blob/main/phisheye/ml/model.py"
click node_dataset "https://github.com/harshil-2008/phisheye/blob/main/phisheye/ml/dataset.py"
click node_content "https://github.com/harshil-2008/phisheye/blob/main/phisheye/content/similarity.py"
click node_visual "https://github.com/harshil-2008/phisheye/blob/main/phisheye/visual/similarity.py"
click node_fusion "https://github.com/harshil-2008/phisheye/blob/main/phisheye/fusion.py"
click node_brands "https://github.com/harshil-2008/phisheye/blob/main/phisheye/config.py"
click node_branddata "https://github.com/harshil-2008/phisheye/blob/main/data/brands.json"
click node_brandcache "https://github.com/harshil-2008/phisheye/tree/main/data/brands_cache"
click node_reports "https://github.com/harshil-2008/phisheye/blob/main/phisheye/report.py"
click node_reportfiles "https://github.com/harshil-2008/phisheye/tree/main/data/reports"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_api toneBlue
class node_scanner,node_whois,node_urlfeatures,node_model toneAmber
class node_content,node_visual,node_fusion toneMint
class node_whoiscache,node_dataset,node_brands,node_branddata,node_brandcache toneRose
class node_reports,node_reportfiles,node_operator toneIndigo
```

## Components

### Entry points

- [CLI commands](https://github.com/harshil-2008/phisheye/blob/main/run.py): `run.py`
- [REST API](https://github.com/harshil-2008/phisheye/blob/main/phisheye/api.py): `phisheye/api.py`

### Screening

- [Scan orchestration](https://github.com/harshil-2008/phisheye/blob/main/phisheye/scanner.py): `phisheye/scanner.py`
- [RDAP age lookup](https://github.com/harshil-2008/phisheye/blob/main/phisheye/whois.py): `phisheye/whois.py`
- [URL features](https://github.com/harshil-2008/phisheye/blob/main/phisheye/features/url_features.py): `phisheye/features/url_features.py`
- [Screening classifier](https://github.com/harshil-2008/phisheye/blob/main/phisheye/ml/model.py): `phisheye/ml/model.py`

### Deep analysis

- [Page snapshots and similarity](https://github.com/harshil-2008/phisheye/blob/main/phisheye/content/similarity.py): `phisheye/content/similarity.py`
- [Visual comparison](https://github.com/harshil-2008/phisheye/blob/main/phisheye/visual/similarity.py): `phisheye/visual/similarity.py`
- [Score and verdict fusion](https://github.com/harshil-2008/phisheye/blob/main/phisheye/fusion.py): `phisheye/fusion.py`

### Models and data

- [WHOIS cache](https://github.com/harshil-2008/phisheye/blob/main/data/whois_cache.json): `data/whois_cache.json`
- [Synthetic training data](https://github.com/harshil-2008/phisheye/blob/main/phisheye/ml/dataset.py): `phisheye/ml/dataset.py`
- [Brand configuration](https://github.com/harshil-2008/phisheye/blob/main/phisheye/config.py): `phisheye/config.py`
- [Brand definitions](https://github.com/harshil-2008/phisheye/blob/main/data/brands.json): `data/brands.json`
- [Brand snapshots](https://github.com/harshil-2008/phisheye/tree/main/data/brands_cache): `data/brands_cache`

### Results

- [JSON CSV HTML reports](https://github.com/harshil-2008/phisheye/blob/main/phisheye/report.py): `phisheye/report.py`
- [Generated reports](https://github.com/harshil-2008/phisheye/tree/main/data/reports): `data/reports`

### Other components

- **Analyst or feed**

## Connections

- Analyst or feed → CLI commands: runs commands (evidence: `README.md`)
- Analyst or feed → REST API: submits analysis (evidence: `README.md`)
- CLI commands → Scan orchestration: checks or scans (evidence: `run.py`)
- REST API → Scan orchestration: routes analysis (evidence: `phisheye/api.py`)
- Scan orchestration → URL features: extracts features (evidence: `phisheye/scanner.py`)
- Scan orchestration → Screening classifier: gets screening score (evidence: `phisheye/scanner.py`)
- Scan orchestration → RDAP age lookup: looks up age (evidence: `phisheye/scanner.py`)
- RDAP age lookup → WHOIS cache: reads and writes (evidence: `phisheye/whois.py`)
- RDAP age lookup → Analyst or feed: queries RDAP
- Screening classifier → Synthetic training data: trains from (evidence: `phisheye/ml/model.py`)
- Synthetic training data → URL features: extracts features (evidence: `phisheye/ml/dataset.py`)
- Scan orchestration → Page snapshots and similarity: compares snapshots (evidence: `phisheye/scanner.py`)
- Scan orchestration → Visual comparison: renders candidate (evidence: `phisheye/scanner.py`)
- Page snapshots and similarity → Visual comparison: hashes favicons (evidence: `phisheye/content/similarity.py`)
- Scan orchestration → Score and verdict fusion: fuses signals (evidence: `phisheye/scanner.py`)
- URL features → Brand configuration: loads brand tokens (evidence: `phisheye/features/url_features.py`)
- Page snapshots and similarity → Brand configuration: uses brand metadata (evidence: `phisheye/content/similarity.py`)
- Brand configuration → Brand definitions: loads definitions (evidence: `phisheye/config.py`)
- Scan orchestration → Brand snapshots: uses snapshots (evidence: `README.md`)
- CLI commands → Page snapshots and similarity: refreshes snapshots (evidence: `run.py`)
- CLI commands → Screening classifier: trains classifier (evidence: `run.py`)
- CLI commands → JSON CSV HTML reports: writes scan reports (evidence: `run.py`)
- JSON CSV HTML reports → Generated reports: writes outputs (evidence: `phisheye/report.py`)
