Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
⚠️ IMPORTANT DISCLAIMER: This is an UNOFFICIAL API wrapper for dnsdumpster.com that scrapes the public website.
DNSDumpster.com offers an official API plan for commercial and heavy usage. If you need reliable, production-grade access, please consider their official API: https://dnsdumpster.com/
This unofficial wrapper should be used responsibly and in accordance with DNSDumpster's terms of service.
A Python client library for interacting with dnsdumpster.com to retrieve DNS records and subdomain information. This tool is useful for security researchers, penetration testers, and network administrators for reconnaissance purposes.
- 🔍 Retrieve A, MX, NS, and TXT records for a domain
- 🌐 Extract subdomain information
- 🗺️ Download network mapping images
- 📊 Export results to Excel format
- 🎯 Clean, type-hinted API
- ✅ Comprehensive test coverage
- 📝 Full backward compatibility
pip install dnsdumpsterpip install git+https://github.com/PaulSec/API-dnsdumpster.com.git# Clone the repository
git clone https://github.com/PaulSec/API-dnsdumpster.com
cd API-dnsdumpster.com
# Install in development mode
pip install -e .
# Install development dependencies
pip install -r requirements-dev.txtfrom dnsdumpster.DNSDumpsterAPI import DNSDumpsterAPI
# Initialize the API
api = DNSDumpsterAPI(verbose=True)
# Search for a domain
results = api.search('example.com')
# Access the results
print(f"Domain: {results['domain']}")
print(f"DNS Records: {results['dns_records']['dns']}")
print(f"MX Records: {results['dns_records']['mx']}")
print(f"NS Records: {results['dns_records']['ns']}")
print(f"TXT Records: {results['dns_records']['txt']}")from dnsdumpster.DNSDumpsterAPI import DNSDumpsterAPI
api = DNSDumpsterAPI()
results = api.search('microsoft.com')
# Print all A records (subdomains)
for record in results['dns_records']['dns']:
print(f"{record['host']} - {record['ip']} - {record['country']}")import base64
results = api.search('example.com')
if results['image_data']:
with open('network_map.png', 'wb') as f:
f.write(base64.b64decode(results['image_data']))
print(f"Network map saved! URL: {results['image_url']}")import base64
results = api.search('example.com')
if results['xls_data']:
with open('results.xlsx', 'wb') as f:
f.write(base64.b64decode(results['xls_data']))
print("Excel file saved!")import requests
from dnsdumpster.DNSDumpsterAPI import DNSDumpsterAPI
# Create custom session with proxy
session = requests.Session()
session.proxies = {
'http': 'http://proxy.example.com:8080',
'https': 'https://proxy.example.com:8080',
}
api = DNSDumpsterAPI(session=session)
results = api.search('example.com')from dnsdumpster.DNSDumpsterAPI import (
DNSDumpsterAPI,
DNSDumpsterAPIError,
DNSDumpsterRequestError,
DNSDumpsterParseError
)
api = DNSDumpsterAPI()
try:
results = api.search('example.com')
except DNSDumpsterRequestError as e:
print(f"Network error: {e}")
except DNSDumpsterParseError as e:
print(f"Parsing error: {e}")
except DNSDumpsterAPIError as e:
print(f"API error: {e}")The search() method returns a dictionary with the following structure:
{
'domain': 'example.com',
'dns_records': {
'dns': [ # A Records (subdomains)
{
'host': 'subdomain.example.com',
'ip': '192.0.2.1',
'reverse_dns': 'reverse.dns.com',
'asn': 'ASN:12345',
'asn_name': 'Provider Name',
'country': 'United States',
'subnet': '192.0.2.0/24',
'open_services': '80, 443',
# Backward compatibility keys:
'domain': 'subdomain.example.com',
'as': 'ASN:12345',
'provider': 'Provider Name'
}
],
'mx': [ # MX Records
{
'priority': '10',
'server': 'mail.example.com',
'ip': '198.51.100.1',
'reverse_dns': 'mail.reverse.com',
'asn': 'ASN:23456',
'asn_name': 'Mail Provider',
'country': 'Germany',
'subnet': '198.51.100.0/24'
}
],
'ns': [ # NS Records
{
'nameserver': 'ns1.example.com',
'ip': '203.0.113.1',
'reverse_dns': 'ns1.reverse.com',
'asn': 'ASN:34567',
'asn_name': 'DNS Provider',
'country': 'United Kingdom',
'subnet': '203.0.113.0/24'
}
],
'txt': [ # TXT Records
'v=spf1 include:_spf.example.com ~all',
'google-site-verification=abcdef123456'
],
'host': [] # Alias for NS records (backward compatibility)
},
'image_data': b'base64_encoded_image_bytes', # or None
'image_url': 'https://dnsdumpster.com/static/map/example.com.png',
'xls_data': b'base64_encoded_excel_bytes', # or None
'xls_url': 'https://dnsdumpster.com/static/xlsx/example-uuid.xlsx'
}# Clone the repository
git clone https://github.com/PaulSec/API-dnsdumpster.com
cd API-dnsdumpster.com
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt
# Install pre-commit hooks (optional)
pip install pre-commit
pre-commit install# Run all tests
pytest
# Run with coverage
pytest --cov=dnsdumpster --cov-report=html
# Run specific test file
pytest tests/test_parsing.py
# Run with verbose output
pytest -v
# Run specific test
pytest tests/test_parsing.py::TestRetrieveResults::test_retrieve_results_basic# Format code with black
black dnsdumpster/ tests/
# Sort imports
isort dnsdumpster/ tests/
# Lint with flake8
flake8 dnsdumpster/ tests/
# Type checking with mypy
mypy dnsdumpster/
# Run all quality checks
black dnsdumpster/ tests/ && isort dnsdumpster/ tests/ && flake8 dnsdumpster/ tests/ && mypy dnsdumpster/API-dnsdumpster.com/ ├── dnsdumpster/ # Main package │ ├── __init__.py │ ├── DNSDumpsterAPI.py # Main API class │ ├── API_example.py # Usage example │ └── requirements.txt ├── tests/ # Test suite │ ├── __init__.py │ ├── conftest.py # Pytest fixtures │ ├── test_parsing.py # Unit tests │ └── test_integration.py # Integration tests ├── .github/ │ └── workflows/ # CI/CD workflows │ ├── tests.yml │ └── publish.yml ├── requirements.txt # Production dependencies ├── requirements-dev.txt # Development dependencies ├── setup.py # Package configuration ├── README.md └── LICENSE
We welcome contributions! Here's how you can help:
- Use GitHub Issues to report bugs
- Include Python version, OS, and error messages
- Provide minimal reproducible examples
- Fork the repository
- Create a feature branch (git checkout -b feature/amazing-feature)
- Make your changes
- Add tests for new functionality
- Ensure all tests pass (pytest)
- Run code quality checks (black, flake8, mypy)
- Commit your changes (git commit -m 'Add amazing feature')
- Push to the branch (git push origin feature/amazing-feature)
- Open a Pull Request
- Follow PEP 8 style guide
- Add type hints to all functions
- Write docstrings for public methods
- Maintain backward compatibility
- Keep test coverage above 80%
- Update documentation for new features
Test individual parsing methods without network calls:
pytest tests/test_parsing.py -vTest the full API workflow with mocked HTTP responses:
pytest tests/test_integration.py -vpytest --cov=dnsdumpster --cov-report=term-missingThe project uses GitHub Actions for:
- Testing: Runs on every push and PR across Python 3.8, 3.9, 3.10, 3.11, 3.12
- Linting: Code quality checks with flake8 and mypy
- Publishing: Automatic PyPI deployment on tagged releases
This project is licensed under the MIT License - see the LICENSE file for details.
This is an unofficial tool and is not affiliated with or endorsed by dnsdumpster.com. Use responsibly and in accordance with the target website's terms of service and robots.txt. The authors are not responsible for misuse of this tool.
- 📧 For bugs and feature requests, use GitHub Issues
- 💬 For general questions, start a GitHub Discussion
- 🐦 Follow the author on Twitter: @PaulWebSec
- Complete code refactoring with type hints
- Improved error handling with custom exceptions
- Comprehensive test suite with pytest
- Better documentation and examples
- CI/CD with GitHub Actions
- Full backward compatibility maintained
See CHANGELOG.md for full version history.
- Original author: PaulSec
- Contributors: See CONTRIBUTORS.md
- DNSDumpster.com for providing the service