DNSRecon - Passive Infrastructure Reconnaissance Tool
DNSRecon is an interactive, passive reconnaissance tool designed to map adversary infrastructure. It operates on a "free-by-default" model, ensuring core functionality without subscriptions, while allowing power users to enhance its capabilities with paid API keys.
Current Status: Phase 2 Implementation
- ✅ Core infrastructure and graph engine
- ✅ Multi-provider support (crt.sh, DNS, Shodan)
- ✅ Session-based multi-user support
- ✅ Real-time web interface with interactive visualization
- ✅ Forensic logging system and JSON export
Features
- Passive Reconnaissance: Gathers data without direct contact with target infrastructure.
- In-Memory Graph Analysis: Uses NetworkX for efficient relationship mapping.
- Real-Time Visualization: The graph updates dynamically as the scan progresses.
- Forensic Logging: A complete audit trail of all reconnaissance activities is maintained.
- Confidence Scoring: Relationships are weighted based on the reliability of the data source.
- Session Management: Supports concurrent user sessions with isolated scanner instances.
Installation
Prerequisites
- Python 3.8 or higher
- A modern web browser with JavaScript enabled
- (Recommended) A Linux host for running the application and the optional DNS cache.
1. Clone the Project
git clone https://github.com/your-repo/dnsrecon.git
cd dnsrecon
2. Install Python Dependencies
It is highly recommended to use a virtual environment:
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
The requirements.txt file contains the following dependencies:
- Flask>=2.3.3
- networkx>=3.1
- requests>=2.31.0
- python-dateutil>=2.8.2
- Werkzeug>=2.3.7
- urllib3>=2.0.0
- dnspython>=2.4.2
- gunicorn
- redis
- python-dotenv
Configuration
DNSRecon is configured using a .env file. You can copy the provided example file and edit it to suit your needs:
cp .env.example .env
The following environment variables are available for configuration:
| Variable | Description | Default |
|---|---|---|
SHODAN_API_KEY |
Your Shodan API key. | |
FLASK_SECRET_KEY |
A strong, random secret key for session security. | your-very-secret-and-random-key-here |
FLASK_HOST |
The host address for the Flask application. | 127.0.0.1 |
FLASK_PORT |
The port for the Flask application. | 5000 |
FLASK_DEBUG |
Enable or disable Flask's debug mode. | True |
FLASK_PERMANENT_SESSION_LIFETIME_HOURS |
How long a user's session in the browser lasts (in hours). | 2 |
SESSION_TIMEOUT_MINUTES |
How long inactive scanner data is stored in Redis (in minutes). | 60 |
DEFAULT_RECURSION_DEPTH |
The default number of levels to recurse when scanning. | 2 |
DEFAULT_TIMEOUT |
Default timeout for provider API requests in seconds. | 30 |
MAX_CONCURRENT_REQUESTS |
The number of concurrent provider requests to make. | 5 |
LARGE_ENTITY_THRESHOLD |
The number of results from a provider that triggers the "large entity" grouping. | 100 |
MAX_RETRIES_PER_TARGET |
The number of times to retry a target if a provider fails. | 8 |
CACHE_EXPIRY_HOURS |
How long cached provider responses are stored (in hours). | 12 |
Systemd Service
To run DNSRecon as a service that starts automatically on boot, you can use systemd.
1. Create a .service file
Create a new service file in /etc/systemd/system/:
sudo nano /etc/systemd/system/dnsrecon.service
2. Add the Service Configuration
Paste the following configuration into the file. Remember to replace /path/to/your/dnsrecon and your_user with your actual project path and username.
[Unit]
Description=DNSRecon Application
After=network.target
[Service]
User=your_user
Group=your_user
WorkingDirectory=/path/to/your/dnsrecon
ExecStart=/path/to/your/dnsrecon/venv/bin/gunicorn --workers 4 --bind 0.0.0.0:5000 app:app
Restart=always
Environment="SECRET_KEY=your-super-secret-and-random-key"
Environment="FLASK_ENV=production"
Environment="FLASK_DEBUG=False"
Environment="SHODAN_API_KEY=your_shodan_key"
[Install]
WantedBy=multi-user.target
3. Enable and Start the Service
Reload the systemd daemon, enable the service to start on boot, and then start it immediately:
sudo systemctl daemon-reload
sudo systemctl enable dnsrecon.service
sudo systemctl start dnsrecon.service
You can check the status of the service at any time with:
sudo systemctl status dnsrecon.service
License
This project is licensed under the terms of the BSD-3-Clause license.
Copyright (c) 2025 mstoeck3.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.