# DNSBL Checker
[](https://github.com/O-X-L/dnsbl-checker/actions/workflows/lint.yml)
[](https://github.com/O-X-L/dnsbl-checker/actions/workflows/test.yml)
This script/library can check if an IP or Domain is listed on DNS-BL's.
Please be aware that the providers of such public DNSBL mirrors discourage high-volume lookups. Do not abuse their services! You will run into rate-limits.
**Features**:
* Asynchronous DNS requests
* Multi-provider support
* Ability to add custom providers
* Check for 50+ lists usually takes a few seconds
* Can also check domains
This started as a fork of [github.com/dmippolitov/pydnsbl](https://github.com/dmippolitov/pydnsbl) - so thanks to the contributors ❤️
If you are interested in [report-based reputation-systems => check out our Risk-DB project](https://github.com/O-X-L/risk-db).
Tip: If you want to run your own DNS-BL server - check out our [DNS-BL microservice](https://github.com/O-X-L/dnsbl-server).
----
## Scope
* This script/library should act as a **simple tool** to query DNS-BL's for the user
* **Response Validation**
Interpreting if the provider's response is 'valid' is **out-of-scope** for this tool. (*like checking for false-positives*)
This heavily depends on the user's context.
Thus, the user should make sure to only use DNS-BL providers that are useful/safe for them to use.
We have added some info about providers here: [Providers.md](https://github.com/O-X-L/dnsbl-checker/blob/latest/Providers.md)
* Users that want to use DNS-BL lookups in commercial settings have to make sure to **read the usage policies of those providers**.
Some providers do not allow commercial usage in their free-tier.
If you want us to add additional providers or have found that existing ones have quit - [open an Issue](https://github.com/O-X-L/dnsbl-checker/issues) or [contact us per e-mail](mailto://contact+dnsblcheck@oxl.at)
----
## Installation
`pip install dnsbl-check`
----
## Usage
### Via CLI
```bash
dnsbl-check --help
usage: DNS-BL Lookup-Client [-h] (-i IP | -d DOMAIN) [-j] [-s SKIP_PROVIDERS]
[-a ADD_PROVIDERS] [-o ONLY_PROVIDERS] [--details]
options:
-h, --help show this help message and exit
-i IP, --ip IP IP to check
-d DOMAIN, --domain DOMAIN
Domain to check
-j JSON, --json JSON Only output JSON
-s SKIP_PROVIDERS, --skip-providers SKIP_PROVIDERS
Comma-separated list of base-providers to skip
-o ONLY_PROVIDERS, --only-providers ONLY_PROVIDERS
Comma-separated list of DNS-BL provider-domains to query
(ignoring the built-in default providers)
--details If the result details should be added to the output
```
**Example:**
```bash
dnsbl-check --ip 134.209.173.54
> Checking IP 134.209.173.54 ..
> {
> "detected": true,
> "detected_by": [
> "all.s5h.net",
> "dnsbl-3.uceprotect.net"
> ],
> "categories": [
> "unknown"
> ],
> "general_errors": [],
> "count": {
> "detected": 2,
> "checked": 43,
> "failed": 2
> }
> }
# add or skip DNS-BL providers:
dnsbl-check --ip=134.209.173.54 --add-providers dnsbl.risk.oxl.app,dnsbl.host-svc.com --skip-providers abuse.spfbl.net
```
----
### Programmatically
```python3
# IPs
from dnsbl_check import CheckIP
with CheckIP() as checker:
result = checker.check('134.209.173.54')
print(result)
# <DNSBLResult: 134.209.173.54 [DETECTED] (2/43)>
print(result.to_dict())
# {'request': '134.209.173.54', 'detected': True, 'detected_by': ['all.s5h.net', 'dnsbl-3.uceprotect.net'], 'categories': ['unknown'], 'general_errors': [], 'count': {'detected': 2, 'checked': 43, 'failed': 2}, 'detected_provider_categories': {'all.s5h.net': ['unknown'], 'dnsbl-3.uceprotect.net': ['unknown']}, 'checked_providers': ['all.s5h.net', 'aspews.ext.sorbs.net', 'b.barracudacentral.org', 'bl.nordspam.com', 'blacklist.woody.ch', 'bogons.cymru.com', 'combined.abuse.ch', 'db.wpbl.info', 'dnsbl-2.uceprotect.net', 'dnsbl-3.uceprotect.net', 'dnsbl.sorbs.net', 'drone.abuse.ch', 'ips.backscatterer.org', 'korea.services.net', 'matrix.spfbl.net', 'proxy.bl.gweep.ca', 'proxy.block.transip.nl', 'psbl.surriel.com', 'rbl.interserver.net', 'relays.bl.gweep.ca', 'relays.bl.kundenserver.de', 'relays.nether.net', 'residential.block.transip.nl', 'singular.ttk.pte.hu', 'spam.dnsbl.sorbs.net', 'spambot.bls.digibase.ca', 'spamlist.or.kr', 'spamrbl.swinog.ch', 'spamsources.fabel.dk', 'ubl.lashback.com', 'virus.rbl.jp', 'z.mailspike.net', 'zen.spamhaus.org'], 'failed_providers': ['ix.dnsbl.manitu.net', 'spamlist.or.kr']}
print(result.to_json())
# ... (to_dict but in pretty json)
# Domains
from dnsbl_check import CheckDomain
with CheckDomain() as checker:
result = checker.check('malware.com')
print(result)
# <DNSBLResult: malware.com (0/2)>
# add or skip DNS-BL providers
from dnsbl_check.provider import Provider, BASE_PROVIDERS_IP
providers = BASE_PROVIDERS_IP + [Provider('dnsbl.risk.oxl.app')]
with CheckIP(providers=providers, skip_providers=['abuse.spfbl.net']) as checker:
result = checker.check('134.209.173.54')
# add or skip DNS-BL providers
from dnsbl_check.provider import Provider, BASE_PROVIDERS_IP
providers = BASE_PROVIDERS_IP + [Provider('dnsbl.risk.oxl.app')]
with CheckIP(providers=providers, skip_providers=['abuse.spfbl.net']) as checker:
result = checker.check('134.209.173.54')
print(result)
# <DNSBLResult: 134.209.173.54 [DETECTED] (3/44)>
```
----
## Contributing
Contributions are welcome (:
See: [Contribute](https://github.com/O-X-L/dnsbl-checker/blob/latest/Contribute.md)
Raw data
{
"_id": null,
"home_page": null,
"name": "dnsbl-check",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "dnsbl, blocklists",
"author": null,
"author_email": "Rath Pascal <contact@oxl.at>",
"download_url": "https://files.pythonhosted.org/packages/4b/3b/80b19f9685df24a95e0bda0990860b9c98912616d2368742cdcee82dc53c/dnsbl_check-2.0.2.tar.gz",
"platform": null,
"description": "# DNSBL Checker\n\n[](https://github.com/O-X-L/dnsbl-checker/actions/workflows/lint.yml)\n[](https://github.com/O-X-L/dnsbl-checker/actions/workflows/test.yml)\n\nThis script/library can check if an IP or Domain is listed on DNS-BL's. \n\nPlease be aware that the providers of such public DNSBL mirrors discourage high-volume lookups. Do not abuse their services! You will run into rate-limits.\n\n**Features**:\n* Asynchronous DNS requests\n* Multi-provider support\n* Ability to add custom providers\n* Check for 50+ lists usually takes a few seconds\n* Can also check domains\n\nThis started as a fork of [github.com/dmippolitov/pydnsbl](https://github.com/dmippolitov/pydnsbl) - so thanks to the contributors \u2764\ufe0f\n\nIf you are interested in [report-based reputation-systems => check out our Risk-DB project](https://github.com/O-X-L/risk-db).\n\nTip: If you want to run your own DNS-BL server - check out our [DNS-BL microservice](https://github.com/O-X-L/dnsbl-server).\n\n----\n\n## Scope\n\n* This script/library should act as a **simple tool** to query DNS-BL's for the user\n\n* **Response Validation**\n\n Interpreting if the provider's response is 'valid' is **out-of-scope** for this tool. (*like checking for false-positives*)\n\n This heavily depends on the user's context.\n\n Thus, the user should make sure to only use DNS-BL providers that are useful/safe for them to use.\n\n We have added some info about providers here: [Providers.md](https://github.com/O-X-L/dnsbl-checker/blob/latest/Providers.md)\n\n* Users that want to use DNS-BL lookups in commercial settings have to make sure to **read the usage policies of those providers**.\n\n Some providers do not allow commercial usage in their free-tier.\n\nIf you want us to add additional providers or have found that existing ones have quit - [open an Issue](https://github.com/O-X-L/dnsbl-checker/issues) or [contact us per e-mail](mailto://contact+dnsblcheck@oxl.at)\n\n----\n\n## Installation\n\n`pip install dnsbl-check`\n\n----\n\n## Usage\n\n### Via CLI\n\n```bash\ndnsbl-check --help\nusage: DNS-BL Lookup-Client [-h] (-i IP | -d DOMAIN) [-j] [-s SKIP_PROVIDERS]\n [-a ADD_PROVIDERS] [-o ONLY_PROVIDERS] [--details]\n\noptions:\n -h, --help show this help message and exit\n -i IP, --ip IP IP to check\n -d DOMAIN, --domain DOMAIN\n Domain to check\n -j JSON, --json JSON Only output JSON\n -s SKIP_PROVIDERS, --skip-providers SKIP_PROVIDERS\n Comma-separated list of base-providers to skip\n -o ONLY_PROVIDERS, --only-providers ONLY_PROVIDERS\n Comma-separated list of DNS-BL provider-domains to query\n (ignoring the built-in default providers)\n --details If the result details should be added to the output\n```\n\n**Example:**\n\n```bash\ndnsbl-check --ip 134.209.173.54\n> Checking IP 134.209.173.54 ..\n> {\n> \"detected\": true,\n> \"detected_by\": [\n> \"all.s5h.net\",\n> \"dnsbl-3.uceprotect.net\"\n> ],\n> \"categories\": [\n> \"unknown\"\n> ],\n> \"general_errors\": [],\n> \"count\": {\n> \"detected\": 2,\n> \"checked\": 43,\n> \"failed\": 2\n> }\n> }\n\n# add or skip DNS-BL providers:\ndnsbl-check --ip=134.209.173.54 --add-providers dnsbl.risk.oxl.app,dnsbl.host-svc.com --skip-providers abuse.spfbl.net\n```\n\n----\n\n### Programmatically\n\n```python3\n# IPs\nfrom dnsbl_check import CheckIP\nwith CheckIP() as checker:\n result = checker.check('134.209.173.54')\n\nprint(result)\n# <DNSBLResult: 134.209.173.54 [DETECTED] (2/43)>\nprint(result.to_dict())\n# {'request': '134.209.173.54', 'detected': True, 'detected_by': ['all.s5h.net', 'dnsbl-3.uceprotect.net'], 'categories': ['unknown'], 'general_errors': [], 'count': {'detected': 2, 'checked': 43, 'failed': 2}, 'detected_provider_categories': {'all.s5h.net': ['unknown'], 'dnsbl-3.uceprotect.net': ['unknown']}, 'checked_providers': ['all.s5h.net', 'aspews.ext.sorbs.net', 'b.barracudacentral.org', 'bl.nordspam.com', 'blacklist.woody.ch', 'bogons.cymru.com', 'combined.abuse.ch', 'db.wpbl.info', 'dnsbl-2.uceprotect.net', 'dnsbl-3.uceprotect.net', 'dnsbl.sorbs.net', 'drone.abuse.ch', 'ips.backscatterer.org', 'korea.services.net', 'matrix.spfbl.net', 'proxy.bl.gweep.ca', 'proxy.block.transip.nl', 'psbl.surriel.com', 'rbl.interserver.net', 'relays.bl.gweep.ca', 'relays.bl.kundenserver.de', 'relays.nether.net', 'residential.block.transip.nl', 'singular.ttk.pte.hu', 'spam.dnsbl.sorbs.net', 'spambot.bls.digibase.ca', 'spamlist.or.kr', 'spamrbl.swinog.ch', 'spamsources.fabel.dk', 'ubl.lashback.com', 'virus.rbl.jp', 'z.mailspike.net', 'zen.spamhaus.org'], 'failed_providers': ['ix.dnsbl.manitu.net', 'spamlist.or.kr']}\nprint(result.to_json())\n# ... (to_dict but in pretty json)\n\n# Domains\nfrom dnsbl_check import CheckDomain\nwith CheckDomain() as checker:\n result = checker.check('malware.com')\n\nprint(result)\n# <DNSBLResult: malware.com (0/2)>\n\n# add or skip DNS-BL providers\nfrom dnsbl_check.provider import Provider, BASE_PROVIDERS_IP\nproviders = BASE_PROVIDERS_IP + [Provider('dnsbl.risk.oxl.app')]\nwith CheckIP(providers=providers, skip_providers=['abuse.spfbl.net']) as checker:\n result = checker.check('134.209.173.54')\n\n# add or skip DNS-BL providers\nfrom dnsbl_check.provider import Provider, BASE_PROVIDERS_IP\nproviders = BASE_PROVIDERS_IP + [Provider('dnsbl.risk.oxl.app')]\nwith CheckIP(providers=providers, skip_providers=['abuse.spfbl.net']) as checker:\n result = checker.check('134.209.173.54')\n\nprint(result)\n# <DNSBLResult: 134.209.173.54 [DETECTED] (3/44)>\n```\n\n----\n\n## Contributing\n\nContributions are welcome (:\n\nSee: [Contribute](https://github.com/O-X-L/dnsbl-checker/blob/latest/Contribute.md)\n",
"bugtrack_url": null,
"license": null,
"summary": "OXL DNSBL Checker",
"version": "2.0.2",
"project_urls": {
"Documentation": "https://github.com/O-X-L/dnsbl-checker",
"Homepage": "https://www.oxl.at",
"Issues": "https://github.com/O-X-L/dnsbl-checker/issues",
"Repository": "https://github.com/O-X-L/dnsbl-checker.git"
},
"split_keywords": [
"dnsbl",
" blocklists"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "822c659d459e8763fab0bcd011e6cfdf78d2f7a140984dc9f1cc6380100daf0c",
"md5": "7c9e7972cb681a0dc4f4a1718d7ab509",
"sha256": "f41e644db5827d0500c3815d3683a15ef1445b06ecf3df8864caba48027b3fff"
},
"downloads": -1,
"filename": "dnsbl_check-2.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7c9e7972cb681a0dc4f4a1718d7ab509",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 17391,
"upload_time": "2025-07-27T10:07:05",
"upload_time_iso_8601": "2025-07-27T10:07:05.235253Z",
"url": "https://files.pythonhosted.org/packages/82/2c/659d459e8763fab0bcd011e6cfdf78d2f7a140984dc9f1cc6380100daf0c/dnsbl_check-2.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "4b3b80b19f9685df24a95e0bda0990860b9c98912616d2368742cdcee82dc53c",
"md5": "acb81654ee0781f125ed0de3087417ba",
"sha256": "255dba70fd6d71a466be1f9f4a84ec1abd43276a11c43ca652d225b31d62f658"
},
"downloads": -1,
"filename": "dnsbl_check-2.0.2.tar.gz",
"has_sig": false,
"md5_digest": "acb81654ee0781f125ed0de3087417ba",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 15926,
"upload_time": "2025-07-27T10:07:06",
"upload_time_iso_8601": "2025-07-27T10:07:06.827964Z",
"url": "https://files.pythonhosted.org/packages/4b/3b/80b19f9685df24a95e0bda0990860b9c98912616d2368742cdcee82dc53c/dnsbl_check-2.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-27 10:07:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "O-X-L",
"github_project": "dnsbl-checker",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "idna",
"specs": []
},
{
"name": "aiodns",
"specs": []
}
],
"lcname": "dnsbl-check"
}
JSON
