MetaMask/eth-phishing-detect: the blocklist and the CLI that maintain it

What the blocklist is actually for

The repository is a list of malicious domains that target Web3 users, and the README describes it as exactly that. The list exists so that a wallet or a browser extension can warn someone before they sign something on a lookalike site. The README's blocking policy names two cases where the maintainers say they will be quick and decisive: sites that impersonate other known and established sites, and sites whose interfaces collect user signing keys, especially cryptocurrency keys, and send them back to home servers. Everything else falls under "other grounds for blocking."

That policy is deliberately short. It tells you the shape of the list but not its edges, which matters if you are deciding whether a domain you own belongs on it. The audience is narrow: people who maintain the list, people who submit domains to it, and engineers who want to consume the list rather than write their own. If you are building a wallet and want a detection layer, this repository is not the layer. The README says the phishing detector has moved to MetaMask/core under packages/phishing-controller, and the package.json depends on @metamask/phishing-controller. The data stayed here; the runtime went elsewhere.

How the list, the safeguards and the test lists fit together

The list itself lives in src/config.json, and every change is expected to go through the CLI or the library functions rather than a hand edit, because the README asks contributors to keep the file tidy. Two functions do the work: addDomains and removeDomains, each taking a config, a list name (blocklist or allowlist) and an array of hosts. The CLI wrappers in bin/ call the same code.

False positives are the real design problem, and the repository handles them with a separate set of files in test/resources. Each file is plaintext with one host per line, pulled from sources the README names: Tranco, CoinMarketCap, Coingecko and the Snaps registry, based on the update:list:* scripts in package.json. These are not blocklists. They are lists of domains that should not be blocked by accident, and the README states that if you need to block a domain that appears on one of them, you must add a bypass to test/test-lists.ts. That is the mechanism: a domain on a safeguard list is presumed legitimate until a human writes an exception.

The data flow is therefore one directional and reviewable. A submission arrives, a maintainer runs an add command, the config changes, and the test suite checks the result against the safeguard lists. Because the config is a file in git, the history is the audit trail. The README gives one way to read it: git log -S "example.com" -- src/config.json pulls every pull request associated with that domain.

Installing eth-phishing-detect and adding your first domain

There is no published install guide beyond the repository itself, and the README's basic usage section points elsewhere for the detector. What it does document is the contributor workflow. Clone the repository, install dependencies with yarn, then use the scripts. The package.json defines the commands; the README shows the invocations.

To add a domain to the blocklist, the README gives this command:

yarn add:blocklist crypto-phishing-site.tld

Running it should leave you with a modified src/config.json containing the new host. The allowlist has a parallel command, yarn add:allowlist legitimate-site.tld, and removal mirrors both: yarn remove:blocklist and yarn remove:allowlist.

If you are writing code rather than running scripts, the README shows the library form:

addDomains(config, "blocklist", ["crypto-phishing-site.tld"]);
addDomains(config, "allowlist", ["legitimate-site.tld"]);

The same functions have removal counterparts, removeDomains(config, "blocklist", [...]) and removeDomains(config, "allowlist", [...]).

If you need to refresh the safeguard lists, the command is yarn update:lists, and the README states you will need a CoinMarketCap Pro API key. The .env.example file shows the variable name:

COINMARKETCAP_PRO_API_KEY=XXXXXXX

Expect that step to fail without the key. Expect the add and remove commands to work without it.

The detector moved, and the list did not

The most important limitation is stated plainly in the README: the phishing detector has been moved to MetaMask/core, into packages/phishing-controller. Anyone who finds this repository while looking for a drop-in detection library is looking at the wrong artifact. What remains here is the data and the tooling around it, and package.json reflects that by depending on @metamask/phishing-controller rather than providing it.

The second limitation is maintenance cadence. The last push was on 2022-04-19, the same date as the v1.2.0 release. The repository is not archived, so it is not formally retired, but nothing in the repository shows activity after that date. A blocklist whose value comes from being current is a poor fit for a project that needs same-day coverage of new phishing domains, unless you are consuming the list through whatever pipeline MetaMask core uses rather than pulling this repository directly.

The third is the licence. package.json declares DBAD, and the repository's licence field is NOASSERTION. That is not a standard OSI identifier, and the README does not explain the terms. If you plan to redistribute the list, read the LICENSE file before you assume anything.

ChainPatrol and the difference between a list and a lookup service

The README itself points to a real alternative for one specific job. For checking why a given domain was blocked, it names a third-party search tool maintained by ChainPatrol at app.chainpatrol.io/search. The difference in approach is the shape of the artifact. eth-phishing-detect is a file in a git repository that you fetch and diff; ChainPatrol is a hosted search interface you query. One gives you the raw entries and their history, the other gives you an answer about a specific domain without you cloning anything.

That distinction decides which one you want. If you are building a submission pipeline or you need to see when a domain was added and by which pull request, the git history here is the thing ChainPatrol does not hand you. If you just want to know why a warning appeared, running git log -S against a config file is a worse experience than typing the domain into a search box. The README treats the two as complementary, not competing, and that framing is honest.

Who should take this on, and what to check first

Use this repository if you are contributing domains to MetaMask's list, auditing what is on it, or consuming the raw config in a pipeline you control. The CLI is small, the data is plain, and the git history answers the question of when and why a domain was added.

Do not use it as an embedded detector. The README says the detector moved to MetaMask/core, and the dependency on @metamask/phishing-controller confirms the split. Do not use it if you need a list that reflects this week's phishing campaigns, because the last push was on 2022-04-19. Do not use it if you need clear redistribution terms, because the licence is declared as DBAD in package.json and NOASSERTION in the repository metadata, and the README does not resolve that.

Before you commit to anything, check two files. Look in src/config.json for the domains you care about, and look in test/resources to see whether they appear on a safeguard list, because the README states that a domain on one of those lists requires a bypass in test/test-lists.ts. If your domain is on a safeguard list and you want it blocked, you are signing up to maintain an exception, not just a line.

Frequently asked questions

The questions below cover the common points of confusion: what the repository still does, how the list is edited, and what the safeguards are for. Answers come from the README and package.json only.

Editorial conclusion

Adopt eth-phishing-detect if you need the raw blocklist or you are submitting a domain to it through the CLI; do not adopt it as an in-app detector, because the README states the phishing detector has moved to MetaMask/core under packages/phishing-controller. Before relying on it, check whether the domain you care about is already present in src/config.json and whether it appears on a safeguard list in test/resources, since a domain on those lists needs a bypass entry in test/test-lists.ts. The last push to this repository was on 2022-04-19, so treat the data as the product and the code as frozen.

Frequently asked questions

Official sources

1. Official README
2. Project repository
3. Release notes