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:

   mkdir dnsrecon
   cd dnsrecon
   

2. Install Python dependencies:

   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:

   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:

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

{
  "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:

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