Discover

Discover is a Python-based network discovery and analysis tool for a local network you own or are authorized to assess. It enumerates active hosts, resolves MAC vendors, maps the network, and provides a handful of common diagnostic utilities (traceroute, DNS lookup, basic OS fingerprinting) behind an interactive menu.

Authorized use only. This tool sends ARP/ICMP/TCP probes and can change your interface's MAC address. Only run it against networks and hosts you own or have explicit written permission to test. Unauthorized scanning may be illegal in your jurisdiction. You are solely responsible for how you use it.

Architecture

The interactive menu engine dispatches to the discovery and diagnostic functions; results are collected and handed to the report generator, which can emit CSV, TXT, or JSON.

flowchart TD
    User([User]) --> Menu["EngineDisover<br/>menu engine"]

    Menu --> ARP["ARP / ICMP<br/>host discovery"]
    Menu --> Trace["Traceroute"]
    Menu --> DNS["DNS lookup"]
    Menu --> FP["OS fingerprinting"]
    Menu --> MAC["MAC ops<br/>change / revert"]
    Menu --> Map["Network mapping<br/>networkx / matplotlib"]

    ARP --> RG["ReportGenerator"]
    Trace --> RG
    DNS --> RG
    FP --> RG
    MAC --> RG
    Map --> RG

    RG --> Out["CSV / TXT / JSON<br/>reports"]

Loading

Features

1. Network data retrieval — private/public IPv4, subnet mask, CIDR, broadcast, usable host range, interface, and MAC address.
2. MAC address manipulation — set a random or specified MAC on an interface, and revert to the original.
3. Host discovery — ARP scan and ICMP (ping) sweep of the local subnet, plus single-host ICMP probing.
4. MAC vendor lookup — offline via the bundled MAC.CSV, with an optional fallback to the macvendorlookup.com API.
5. Network mapping — renders a graph of discovered hosts with networkx / matplotlib.
6. Diagnostics — traceroute, DNS lookup, and TTL/window-based OS fingerprinting.
7. Reporting — export results to CSV, TXT, or JSON via ReportGenerator.

Requirements

• Python 3.8+
• Linux (uses ifconfig, ping, curl, and netifaces; behavior on other platforms is untested)
• Third-party packages listed in requirements.txt: matplotlib, networkx, requests, scapy, netifaces

Setup

git clone https://github.com/kassam-99/Discover.git
cd Discover
pip install -r requirements.txt

Privileges

Raw packet operations (ARP scanning, traceroute, OS fingerprinting via scapy) and changing a MAC address require root/administrator privileges. Run with sudo when using those features:

sudo python3 Discover.py

Network data retrieval, DNS lookup, and ICMP host checks generally work without elevated privileges.

Usage

Run the interactive menu:

python3 Discover.py

You will be presented with a top-level menu (Discover / Help / Exit). Selecting Discover opens a submenu of the actions above; each action prompts for its parameters (with sensible defaults). The bundled MAC.CSV and Discover.txt files are located relative to the script, so the tool can be run from any working directory.

Programmatic use

The Discover class can also be imported and used directly:

from Discover import Discover

d = Discover()
d.GetNetworkData(PrintDetails=True)
# maxHostgroup is the number of ARP scan rounds to run; the scan also stops
# early once a round discovers no new hosts.
d.ARP_DiscoverHosts(maxHostgroup=3, verbose=True, save_to_file=True)

Files

File	Purpose
Discover.py	Main tool and interactive engine.
ReportGenerator.py	CSV / TXT / JSON report generation.
MAC.CSV	Offline MAC-prefix to vendor lookup table.
Discover.txt	Long-form help / method reference.
requirements.txt	Third-party dependencies.

Running with Docker

A Dockerfile is provided so the tool's dependencies (scapy, netifaces, matplotlib, networkx, requests) and the system packages it shells out to (ping, ip, ifconfig, libpcap) come pre-installed and reproducible.

Docker here is for reproducible dependencies, not isolation. Discover needs to see and probe the host network, so it must run with host networking and raw-socket capabilities. That intentionally removes the network isolation a container would normally give you. The authorized-use notice above still applies: only run this against networks and hosts you own or are explicitly authorized to assess.

Build

docker build -t discover .

Run

Because the tool performs ARP/ICMP/TCP probing and can change an interface's MAC address, the container needs host networking plus the NET_RAW and NET_ADMIN capabilities:

docker run --rm -it \
  --net=host \
  --cap-add=NET_RAW \
  --cap-add=NET_ADMIN \
  -v "$(pwd)/reports:/data" \
  discover

• --net=host gives the container visibility of the real network interfaces (without it, scapy would only see the container's virtual interface).
• --cap-add=NET_RAW / --cap-add=NET_ADMIN allow raw packet crafting and MAC-address changes without running the whole container as root — the image runs as a non-root appuser by default.
• -it keeps the interactive menu usable.
• -v "$(pwd)/reports:/data" persists generated CSV/TXT/JSON reports to a reports/ directory on the host; the container's working directory is /data.

The bundled MAC.CSV and Discover.txt are baked into the image at /app, so the tool works from any working directory.

Contributing

Contributions, bug reports, and feature requests are welcome. Fork the repository, make your changes, and open a pull request.