Metadata-Version: 2.4
Name: nagunetwork
Version: 1.0.0
Summary: Cross-platform first-response diagnostic report: hardware, OS, storage, network ladder, security and logs (optional BETA temporary LAN SSH access)
Author: NagusameCS
License-Expression: MIT
Project-URL: Homepage, https://github.com/NagusameCS/NaguNetwork
Project-URL: Repository, https://github.com/NagusameCS/NaguNetwork
Project-URL: Issues, https://github.com/NagusameCS/NaguNetwork/issues
Keywords: diagnostics,troubleshooting,network,support,report,connectivity,smart,ssh
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Information Technology
Classifier: Environment :: Console
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Networking :: Monitoring
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == "dev"
Requires-Dist: jsonschema>=4; extra == "dev"
Provides-Extra: build
Requires-Dist: pyinstaller>=6; extra == "build"
Dynamic: license-file

# NaguNetwork

A read-mostly, cross-platform (Linux, macOS, Windows) first-response diagnostic evidence collector.
It produces a privacy-reviewed, integrity-protected report that a technician can trace from every
conclusion back to timestamped evidence.

It does **not** claim to detect every fault. It collects broad evidence, runs safe bounded tests,
explains every collection gap, and never turns "unknown" into "pass".

> **Mode B (report only) is the primary mode and changes nothing on your system.**
> **Mode A (temporary SSH access) is BETA. See the warnings below before using it.**

## Install and run

```bash
pip install nagunetwork          # Python 3.9+, no third-party dependencies
nagunetwork                      # interactive menu: [A] BETA SSH + report, [B] report only, [Q] quit
nagunetwork report               # Mode B directly (asks for consent first)
nagunetwork report --yes         # accept the printed disclosure non-interactively
```

From a source checkout: `cd src && python3 -m nagunetwork`. Standalone executables that need no
Python are built with `python packaging/build.py`.

## What you get

Each run writes an **uncompressed folder** you can open immediately, plus a **compressed copy** to send:

```text
NaguNetwork_<device>_<UTC time>_<run id>/        open report.html
    report.html     self-contained page (no scripts, fonts or remote assets)
    report.json     canonical, schema-versioned data (schemas/report.schema.json)
    summary.txt     plain-text triage
    manifest.json   SHA-256 and size of every file
    raw/            bounded, redacted command and log output
NaguNetwork_<device>_<UTC time>_<run id>.zip     the same folder, compressed
NaguNetwork_<device>_<UTC time>_<run id>.zip.sha256
```

Folder and files are owner-only. Reports default to `~/Documents/NaguNetwork Reports`
(override with `--output`). Nothing is uploaded.

`nagunetwork verify <folder or zip>` checks every file against the manifest and the schema.
`nagunetwork compare <old> <new>` shows what changed between two runs.

### Nothing can stop the report from being written

Every collector is isolated. A crash, a hang past its time limit, a missing tool, a permission error or
garbage output becomes a recorded `error`/`timeout`/`unsupported` result, never a missing report.
Report assembly degrades step by step:

- If the rule engine, a renderer or redaction of one check fails, that part is simplified or withheld
  and the problem is listed in `run.report_errors`.
- If the folder can't be written, the zip is still written, and vice versa.
- If the output location is unwritable or full, NaguNetwork falls back to the default folder, then the
  temp directory, then the current directory.
- Ctrl+C (or SIGTERM) stops the active tests and still writes a partial report. Interrupts are
  ignored during the few seconds the report is being written.
- On Linux systems without `ip` or `ss`, interfaces, routes, neighbours and sockets are read
  from `/proc` and `/sys` instead.

## What it checks

58 checks across hardware, OS, storage (including SMART when elevated), power and thermal,
network, security, software, performance, logs and peripherals. They include:

- a layered connectivity ladder: link → address → route → gateway → DNS → TCP over IPv4 and IPv6 →
  TLS (clock skew and interception) → HTTP (captive portal or proxy) → path → latency, jitter and loss;
- **hybrid-graphics checks on Linux:** flags a game or heavy app rendering on the integrated GPU while
  an NVIDIA GPU sits idle, with the exact fix (including the Flatpak override command);
- **memory-hog detection:** names the process holding most of the RAM, including oversized Java
  `-Xmx` heaps that push the system into swap.

Findings carry a severity, an independent confidence level, a kind
(confirmed / likely / possible / ruled-out), evidence IDs, next steps and an escalation target.

### Privacy

Secrets (passwords, private keys, tokens, cookies, URI credentials) are removed in every profile.
Credential stores, Wi-Fi keys, documents, e-mail, clipboard, camera and microphone are never read.
Each profile aliases a different set of identifiers, using per-report aliases such as `USER-1` and
`LAN-IP-3`:

- `standard` (default): user and host names, serials, SSIDs, MACs and public IPs.
- `strict`: everything in `standard`, plus LAN addresses.
- `full`: nothing is aliased; requires explicit confirmation.

Optional modules, off unless consented: `public-ip`, `resolver-compare`, `throughput` (~10 MB),
`wifi-scan`, `extended-logs`, `crash-reports`, `command-lines`, `disk-benchmark`.

## ⚠️ Mode A: temporary SSH access (BETA)

> **BETA / EXPERIMENTAL. It has not been field-tested on real Windows, macOS or Linux machines.**
>
> - It **changes system configuration**: it may install the OpenSSH server, starts a second SSH
>   server, adds firewall rules (and an SELinux port label on Fedora/RHEL) and schedules a cleanup job.
> - Anyone holding the technician's **private key**, connecting from the allowed LAN address, can run
>   commands as the chosen account, **including its sudo/administrator rights**, until access closes.
> - Rollback is automatic but **could fail**. If it does, run `nagunetwork stop-access` as
>   administrator, follow the printed journal, and reboot if in doubt.
> - Never use it on shared, public, workplace or managed devices without written permission.
> - If you only need a report, use Mode B. It changes nothing.

Mode A needs administrator/root access and a typed acknowledgement (`I ACCEPT THE BETA RISK`, or
`--accept-beta-risk` for scripted use), plus an `open access` confirmation. Its limits:

- **Duration:** at most 60 minutes.
- **Login:** public key only, for one named, non-root account.
- **Source:** one LAN address or the local subnet. RFC 1918, ULA and link-local only; `0.0.0.0/0`
  is never accepted.
- **Network exposure:** no router port-forwarding, UPnP, relay or tunnel.

It runs a separate sshd instance, so an existing SSH server is left untouched. Every change is
journaled before it is made and reversed in reverse order. Independent expiry is created before the
port opens: a systemd timer, a launchd job or a Windows scheduled task, plus a hard runtime limit and
a key `expiry-time`.

```text
nagunetwork assist --public-key tech.pub --source 192.168.1.20 [--minutes 60] [--user NAME] --accept-beta-risk
nagunetwork stop-access          # close every open access window now
```

## Command line

```text
nagunetwork report  [--privacy strict|standard|full] [--output PATH] [--modules LIST]
                    [--sample-seconds N] [--log-days N] [--offline] [--during-fault yes|no|unknown]
                    [--config FILE] [--yes] [--no-elevate]
nagunetwork verify  REPORT            # folder or zip
nagunetwork compare OLD NEW [--json]
nagunetwork list-checks
nagunetwork assist ... | stop-access | cleanup --journal PATH      # Mode A (BETA)
```

**Exit codes:** 0 success · 10 partial report · 11 cancelled (partial report written) ·
12 unsupported platform · 13 privilege refused · 14 report could not be written anywhere ·
15 rollback failed · 16 verification failed · 2 usage error.

## Verification status (1.0.0)

| Area | Status |
|---|---|
| **Mode B on Linux** | Verified end to end on Fedora 44 across 14 real-run variants: default, all privacy profiles, all optional modules, offline, no network namespace, fake-root user namespace, German locale, Unicode output path, Ctrl+C, SIGTERM and a global deadline. Python 3.9 and 3.14. |
| Mode B elevated (Linux) | Root-only code paths exercised with recorded tool outputs; not yet run as real root. |
| Mode B on macOS / Windows | Every collector exercised against recorded outputs, missing tools and empty outputs; **not yet run on real machines** (CI runs them as informational). |
| **Mode A (all platforms)** | **BETA.** Transaction and rollback tested with fault injection at every step. On Linux the generated sshd config, key line and nftables rules were validated with real OpenSSH 10 and nft, including a live unprivileged loopback login. **The full root flow has not been run on a real system.** |

## Development

```bash
pip install -e ".[dev]" && pytest          # or: uv run --with pytest --with jsonschema python -m pytest
pytest -m "not slow"                       # skip end-to-end runs of the real collectors
```

Layout: `src/nagunetwork/` contains `__main__.py` (CLI, consent, scheduler), `model.py` (schema and
redaction), `runner.py` (the single hardened command runner and allowlist), `platforms.py`
(collectors), `netcheck.py` (connectivity ladder), `report.py` (rules, rendering, bundle,
verify, compare) and `ssh.py` (Mode A, BETA).

Not in 1.0.0: report encryption, packet capture, browser settings, file-system metadata, native OS
diagnostic bundles, and a temporary support account for Mode A. Each gap is reported in the report
as `unsupported` or `skipped`, with a reason and a manual alternative.
