Metadata-Version: 2.4
Name: ncheck
Version: 1.1.2
Summary: Professional network diagnostics CLI with rich terminal output
Author: Pablo
License: MIT
Project-URL: Homepage, https://github.com/pardall-dev
Project-URL: Repository, https://github.com/pardall-dev/Ncheck
Keywords: network,cli,ping,diagnostics
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Environment :: Console
Classifier: Topic :: System :: Networking
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.0
Requires-Dist: pythonping>=1.1.4
Requires-Dist: psutil>=6.1
Requires-Dist: streamlit>=1.41
Provides-Extra: dev
Requires-Dist: pytest>=8.3; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.8; extra == "dev"
Provides-Extra: batch
Requires-Dist: PyYAML>=6.0; extra == "batch"
Provides-Extra: gui
Requires-Dist: streamlit>=1.41; extra == "gui"
Requires-Dist: PyYAML>=6.0; extra == "gui"
Dynamic: license-file

# 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

```bash
pip install -e .
```

Development setup:

```bash
pip install -e .[dev]
```

Optional extras:

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

## Command Examples

```bash
ncheck --help
ncheck --version
```

```bash
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 analyst@example.com --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):

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

JSON mode for automation:

```bash
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:

```json
{
  "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:

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

```bash
ruff check .
pytest
```
