Registry / auth-security / eth-phishing-detect

eth-phishing-detect

library1.2.0jsnpmunverified

The `eth-phishing-detect` utility is a JavaScript library designed to identify and block domains known for targeting Ethereum users with phishing attacks. Maintained by MetaMask, it provides an up-to-date list of malicious websites, actively evolving its blocking policy to include sites that impersonate established services or attempt to collect cryptocurrency keys. The package is currently at version `1.2.0` and was last published about 4 years ago (as of April 2026), with prior versions indicating a more active cadence for configuration updates. It differentiates itself through its direct integration and maintenance by a major wallet provider, offering a robust and proactive defense mechanism against specific web3-related threats. Developers can use it to integrate real-time phishing detection into their applications, enhancing user security by preventing access to known harmful sites.

auth-security

npm install eth-phishing-detect

github ↗package ↗

INSTALL

IMPORT

SIG · ETH-PHISHING-DETEC

eth-phishing-detect

auth-securityjavascriptv1.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

checkForPhishing

✓ import checkForPhishing from 'eth-phishing-detect'

✗ const { checkForPhishing } = require('eth-phishing-detect')

The main entry point is a default export in ESM, and a direct module export in CJS. Avoid destructuring for CJS.

PhishingDetector

✓ import { PhishingDetector } from 'eth-phishing-detect/detector'

✗ const PhishingDetector = require('eth-phishing-detect/src/detector')

The README's CJS example uses `require('eth-phishing-detect/src/detector')`. For ESM and stability, import from `eth-phishing-detect/detector`.

PhishingDetector (CommonJS)

✓ const PhishingDetector = require('eth-phishing-detect/src/detector')

This specific path is provided in the README for CommonJS advanced usage. While it uses `src/`, it's the documented CJS path for this class.

Demonstrates initializing the `PhishingDetector` with custom lists and checking various domains for phishing status, including legitimate, blacklisted, and fuzzy-matched examples.

import { PhishingDetector } from 'eth-phishing-detect/detector'; // Example configuration (these are just illustrative values) const whitelist = ['mylegitwallet.com']; const blacklist = ['fakephishingsite.net']; const fuzzylist = ['fuzzyphishing.io']; const tolerance = 2; const detector = new PhishingDetector({ whitelist, blacklist, fuzzylist, tolerance }); // Check a known phishing domain const resultPhishing = detector.check('fakephishingsite.net'); console.log('Is fakephishingsite.net phishing?', resultPhishing); // Expected: { type: 'blacklist', result: true, url: 'fakephishingsite.net' } // Check a legitimate domain const resultLegit = detector.check('google.com'); console.log('Is google.com phishing?', resultLegit); // Expected: { result: false, url: 'google.com' } // Check a fuzzy match const resultFuzzy = detector.check('fuzzyphising.io'); // typo 'phising' console.log('Is fuzzyphising.io phishing?', resultFuzzy); // Expected: { type: 'fuzzylist', result: true, url: 'fuzzyphising.io', ... }

Debug

Known issues

breakingVersion 1.2.0 changed the configuration object and return value if an array of configuration values is passed to the PhishingDetector constructor. While backward compatible for single configuration objects, new usage with arrays will have a different API shape and return type.

fix

Review the documentation for `PhishingDetector` constructor when passing an array of configurations. Adjust code to handle the new return value structure (e.g., an array of results instead of a single object).

affects: >=1.2.0

gotchaThe README's advanced usage example for CommonJS directly imports from `eth-phishing-detect/src/detector`. Directly importing from `src/` paths is generally discouraged as they are often internal, unstable, and may change in minor or patch releases, potentially breaking your application.

fix

For CommonJS, use the documented `require('eth-phishing-detect/src/detector')` if you must, but be aware of potential instability. For ESM, prefer `import { PhishingDetector } from 'eth-phishing-detect/detector'` for potentially better stability and compatibility.

affects: >=1.0.0

gotchaThe blocking policy for phishing domains is constantly evolving and updated by MetaMask. While this ensures up-to-date protection, it means the exact list of blocked domains can change without a new package version, only through configuration updates.

fix

Integrators should be aware that the underlying blocklist is dynamic. Avoid hardcoding assumptions about specific blocked or whitelisted domains. Regularly check the interactive page or library updates for policy changes.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: checkForPhishing is not a function

Attempting to import `checkForPhishing` as a named export in CommonJS, or incorrectly destructuring the default ESM import.

fix

For CommonJS: `const checkForPhishing = require('eth-phishing-detect')`. For ESM: `import checkForPhishing from 'eth-phishing-detect'`.

Cannot find module 'eth-phishing-detect/src/detector'

This error can occur in ESM environments or with certain bundler configurations if the `src/` path is not correctly resolved as a subpath export, or if the `detector` module has been refactored.

fix

For ESM, try `import { PhishingDetector } from 'eth-phishing-detect/detector'`. If using CJS and facing this issue, ensure your build system supports direct `src/` imports or check for an alternative, stable path in the package's `package.json` `exports` field.

Upgrade

Version history

1.2.0latest on npm

Audit

Dependencies

@metamask/phishing-controllerrequiredCore dependency for phishing detection logic and data management.

fastest-levenshteinrequiredLikely used for fuzzy matching domains to detect variations of known phishing sites.

Agent activity

20 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/MetaMask/eth-phishing-detect ↗

packagehttps://www.npmjs.com/package/eth-phishing-detect ↗