# 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](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. * **Confidence Scoring**: Relationships are weighted based on the reliability of the data source. * **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:** ```bash sudo apt-get update sudo apt-get install redis-server ``` **On CentOS/RHEL:** ```bash sudo yum install redis sudo systemctl start redis sudo systemctl enable redis ``` You can verify that Redis is running with the following command: ```bash redis-cli ping ``` You should see `PONG` as the response. ### 2\. Clone the Project ```bash git clone https://github.com/overcuriousity/DNScope cd DNScope ``` ### 3\. 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 * 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: ```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` | ----- ## Running the Application For development, you can run the application using the following command: ```bash python app.py ``` For production, it is recommended to use a more robust server, such as Gunicorn: ```bash 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/`: ```bash 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.** ```ini [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: ```bash 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: ```bash 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 ```bash git pull ``` ### 2\. Wipe the Redis Database ```bash redis-cli FLUSHALL ``` ### 3\. Wipe the Local Cache ```bash rm -rf cache/* ``` ### 4\. Restart the Service ```bash 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.