Download the PHP package ngfw/dnsdumpster without Composer

DNSDumpster - Laravel Service Provider

A Laravel package for fetching and managing DNS reconnaissance data using the DNSDumpster API. This package simplifies integration with the API, enabling you to query domain-related data directly within your Laravel application.

Features

• Rate Limiting: Built-in rate limiting (1 request per 2 seconds) to comply with API restrictions
• Caching: Optional caching support to reduce API calls and improve performance
• Retry Logic: Automatic retry mechanism for failed requests
• Bulk Lookups: Support for querying multiple domains at once
• Custom Exceptions: Specific exception types for better error handling
• Logging: Optional logging support for debugging and monitoring
• CLI Command: Artisan command for testing and manual lookups
• Full Test Coverage: Comprehensive test suite with PHPUnit
• Static Analysis: PHPStan integration for code quality
• CI/CD: GitHub Actions workflow for automated testing

Installation

Install the package using Composer:

The package will automatically register the service provider.

Configuration

Publish the configuration file:

Add the required environment variables to your .env file:

You can obtain your key here: dnsdumpster api

Configuration Options:

• DNSDumpster_API_KEY: Your API key (required)
• DNSDumpster_API_URL: The API endpoint URL (required)
• DNSDumpster_ENABLE_LOGGING: Enable logging for debugging (optional, default: false)
• DNSDumpster_CACHE_ENABLED: Enable caching of API responses (optional, default: true)
• DNSDumpster_CACHE_TTL: Cache time-to-live in seconds (optional, default: 3600)

Usage

Basic Usage

Here's how you can fetch domain data using this package:

1. Using Dependency Injection

2. Using the Facade-like Access

3. Using the app() Helper

Advanced Features

Pagination

For domains with more than 200 host records, use pagination to retrieve additional results:

Cache Management

Force refresh data from the API, bypassing cache:

Clear cache for a specific domain:

Bulk Domain Lookups

Query multiple domains at once:

CLI Command

Use the Artisan command for quick lookups:

Exception Handling

The package provides custom exceptions for better error handling:

• ConfigurationException: Thrown when API configuration is missing or invalid
• InvalidDomainException: Thrown when an invalid domain is provided
• RateLimitException: Thrown when API rate limit is exceeded
• ApiException: Thrown when an API request fails

Rate Limiting

The package includes built-in rate-limiting logic to prevent exceeding the API's limit of 1 request per 2 seconds. This is handled automatically and transparently.

Development

Running Tests

Running PHPStan

Generating Code Coverage

API Response Format

The API returns data in the following format:

Troubleshooting

Common Issues

Rate Limit Exceeded

• The API enforces a rate limit of 1 request per 2 seconds
• The package automatically handles this with built-in rate limiting
• If you still encounter issues, enable caching to reduce API calls

Invalid API Key

• Ensure your API key is set correctly in the .env file
• Verify the key is valid at dnsdumpster.com/developer/

Configuration Not Found

• Run php artisan vendor:publish --tag=dnsdumpster-config to publish the config file
• Ensure environment variables are set correctly

Debugging

Enable logging in your .env file:

Then check your Laravel logs for detailed information:

Changelog

Refer to the CHANGELOG for details on recent changes.

Contributing

Contributions are welcome! Please see CONTRIBUTING for guidelines.

Credits

• Nick Gejadze
• All Contributors

License

This package is open-sourced software licensed under the MIT License.