Mac Triage

Turn macOS endpoint checks into a clear support-ticket handoff.

Mac Triage is a Python command-line portfolio project for IT support and endpoint troubleshooting. It runs six read-only checks and produces a local HTML dashboard, Markdown ticket summary, and structured JSON report. No third-party Python packages are required.

Demo preview

Synthetic example showing the report layout and troubleshooting guidance.

Status: starter implementation. Automated tests and synthetic demo are available. Live macOS validation must be documented before claiming production readiness. This project was developed with AI assistance; the learning goal is to understand, test, and extend it personally.

The problem

First-line support often repeats the same checks and manually assembles findings. This tool standardizes the evidence and next steps without copying usernames, hostnames, SSIDs, IP addresses, serial numbers, or raw command output into reports. It offers a focused workflow, not a claim of market novelty.

Quick start

Requires macOS and Python 3.9 or newer. Demo mode and unit tests also run on Linux. No sudo, pip packages, or background service required.

python3 --version
python3 triage.py --demo
python3 triage.py
python3 -m unittest discover -s tests -v

Each run prints its report folder. Open the HTML report using its printed path, for example:

open reports/run-EXAMPLE/report.html

Replace run-EXAMPLE with the actual folder printed by your run. Or use open reports and browse to the newest folder.

To skip all network probes:

python3 triage.py --offline

Checks and interpretation

Check	Evidence	Limitation
Disk space	Available percentage on the home volume; warning below 15%	Heuristic, not an APFS storage audit
IPv4 default route	A route has an interface	Does not prove connectivity; IPv6-only and VPN networks differ
Name resolution	System resolver resolves example.com	May use cache; does not isolate DNS-server health
HTTPS	Successful response from example.com using verified TLS	One endpoint only; proxies and service outages can affect results
FileVault	macOS reports encryption enabled or disabled	Unrecognized or inaccessible output becomes UNKNOWN
Application firewall	macOS reports firewall enabled or disabled	Not a complete security assessment

PASS means the specific observation met its criterion. WARN means investigate. UNKNOWN means the tool could not confirm the state. SKIP means the check was intentionally omitted. A warning is not a root-cause diagnosis.

Outputs

• report.html: self-contained browser report; no external scripts, fonts, or assets.
• report.md: findings and next steps for a ticket.
• report.json: versioned data for future automation.
• examples/: deliberately synthetic sample reports suitable for a public repository.

Generated live reports go in reports/, excluded by .gitignore. Review any file before publishing. Using --output outside reports/ means you must separately prevent those files from being committed.

Privacy and operating behavior

The program only reads system state and writes report files. It does not repair settings, delete data, upload reports, install agents, or request administrator access. Online mode performs a DNS lookup and HTTPS request to example.com; network providers and the destination may observe the connection and source IP. No diagnostic report is sent. Curl can honor environment proxy settings. --offline skips these probes; --demo does not inspect the machine.

Raw command output is held transiently for parsing, then replaced with predefined observations. Reports retain UTC timestamps and coarse disk-space percentages, so they are minimal reports rather than a guarantee of anonymity.

Design

1. Collectors call fixed system commands with bounded timeouts and without a shell.
2. Parsers produce a Check with status, evidence, and next step.
3. A report object contains only selected fields.
4. Renderers serialize that object into HTML, Markdown, and JSON.

Standard library modules include subprocess, shutil, argparse, dataclasses, json, and unittest. HTML output escapes diagnostic text. Each run receives a separate output directory. Exit status 0 means the report was generated, even if checks warn; 2 means a usage or write error.

Validation

python3 -m unittest discover -s tests -v

Tests exercise threshold boundaries, missing commands, timeouts, unexpected security output, network failures, omission of raw identifiers, offline behavior, HTML escaping, and report serialization. GitHub Actions is configured to run tests and a synthetic demo on Linux and macOS. A workflow file is not evidence that CI has run successfully; check the repository's Actions tab after publishing.

For real-device testing, see docs/VALIDATION.md. For setup and publishing, see docs/START_HERE.md. For the code walkthrough, see docs/LEARNING.md.

Next improvements

• Add a comparison command for two reports, using synthetic test fixtures first.
• Add configurable disk thresholds with argument validation.
• Expand IPv6 and proxy-aware troubleshooting.
• Add supported macOS version results after real-device testing.

References

• Python subprocess documentation
• Python shutil documentation
• GitHub: adding locally hosted code
• Local macOS command references: man route, man fdesetup, and man curl.

MIT licensed. See LICENSE.