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

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:

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.

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

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.1)

Development

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.x: 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.