Skip to main content

Security "x-ray" for ENS names

Project description

NameGuard Python

Tests Coverage

The NameHash team is proud to present NameGuard, a tool for identifying and preventing malicious use of ENS names.

  • Offers multiple levels of protection
    • Impersonated name detection
    • Confusable grapheme detection
    • International accessibility checks
    • Rendering checks for different fonts
    • ENSIP-15 verification with detailed explanations and auto-suggestions (provided by ens-normalize-python)
    • Punycode and DNS hostname compatibility checks
    • and more!
  • Provides a unified rating system for entire names, as well as detailed explanations for each check
    • :green_circle: Pass: no issues found
    • :yellow_circle: Warn: potential issues found
    • :red_circle: Fail: serious issues found
  • Supports many use cases

⚠️ This package and API is BETA. Things will change based on community feedback.

Getting Started

This package contains the core logic for NameGuard, a python library and web API server.

Try the official web app

Using the public API

NameGuard is hosted at https://api.nameguard.io

You can make a basic request to the API like this:

curl https://api.nameguard.io/inspect-name/mainnet/nick.eth

The API documentation is available at https://api.nameguard.io/redoc or https://api.nameguard.io/docs.

Using the TypeScript SDK

Quickstart:

npm install @namehash/nameguard
import { nameguard } from "@namehash/nameguard";
await nameguard.inspectName("nick.eth");

See the SDK README for more details.

Using the Python library

NameGuard is available as a Python library on PyPI. You can install it with pip:

pip install nameguard
from nameguard import NameGuard
ng = NameGuard()
await ng.inspect_name(network_name='mainnet', name='nick.eth')

See the NameGuard Python README for more details.

Environment Variables

NameGuard uses the specified Provider endpoints (e.g. Alchemy, Infura, your own Ethereum node, etc...) for secure-primary-name/. Provider endpoints have to be set by environment variables, e.g.:

export PROVIDER_URI_MAINNET=https://eth-mainnet.g.alchemy.com/v2/[YOUR_ALCHEMY_API_KEY]
export PROVIDER_URI_SEPOLIA=https://eth-sepolia.g.alchemy.com/v2/[YOUR_ALCHEMY_API_KEY]
export ALCHEMY_URI_MAINNET=https://eth-mainnet.g.alchemy.com/v2/[YOUR_ALCHEMY_API_KEY]
export ALCHEMY_URI_SEPOLIA=https://eth-sepolia.g.alchemy.com/v2/[YOUR_ALCHEMY_API_KEY]
export ENS_SUBGRAPH_URL_MAINNET="https://gateway-arbitrum.network.thegraph.com/api/[YOUR_SUBGRAPH_API_KEY]/subgraphs/id/5XqPmWe6gjyrJtFn9cLy237i4cWw2j9HcUJEXsP5qGtH"
export ENS_SUBGRAPH_URL_SEPOLIA="https://gateway-arbitrum.network.thegraph.com/api/[YOUR_SUBGRAPH_API_KEY]/subgraphs/id/DmMXLtMZnGbQXASJ7p1jfzLUbBYnYUD9zNBTxpkjHYXV"

Starting the webserver

A FastAPI application is included in the nameguard.web_api module. The default installation from PyPI does not include an ASGI server, so you will need to install one separately. For example, to install uvicorn:

pip install 'uvicorn[standard]'

You can start the web server with:

uvicorn nameguard.web_api:app

Make an example request:

curl -d '{"name":"nick.eth", "network_name": "mainnet"}' -H "Content-Type: application/json" -X POST http://localhost:8000/inspect-name
# {
#   "rating": "pass",
#   "risk_count": 0,
#   "highest_risk": null,
#   "name": "nick.eth",
#   "namehash": "0x05a67c0ee82964c4f7394cdd47fee7f4d9503a23c09c38341779ea012afe6e00",
#   "normalization": "normalized",
#   "checks": [...],
#   "labels": [...],
#   "canonical_name": "nick.eth",
#   "title": "Looks Good",
#   "subtitle": "All security checks passed!",
#   "beautiful_name": "nick.eth"
# }

Development

Running tests

Before running nameguard tests, make sure you have installed the required dependencies (along with dev dependencies). They are installed by default using poetry:

poetry install

To run nameguard tests locally, just run pytest from the root directory:

pytest ./packages/nameguard-python/tests/

NameGuard also provides an option to run API tests (packages/nameguard-python/tests/test_api.py) against a remote host (e.g. Lambda) where a NameGuard instance is running. To enable this, you will need to set an environment variable LAMBDA_ROOT_URL to specify the remote host URL.

This can be done like this:

LAMBDA_ROOT_URL=https://api.nameguard.io poetry run pytest packages/nameguard-python/tests/test_api.py

Using the AWS Lambda handler

NameGuard includes a handler for Amazon AWS Lambda. It is available in the nameguard.lambda module. You can use it to create a Lambda function that will respond to HTTP requests. It uses the mangum library.

Check out the included Dockerfile for an example of how to build a Lambda container image.

See the AWS Lambda deployment scripts for more details.

Disable monkeypatch tests

By default, the tests are using mock responses from external APIs. If you want to run tests using real requests to external APIs then set MONKEYPATCH=0.

MONKEYPATCH=0 poetry run pytest

NameGuard Specification

Checks

  1. Impersonation: Detects names that could be trying to impersonate a different name by using similar characters. Example: vitalìk.eth

  2. Confusables: Detects characters that can be confused with other characters. Example: vitalìk.eth

  3. Font Support: Checks if the characters in the name are supported by commonly used fonts. Example: 🛈.eth

  4. Invisibles: Detects invisible characters. Example: 888‍‍.eth

  5. Typing Difficulty: Detects names that are difficult to type on some keyboards. Example: żółć.eth

  6. Mixed Scripts: Detects names that contain characters from multiple scripts or alphabets. Example: あア.eth

  7. Name Wrapper: Checks if the name is supported by the new ENS Name Wrapper. Example: abcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcd.eth

  8. ENSIP-15: Checks if the name is normalized according to ENSIP-15. Example: bitсoin.eth

  9. Punycode: Checks if the name is compatible with Punycode encoding. Example: ab--abc.eth

  10. Unknown Labels: Checks if the name contains unknown labels. Example: [5bc926fc40cc7c49e0df6dddf26e4dc7b9d6d32f4a55d4f0670320dbf414afd2].byongdok.eth

  11. Decentralized Name: Checks if the name is decentralized (unruggable). Example: example.com

  12. NameWrapper fuses: Checks that the NameWrapper configuration of a name is safe.

  13. Uninspected Name: Checks if the name is exceptionally long and would not be inspected by NameGuard for performance reasons.

License

Licensed under the MIT License, Copyright © 2023-present NameHash Labs.

See LICENSE for more information.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

nameguard-0.1.10.tar.gz (36.3 kB view details)

Uploaded Source

Built Distribution

nameguard-0.1.10-py3-none-any.whl (46.3 kB view details)

Uploaded Python 3

File details

Details for the file nameguard-0.1.10.tar.gz.

File metadata

  • Download URL: nameguard-0.1.10.tar.gz
  • Upload date:
  • Size: 36.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.12.7

File hashes

Hashes for nameguard-0.1.10.tar.gz
Algorithm Hash digest
SHA256 da9a54fdaeab0dc14a23d709d5cd146be4dc6d48d9db515129359e92af0d02b3
MD5 cf83b795900d2931bd5141ddd8c44192
BLAKE2b-256 13bae8ebeaca3cc2ee30d071ee7a14f92eaf28f1e771acc2ab316bd247fc0231

See more details on using hashes here.

File details

Details for the file nameguard-0.1.10-py3-none-any.whl.

File metadata

  • Download URL: nameguard-0.1.10-py3-none-any.whl
  • Upload date:
  • Size: 46.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/5.0.0 CPython/3.12.7

File hashes

Hashes for nameguard-0.1.10-py3-none-any.whl
Algorithm Hash digest
SHA256 a22dc47789445ad5bd5707f7a3a812063476a8c9d09f8515d38eaffdda6ac47b
MD5 e4891565bda85ea00ca65367fdf9a47a
BLAKE2b-256 bdd78f20e90dd41d4845645b5b99cb295075eeb90c712dabf8e8ae52d1cec8a7

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page