From 0e882c5d250d4f6dc5b119b8ec54c3635931fdef Mon Sep 17 00:00:00 2001
From: ashishsinghbora <135435891+ashishsinghbora@users.noreply.github.com>
Date: Thu, 24 Sep 2026 23:55:02 +0530
Subject: [PATCH] docs: polish documentation with accurate options, safety
 details, and test framework

---
 README.md | 119 +++++++++++++++++++++++++++++++-----------------------
 1 file changed, 69 insertions(+), 50 deletions(-)

diff --git a/README.md b/README.md
index 8bf04c4..0b13f77 100644
--- a/README.md
+++ b/README.md
@@ -10,10 +10,11 @@ A clean, reliable, beginner-friendly Linux utility toolkit designed for systems
 
 **LinuxScripts** is a modular collection of well-tested, standalone Bash utilities organized into logical categories. Each script adheres to strict engineering and safety standards:
 - Starts with `#!/usr/bin/env bash` and enforces `set -euo pipefail`.
-- Supports `--help` / `-h` with consistent documentation.
+- Supports `--help` / `-h` with consistent documentation and examples.
 - Prioritizes read-only inspection; destructive operations require explicit user confirmation or flags.
 - Relies on standard Linux userland utilities with graceful dependency detection.
-- Includes an interactive terminal dashboard (`bin/linux-toolbox`) to run any tool easily.
+- Includes a CLI dispatcher and interactive terminal dashboard (`bin/linux-toolbox`) to run any tool easily.
+- Backed by an automated 53-point behavioral test suite run across multiple Linux distribution containers.
 
 ---
 
@@ -22,7 +23,7 @@ A clean, reliable, beginner-friendly Linux utility toolkit designed for systems
 ```text
 LinuxScripts/
 ├── bin/
-│   └── linux-toolbox                 # Interactive menu front-end
+│   └── linux-toolbox                 # CLI dispatcher and interactive menu
 ├── scripts/
 │   ├── system/                       # Host, health, kernel, boot, and service inspectors
 │   ├── storage/                      # Disk usage, large files, inodes, mounts, filesystems, SMART
@@ -34,11 +35,12 @@ LinuxScripts/
 │   ├── developer/                    # Dev tools, Git, Docker, Python, Node, command checks
 │   └── maintenance/                  # Safe cleanup, backups, archive extraction, file organizer, logs
 ├── tests/
-│   ├── test_all.sh                   # Automated validation and linting test harness
+│   ├── test_all.sh                   # Comprehensive test harness (syntax, lint, permissions, functional)
+│   ├── functional_test.sh            # Isolated behavioral and security assertion test suite
 │   └── fixtures/                     # Test fixtures
 ├── .github/
 │   └── workflows/
-│       └── shellcheck.yml            # CI validation workflow
+│       └── shellcheck.yml            # Multi-distro CI workflow (Ubuntu, Fedora, Arch, Alpine)
 ├── CONTRIBUTING.md                   # Contribution guide
 ├── LICENSE                           # MIT License
 └── SECURITY.md                       # Security reporting policy
@@ -50,9 +52,10 @@ LinuxScripts/
 
 The toolkit automatically detects and adapts to the following distributions and package managers:
 - **Arch Linux** (`pacman`)
-- **Debian / Ubuntu / Linux Mint** (`apt`)
+- **Debian / Ubuntu / Linux Mint** (`apt` / `apt-get`)
 - **Fedora / RHEL / AlmaLinux / Rocky** (`dnf`)
 - **openSUSE** (`zypper`)
+- **Alpine Linux** (`apk`)
 
 If an optional command is missing on a specific platform, scripts fail gracefully with clear installation hints instead of crashing.
 
@@ -65,13 +68,25 @@ Clone the repository and set executable permissions:
 ```bash
 git clone https://github.com/ashishsinghbora/LinuxScripts.git
 cd LinuxScripts
-chmod +x bin/linux-toolbox scripts/*/*.sh
+chmod +x bin/linux-toolbox scripts/*/*.sh tests/*.sh
 ```
 
-### Launch Interactive Toolbox
+### Linux Toolbox CLI & Interactive Menu
+
+The `linux-toolbox` binary acts both as an interactive menu and a CLI dispatcher:
 
 ```bash
+# Launch interactive keyboard menu
 ./bin/linux-toolbox
+
+# List all available categories and utilities
+./bin/linux-toolbox list
+
+# Run a utility directly by category/name
+./bin/linux-toolbox developer/command-exists bash
+
+# Run a utility with arguments
+./bin/linux-toolbox storage/directory-size -d /var/log
 ```
 
 ### Run Any Script Directly
@@ -85,14 +100,20 @@ Every script is standalone and can be executed directly from anywhere:
 # Find top 10 largest files in /var/log
 ./scripts/storage/find-large-files.sh -n 10 -d /var/log
 
-# Run full network diagnostics
+# Run full network diagnostics with status badges [PASS/FAIL/SKIPPED/UNKNOWN]
 ./scripts/network/network-diagnostics.sh
 
 # Audit SSH daemon security settings (read-only)
 ./scripts/ssh/ssh-hardening-check.sh
 
+# Safely extract archive with Zip Slip and traversal protection
+./scripts/maintenance/extract.sh archive.tar.gz ./output
+
+# Create timestamped backup with automatic destination exclusion
+./scripts/maintenance/backup.sh -d ./myproject -o ./backups
+
 # Organize loose files in a directory safely (dry-run first)
-./scripts/maintenance/file-organizer.sh --dry-run
+./scripts/maintenance/file-organizer.sh --dry-run -d ~/Downloads
 ```
 
 ---
@@ -102,17 +123,17 @@ Every script is standalone and can be executed directly from anywhere:
 | Category | Script | Description | Safety Mode |
 |---|---|---|---|
 | **System** | `system-info.sh` | OS, kernel, arch, uptime, CPU, memory, and root disk summary | Read-only |
-| | `system-health.sh` | Quick CPU, RAM, disk, load average, and service triage | Read-only |
-| | `kernel-info.sh` | Kernel version, architecture, and loaded modules | Read-only |
-| | `boot-info.sh` | Boot performance and startup times via `systemd-analyze` | Read-only |
+| | `system-health.sh` | Quick CPU, RAM, disk, load average, and process triage | Read-only |
+| | `kernel-info.sh` | Kernel version, loaded modules (`lsmod` / `/proc/modules`), and config | Read-only |
+| | `boot-info.sh` | Boot performance via `systemd-analyze` and logs (graceful container fallback) | Read-only |
 | | `failed-services.sh` | Lists systemd units currently in a failed state | Read-only |
 | **Storage** | `disk-usage.sh` | Human-readable mounted filesystem utilization | Read-only |
 | | `find-large-files.sh` | Locates largest files in specified directories | Read-only |
-| | `directory-size.sh` | Calculates directory disk space usage | Read-only |
+| | `directory-size.sh` | Calculates human-readable directory disk space usage (`-d / --dir`) | Read-only |
 | | `inode-usage.sh` | Inspects inode allocation and flags >90% exhaustion | Read-only |
 | | `mount-info.sh` | Details mounted filesystems and options via `findmnt` | Read-only |
-| | `filesystem-info.sh` | Inspects filesystem types, UUIDs, and block devices | Read-only |
-| | `disk-health.sh` | SMART health assessment using `smartctl` | Read-only |
+| | `filesystem-info.sh` | Inspects filesystem types, UUIDs, block devices, and ext* stats | Read-only |
+| | `disk-health.sh` | S.M.A.R.T. health assessment using `smartctl` with device targeting | Read-only |
 | **Network** | `network-info.sh` | IP addresses, interfaces, default gateway, and DNS | Read-only |
 | | `ping-test.sh` | ICMP latency and packet loss verification | Read-only |
 | | `dns-test.sh` | DNS resolution check via `dig` or `nslookup` | Read-only |
@@ -120,14 +141,14 @@ Every script is standalone and can be executed directly from anywhere:
 | | `route-info.sh` | Displays kernel IP routing tables | Read-only |
 | | `internet-test.sh` | Tests WAN internet connectivity | Read-only |
 | | `listening-ports.sh` | Lists open listening TCP/UDP ports via `ss` / `netstat` | Read-only |
-| | `network-diagnostics.sh`| End-to-end connectivity, DNS, ping, and gateway diagnostics | Read-only |
-| **Process** | `process-info.sh` | Top CPU and RAM consuming processes | Read-only |
-| | `kill-process.sh` | Safe process termination with prompt and custom signals | Confirmation required |
-| **Packages** | `update-system.sh` | Multi-distro package database and package updates | Dry-run available (`-n`) |
-| | `install-package.sh` | Installs packages across supported package managers | Prompts before install |
-| | `remove-package.sh` | Safely removes packages across supported package managers | Prompts before removal |
-| | `search-package.sh` | Queries package repositories for keywords | Read-only |
-| | `package-info.sh` | Inspects package details and version metadata | Read-only |
+| | `network-diagnostics.sh`| Connectivity, DNS, ping, and gateway diagnostics with status badges | Read-only |
+| **Process** | `process-info.sh` | Process status by PID, process search, user filter, or top CPU/RAM | Read-only |
+| | `kill-process.sh` | Process termination guarding against PID 1, self ($$), and parent ($PPID) | Confirmation required |
+| **Packages** | `update-system.sh` | Updates system across pacman, apt, dnf, zypper, and apk | Dry-run available (`-n`) |
+| | `install-package.sh` | Array-safe package installation with dry-run support | Prompts before install |
+| | `remove-package.sh` | Array-safe package removal with dry-run support | Prompts before removal |
+| | `search-package.sh` | Queries package repositories across all supported package managers | Read-only |
+| | `package-info.sh` | Package details and version metadata with sync database fallback | Read-only |
 | | `package-manager-info.sh`| Identifies active system package manager and version | Read-only |
 | **Hardware** | `hardware-summary.sh`| Aggregates CPU, GPU, memory, disk, and USB information | Read-only |
 | | `cpu-info.sh` | CPU model, architecture, cores, sockets, and flags | Read-only |
@@ -136,7 +157,7 @@ Every script is standalone and can be executed directly from anywhere:
 | | `usb-devices.sh` | Enumerates attached USB devices via `lsusb` or sysfs | Read-only |
 | | `pci-devices.sh` | Lists all detected PCI devices via `lspci` | Read-only |
 | | `battery-info.sh` | Power supply and battery capacity/status | Read-only |
-| **SSH** | `ssh-key-setup.sh` | Secure Ed25519/RSA key generator with overwrite protection | Confirmation required |
+| **SSH** | `ssh-key-setup.sh` | Ed25519/RSA-4096 key generator with automatic backup on overwrite | Confirmation required |
 | | `ssh-config-check.sh` | Validates client SSH configuration (`~/.ssh/config`) | Read-only |
 | | `ssh-host-info.sh` | Queries remote host fingerprints via `ssh-keyscan` | Read-only |
 | | `ssh-hardening-check.sh`| Security audit of `sshd_config` against best practices | Read-only (never edits) |
@@ -146,46 +167,44 @@ Every script is standalone and can be executed directly from anywhere:
 | | `python-info.sh` | Python 3 version, virtual environment, and pip packages | Read-only |
 | | `node-info.sh` | Node.js, npm, and global package modules | Read-only |
 | | `command-exists.sh` | Verifies binary availability across `$PATH` | Read-only |
-| **Maintenance**| `cleanup-cache.sh` | Cleans user caches and logs safely | Confirmation required |
-| | `backup.sh` | Creates compressed `.tar.gz` archives of directories | Safe write |
-| | `extract.sh` | Universal archive unpacker (`tar`, `zip`, `gz`, `bz2`, `xz`, `7z`) | Safe write |
-| | `file-organizer.sh` | Categorizes loose files by extension | Dry-run available (`-n`) |
+| **Maintenance**| `cleanup-cache.sh` | Safe user thumbnail/trash cleanup and package manager cache reporting | Confirmation required |
+| | `backup.sh` | Creates compressed `.tar.gz` with destination recursion exclusion | Safe write |
+| | `extract.sh` | Unpacker with Zip Slip and path traversal (`../`) protection | Safe write |
+| | `file-organizer.sh` | Categorizes loose files by extension (skips symlinks/hidden/collisions) | Dry-run available (`-n`) |
 | | `log-inspect.sh` | Inspects and filters system and application logs | Read-only |
 
 ---
 
-## Safety Philosophy
+## Safety & Security Engineering
 
-- **Zero Hidden Actions:** Every script clearly describes what it does before taking action.
-- **Read-Only by Default:** All diagnostics, audits, and hardware/system inspectors never alter files or configs.
-- **Protection for Destructive Steps:** Operations that delete caches or terminate processes (`kill-process.sh`, `cleanup-cache.sh`, `remove-package.sh`) require interactive confirmation unless explicit override flags are supplied.
-- **SSH Hardening is Advisory:** `ssh-hardening-check.sh` will **never** alter or overwrite `sshd_config`. It only highlights recommendations.
-- **Safe Path Handling:** All scripts use proper quoting (`"$variable"`) to avoid space-splitting and injection bugs.
+- **Path Traversal & Archive Security:** `extract.sh` validates all archive entries before extraction, rejecting relative path traversal (`../`) and absolute paths (`/etc/...`).
+- **Backup Recursion Prevention:** `backup.sh` automatically computes relative paths and excludes destination directories situated inside the source directory, preventing infinite archive bloat. Includes failure cleanup traps.
+- **Process Termination Safeguards:** `kill-process.sh` strictly forbids sending signals to PID 1 (init/systemd), PID 0, the script itself (`$$`), or its parent process (`$PPID`).
+- **Cache Cleaning Protection:** `cleanup-cache.sh` eliminates arbitrary deletions of `/tmp` sockets/locks, safely targeting only user thumbnail caches and trash directories with interactive confirmation.
+- **SSH Key Overwrite Safety:** `ssh-key-setup.sh` generates modern Ed25519 keys, sets strict 0700/0600 permissions, and creates timestamped `.bak_*` backups before replacing existing keys.
+- **Array-Based Command Execution:** Package manager scripts invoke commands via Bash arrays (`"${CMD[@]}"`) rather than evaluated strings, preventing argument word-splitting bugs.
 
 ---
 
 ## Testing & Quality Assurance
 
-The repository includes an automated validation test suite in `tests/test_all.sh`.
-
-Run the test suite locally:
+The repository includes a comprehensive two-tier test framework:
 
 ```bash
+# Run full static analysis, ShellCheck, and behavioral tests
 bash tests/test_all.sh
-```
-
-What the test suite checks:
-1. **Syntax:** Executes `bash -n` on every script.
-2. **Linting:** Runs `shellcheck` when installed.
-3. **Permissions:** Confirms executable bits are set.
-4. **Help Flag:** Verifies that every script responds to `-h` or `--help` and exits with status `0`.
 
----
-
-## Limitations
+# Run behavioral assertion suite directly
+bash tests/functional_test.sh
+```
 
-- **Systemd vs Non-Systemd:** Scripts like `boot-info.sh` and `failed-services.sh` rely on `systemd`. On runit, openrc, or SysVinit systems, these will report that systemd is unavailable.
-- **Root Permissions:** Read-only inspection commands run without elevated privileges. Commands requiring root privileges (e.g., package installation, SMART tests via `smartctl`) will prompt for `sudo` only when strictly required.
+What the test framework verifies:
+1. **Syntax Validation:** Executes `bash -n` on all 34 scripts.
+2. **Linting:** Enforces strict ShellCheck rules with zero warnings.
+3. **Executable Bit:** Verifies executable file permissions.
+4. **Interface Consistency:** Tests `--help` and `-h` across every utility.
+5. **Behavioral Assertions:** Runs 53 isolated functional tests using temporary workspaces (`mktemp`), mock package managers, simulated archives, and controlled processes.
+6. **Continuous Integration:** Automatically tested on every push and PR across Ubuntu 24.04, Fedora, Arch Linux, and Alpine Linux container environments.
 
 ---