Security "x-ray" for ENS names
Project description
NameGuard Python
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
- Standalone Python library (PyPI)
- ASGI web server
- Amazon AWS Lambda handler
⚠️ 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
-
Impersonation: Detects names that could be trying to impersonate a different name by using similar characters. Example:
vitalìk.eth
-
Confusables: Detects characters that can be confused with other characters. Example:
vitalìk.eth
-
Font Support: Checks if the characters in the name are supported by commonly used fonts. Example:
🛈.eth
-
Invisibles: Detects invisible characters. Example:
888.eth
-
Typing Difficulty: Detects names that are difficult to type on some keyboards. Example:
żółć.eth
-
Mixed Scripts: Detects names that contain characters from multiple scripts or alphabets. Example:
あア.eth
-
Name Wrapper: Checks if the name is supported by the new ENS Name Wrapper. Example:
abcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcdabcd.eth
-
ENSIP-15: Checks if the name is normalized according to ENSIP-15. Example:
bitсoin.eth
-
Punycode: Checks if the name is compatible with Punycode encoding. Example:
ab--abc.eth
-
Unknown Labels: Checks if the name contains unknown labels. Example:
[5bc926fc40cc7c49e0df6dddf26e4dc7b9d6d32f4a55d4f0670320dbf414afd2].byongdok.eth
-
Decentralized Name: Checks if the name is decentralized (unruggable). Example:
example.com
-
NameWrapper fuses: Checks that the NameWrapper configuration of a name is safe.
-
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
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | da9a54fdaeab0dc14a23d709d5cd146be4dc6d48d9db515129359e92af0d02b3 |
|
MD5 | cf83b795900d2931bd5141ddd8c44192 |
|
BLAKE2b-256 | 13bae8ebeaca3cc2ee30d071ee7a14f92eaf28f1e771acc2ab316bd247fc0231 |
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | a22dc47789445ad5bd5707f7a3a812063476a8c9d09f8515d38eaffdda6ac47b |
|
MD5 | e4891565bda85ea00ca65367fdf9a47a |
|
BLAKE2b-256 | bdd78f20e90dd41d4845645b5b99cb295075eeb90c712dabf8e8ae52d1cec8a7 |