disk-guardian

S.M.A.R.T. drive health scanner for macOS and Linux.

Scripts

All scripts are in scripts/. Run them in sequence or pipe them together:

cd ~/.openclaw/workspace/skills/disk-guardian/scripts

# Full pipeline (may need sudo on Linux):
python3 scan_drives.py | python3 parse_smart.py | python3 report.py

# With sudo (required on many Linux systems):
python3 scan_drives.py --sudo | python3 parse_smart.py | python3 report.py

# Save report to file:
python3 scan_drives.py | python3 parse_smart.py | python3 report.py --output ~/disk-report.md

# Record scan to history and get trend analysis:
python3 scan_drives.py | python3 parse_smart.py | python3 history.py --record

Data is stored in ~/.openclaw/workspace/disk-guardian/ by default. Use --data-dir to override on any script.

Workflow

1. Run scan_drives.py — detects drives and runs smartctl -a on each. Outputs JSON.
2. Pipe to parse_smart.py — extracts health attributes, assesses status (Good/Warning/Critical).
3. Pipe to report.py — generates markdown report with risk rankings and recommendations.
4. Optionally pipe to history.py --record to log the scan and get trend alerts.

Prerequisites

smartctl must be installed:

• macOS: brew install smartmontools
• Linux: sudo apt install smartmontools or sudo dnf install smartmontools

If smartctl is missing, scan_drives.py will output the install command and exit gracefully.

Script Details

scan_drives.py

• macOS: uses diskutil list to find whole disks, then smartctl -a /dev/diskN
• Linux: uses lsblk to find block devices, then smartctl -a /dev/sdX
• --sudo: prepend sudo to smartctl commands (needed on Linux without udev rules)
• Outputs JSON: {os, smartctl_path, drives_found, scan_results: [{device, smartctl_output|error}]}

parse_smart.py

• Detects drive type: NVMe, SSD, or HDD
• SATA/SSD: parses attribute table, extracts Reallocated Sector Count, Current Pending Sector, Uncorrectable Errors, Temperature, Power-On Hours, Read Error Rate, Seek Error Rate, and more
• NVMe: parses health log for Available Spare, Percentage Used, Media Errors, Unsafe Shutdowns, Critical Warning
• Assigns health_status: Good / Warning / Critical
• --input FILE: read from file instead of stdin
• --raw FILE --device NAME: parse a single raw smartctl text dump

history.py

• --record: append current scan to ~/.openclaw/workspace/disk-guardian/history.json
• --trends: analyze stored history for concerning patterns (rising reallocated sectors, climbing temps, declining NVMe spare)
• --list [--limit N]: show last N entries per device
• --data-dir PATH: use alternate storage location
• --device /dev/diskN: filter output to one device

report.py

• Generates markdown with drive inventory table, per-drive status, risk ranking with scores, human-readable flag explanations, trend alerts, and recommendations
• Risk ranking accounts for health status, flag severity, trend alerts, and drive age (power-on hours)
• --output FILE: save report to file instead of printing
• --trends FILE: load pre-computed trend JSON

SMART Attribute Reference

See references/smart-attributes.md for plain-English explanations of the 10 most critical SMART attributes and NVMe health indicators. Read it when explaining specific attributes to the user or when triaging a flagged drive.

Edge Cases

• smartctl not installed: scan_drives.py prints install instructions and exits with code 2
• Permission denied: Output includes hint to use --sudo; on Linux, add user to disk group as permanent fix
• Virtual drives (VMware, loop devices): smartctl will return errors; these are captured and included in error entries
• NVMe vs SATA: drive type auto-detected; NVMe uses health log fields instead of attribute table
• Corrupt history: history.py backs up the file and starts fresh automatically