mstoeck3/dnscope
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
dnscope/README.md
overcuriousity 897bb80183 gradient
2025-09-24 09:30:42 +02:00

11 KiB
Raw Permalink Blame History

DNScope - Passive Infrastructure Reconnaissance Tool

DNScope 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. It is aimed at cybersecurity researchers, pentesters, and administrators who want to understand the public footprint of a target domain.

Repo Link: https://github.com/overcuriousity/DNScope

Concept and Philosophy

The core philosophy of DNScope is to provide a comprehensive and accurate map of a target's infrastructure using only passive data sources by default. This means that, out of the box, DNScope will not send any traffic to the target's servers. Instead, it queries public and historical data sources to build a picture of the target's online presence. This approach is ideal for researchers and pentesters who want to gather intelligence without alerting the target, and for administrators who want to see what information about their own infrastructure is publicly available.

For power users who require more in-depth information, DNScope can be configured to use API keys for services like Shodan, which provides a wealth of information about internet-connected devices. However, this is an optional feature, and the core functionality of the tool will always remain free and passive.

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.
  • Session Management: Supports concurrent user sessions with isolated scanner instances.
  • Extensible Provider Architecture: Easily add new data sources to expand the tool's capabilities.
  • Web-Based UI: An intuitive and interactive web interface for managing scans and visualizing results.
  • Export Options: Export scan results to JSON, a list of targets to a text file, or an executive summary.
  • API Key Management: Securely manage API keys for various providers through the web interface.
  • Provider Management: Enable or disable providers for the current session.

Technical Architecture

DNScope is a web-based application built with a modern technology stack:

  • Backend: The backend is a Flask application that provides a REST API for the frontend and manages the scanning process.
  • Scanning Engine: The core scanning engine is a multi-threaded Python application that uses a provider-based architecture to query different data sources.
  • Session Management: Redis is used for session management, allowing for concurrent user sessions with isolated scanner instances.
  • Data Storage: The application uses an in-memory graph to store and analyze the relationships between different pieces of information. The graph is built using the NetworkX library.
  • Frontend: The frontend is a single-page application that uses JavaScript to interact with the backend API and visualize the graph.

Data Sources

DNScope queries the following data sources:

  • DNS: Standard DNS lookups (A, AAAA, CNAME, MX, NS, SOA, TXT).
  • crt.sh: A certificate transparency log that provides information about SSL/TLS certificates.
  • Shodan: A search engine for internet-connected devices (requires an API key).

Installation and Setup

Prerequisites

  • Python 3.8 or higher
  • A modern web browser with JavaScript enabled
  • A Linux host for running the application
  • Redis Server

1. Install Redis

It is recommended to install Redis from the official repositories.

On Debian/Ubuntu:

sudo apt-get update
sudo apt-get install redis-server

On CentOS/RHEL:

sudo yum install redis
sudo systemctl start redis
sudo systemctl enable redis

You can verify that Redis is running with the following command:

redis-cli ping

You should see PONG as the response.

2. Clone the Project

git clone https://github.com/overcuriousity/DNScope
cd DNScope

3. 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
  • networkx
  • requests
  • python-dateutil
  • Werkzeug
  • urllib3
  • dnspython
  • gunicorn
  • redis
  • python-dotenv
  • psycopg2-binary

4. Configure the Application

DNScope 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

Running the Application

For development, you can run the application using the following command:

python app.py

For production, it is recommended to use a more robust server, such as Gunicorn:

gunicorn --workers 4 --bind 0.0.0.0:5000 app:app

Systemd Service

To run DNScope 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/DNScope.service

2. Add the Service Configuration

Paste the following configuration into the file. Remember to replace /path/to/your/DNScope and your_user with your actual project path and username.

[Unit]
Description=DNScope Application
After=network.target

[Service]
User=your_user
Group=your_user
WorkingDirectory=/path/to/your/DNScope
ExecStart=/path/to/your/DNScope/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 DNScope.service
sudo systemctl start DNScope.service

You can check the status of the service at any time with:

sudo systemctl status DNScope.service

Updating the Application

To update the application, you should first pull the latest changes from the git repository. Then, you will need to wipe the Redis database and the local cache to ensure that you are using the latest data.

1. Update the Code

git pull

2. Wipe the Redis Database

redis-cli FLUSHALL

3. Wipe the Local Cache

rm -rf cache/*

4. Restart the Service

sudo systemctl restart DNScope.service

Extensibility

DNScope is designed to be extensible, and adding new providers is a straightforward process. To add a new provider, you will need to create a new Python file in the providers directory that inherits from the BaseProvider class. The new provider will need to implement the following methods:

  • get_name(): Return the name of the provider.
  • get_display_name(): Return a display-friendly name for the provider.
  • requires_api_key(): Return True if the provider requires an API key.
  • get_eligibility(): Return a dictionary indicating whether the provider can query domains and/or IPs.
  • is_available(): Return True if the provider is available (e.g., if an API key is configured).
  • query_domain(domain): Query the provider for information about a domain.
  • query_ip(ip): Query the provider for information about an IP address.

Unique Capabilities and Limitations

Unique Capabilities

  • Graph-Based Analysis: The use of a graph-based data model allows for a more intuitive and powerful analysis of the relationships between different pieces of information.
  • Real-Time Visualization: The real-time visualization of the graph provides immediate feedback and allows for a more interactive and engaging analysis experience.
  • Session Management: The session management feature allows multiple users to use the application concurrently without interfering with each other's work.

Limitations

  • Passive-Only by Default: While the passive-only approach is a key feature of the tool, it also means that the information it can gather is limited to what is publicly available.
  • No Active Scanning: The tool does not perform any active scanning, such as port scanning or vulnerability scanning.

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.