netscope

netscope is a CLI network diagnostics tool.
It runs multiple checks in parallel and produces terminal, JSON, and health JSON reports.

Features

• Parallel collection via asyncio + httpx
• Modular checks: ip, routing, dns, speed, host, security, subscription
• Graceful degradation: one failed provider does not break the full run
• Output modes: terminal report, --json, --health-json, --save FILE

Requirements

• Python 3.11+
• Linux
• System tools: mtr, traceroute, dig, whois, nmap

Example (Arch Linux):

sudo pacman -S mtr nmap bind whois traceroute

Quick Start

From repository root:

./run-local-check.sh
./run-local-check.sh --json
./run-local-check.sh --health-json

Install local launcher:

chmod +x scripts/install-netscope.sh scripts/doctor.sh
./scripts/install-netscope.sh
./scripts/doctor.sh

Core Flags

• Modules: --all, --ip, --routing, --dns, --speed, --host, --security
• Fast mode: --fast (skips slow modules speed and routing)
• Output: --json, --health-json, --save FILE, --brief, --explain
• Integration: --target, --profile-name, --run-id
• Subscription: --subscription-url https://...
• AI (optional): --ai-summary, --ai-model

Examples

netscope --fast
netscope --host --target 8.8.8.8
netscope --all --save report.txt
netscope --health-json --profile-name home-vpn --run-id "$(date -Iseconds)"
netscope --subscription-url "https://example.com/subscription"
netscope --brief --explain

Configuration

Config loading priority:

1. NETSCOPE_CONFIG (path to JSON)
2. ./config/netscope.config.json
3. ~/.config/netscope/config.json

Templates:

• .env.example
• config/netscope.config.example.json

Local setup:

cp .env.example .env
cp config/netscope.config.example.json config/netscope.config.json

AI Setup (OpenRouter)

AI mode is optional and enabled only when OPENROUTER_API_KEY is set.

1. Create/update .env:

cp .env.example .env

2. Set values:

OPENROUTER_API_KEY=your_openrouter_key
OPENROUTER_MODEL=openrouter/auto

3. Run with AI summary:

netscope --brief --ai-summary

4. Optional model override:

netscope --brief --ai-summary --ai-model "openai/gpt-4.1-mini"

If the key is missing, netscope runs normally without AI summary.

Security

• Never commit real keys in .env or config/*.json
• --subscription-url accepts only public https URLs
• Insecure HTTP providers are disabled by default
• Rotate keys if they were exposed in git history or logs

See SECURITY.md.

Development

python -m pip install -r requirements-dev.txt
pytest -q