netscope-cli 1.0.0

Comprehensive network diagnostics, testing, and security audit tool

NetScope - Network Diagnostics & Reporting Tool

A comprehensive CLI tool for network diagnostics, testing, and reporting.

Features

• ✅ Cross-platform OS detection (Linux, macOS, Windows)
• ✅ Automatic tool availability checking
• ✅ Ping connectivity tests (with min/avg/max latency)
• ✅ Traceroute path analysis (with hop table)
• ✅ DNS resolution testing (IPv4/IPv6 aware)
• ✅ Pure-Python port scan (top ports) + optional nmap integration
• ✅ ARP scan and ping sweep for local discovery
• ✅ CSV logging with timestamps + structured logs
• ✅ HTML reports and Jupyter notebook reports per run
• ✅ Beautiful, educational terminal output (summaries, interpretations, glossary)

For a deeper guide, see:

• docs/manual.md – concepts, tests, interpreting results, reports.
• docs/cli-reference.md – full command and option reference.

Getting started

Prerequisites

• Git – to clone the repository
• Python 3.9+ – python.org or your OS package manager

1. Clone the repository

Clone the repo and go into the project directory. The folder name depends on how you cloned (e.g. netscope-cli if you cloned that repo).

git clone https://github.com/netscope-tool/netscope-cli.git
cd netscope-cli

Important: All following commands must be run from this project directory (the one that contains setup.py, requirements.txt, and the netscope folder).

2. Create and activate a virtual environment

Installing packages system‑wide can fail on macOS/Homebrew and some Linux setups with an externally-managed-environment error. Use a virtual environment in the project directory.

macOS / Linux (Terminal, bash/zsh):

# From the project directory (e.g. ~/.../netscope-cli)
python3 -m venv .venv
source .venv/bin/activate

Windows – Command Prompt (cmd):

REM From the project directory (e.g. C:\Users\You\netscope-cli)
python -m venv .venv
.venv\Scripts\activate.bat

Windows – PowerShell:

# From the project directory (e.g. C:\Users\You\netscope-cli)
python -m venv .venv
.venv\Scripts\Activate.ps1

You should see (.venv) (or .venv on Windows) in your prompt. If you open a new terminal later, go back into the project directory and activate the venv again before running netscope.

3. Install dependencies and NetScope

With the virtual environment activated and from the project directory:

pip install -r requirements.txt
pip install -e .

After this, the netscope command is available while the venv is active.

Usage

Interactive mode (menu-driven)

Run netscope with no arguments to start the interactive menu (or use netscope main for the same thing):

# From inside the virtual environment — starts the menu
netscope

# Same as above
netscope main

# Or using the Python module entry point
python -m netscope

You’ll see a header, system information, and then a menu where you can choose:

• Quick Network Check
• Ping Test
• Traceroute Test
• DNS Lookup
• Port Scan
• Nmap Scan (if nmap is installed)
• ARP Scan
• Ping Sweep
• Exit

Non-interactive mode (scripts / automation)

You can also run individual tests directly from the command line, which is useful for scripts, cron jobs, or quick one‑off checks:

# Ping test
netscope ping 8.8.8.8

# Traceroute test
netscope traceroute 8.8.8.8

# DNS lookup
netscope dns example.com

# Quick network check (ping + traceroute + DNS)
netscope quick-check example.com

# Pure-Python port scan (top ports)
netscope ports 192.168.1.1 --preset top100

# Nmap-based scan (if nmap is installed)
netscope nmap-scan example.com

# ARP scan (local devices)
netscope arp-scan

# Ping sweep over a small CIDR
netscope ping-sweep 192.168.1.0/24

By default, results are shown with the Rich TUI formatting.
For machine‑readable output (e.g. piping to jq or logs), you can use:

netscope ping 8.8.8.8 --format json
netscope quick-check example.com --format json

Help and learning

netscope --version          # or -V
netscope explain ping       # what the test does and how to interpret results
netscope explain traceroute
netscope explain quick-check
netscope glossary           # list networking terms
netscope glossary latency   # definition of a term
netscope history            # last 10 test runs (use -o to point to output dir)
netscope history -n 5       # last 5 runs
netscope examples           # common usage scenarios
netscope troubleshoot       # guided troubleshooting wizard

For a full command reference, see docs/cli-reference.md.

Optional config file

You can set defaults in ~/.netscope.yaml or .netscope.yaml in the current directory (optional; requires PyYAML):

output_dir: ./my-output
verbose: false
timeout: 30

CLI options (e.g. -o, -v) override these values.

Quick Start

1. Open a terminal, go to the project directory, and activate the venv (see Getting started above).
2. Run netscope
3. Select a test from the menu
4. Enter target host/IP (e.g. 8.8.8.8 or google.com)
5. View results in the terminal; detailed logs and CSV are in the output/ directory

Running tests

With the virtual environment activated and from the project directory:

pip install -r requirements.txt   # includes pytest
pytest tests/ -v

Distribution

• PyPI (after release): pip install netscope-cli
• Docker: From the project root, docker build -t netscope-cli . then
  docker run --rm netscope-cli --version or docker run --rm -v $(pwd)/output:/data netscope-cli ping 8.8.8.8
• Homebrew: A formula template is in netscope.rb; after the first PyPI release, update the sha256 and use
  brew install --build-from-source ./netscope.rb or add to a tap. See DISTRIBUTION_GUIDE.md.

Version is defined in netscope/__init__.py and pyproject.toml; keep them in sync for releases.

Requirements

Linux

• ping, traceroute, dig (usually pre-installed)

macOS

• ping, traceroute, dig (pre-installed)

Windows

• ping, tracert, nslookup (pre-installed)

Output Structure

output/
└── YYYY-MM-DD_HHMMSS_test_name/
    ├── metadata.json
    ├── results.csv
    ├── netscope.log
    └── raw_output/

License

MIT License - See LICENSE file for details