Linux Diagnostics Toolkit

A modular, lightweight Bash diagnostic toolkit that automates Linux health checks — network reachability, filesystem capacity, systemd boot performance, service stability, and security posture. Each check operates standalone or as part of a central menu runner, logging reports to a secure reports/ directory with standardized exit codes.

---

Repository Structure

linux-diagnostics-toolkit/
├── toolkit.sh                      # Central CLI entry point & interactive menu
├── README.md                       # Documentation & reference guide
├── .gitignore                      # Excludes reports, temporary files, and caches
├── .shellcheckrc                   # ShellCheck linting configuration
├── scripts/
│   ├── common.sh                   # Shared utility library (logging, exit codes, reports)
│   ├── network_health_check.sh     # Network interfaces, routing, DNS, ICMP, listening ports
│   ├── disk_usage_check.sh         # Filesystem usage, threshold alerts, directory scans, cache
│   ├── boot_time_check.sh          # Systemd boot times, blame analysis, errors, enabled units
│   ├── service_audit.sh            # Service failure audit, oneshot filtering, restart counts
│   └── security_audit.sh           # Port audit, world-writable files, SSH/sudo logs, UID 0 accounts
└── tests/
    ├── run_tests.sh                # Test runner executing all unit and mock test suites
    ├── test_common.sh              # Assertion helpers
    ├── test_boot_time.sh           # Duration parser & unit threshold tests
    ├── test_disk_usage.sh          # Filesystem threshold & space-safe mount tests
    ├── test_network_health.sh      # Gateway parsing & route extraction tests
    ├── test_security_audit.sh      # Log fallback & UID 0 tests
    ├── test_service_audit.sh       # Oneshot filtering & service alias tests
    └── test_toolkit.sh             # CLI dispatch, reports dir, and exit code tests

---

Features & Diagnostics

Diagnostic Script	Key Checks & Implementation
scripts/network_health_check.sh	• Active interfaces & IP addresses via ip -brief / ifconfig • Routing table & default gateway extraction (supports direct device routes) • DNS resolution test with multi-tool fallback (host, dig, nslookup, getent) • Gateway reachability with timeout (-W 2) & packet loss detection • External connectivity test (default: 8.8.8.8) • Listening TCP/UDP sockets via ss / netstat / lsof
scripts/disk_usage_check.sh	• Filesystem capacity overview (df -h) • Capacity threshold alert (configurable THRESHOLD=80, space-safe parser) • Top largest top-level directories bounded to single filesystem (avoids /proc, /sys, /dev, network mounts) • Package manager cache size (apt, dnf, yum, pacman) • Installed kernel packages (dpkg, rpm, /boot/vmlinuz*) vs running kernel (uname -r) • Systemd journal log disk usage (journalctl --disk-usage)
scripts/boot_time_check.sh	• Overall boot time breakdown (systemd-analyze) • Top 10 slowest initializing units (systemd-analyze blame) • Slow unit threshold warning (configurable SLOW_UNIT_THRESHOLD=1000 ms, pure Bash duration parser supporting ms, s, min, h without bc) • Critical startup dependency chain (systemd-analyze critical-chain) • Boot-time errors & warnings from current boot (journalctl -b -p err) • Count of enabled startup units (systemctl list-unit-files)
scripts/service_audit.sh	• Failed systemd services (systemctl --failed) • Masked service units (systemctl list-unit-files --state=masked) • Enabled inactive services with smart filtering (ignores normal oneshot and timer/socket-triggered services) • Crash-looping detection (configurable RESTART_THRESHOLD=3, optimized to avoid querying inactive units) • Key service status with multi-distro alias matching (ssh/sshd, cron/crond, network managers, system loggers) • Service summary counts (total, active, failed)
scripts/security_audit.sh	• Listening network ports and services (ss -tuln) • World-writable files scan across common directories (/home, /var/www, /srv) • Recent failed SSH logins (inspects journal, with fallback to /var/log/auth.log or /var/log/secure) • Recent sudo command execution (queries _COMM=sudo in journal, with fallback to auth logs) • UID 0 privilege verification (flags accounts other than root in /etc/passwd) • Pending package updates (apt, dnf, yum, pacman)

---

Usage

1. Central Menu & CLI Runner (toolkit.sh)

Run all or individual checks interactively:

chmod +x toolkit.sh scripts/*.sh tests/*.sh
./toolkit.sh

Or pass subcommands directly:

./toolkit.sh network     # Run network diagnostics
./toolkit.sh disk        # Run disk & storage checks
./toolkit.sh boot        # Run systemd boot performance checks
./toolkit.sh service     # Run systemd service audit
./toolkit.sh security    # Run security posture audit
./toolkit.sh all         # Run all 5 diagnostics in sequence
./toolkit.sh --help      # Show CLI help

2. Standalone Script Execution

Each script in scripts/ is fully independent and can be executed from any working directory:

./scripts/network_health_check.sh
./scripts/disk_usage_check.sh
./scripts/boot_time_check.sh
./scripts/service_audit.sh
./scripts/security_audit.sh

---

Reports & Security

• Report Directory: Reports are saved to reports/ located in the repository root (or customized via REPORTS_DIR).
• File Naming: Timestamped format: <check_name>_report_YYYYMMDD_HHMMSS.txt.
• Restrictive Permissions: Created with umask 077 (read/write only by the executing user) to prevent leaking sensitive system information.
• Git Ignore: The reports/ folder and *_report_*.txt patterns are excluded in .gitignore.

---

Standardized Exit Codes

All scripts and the toolkit.sh orchestrator use consistent exit code semantics:

Exit Code	Meaning	Description
0	HEALTHY / OK	All diagnostics passed without warnings or detected issues.
1	WARNINGS DETECTED	One or more non-fatal warnings detected (e.g. partition $>80%$, failed services, slow boot unit).
2	EXECUTION ERROR	Missing required prerequisite or invalid configuration (e.g. running systemd checks on non-systemd init).

---

Cross-Distribution Support

• Primary Support: Debian, Ubuntu, Kali Linux, Linux Mint.
• Extended Support: Fedora, RHEL, Rocky Linux, AlmaLinux, CentOS, Arch Linux, openSUSE.
• Graceful Degradation: Scripts check for required utilities and degrade gracefully with informative messages rather than crashing when an optional component is unavailable.

---

Automated Testing & Linting

Running the Test Suite

The repository includes automated unit and mock tests validating duration parsing, threshold math, gateway routing logic, log fallback branching, and exit codes:

./tests/run_tests.sh

Running ShellCheck

All scripts adhere to ShellCheck standards:

shellcheck toolkit.sh scripts/*.sh tests/*.sh