# metamask/eth-phishing-detect architecture

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

- Interactive diagram: https://gitdiagram.com/metamask/eth-phishing-detect
- Repository: https://github.com/metamask/eth-phishing-detect

## Overview

eth-phishing-detect is a domain-list package for detecting phishing sites targeting Web3 users, with tools for maintaining its allow/block/fuzzy lists. The main runtime flow loads the bundled configuration into a detector and checks a supplied domain. Contribution tooling updates or cleans that configuration; a separate list-refresh tool maintains domain corpora used as false-positive safeguards. The graph reflects documented workflows and shown imports/calls; unsampled implementation details are omitted.

Main entry points: [`bin/update-config.ts`](https://github.com/metamask/eth-phishing-detect/blob/main/bin/update-config.ts) (Config CLI), [`bin/clean-config.ts`](https://github.com/metamask/eth-phishing-detect/blob/main/bin/clean-config.ts) (Clean CLI), [`src/index.ts`](https://github.com/metamask/eth-phishing-detect/blob/main/src/index.ts) (Domain check API), [`src/clean-config.ts`](https://github.com/metamask/eth-phishing-detect/blob/main/src/clean-config.ts) (Config cleaning)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_detection["Domain detection"]
  node_api["Domain check API<br/>[index.ts]"]
  node_config[("Bundled lists<br/>[config.json]")]
  node_detector["Detector wrapper<br/>[detector.ts]"]
  node_controller["Phishing controller"]
end

subgraph group_maintenance["List maintenance"]
  node_editor["Config CLI<br/>[update-config.ts]"]
  node_updater["List operations<br/>[update-config.ts]"]
  node_cleaner_cli["Clean CLI<br/>[clean-config.ts]"]
  node_cleaner["Config cleaning<br/>[clean-config.ts]"]
  node_serializer["Config serializer<br/>[utils.ts]"]
  node_keys["List key mapping<br/>[constants.ts]"]
  node_validator["Config validator"]
end

subgraph group_safeguards["False-positive safeguards"]
  node_list_refresh["Safeguard list refresh"]
  node_source_services["List source services"]
  node_corpora[("Domain corpora")]
end

node_consumer(("Package user"))

node_consumer -->|"checks domain"| node_api
node_api -->|"loads lists"| node_config
node_api -->|"checks domain"| node_controller
node_detector -->|"wraps check"| node_controller
node_editor -->|"dispatches edits"| node_updater
node_editor -->|"reads and writes"| node_config
node_editor -->|"serializes config"| node_serializer
node_editor -->|"validates list key"| node_keys
node_updater -->|"cleans additions"| node_cleaner
node_cleaner -->|"checks fuzzy entries"| node_detector
node_cleaner_cli -->|"cleans selected list"| node_cleaner
node_cleaner_cli -->|"reads and writes"| node_config
node_cleaner_cli -->|"serializes config"| node_serializer
node_cleaner_cli -->|"validates list key"| node_keys
node_list_refresh -->|"fetches domains"| node_source_services
node_list_refresh -->|"writes lists"| node_corpora

click node_api "https://github.com/metamask/eth-phishing-detect/blob/main/src/index.ts"
click node_config "https://github.com/metamask/eth-phishing-detect/blob/main/src/config.json"
click node_detector "https://github.com/metamask/eth-phishing-detect/blob/main/src/detector.ts"
click node_editor "https://github.com/metamask/eth-phishing-detect/blob/main/bin/update-config.ts"
click node_updater "https://github.com/metamask/eth-phishing-detect/blob/main/src/update-config.ts"
click node_cleaner_cli "https://github.com/metamask/eth-phishing-detect/blob/main/bin/clean-config.ts"
click node_cleaner "https://github.com/metamask/eth-phishing-detect/blob/main/src/clean-config.ts"
click node_serializer "https://github.com/metamask/eth-phishing-detect/blob/main/src/utils.ts"
click node_keys "https://github.com/metamask/eth-phishing-detect/blob/main/src/constants.ts"
click node_validator "https://github.com/metamask/eth-phishing-detect/blob/main/bin/validate-new-config.ts"
click node_list_refresh "https://github.com/metamask/eth-phishing-detect/blob/main/bin/update-test-lists.ts"
click node_corpora "https://github.com/metamask/eth-phishing-detect/tree/main/test/resources"

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_api,node_config,node_detector,node_controller,node_consumer toneBlue
class node_editor,node_updater,node_cleaner_cli,node_cleaner,node_serializer,node_keys,node_validator toneAmber
class node_list_refresh,node_source_services,node_corpora toneMint
```

## Components

### Domain detection

- [Domain check API](https://github.com/metamask/eth-phishing-detect/blob/main/src/index.ts): `src/index.ts`
- [Bundled lists](https://github.com/metamask/eth-phishing-detect/blob/main/src/config.json): `src/config.json`
- [Detector wrapper](https://github.com/metamask/eth-phishing-detect/blob/main/src/detector.ts): `src/detector.ts`
- **Phishing controller**

### List maintenance

- [Config CLI](https://github.com/metamask/eth-phishing-detect/blob/main/bin/update-config.ts): `bin/update-config.ts`
- [List operations](https://github.com/metamask/eth-phishing-detect/blob/main/src/update-config.ts): `src/update-config.ts`
- [Clean CLI](https://github.com/metamask/eth-phishing-detect/blob/main/bin/clean-config.ts): `bin/clean-config.ts`
- [Config cleaning](https://github.com/metamask/eth-phishing-detect/blob/main/src/clean-config.ts): `src/clean-config.ts`
- [Config serializer](https://github.com/metamask/eth-phishing-detect/blob/main/src/utils.ts): `src/utils.ts`
- [List key mapping](https://github.com/metamask/eth-phishing-detect/blob/main/src/constants.ts): `src/constants.ts`
- [Config validator](https://github.com/metamask/eth-phishing-detect/blob/main/bin/validate-new-config.ts): `bin/validate-new-config.ts`

### False-positive safeguards

- [Safeguard list refresh](https://github.com/metamask/eth-phishing-detect/blob/main/bin/update-test-lists.ts): `bin/update-test-lists.ts`
- **List source services**
- [Domain corpora](https://github.com/metamask/eth-phishing-detect/tree/main/test/resources): `test/resources`

### Other components

- **Package user**

## Connections

- Package user → Domain check API: checks domain (evidence: `README.md`)
- Domain check API → Bundled lists: loads lists (evidence: `src/index.ts`)
- Domain check API → Phishing controller: checks domain (evidence: `src/index.ts`)
- Detector wrapper → Phishing controller: wraps check (evidence: `src/detector.ts`)
- Config CLI → List operations: dispatches edits (evidence: `bin/update-config.ts`)
- Config CLI → Bundled lists: reads and writes (evidence: `bin/update-config.ts`)
- Config CLI → Config serializer: serializes config (evidence: `bin/update-config.ts`)
- Config CLI → List key mapping: validates list key (evidence: `bin/update-config.ts`)
- List operations → Config cleaning: cleans additions (evidence: `src/update-config.ts`)
- Config cleaning → Detector wrapper: checks fuzzy entries (evidence: `src/clean-config.ts`)
- Clean CLI → Config cleaning: cleans selected list (evidence: `bin/clean-config.ts`)
- Clean CLI → Bundled lists: reads and writes (evidence: `bin/clean-config.ts`)
- Clean CLI → Config serializer: serializes config (evidence: `bin/clean-config.ts`)
- Clean CLI → List key mapping: validates list key (evidence: `bin/clean-config.ts`)
- Safeguard list refresh → List source services: fetches domains (evidence: `bin/update-test-lists.ts`)
- Safeguard list refresh → Domain corpora: writes lists (evidence: `README.md`)
