Metadata-Version: 2.4
Name: ghostnet
Version: 1.2.2
Summary: GhostNet - Network Scanner
Author: Jeff Mutugi
License: MIT
Project-URL: Homepage, https://github.com/Debug-Jeff/GhostNet
Project-URL: Repository, https://github.com/Debug-Jeff/GhostNet
Project-URL: Changelog, https://github.com/Debug-Jeff/GhostNet/blob/main/CHANGELOG.md
Keywords: network,security,scanner,nmap,port-scanner,pentest
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25.1
Requires-Dist: beautifulsoup4>=4.9.3
Requires-Dist: pytz>=2021.1
Requires-Dist: colorama>=0.4.4
Requires-Dist: dnspython>=2.1.0
Requires-Dist: xmltodict>=0.12.0
Requires-Dist: python-whois>=0.7.3
Requires-Dist: cryptography>=38.0.1
Provides-Extra: full
Requires-Dist: scapy>=2.4.5; extra == "full"
Requires-Dist: impacket>=0.10.0; extra == "full"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# 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](https://scapy.net/) and usually root. Without it, GhostNet falls back
> to TCP connect scanning and banner-based detection.

## Install

The easiest way is [pipx](https://pipx.pypa.io), which installs the `ghostnet` command into its own isolated environment:

```bash
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:

```bash
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):**
```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:**
```bash
brew install pipx        # or: python3 -m pip install --user pipx
pipx ensurepath          # then restart the terminal
```

**Linux (Debian/Ubuntu):**
```bash
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)

```bash
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

```bash
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

```bash
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.
