Metadata-Version: 2.4
Name: netscout
Version: 1.1.0
Summary: Production-ready pentest recon CLI — speed first.
Author: NetScout Contributors
License: MIT
Keywords: pentest,recon,scanner,network,cli
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Security
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-asyncio; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"

# 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

```bash
# Clone and install in editable mode
git clone https://github.com/youruser/netscout.git
cd netscout
pip install -e .

# Now available globally
netscout --version
```

### Requirements

- Python ≥ 3.10
- [nmap](https://nmap.org/) (optional but recommended for full functionality)

---

## Quick Start

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

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

---

## License

MIT
