dnsdumpster 0.11.0

UNOFFICIAL Python API wrapper for dnsdumpster.com

DNSDumpster API (UNOFFICIAL)

⚠️ 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.

Overview

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.

Features

• 🔍 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

Installation

From PyPI (Recommended)

pip install dnsdumpster

From GitHub

pip install git+https://github.com/PaulSec/API-dnsdumpster.com.git

From Source (Development)

# 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.txt

Quick Start

from 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']}")

Usage Examples

Basic Domain Lookup

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']}")

Save Network Map Image

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']}")

Export to Excel

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!")

Using Custom Session

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')

Error Handling

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}")

API Response Structure

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'
}

Development

Setup Development Environment

# 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

Running Tests

# 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

Code Quality

# 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/

Project Structure

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

Contributing

We welcome contributions! Here's how you can help:

Reporting Issues

• Use GitHub Issues to report bugs
• Include Python version, OS, and error messages
• Provide minimal reproducible examples

Submitting Pull Requests

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (pytest)
6. Run code quality checks (black, flake8, mypy)
7. Commit your changes (git commit -m 'Add amazing feature')
8. Push to the branch (git push origin feature/amazing-feature)
9. Open a Pull Request

Coding Guidelines

• 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

Testing Instructions

Unit Tests

Test individual parsing methods without network calls:

pytest tests/test_parsing.py -v

Integration Tests

Test the full API workflow with mocked HTTP responses:

pytest tests/test_integration.py -v

Coverage Report

pytest --cov=dnsdumpster --cov-report=term-missing

CI/CD

The 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

License

This project is licensed under the MIT License - see the LICENSE file for details.

Disclaimer

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.

Support

• 📧 For bugs and feature requests, use GitHub Issues
• 💬 For general questions, start a GitHub Discussion
• 🐦 Follow the author on Twitter: @PaulWebSec

Changelog

Version 0.10 (Current)

• 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

Previous Versions

See CHANGELOG.md for full version history.

Acknowledgments

• Original author: PaulSec
• Contributors: See CONTRIBUTORS.md
• DNSDumpster.com for providing the service