netscout 1.1.7

Production-ready pentest recon CLI — speed first.

NetScout

Production-ready pentest recon CLI — speed first.

NetScout is a fast, async network reconnaissance tool designed for penetration testers and security professionals. It discovers live hosts, checks ports, grabs banners, fingerprints OS, and exports results — all with minimal packets and maximum parallelism.

---

Features

• Blazing fast — async I/O with semaphore-gated concurrency (default 150 threads)
• Multi-CIDR input — CIDR, single IP, ranges, hostnames, file input, or interactive prompt
• Smart discovery — nmap ping sweep (preferred) with asyncio TCP/ICMP fallback
• Port scanning — async TCP connect with banner grabbing
• OS fingerprinting — zero-cost TTL heuristic + optional deep nmap -O
• Service detection — nmap -sV with intensity 0 (single probe per port)
• Script scanning — nmap default scripts on demand
• Rich terminal UI — live progress dashboard with hacker aesthetics
• Multi-format export — txt, json, csv, gnmap (auto-detected from extension)
• Graceful degradation — works without nmap, without root, behind firewalls

---

Installation

The easiest way to install and configure netscout (and its dependencies like nmap) on macOS and Linux is using our automated script:

curl -sL https://raw.githubusercontent.com/RamKansal/netscout/main/install.sh | bash

Alternatively, you can manually use pipx (Recommended for Linux) or pip:

# Recommended for modern Linux (Ubuntu 24.04+, Debian 12+)
pipx install netscout

pip install -U netscout

Requirements

• Python ≥ 3.10
• nmap (optional but recommended for full functionality)

---

Quick Start

# Scan a single subnet
netscout 10.10.10.0/24

# Multiple ranges with port check
netscout 10.10.10.0/24 172.20.0.0/16 --port 22 80 443 8080

# Fast enum (OS + banner + DNS, zero extra packets)
netscout 192.168.1.0/24 --enum

# Deep scan with export
netscout 10.10.10.0/24 --deep --fast -o results.json

# Read targets from file
netscout --targets-file ranges.txt --enum -o scan.csv

# Interactive mode (no args)
netscout

---

Usage

netscout [OPTIONS] [TARGET ...]

Targets (positional, or interactive prompt if omitted):
    10.10.10.0/24               Single CIDR
    10.10.10.0/24 172.20.0.0/16 Multiple CIDRs
    10.10.10.1-50               Range shorthand
    10.10.10.5                  Single IP
    --targets-file FILE         One target per line

Discovery:
    --tcp                       TCP fallback for ICMP-dark hosts
    --ports TEXT                Ports for TCP fallback probe (default: 22,80,443,445,3389)
    --threads INT               Concurrent threads (default: 150)
    --timeout FLOAT             Timeout per probe in seconds (default: 1.0)
    --fast                      Use nmap T5 + max-parallelism (fastest, noisier)

Enumeration:
    --port INT [INT ...]        Check if specific port(s) are open on live hosts
    --os                        Guess OS via TTL (zero extra packets)
    --services                  Service version detection (nmap -sV intensity 0)
    --scripts                   Run nmap default scripts (slow, explicit only)
    --enum                      All fast enum: OS + banner + DNS (recommended)
    --deep                      Full nmap -O -sV on live hosts (slowest, most info)

Output:
    -o, --output FILE           Save results (auto-format: .txt .json .csv .gnmap)
    --no-color                  Disable colors (for piping)
    -v, --verbose               Show dead hosts
    -q, --quiet                 Only print IP:PORT, no UI chrome
    --no-banner                 Suppress ASCII banner
    --force                     Scan ranges > 65536 hosts

---

Architecture

netscout/
├── main.py            # CLI entrypoint + interactive prompt
├── scanner.py         # Async ping sweep + TCP SYN probe
├── cidr.py            # Multi-CIDR parsing, expansion, dedup
├── enumerator.py      # Port check, OS fingerprint, banner grab
├── resolver.py        # DNS forward/reverse with cache
├── output.py          # Rich terminal UI: live dashboard, summary
├── exporter.py        # txt / json / csv / gnmap output
├── tests/
├── pyproject.toml
└── README.md

Speed Optimizations

1. Single nmap call per phase — never loops nmap per-host
2. Semaphore-gated async for all socket ops
3. Zero duplicate probes — cached results, never re-probe same IP
4. Randomised scan order — shuffles IPs to evade rate limiting
5. Connect timeout 0.5s for TCP port checks
6. Batch hostname resolution before scan starts
7. Progress bar at max 20fps — rendering never slows down scanning

Graceful Degradation

Condition	Behaviour
No nmap	Warns once, falls back to asyncio TCP/ICMP
No root/sudo	Skips raw socket features, uses connect()
ICMP blocked	Auto-enables TCP fallback silently
KeyboardInterrupt	Prints partial results + summary, clean exit
All errors	Go to stderr; results to stdout (pipeable)

---

Output Formats

Quiet mode (-q)

10.10.10.5:22
10.10.10.5:80
10.10.10.12:445

JSON (-o results.json)

{
  "total_hosts": 256,
  "alive_hosts": 12,
  "results": [
    {
      "ip": "10.10.10.5",
      "hostname": "htb-target.local",
      "os_guess": "Linux/Unix",
      "open_ports": [22, 80, 443],
      "ports": {
        "22": {"state": "open", "service": "ssh", "banner": "SSH-2.0-OpenSSH_8.9"}
      }
    }
  ]
}

---

Development

pip install -e ".[dev]"
pytest --cov=netscout

---

License

MIT