dnsrecon/README.md

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

### 3\. (Optional but Recommended) Set up a Local DNS Caching Resolver

Running a local DNS caching resolver can significantly speed up DNS queries and reduce your network footprint. Here’s how to set up `unbound` on a Debian-based Linux distribution (like Ubuntu).

**a. Install Unbound:**

```bash
sudo apt update
sudo apt install unbound -y
```

**b. Configure Unbound:**
Create a new configuration file for DNSRecon:

```bash
sudo nano /etc/unbound/unbound.conf.d/dnsrecon.conf
```

Add the following content to the file:

```
server:
    # Listen on localhost for all users
    interface: 127.0.0.1
    access-control: 0.0.0.0/0 refuse
    access-control: 127.0.0.0/8 allow

    # Enable prefetching of popular items
    prefetch: yes
```

**c. Restart Unbound and set it as the default resolver:**

```bash
sudo systemctl restart unbound
sudo systemctl enable unbound
```

To use this resolver for your system, you may need to update your network settings to point to `127.0.0.1` as your DNS server.

**d. Update DNSProvider to use the local resolver:**
In `dnsrecon/providers/dns_provider.py`, you can explicitly set the resolver's nameservers in the `__init__` method:

```python
# dnsrecon/providers/dns_provider.py

class DNSProvider(BaseProvider):
    def __init__(self, session_config=None):
        """Initialize DNS provider with session-specific configuration."""
        super().__init__(...)

        # Configure DNS resolver
        self.resolver = dns.resolver.Resolver()
        self.resolver.nameservers = ['127.0.0.1'] # Use local caching resolver
        self.resolver.timeout = 5
        self.resolver.lifetime = 10
```

## Usage (Development)

### 1\. Start the Application

```bash
python app.py
```

### 2\. Open Your Browser

Navigate to `http://127.0.0.1:5000`.

### 3\. Basic Reconnaissance Workflow

1.  **Enter Target Domain**: Input a domain like `example.com`.
2.  **Select Recursion Depth**: Depth 2 is recommended for most investigations.
3.  **Start Reconnaissance**: Click "Start Reconnaissance" to begin.
4.  **Monitor Progress**: Watch the real-time graph build as relationships are discovered.
5.  **Analyze and Export**: Interact with the graph and download the results when the scan is complete.

## Production Deployment

To deploy DNSRecon in a production environment, follow these steps:

### 1\. Use a Production WSGI Server

Do not use the built-in Flask development server for production. Use a WSGI server like **Gunicorn**:

```bash
pip install gunicorn
gunicorn --workers 4 --bind 0.0.0.0:5000 app:app
```

### 2\. Configure Environment Variables

Set the following environment variables for a secure and configurable deployment:

```bash
# Generate a strong, random secret key
export SECRET_KEY='your-super-secret-and-random-key'

# Set Flask to production mode
export FLASK_ENV='production'
export FLASK_DEBUG=False

# API keys (optional, but recommended for full functionality)
export SHODAN_API_KEY="your_shodan_key"
```

### 3\. Use a Reverse Proxy

Set up a reverse proxy like **Nginx** to sit in front of the Gunicorn server. This provides several benefits, including:

  - **TLS/SSL Termination**: Securely handle HTTPS traffic.
  - **Load Balancing**: Distribute traffic across multiple application instances.
  - **Serving Static Files**: Efficiently serve CSS and JavaScript files.

**Example Nginx Configuration:**

```nginx
server {
    listen 80;
    server_name your_domain.com;

    location / {
        return 301 https://$host$request_uri;
    }
}

server {
    listen 443 ssl;
    server_name your_domain.com;

    # SSL cert configuration
    ssl_certificate /etc/letsencrypt/live/your_domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your_domain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }

    location /static {
        alias /path/to/your/dnsrecon/static;
        expires 30d;
    }
}
```

## Autostart with systemd

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
```

## Security Considerations

  - **API Keys**: API keys are stored in memory for the duration of a user session and are not written to disk.
  - **Rate Limiting**: DNSRecon includes built-in rate limiting to be respectful to data sources.
  - **Local Use**: The application is designed for local or trusted network use and does not have built-in authentication. **Do not expose it directly to the internet without proper security controls.**

## License

This project is licensed under the terms of the license agreement found in the `LICENSE` file.