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 1 Implementation**
- ✅ Core infrastructure and graph engine
- ✅ Certificate transparency data provider (crt.sh)
- ✅ Basic web interface with real-time visualization
- ✅ Forensic logging system
- ✅ JSON export functionality

## Features

### Core Capabilities
- **Zero Contact Reconnaissance**: Passive data gathering without touching target infrastructure
- **In-Memory Graph Analysis**: Uses NetworkX for efficient relationship mapping
- **Real-Time Visualization**: Interactive graph updates during scanning
- **Forensic Logging**: Complete audit trail of all reconnaissance activities
- **Confidence Scoring**: Weighted relationships based on data source reliability

### Data Sources (Phase 1)
- **Certificate Transparency (crt.sh)**: Discovers domain relationships through SSL certificate SAN analysis
- **Basic DNS Resolution**: A/AAAA record lookups for IP relationships

### Visualization
- **Interactive Network Graph**: Powered by vis.js with cybersecurity theme
- **Node Types**: Domains, IP addresses, certificates, ASNs
- **Confidence-Based Styling**: Visual indicators for relationship strength
- **Real-Time Updates**: Graph builds dynamically as relationships are discovered

## Installation

### Prerequisites
- Python 3.8 or higher
- Modern web browser with JavaScript enabled

### Setup
1. **Clone or create the project directory**:
   ```bash
   mkdir dnsrecon
   cd dnsrecon
   ```

2. **Install Python dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

3. **Verify the directory structure**:
   ```
   dnsrecon/
   ├── app.py
   ├── config.py
   ├── requirements.txt
   ├── core/
   │   ├── __init__.py
   │   ├── graph_manager.py
   │   ├── scanner.py
   │   └── logger.py
   ├── providers/
   │   ├── __init__.py
   │   ├── base_provider.py
   │   └── crtsh_provider.py
   ├── static/
   │   ├── css/
   │   │   └── main.css
   │   └── js/
   │       ├── graph.js
   │       └── main.js
   └── templates/
       └── index.html
   ```

## Usage

### Starting the Application
1. **Run the Flask application**:
   ```bash
   python app.py
   ```

2. **Open your web browser** and navigate to:
   ```
   http://127.0.0.1:5000
   ```

### Basic Reconnaissance Workflow

1. **Enter Target Domain**: Input the domain you want to investigate (e.g., `example.com`)

2. **Select Recursion Depth**: 
   - **Depth 1**: Direct relationships only
   - **Depth 2**: Recommended for most investigations
   - **Depth 3+**: Extended analysis for comprehensive mapping

3. **Start Reconnaissance**: Click "Start Reconnaissance" to begin passive data gathering

4. **Monitor Progress**: Watch the real-time graph build as relationships are discovered

5. **Analyze Results**: Interact with the graph to explore relationships and click nodes for detailed information

6. **Export Data**: Download complete results including graph data and forensic audit trail

### Understanding the Visualization

#### Node Types
- 🟢 **Green Circles**: Domain names
- 🟠 **Orange Squares**: IP addresses  
- ⚪ **Gray Diamonds**: SSL certificates
- 🔵 **Blue Triangles**: ASN (Autonomous System) information

#### Edge Confidence
- **Thick Green Lines**: High confidence (≥80%) - Certificate SAN relationships
- **Medium Orange Lines**: Medium confidence (60-79%) - DNS record relationships  
- **Thin Gray Lines**: Lower confidence (<60%) - Passive DNS or uncertain relationships

### Example Investigation

Let's investigate `github.com`:

1. Enter `github.com` as the target domain
2. Set recursion depth to 2
3. Start the scan
4. Observe relationships to other GitHub domains discovered through certificate analysis
5. Export results for further analysis

Expected discoveries might include:
- `*.github.com` domains through certificate SANs
- `github.io` and related domains
- Associated IP addresses
- Certificate authority relationships

## Configuration

### Environment Variables
You can configure DNSRecon using environment variables:

```bash
# API keys for future providers (Phase 2)
export VIRUSTOTAL_API_KEY="your_api_key_here"
export SHODAN_API_KEY="your_api_key_here"

# Application settings
export DEFAULT_RECURSION_DEPTH=2
export FLASK_DEBUG=False
```

### Rate Limiting
DNSRecon includes built-in rate limiting to be respectful to data sources:
- **crt.sh**: 60 requests per minute
- **DNS queries**: 100 requests per minute

## Data Export Format

Results are exported as JSON with the following structure:

```json
{
  "scan_metadata": {
    "target_domain": "example.com",
    "max_depth": 2,
    "final_status": "completed"
  },
  "graph_data": {
    "nodes": [...],
    "edges": [...]
  },
  "forensic_audit": {
    "session_metadata": {...},
    "api_requests": [...],
    "relationships": [...]
  },
  "provider_statistics": {...}
}
```

## Forensic Integrity

DNSRecon maintains complete forensic integrity:

- **API Request Logging**: Every external request is logged with timestamps, URLs, and responses
- **Relationship Provenance**: Each discovered relationship includes source provider and discovery method
- **Session Tracking**: Unique session IDs for investigation continuity
- **Confidence Metadata**: Scoring rationale for all relationships
- **Export Integrity**: Complete audit trail included in all exports

## Architecture Overview

### Core Components

- **GraphManager**: NetworkX-based in-memory graph with confidence scoring
- **Scanner**: Multi-provider orchestration with depth-limited BFS exploration  
- **ForensicLogger**: Thread-safe audit trail with structured logging
- **BaseProvider**: Abstract interface for data source plugins

### Data Flow
1. User initiates scan via web interface
2. Scanner coordinates multiple data providers
3. Relationships discovered and added to in-memory graph
4. Real-time updates sent to web interface
5. Graph visualization updates dynamically
6. Complete audit trail maintained throughout

## Troubleshooting

### Common Issues

**Graph not displaying**:
- Ensure JavaScript is enabled in your browser
- Check browser console for errors
- Verify vis.js library is loading correctly

**Scan fails to start**:
- Check target domain is valid
- Ensure crt.sh is accessible from your network
- Review Flask console output for errors

**No relationships discovered**:
- Some domains may have limited certificate transparency data
- Try a well-known domain like `google.com` to verify functionality
- Check provider status in the interface

### Debug Mode
Enable debug mode for verbose logging:
```bash
export FLASK_DEBUG=True
python app.py
```

## Development Roadmap

### Phase 2 (Planned)
- Multi-provider system with Shodan and VirusTotal integration
- Real-time scanning with enhanced visualization
- Provider health monitoring and failure recovery

### Phase 3 (Planned)  
- Advanced correlation algorithms
- Enhanced forensic reporting
- Performance optimization for large investigations

## Security Considerations

- **No Persistent Storage**: All data stored in memory only
- **API Keys**: Stored in memory only, never written to disk
- **Rate Limiting**: Prevents abuse of external services
- **Local Use Only**: No authentication required (designed for local use)

## Contributing

DNSRecon follows a phased development approach. Currently in Phase 1 with core infrastructure completed. 

### Code Quality Standards
- Follow PEP 8 for Python code
- Comprehensive docstrings for all functions
- Type hints where appropriate
- Forensic logging for all external interactions

## License

This project is intended for legitimate security research and infrastructure analysis. Users are responsible for compliance with applicable laws and regulations.

## Support

For issues and questions:
1. Check the troubleshooting section above
2. Review the Flask console output for error details
3. Ensure all dependencies are properly installed

---

**DNSRecon v1.0 - Phase 1 Implementation**  
*Passive Infrastructure Reconnaissance for Security Professionals*