netscout 1.0.1__tar.gz

netscout-1.0.1/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: netscout
+Version: 1.0.1
+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

netscout-1.0.1/README.md

@@ -0,0 +1,184 @@
+# 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

netscout-1.0.1/cidr.py

@@ -0,0 +1,195 @@
+"""
+Multi-CIDR input parsing, expansion, deduplication, and merging.
+
+Handles:
+  - CIDR notation: 10.10.10.0/24
+  - Single IPs:   10.10.10.5
+  - Ranges:       10.10.10.1-50  OR  10.10.10.1-10.10.10.254
+  - Hostnames:    auto-resolved to IP
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+import socket
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Sequence
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+MAX_HOSTS_NO_FORCE = 65_536
+
+# ---------------------------------------------------------------------------
+# Dataclass for parsed input
+# ---------------------------------------------------------------------------
+
+@dataclass
+class TargetSpec:
+    """Represents a parsed target specification."""
+    raw: str
+    networks: list[ipaddress.IPv4Network] = field(default_factory=list)
+    individual_ips: list[ipaddress.IPv4Address] = field(default_factory=list)
+    resolved_hostname: str = ""
+    error: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Parsing helpers
+# ---------------------------------------------------------------------------
+
+_RANGE_SHORT_RE = re.compile(
+    r"^(\d{1,3}\.\d{1,3}\.\d{1,3})\.(\d{1,3})-(\d{1,3})$"
+)
+_RANGE_FULL_RE = re.compile(
+    r"^(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})-(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$"
+)
+
+
+def _parse_single(raw: str) -> TargetSpec:
+    """Parse a single target string into a TargetSpec."""
+    spec = TargetSpec(raw=raw)
+    text = raw.strip()
+    if not text:
+        spec.error = "empty input"
+        return spec
+
+    # 1) Try CIDR
+    if "/" in text:
+        try:
+            net = ipaddress.IPv4Network(text, strict=False)
+            spec.networks.append(net)
+            return spec
+        except (ipaddress.AddressValueError, ValueError) as exc:
+            spec.error = str(exc)
+            return spec
+
+    # 2) Try short range: 10.10.10.1-50
+    m = _RANGE_SHORT_RE.match(text)
+    if m:
+        prefix, start_s, end_s = m.group(1), int(m.group(2)), int(m.group(3))
+        if start_s > end_s or end_s > 255:
+            spec.error = f"invalid range {text}"
+            return spec
+        for octet in range(start_s, end_s + 1):
+            spec.individual_ips.append(ipaddress.IPv4Address(f"{prefix}.{octet}"))
+        return spec
+
+    # 3) Try full range: 10.10.10.1-10.10.10.254
+    m = _RANGE_FULL_RE.match(text)
+    if m:
+        try:
+            start_ip = ipaddress.IPv4Address(m.group(1))
+            end_ip = ipaddress.IPv4Address(m.group(2))
+        except ipaddress.AddressValueError as exc:
+            spec.error = str(exc)
+            return spec
+        if int(start_ip) > int(end_ip):
+            spec.error = f"start > end in range {text}"
+            return spec
+        for ip_int in range(int(start_ip), int(end_ip) + 1):
+            spec.individual_ips.append(ipaddress.IPv4Address(ip_int))
+        return spec
+
+    # 4) Try single IP
+    try:
+        addr = ipaddress.IPv4Address(text)
+        spec.individual_ips.append(addr)
+        return spec
+    except ipaddress.AddressValueError:
+        pass
+
+    # 5) Try hostname resolution
+    try:
+        resolved = socket.gethostbyname(text)
+        spec.individual_ips.append(ipaddress.IPv4Address(resolved))
+        spec.resolved_hostname = text
+        return spec
+    except (socket.gaierror, socket.herror) as exc:
+        spec.error = f"cannot resolve hostname '{text}': {exc}"
+        return spec
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def parse_targets(raw_inputs: Sequence[str]) -> tuple[list[TargetSpec], list[str]]:
+    """
+    Parse a list of raw target strings.
+
+    Returns (specs, errors) where *specs* is successfully parsed targets
+    and *errors* is a list of human-readable error strings.
+    """
+    specs: list[TargetSpec] = []
+    errors: list[str] = []
+    for raw in raw_inputs:
+        # Split on commas and whitespace for multi-target pasting
+        tokens = re.split(r"[,\s]+", raw.strip())
+        for tok in tokens:
+            if not tok:
+                continue
+            spec = _parse_single(tok)
+            if spec.error:
+                errors.append(f"  ✗ {tok}: {spec.error}")
+            else:
+                specs.append(spec)
+    return specs, errors
+
+
+def load_targets_file(path: str | Path) -> list[str]:
+    """Read one target per line from a file, stripping comments & blanks."""
+    p = Path(path)
+    if not p.exists():
+        raise FileNotFoundError(f"targets file not found: {p}")
+    lines: list[str] = []
+    for line in p.read_text().splitlines():
+        line = line.strip()
+        if line and not line.startswith("#"):
+            lines.append(line)
+    return lines
+
+
+def deduplicate_and_merge(
+    specs: list[TargetSpec],
+) -> tuple[list[ipaddress.IPv4Network], int]:
+    """
+    Collapse all parsed specs into a minimal set of non-overlapping networks.
+
+    Returns (networks, total_hosts).
+    """
+    all_nets: list[ipaddress.IPv4Network] = []
+    for spec in specs:
+        all_nets.extend(spec.networks)
+        for ip in spec.individual_ips:
+            all_nets.append(ipaddress.IPv4Network(f"{ip}/32"))
+
+    collapsed = list(ipaddress.collapse_addresses(all_nets))
+    total = sum(net.num_addresses for net in collapsed)
+    return collapsed, total
+
+
+def expand_hosts(networks: list[ipaddress.IPv4Network]) -> list[ipaddress.IPv4Address]:
+    """Expand collapsed networks into an ordered list of host addresses."""
+    hosts: list[ipaddress.IPv4Address] = []
+    for net in networks:
+        if net.prefixlen == 32:
+            hosts.append(net.network_address)
+        else:
+            hosts.extend(net.hosts())
+    return hosts
+
+
+def check_host_count(total: int, force: bool) -> bool:
+    """
+    Return True if scan should proceed.
+    Raises SystemExit if total > MAX_HOSTS_NO_FORCE and --force not set.
+    """
+    if total > MAX_HOSTS_NO_FORCE and not force:
+        raise SystemExit(
+            f"[!] Target range contains {total:,} hosts (limit: {MAX_HOSTS_NO_FORCE:,}). "
+            f"Use --force to proceed."
+        )
+    return True