160 lines
6.1 KiB
Markdown
160 lines
6.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
git clone https://github.com/your-repo/dnsrecon.git
|
|
cd dnsrecon
|
|
```
|
|
|
|
### 2\. Install Python Dependencies
|
|
|
|
It is highly recommended to use a virtual environment:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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/`:
|
|
|
|
```bash
|
|
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.**
|
|
|
|
```ini
|
|
[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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
|
|
2. 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.
|
|
3. 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. |