ncheck 1.1.2

Professional network diagnostics CLI with rich terminal output

ncheck

ncheck is a professional security platform for diagnostics, authorized pentest workflows, personal security hygiene and passive OSINT. It is designed for SRE, platform and security teams that need terminal-first checks with clean rich output and machine-friendly JSON.

Professional Capabilities

• Network diagnostics:
• ping: ICMP latency and packet-loss checks
• dns: hostname resolution by family (any, ipv4, ipv6)
• http: endpoint reachability and timing checks
• ports: concurrent TCP port scan
• traceroute: path visibility to a target
• tls: certificate, issuer, protocol and expiry inspection
• Defensive pentest posture:
• audit: pentest-style exposure audit for authorized targets
• surface: composed attack-surface assessment (DNS + ports + HTTP + TLS)
• risky port exposure classification
• HTTP security-header posture analysis
• Passive OSINT toolkit:
• osint-domain: WHOIS, DNS intelligence, CT subdomains, security.txt posture
• osint-email: MX, breach intelligence (optional HIBP API key), identity indicators
• Personal security hygiene:
• personal-security: local firewall state + listening service exposure triage
• System observability:
• system: local CPU, memory and top process usage
• Engineering quality:
• typed service layer + dataclass result models
• consistent non-zero exit codes on failures/findings
• rich terminal rendering + JSON automation mode
• declarative batch plans (JSON/YAML) for repeatable diagnostics
• optional enterprise GUI dashboard with execution timeline and report export
• unit tests with pytest and linting with ruff

Legal and Ethical Use

Some commands can assess remote exposure (ports, audit, surface, traceroute). Only run them against systems you own or have explicit permission to test.

audit and surface require --authorized as explicit confirmation.

Installation

pip install -e .

Development setup:

pip install -e .[dev]

Optional extras:

pip install -e .[batch]
pip install -e .[gui]

Command Examples

ncheck --help
ncheck --version

ncheck ping 8.8.8.8 --count 6 --timeout 1.2
ncheck dns github.com --family ipv4
ncheck http https://api.github.com --method HEAD --timeout 3
ncheck ports scanme.nmap.org --ports 22,80,443,8080
ncheck traceroute cloudflare.com --max-hops 25
ncheck tls cloudflare.com --port 443 --fail-on-warnings
ncheck system --top 10
ncheck personal-security --json
ncheck osint-domain example.com --include-subdomains
ncheck osint-email [e-mail] --hibp-api-key $HIBP_API_KEY
ncheck surface example.com --authorized --ports 21,22,80,443,445 --json
ncheck batch examples/batch-plan.json --json
ncheck gui --host 127.0.0.1 --port 8501

Defensive audit (authorized targets only):

ncheck audit example.com --authorized --ports 21,22,80,443,445,3389

JSON mode for automation:

ncheck ping cloudflare.com --json
ncheck http cloudflare.com --json
ncheck system --json
ncheck audit example.com --authorized --json
ncheck surface example.com --authorized --json
ncheck osint-domain example.com --json
ncheck personal-security --json
ncheck batch plan.yaml --json

Batch Plans (JSON/YAML)

You can execute multiple checks from a single declarative file:

{
  "checks": [
    {"check": "ping", "host": "8.8.8.8", "count": 4, "timeout": 2.0},
    {"check": "dns", "host": "example.com", "family": "ipv4"},
    {"check": "osint_domain", "target": "example.com", "include_subdomains": true},
    {"check": "personal_security", "top_ports": 20},
    {"check": "surface", "host": "example.com", "authorized": true, "ports": "80,443"}
  ]
}

Rules:

• each item must define check
• check options can be top-level fields or grouped inside options
• audit and surface require authorized: true

GUI Dashboard

The GUI is web-based and built with Streamlit:

ncheck gui --host 127.0.0.1 --port 8501

It provides:

• interactive forms for diagnostics, pentest posture, OSINT and personal security
• execution timeline with success/failure tracking
• consolidated JSON report download for governance/audit trails

Exit Codes

• 0: command completed without failure conditions
• 1: runtime error, check failure, or finding-based failure
• 2: invalid CLI usage/argument validation error

Development

ruff check .
pytest