GhostNet

A network scanner in Python: host discovery, port scanning, service/OS detection, lightweight web checks, and traceroute mapping via a CLI or an interactive menu.

SYN scanning, OS fingerprinting, traceroute and MAC spoofing need scapy and usually root. Without it, GhostNet falls back to TCP connect scanning and banner-based detection.

Install

The easiest way is pipx, which installs the ghostnet command into its own isolated environment:

pipx install git+https://github.com/Debug-Jeff/GhostNet                     # core
pipx install "ghostnet[full] @ git+https://github.com/Debug-Jeff/GhostNet"  # + scapy/impacket

ghostnet -t 127.0.0.1        # first scan
ghostnet                     # interactive menu

Installed the core already and want scapy/impacket later? pipx keeps GhostNet in its own environment, so a global pip install scapy won't be seen; inject them into GhostNet's environment instead:

pipx inject ghostnet scapy impacket

(SYN/OS scans on Windows also need Npcap and an administrator shell. Once the first release is published to PyPI this becomes simply pipx install ghostnet the release workflow publishes automatically when a v* tag is pushed.)

Don't have pipx?

Install it, then open a new terminal so the pipx command is on your PATH (skipping that restart is the usual cause of "pipx is not recognized").

Windows (PowerShell):

py -m pip install --user pipx
py -m pipx ensurepath
# close and reopen PowerShell, then:
pipx install git+https://github.com/Debug-Jeff/GhostNet

(If py isn't found, use python instead.)

macOS:

brew install pipx        # or: python3 -m pip install --user pipx
pipx ensurepath          # then restart the terminal

Linux (Debian/Ubuntu):

sudo apt install pipx    # or: python3 -m pip install --user pipx
pipx ensurepath          # then restart the terminal

Prefer not to use pipx at all? Install into a virtual environment instead see From source below.

From source (for development)

git clone https://github.com/Debug-Jeff/GhostNet.git
cd GhostNet
python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python main.py -t 127.0.0.1

Run ghostnet/python main.py with no arguments for the interactive menu, or pass any flag to use the CLI (scriptable, returns an exit code). scapy/impacket are optional missing ones just disable their features, and raw-socket scans (--syn-scan, --traceroute) still need sudo.

Usage

ghostnet -t 192.168.1.1                 # common ports
ghostnet -t 192.168.1.0/24 -p-          # whole subnet, all 65535 ports
ghostnet -t host -A                     # aggressive: -sV -O -b
ghostnet -t host -sV -T4                # version detection, fast timing
ghostnet -t 192.168.1.0/24 -sn          # host discovery (ping sweep) only
sudo ghostnet -t host --syn-scan        # SYN scan (scapy/root)
ghostnet -t host -oA results            # write results.txt/.json/.xml
ghostnet -t host --vuln-scan            # vulnerability checks
ghostnet --update-db                    # refresh local NVD DB (API key)

(From source, use python main.py in place of ghostnet.) Handy flags: -A aggressive, -T0..-T5 timing (paranoid→insane), -sn ping sweep, -Pn skip discovery, -p- all ports, -n no DNS, -oA all output formats. Full reference: ghostnet --help.

NVD API key — --update-db and live NVD lookups need a free key from https://nvd.nist.gov/developers/request-an-api-key, via the NVD_API_KEY environment variable or a .env file in the project root.

Tests

pip install pytest        # or: pip install '.[dev]'
python -m pytest tests/ -v

Runs in CI on Python 3.9–3.12; passes without scapy/impacket.

Notes

• -sV is banner/probe-driven, not a full nmap-style version database.
• Rate controls: --max-rate caps throughput, --min-rate is a floor on that cap, --max-retries retries lossy UDP/SYN probes. --data-length is accepted but not yet applied.

Project layout

The code lives in the ghostnet/ package — cli (flags/dispatch), menu (interactive mode), engine (the scanner), detectors, webapp, netmap, reporting, vulndb, config, parsing, and constants (shared globals and optional-dependency symbols). A thin main.py shim re-exports the package so import main and python main.py still work; python -m ghostnet works too.

Disclaimer

For authorized security assessment only. Scanning systems without explicit permission is illegal in many jurisdictions only scan what you own or are permitted to test.

License

MIT — see the LICENSE file.