Monocle inspects code and produces four audience-specific summaries: Executive, Security, Manager, Engineer

Background
Problem
Reviewing a 5k-line zsh script for leadership, a change board, the security team, and the engineer who has to maintain it is painful — and typically produces several different, inconsistent reports.
Inspiration
After attending Rob Potvin’s JNUC 2026 session — where he shared his quiz-my-code AI skill — on the plane ride home, I captured the following, heaven-inspired idea:
Create an AI skill to summarize code at various levels: Executive, Security, Manager, Engineer
But what to call it?
🔍 Monocle
Monocle inspects scripts and small repos (local or on GitHub), plus diagnostic and support bundles, and produces four audience-specific summaries (Executive, Security, Manager, Engineer) plus a Monocle Score.
Monocle is an Agent Skill tuned for shell (sh / bash / zsh), Python, AppleScript, Swift helpers, and Jamf Pro / macOS automation. While it pays particular attention to privilege elevation, silent failures, secrets, and environment assumptions, it aims to provide AI-assisted analysis, not a deterministic security scanner. Caveat emptor.
| View | For | Answers |
|---|---|---|
| 👔 Executive | Leadership, change boards | What it does, business risk, and a clear recommendation (up to 6 bullets) |
| 🔒 Security | Security reviewers | Severity-ranked findings, privilege map, secrets, network, and persistence |
| 📋 Manager | Team leads, service owners | Ownership, fragility, change risk, and prioritized action items |
| 🛠️ Engineer | Maintainers, reviewers | Control flow, footguns, edge cases, and before/after refactors with line references |
📈 Monocle Score
Every report starts at 100 and loses points for distinct issues:
| Issue | Deduction |
|---|---|
| 🔴 Critical / 🟠 High / 🟡 Medium / 🔵 Low Security finding | 40 / 20 / 8 / 3 |
| ⚪ Info Security finding | 0 |
| Non-security issue (Manager fragility, Engineer footgun / edge-case) | 2 each (max 20) |
The most severe finding also sets a hard band. The final score must land in (Critical 0–39, High 25–69, Medium 50–89, otherwise 70–100). A raw score outside that band is clamped. One serious finding cannot hide inside an otherwise clean report, and a pile of small issues cannot push a report into a worse band than its worst finding warrants.
Bands:
90–100 🟢 Excellent | 70–89 🔵 Good | 50–69 🟡 Fair | 25–49 🟠 Poor | 0–24 🔴 Critical
Philosophy: The score rates the code, not the Mac Admin. Documented powerful operations behind an admin-controlled gate (Jamf Pro parameters, policy scope, confirmation dialog, etc.) are not scored as defects. When severity depends on deployment choices, the headline score rates the Deployment context you supply (or, without one, the documented / safe baseline); the riskier alternate is shown separately, and the assumptions are listed as an Operator baseline checklist.
Probable, not possible: Severity weighs likelihood as well as impact. Local abuse that crosses no privilege or account boundary — and either gains no more than the tool’s own UI already gives or meets a platform control that enforces the outcome anyway — is lowered one level. When that control is the backstop and only a reminder or that Mac’s own reported state changes (for example, DDM still installs at its deadline), it’s ⚪ Info. Obscurity, required skill, and no public exploit never lower a rating.
Installation
- Visit the Monocle releases page
- Download both the
.zipand the.zip.sha256from the latest release - In Terminal,
cd ~/Downloadsand validate the downloaded.zip- For example:
shasum -a 256 -c Monocle-b-as-in-bdellium.zip.sha256
- For example:
- Only if you observe
OK, expand the.zip- For example,
unzip Monocle-b-as-in-bdellium.zip
- For example,
- Validate the unpacked skill’s SHA256 matches the
skill_sha256hash displayed on the release page- For example,
python3 monocle/scripts/verify_report.py --manifest monocle
- For example,
- Only after you’ve confirmed a matching
skill_sha256, install the skill:- Claude Code
mkdir -pv ~/.claude/skills(as needed)rm -Rfv ~/.claude/skills/monocle(if upgrading, remove the old directory first)cp -Rv monocle ~/.claude/skills/
- Codex
mkdir -pv ~/.agents/skills(as needed)rm -Rfv ~/.agents/skills/monocle(if upgrading, remove the old directory first)cp -Rv monocle ~/.agents/skills/
- Claude Code
- Re-verify the installed skill
- Claude Code:
python3 ~/.claude/skills/monocle/scripts/verify_report.py --manifest ~/.claude/skills/monocle - Codex:
python3 ~/.agents/skills/monocle/scripts/verify_report.py --manifest ~/.agents/skills/monocle
- Claude Code:
Usage
Monocle activates automatically when a request matches its description; you can also call it by name.
Explicit invocation: Claude Code: /monocle; Codex: $monocle.
monocle this https://github.com/owner/repo/blob/main/script.zshmonocle review ./postinstallGive me the security view of this script(attach the file)
See Usage in the README.md for additional information.
Examples
Monocle reports may contain security-sensitive findings; by default they’re stored outside the target repository, and they should not be committed to source control without review.
DDM OS Reminder
Monocle Report: DDM-OS-Reminder
Monocle Score
Monocle Score: 79/100 (🔵 Good) — Approve
Score: 79/100 (🔵 Good) at the documented-deployment baseline — 3 Low, 1 Info, 6 non-security, or 76/100 (🔵 Good) if Force restart mode is enabled on Macs that lack Apple’s DDM state plist
Overall risk: 🔵 Low, or 🔵 Low if Force restart mode is enabled on Macs that lack Apple’s DDM state plist
Recommendation: Approve — no Critical, High, or Medium findings; the remaining gaps let a local user quiet their own reminders or affect admin-side reports, and none changes Apple’s DDM enforcement.
Generated by: Claude Opus 5.5 (claude-opus-5-5) · Skill: monocle
| Source | IDs | Count | Each | Deduction |
|---|---|---|---|---|
| 🔴 Critical | — | 0 | 40 | 0 |
| 🟠 High | — | 0 | 20 | 0 |
| 🟡 Medium | — | 0 | 8 | 0 |
| 🔵 Low | S1, S2, S3 | 3 | 3 | 9 |
| ⚪ Info | S4 | 1 | 0 | 0 |
| Non-security | fatal-exit relaunch loop; shared-log interaction history; dscl home parse; triplicated resolver; undocumented Apple log wording fails silent; swiftDialog update unverified | 6 | 2 (max 20) | 12 |
| Not scored | assemble RDNN regex and temp cleanup; createPlist eval; createSelfExtracting newest-file pick; preference-test dead trap; CSV helper echo escapes and parallel token handling; demo Force restarts the test Mac | 8 | 0 | 0 |
Total: 100 − 21 = 79 → 79/100 (🔵 Good)
Alternate: S4 becomes 🔵 Low when PastDeadlineRestartBehavior is Force on Macs without SoftwareUpdateDDMStatePersistence.plist: 100 − 24 = 76, no clamp → 76/100 (🔵 Good).
Operator baseline:
PastDeadlineRestartBehaviorstays at its defaultOff, orForceis used only on macOS versions where/var/db/softwareupdate/SoftwareUpdateDDMStatePersistence.plistexists (S4 → Low if not).
Executive View
Executive View: Approve — well-hardened; residual gaps only quiet reminders
In one sentence: Shows Mac users a clear, branded reminder of the macOS update deadline that Apple’s device management already enforces, escalating as the deadline approaches and passes, so fewer Macs reach the forced deadline unprepared.
- Runs with full administrator access on every Mac it is deployed to, and keeps running in the background after restarts. It checks every minute whether a reminder is due; most checks finish immediately.
- Can restart Macs after the deadline, but only if administrators turn that on. The default is off; when set to “Force”, users get a countdown and may lose unsaved work.
- A determined user can silence their own reminders by writing fake entries into a system log every user can write to. This weakens the nudge, not the enforcement: Apple still installs the update at the deadline.
- The companion reporting tool for administrators can be fed spreadsheet formulas by anyone with admin rights on a managed Mac who renames it; the risk is to the administrator who opens the report, not to the fleet.
- Maintained by one person (about 96% of commits), with active releases and a documented security policy.
Monocle Score: 79/100 (🔵 Good), or 76/100 (🔵 Good) if Force restarts are enabled on older Macs that lack Apple’s update-state file
Recommendation: Approve — no Critical, High, or Medium findings; the remaining gaps let a local user quiet their own reminders or affect admin-side reports, and none changes Apple’s DDM enforcement.
Security View
Security View: 🔵 Low risk — 3 Low, 1 Info findings
Execution context: Deployment script runs as root via MDM policy; runtime dor.zsh and dor-starter.zsh run as root from a LaunchDaemon; UI and open calls drop to the console user with launchctl asuser … sudo -u. Resources/Jamf-getDDMstatusFromCSV.zsh runs as the administrator on their own workstation.
Overall risk: 🔵 Low — the code is defensively built; the remaining issues let a local user suppress their own reminders or inject formulas into an admin-side report, and none yields privilege escalation or alters Apple’s enforcement.
Findings
| ID | Severity | Title | Location |
|---|---|---|---|
| S1 | 🔵 Low | User-appendable install.log can suppress reminders despite corroboration |
reminderDialog.zsh:3750 |
| S2 | 🔵 Low | CSV formula injection in the Jamf Pro status report | Resources/Jamf-getDDMstatusFromCSV.zsh:898 |
| S3 | 🔵 Low | Jamf API helper leaves tokens live on error exits and accepts plain-HTTP server URLs | Resources/Jamf-getDDMstatusFromCSV.zsh:141 |
| S4 | ⚪ Info | Uncorroborated declarations trusted when Apple’s DDM state plist is absent (documented residual risk) | reminderDialog.zsh:3725 |
S1 — User-appendable install.log can suppress reminders despite corroboration · 🔵 Low
- Location:
reminderDialog.zsh:3750(invalid-declaration match),reminderDialog.zsh:3476(candidateHasNoMatchScanFailure),reminderDialog.zsh:3003(Update Tonight sender check),reminderDialog.zsh:3128(4,000-line window); the same resolver is copied intoResources/JamfEA-Pending_OS_Update_Date.zsh:712andResources/JamfEA-Pending_OS_Update_Version.zsh:673. - Origin: Platform + Code — any local user can append lines, sender tag included, to
/var/log/install.log(Known Apple platform behaviors: install.log is user-writable). The code corroborates positive declarations against the root-ownedSoftwareUpdateDDMStatePersistence.plist, but trusts negative and suppressive evidence from the log without corroboration. - Evidence:
if (( ${+ddmInvalidCandidateContexts[${candidateSignature}]} )); then(a “Failed to add declaration … Invalid declaration” line from any sender discards the real candidate);[[ ! "${logLine}" =~ ${ddmSoftwareUpdatedSenderRegex} ]](Update Tonight evidence accepted when the line merely carries asoftwareupdated[pid]:tag, whichlogger -t softwareupdated -iproduces). - Impact: A standard user can make the resolver return
missing,noMatch, or (by flooding past the 4,000-line window) find nothing, which suppresses all reminders, aggressive mode, and the Prompt/Force restart workflow; or forge Update Tonight evidence to pause normal reminders until midnight each day. The Pending OS Update EAs report the same wrong state to inventory. Apple’s DDM enforcement is unaffected. README’s claim that Update Tonight “Evidence must be logged bysoftwareupdated” (README.md:49) is not upheld. Traced from reading the code; not reproduced. - Fix: Treat the persistence plist as authoritative when it is available: if it lists an active declaration, keep reminding even when the log offers no candidate, an invalid marker, or a no-match marker, and log the disagreement at
[WARNING]. Require Update Tonight evidence to be corroborated by root-owned state (or drop the suppression), and state the residual log-spoofing risk for Update Tonight inSECURITY.md.
S2 — CSV formula injection in the Jamf Pro status report · 🔵 Low
- Location:
Resources/Jamf-getDDMstatusFromCSV.zsh:898(sanitizeForCsv), written atResources/Jamf-getDDMstatusFromCSV.zsh:3831, opened atResources/Jamf-getDDMstatusFromCSV.zsh:4215. - Origin: Code — device-reported inventory values are quoted for CSV structure but not neutralized for spreadsheet formulas.
- Evidence:
data="${data//\"/\"\"}"(only quotes and CR/LF are handled);open "${csvOutput}" >/dev/null 2>&1 &! - Impact: Anyone with local admin rights on one managed Mac can set its computer name to a value starting with
=,+,-, or@. When the administrator’s report opens in Excel or Numbers, the cell evaluates as a formula (for example aHYPERLINKlure or data-exfiltration formula). Requires the admin to open the report and, for most payloads, to click or enable content. - Fix: In
sanitizeForCsv, prefix a single quote when the value starts with=,+,-,@, tab, or CR:[[ "${data}" == [=+\-@$'\t'$'\r']* ]] && data="'${data}".
S3 — Jamf API helper leaves tokens live on error exits and accepts plain-HTTP server URLs · 🔵 Low
- Location:
Resources/Jamf-getDDMstatusFromCSV.zsh:141(cleanupEXIT trap),Resources/Jamf-getDDMstatusFromCSV.zsh:437andResources/Jamf-getDDMstatusFromCSV.zsh:463(typed URL),Resources/Jamf-getDDMstatusFromCSV.zsh:425(plist URL check). - Origin: Code — the normal exit invalidates the bearer token (
Resources/Jamf-getDDMstatusFromCSV.zsh:4190) and so does INT/TERM (Resources/Jamf-getDDMstatusFromCSV.zsh:205), butdie()paths such asResources/Jamf-getDDMstatusFromCSV.zsh:3137exit throughcleanup, which never callsinvalidateBearerToken. - Evidence:
die "Failed to process CSV file.";apiUrl="${userInput}"with nohttps://check (the plist path only checks!= http*). - Impact: A failed run leaves a valid Jamf Pro bearer token alive until it expires; a mistyped
http://URL sends basic-auth credentials or the client secret in cleartext. - Fix: Call
invalidateBearerTokenfromcleanup; reject anyapiUrlthat doesn’t match^https://at every entry point.
S4 — Uncorroborated declarations trusted when Apple’s DDM state plist is absent · ⚪ Info
- Location:
reminderDialog.zsh:3725,reminderDialog.zsh:3198 - Origin: Platform + Deployment — when
SoftwareUpdateDDMStatePersistence.plistis missing or unrecognized, the code falls back to trustinginstall.logtext, logs a[WARNING], andSECURITY.md:45documents this as accepted residual risk. - Evidence:
[[ "${ddmStatePersistenceStatus}" == "available" ]] || return 0 - Impact: At the documented default (
PastDeadlineRestartBehaviorOff), a forged past-due declaration only produces false reminders and wrong EA inventory, asSECURITY.mdstates. If an admin setsForce, a local user on such a Mac can forge a declaration two days past due and trigger the forced-restart countdown for whoever is at the console;SECURITY.mddoesn’t mention this. 🔵 Low in that configuration. - Fix: Never enter Force mode from an uncorroborated declaration (downgrade to Prompt), and extend
SECURITY.md:45to say so.
Low / Info roll-up:
- Credit:
PATHpinned to system directories and swiftDialog called by its root-owned bundle path (reminderDialog.zsh:20,launchDaemonManagement.zsh:41); per-runmktemp -ddialog directory with guarded cleanup (reminderDialog.zsh:4348); atomicmktemp+mv -freplacement of the runtime script, starter, fallback plist, and LaunchDaemon with ownership verified bystat(launchDaemonManagement.zsh:603,launchDaemonManagement.zsh:887);chown -hon owned assets; console-user language sanitized with an allowlist regex before it reaches${(P)}/printf -v(reminderDialog.zsh:571); swiftDialog pkg checked withspctl -a -vv -t installand Team IDPWA5…beforeinstaller(launchDaemonManagement.zsh:1126); allcurlcalls use--failand timeouts; CI actions SHA-pinned withpermissions: read-all; API credentials reach curl through--config -on stdin (Resources/Jamf-getDDMstatusFromCSV.zsh:655). - Info:
Resources/JamfEA-DDM-OS-Reminder-User-Clicks.zsh:17andResources/monitorRemoteSession.zsh:111append/usr/local:/usr/local/binto root’sPATH; system directories come first and every command used exists there, so no hijack path today, but it departs from the main scripts’ hardening. - Info: the Jamf CSV helper accepts the password as a positional argument and offers
--insecure; both are opt-in and print warnings (Resources/Jamf-getDDMstatusFromCSV.zsh:2918,Resources/Jamf-getDDMstatusFromCSV.zsh:637). - Info: agent configuration (
AGENTS.md,.github/copilot-instructions.md,.github/agents/,.github/instructions/) contains coding and style rules only, including a terse reply-mode preference; no reviewer-steering text and no session hooks.
Privilege map
- Install/replace swiftDialog pkg —
launchDaemonManagement.zsh:1131— root - Write
/Library/Management/<rdnn>/dor.zsh,dor-starter.zsh, fallback plist —launchDaemonManagement.zsh:603,launchDaemonManagement.zsh:331— root - Write and bootstrap LaunchDaemon
/Library/LaunchDaemons/<rdnn>.dor.plist; remove its quarantine xattr —launchDaemonManagement.zsh:887— root - Write
dor-state.plist,dor.pid—reminderDialog.zsh:777,reminderDialog.zsh:702— root - Download icons into a private
/var/tmpdirectory —reminderDialog.zsh:4405,reminderDialog.zsh:4427— root - Restart the Mac (
/sbin/shutdown -r now) in Force mode —reminderDialog.zsh:4682— root - Open System Settings / URLs, request restart via loginwindow —
reminderDialog.zsh:4693and thecase ${returncode}block — console user vialaunchctl asuser - Uninstall: removes only the project’s own files and empty directories —
launchDaemonManagement.zsh:510— root
Secrets inventory
- Jamf Pro API password or client secret — prompted with
read -s, or optional positional argument —Resources/Jamf-getDDMstatusFromCSV.zsh:539— passed to curl via stdin config; exposed inpsand shell history only when the admin uses the positional form. - Jamf Pro bearer token — in memory —
Resources/Jamf-getDDMstatusFromCSV.zsh:655— not logged; not invalidated ondie()paths (S3). - No secrets in the endpoint scripts or in MDM parameters (Parameters 4–6 carry a reset mode, a version, and a date).
Network egress
api.github.com/repos/swiftDialog/swiftDialog/releases/latestand thegithub.compkg URL — GET — TLS verified, URL prefix checked, Team ID verified —launchDaemonManagement.zsh:1095*.ics.services.jamfcloud.com/icon/…(or admin-set overlay URL) — GET — TLS verified by default,--fail --max-time 10—reminderDialog.zsh:4405,reminderDialog.zsh:4427- Admin-supplied Jamf Pro URL — GET/POST — TLS verified unless
--insecure; nohttpsenforcement on typed URLs (S3) —Resources/Jamf-getDDMstatusFromCSV.zsh:655
Persistence
- LaunchDaemon
/Library/LaunchDaemons/<rdnn>.dor.plist,StartInterval60,RunAtLoad, output to the project log —launchDaemonManagement.zsh:887 - Runtime scripts and state under
/Library/Management/<rdnn>/(root:wheel 0755) —launchDaemonManagement.zsh:510
Manager View
Manager View: Production-grade; single maintainer, active releases
Ownership: Dan K. Snelson — 517 of 536 GitHub contributions (about 96%), script headers point to snelson.us/ddm, SECURITY.md names a reporting address. Bus factor: 1.
Maturity: Production-grade — validates preferences and parameters, writes atomically, logs to a known path, versioned with a changelog, CI security gates, fails closed on unknown DDM states.
Change risk: High — root runtime on every in-scope Mac with a per-minute heartbeat; ~5,500-line runtime with resolver logic copied into two EAs; no automated behavior tests.
What it depends on
- Apple’s
install.logwording and the layout ofSoftwareUpdateDDMStatePersistence.plist— undocumented internals; a wording change silently turns reminders off (see hotspots). - swiftDialog 3.1.0.4994+ at
/Library/Application Support/Dialog/Dialog.app— installed from GitHub by the deployment script. - Managed preferences (
<rdnn>.dormconfiguration profile) — supply branding, schedule, and restart policy; RDNN must match across all generated files. - Jamf-hosted icon URLs — cosmetic; failures fall back to the Finder icon.
- One maintainer for releases and security fixes.
Fragility hotspots
- If no one is logged in, or swiftDialog is missing, the runtime exits fatally without advancing its schedule, so the starter relaunches it every minute; at the login window each run logs about 120 counter lines. You’d notice only from log volume —
reminderDialog.zsh:5058,reminderDialog.zsh:2700. - Quiet-period and periodic-reminder history is grepped from the shared organization log without filtering by script name, so other tools writing
Return Code:lines can suppress reminders; a 10 MB rotation wipes the history, and rotated.oldfiles are never pruned —reminderDialog.zsh:5269,reminderDialog.zsh:5014. - An Apple wording change in
install.logmakes the resolver returnmissing, which suppresses every reminder and is logged only as a notice; the Pending OS Update EAs then show no pending update —reminderDialog.zsh:4083. - The ~800-line DDM resolver exists three times (runtime plus two EAs); a fix applied to one copy drifts from the others —
reminderDialog.zsh:3681,Resources/JamfEA-Pending_OS_Update_Date.zsh:654,Resources/JamfEA-Pending_OS_Update_Version.zsh:615. - swiftDialog upgrades don’t check the
installerexit code or re-check the version, so a failed upgrade leaves the old version in place and deployment reports success —launchDaemonManagement.zsh:1131,launchDaemonManagement.zsh:1174.
Change & rollback
- Testing:
zsh -nsyntax checks, Semgrep, Gitleaks, and ShellCheck in CI;demomode andResources/reminderDialogPreferenceTest.zshfor manual checks. No automated behavior or resolver fixture tests in the repo. - Rollback: Clean. Parameter 4
Uninstallremoves the LaunchDaemon and every runtime file, leaving shared directories that aren’t empty; redeploying an older artifact replaces the runtime atomically. - Deploy path: MDM policy runs the assembled
Artifacts/ddm-os-reminder-<rdnn>-….zsh(or the self-extracting wrapper) as root; preferences arrive by configuration profile.
Action items
| # | Action | Owner role | Effort | Priority |
|---|---|---|---|---|
| 1 | Make the DDM state plist authoritative over log-based suppression; corroborate or drop Update Tonight suppression (S1) | Mac engineer | M | P2 |
| 2 | Block Force mode on uncorroborated declarations and update SECURITY.md (S4) |
Mac engineer | S | P2 |
| 3 | Neutralize formula prefixes in the CSV report; invalidate tokens on every exit; require https:// (S2, S3) |
Mac engineer | S | P2 |
| 4 | Advance or back off the schedule on fatal exits, and stop the per-second counter log at the login window | Mac engineer | S | P2 |
| 5 | Record interaction history in dor-state.plist rather than grepping the shared log; prune rotated logs |
Mac engineer | M | P3 |
| 6 | Move the DDM resolver into one shared source that assemble.zsh injects into the runtime and both EAs |
Mac engineer | M | P3 |
| 7 | Add a second maintainer or reviewer for releases | Service owner | M | P3 |
Engineer View
Engineer View: Careful resolver and file handling; fix fatal-exit scheduling and log-derived state
Shape: zsh; reminderDialog.zsh ~5,475 lines / 156 functions (runtime, deployed as dor.zsh), launchDaemonManagement.zsh ~1,289 lines / 43 functions (MDM entry point, embeds runtime and starter via heredoc), assemble.zsh builds artifacts; invoked as an MDM policy, then every 60 s by a LaunchDaemon running dor-starter.zsh.
Inputs → Outputs: MDM Parameters 4–6, managed/local <rdnn>.dorm plists, /var/log/install.log, SoftwareUpdateDDMStatePersistence.plist, dor-state.plist, console user’s .GlobalPreferences.plist → swiftDialog UI, dor-state.plist schedule, /var/log/<rdnn>.log, optional restart, exit codes.
Control flow
- Deployment: validate/install swiftDialog (
launchDaemonManagement.zsh:1156), reset per Parameter 4 (launchDaemonManagement.zsh:510), write or remove fallback plist from Parameters 5–6 (launchDaemonManagement.zsh:379). - Atomically install
dor.zshanddor-starter.zshafterzsh -n(launchDaemonManagement.zsh:603), then the LaunchDaemon, bootstrap, andkickstart -k(launchDaemonManagement.zsh:887). - Starter every 60 s: exit if
dor.pidis live orNextScheduledReminderis in the future orFALSE; otherwise launchdor.zshwithDOR_LAUNCH_SOURCE=starter(launchDaemonManagement.zsh:825). - Runtime globals: uptime, disk space via JXA with
diskutilfallback (reminderDialog.zsh:190); log pre-flight and 10 MB rotation (reminderDialog.zsh:4999); root check, PID file, traps (reminderDialog.zsh:5036). - Wait up to 120 s for a real console user, else
fatal(reminderDialog.zsh:5052). - Load preferences Managed → Local → Defaults with type validation (
reminderDialog.zsh:1960), validate cadence values (reminderDialog.zsh:2094), resolve language (reminderDialog.zsh:2584). demobranch (source copy only; stripped from assembled artifacts) simulates a deadline and displays (reminderDialog.zsh:5106).- Resolve DDM declaration from the last 4,000
install.loglines, corroborated against the persistence plist; onmissing/conflict/noMatch/invalidVersiontry the MDM fallback plist; unknown states fail closed (reminderDialog.zsh:4060). - Evaluate past-deadline Prompt/Force and aggressive mode, with kill-switch file (
reminderDialog.zsh:4542,reminderDialog.zsh:4582). - Suppression gates in order: display window and periodic reminder from log history, Update Tonight, quiet period, display-sleep assertions (up to
MeetingDelay) (reminderDialog.zsh:5251). - Build text, download icons, display swiftDialog; threshold monitor can refresh an open dialog (
reminderDialog.zsh:4708). - Handle return codes: Force mode loops until restart; otherwise schedule quiet-period or aggressive redisplay and open Software Update (
reminderDialog.zsh:4808). quitScriptwrites the next schedule and cleans the runtime directory and PID file (reminderDialog.zsh:4969);fatalexits through the EXIT trap only (reminderDialog.zsh:1538).
Footguns
- Fatal exits don’t schedule —
reminderDialog.zsh:423,reminderDialog.zsh:1538—fatalrunsexit 1, and the EXIT trap only cleans up, soNextScheduledReminderstays due and the starter relaunches every minute. Triggered by no console user for 120 s (reminderDialog.zsh:5058) or missing swiftDialog (reminderDialog.zsh:2700). Inferred from the code; not reproduced. - Interaction history from a shared log —
reminderDialog.zsh:5269—grep -n -E '\[INFO\].*Return Code: (0|2|3|4|10)'matches any tool writing to the organization log, not justdorm (. Log rotation atreminderDialog.zsh:5014drops all history, so the quiet period and the 28-day periodic window reset. dsclhome parse —reminderDialog.zsh:5069—awk -F ' ' '{print $2}'returns\n<last word>for a home path containing a space; language detection and dark-mode detection then read a nonexistent path and silently fall back to English and Light.- swiftDialog upgrade unchecked —
launchDaemonManagement.zsh:1131—installerstatus ignored;dialogCheckre-checks only-x(launchDaemonManagement.zsh:1174), so an older swiftDialog passes. - Demo Force restarts for real —
reminderDialog.zsh:4682—zsh reminderDialog.zsh demo ForcereachesexecuteRestartAction "Restart"and runs/sbin/shutdown -r nowon the admin’s test Mac when the timer expires. Not deployed (assembled artifacts strip demo mode).
Edge cases not handled
- Apple changes
install.logwording → resolver returnsmissing, reminders stop, logged only as NOTICE —reminderDialog.zsh:4083. - Persistence plist lists an active declaration but the log offers none in its last 4,000 lines →
missing, no reminder —reminderDialog.zsh:3784. - Login window with a due reminder → ~120 counter lines per minute in the log —
reminderDialog.zsh:5063.
Refactor suggestions
R1 — Back off the schedule on fatal exits · Quick win
reminderDialog.zsh:423
# before
function fatal() { updateScriptLog "[FATAL ERROR] ${1}"; exit 1; }
# after
function fatal() {
updateScriptLog "[FATAL ERROR] ${1}"
shouldManageDaemonScheduling && scheduleNextReminderInMinutes 15 "Retry after fatal error" >/dev/null 2>&1
exit 1
}
Stops the per-minute relaunch loop; scheduleNextReminderInMinutes is defined later but resolves at call time.
R2 — Let Apple’s persisted state veto log-based suppression · Deeper
reminderDialog.zsh:3750
# before
if (( ${+ddmInvalidCandidateContexts[${candidateSignature}]} )); then
# after
if (( ${+ddmInvalidCandidateContexts[${candidateSignature}]} )) \
&& ! { [[ "${ddmStatePersistenceStatus}" == "available" ]] && ddmDeclarationIsCorroborated "${parsedDDMVersionString}" "${parsedDDMEnforcedInstallDate}"; }; then
An invalid marker can no longer discard a declaration that softwareupdated still persists (S1). Apply the same rule to the noMatch and missing paths, and sync both EAs.
R3 — Neutralize spreadsheet formulas · Quick win
Resources/Jamf-getDDMstatusFromCSV.zsh:903
# before
data="${data//\"/\"\"}"
printf "%s" "${data}"
# after
data="${data//\"/\"\"}"
[[ "${data}" == [=+\-@$'\t']* ]] && data="'${data}"
printf "%s" "${data}"
Closes S2.
R4 — Robust home-directory lookup · Quick win
reminderDialog.zsh:5069
# before
loggedInUserHomeDirectory=$( dscl . read "/Users/${loggedInUser}" NFSHomeDirectory | awk -F ' ' '{print $2}' )
# after
loggedInUserHomeDirectory=$( dscacheutil -q user -a name "${loggedInUser}" | awk -F ': ' '/^dir:/ {print $2; exit}' )
Handles spaces in home paths.
R5 — Verify swiftDialog after install · Quick win
launchDaemonManagement.zsh:1131
# before
installer -pkg "$tempDirectory/Dialog.pkg" -target /
# after
if ! installer -pkg "$tempDirectory/Dialog.pkg" -target /; then
rm -Rf "$tempDirectory"
fatal "swiftDialog installer failed"
fi
Pair with an is-at-least re-check in dialogCheck after dialogInstall.
R6 — Single-source the resolver · Deeper
reminderDialog.zsh:3681
Move the resolver functions to one file under Resources/ and have assemble.zsh splice it into the runtime and both EAs, checked with cmp -s as it already does for the embedded message. Removes three-way drift.
Quick wins vs deeper work
- Quick wins (< 1 hr): R1, R3, R4, R5
- Deeper work: R2 — touches resolver semantics and both EAs, needs fixture tests; R6 — build-pipeline change.
Cross-cutting notes
Cross-cutting notes: log trust and log volume share one root — state kept in text logs
- Two kinds of log-derived state. S1 (Apple’s
install.log) and the interaction-history hotspot (the project’s own log) both decide behavior by grepping text. Moving project state into the root-owneddor-state.plistand preferring Apple’s persistence plist would close S1’s main path and the shared-log hotspot together. - Unattended schedule amplifies the fatal-exit loop. The per-minute heartbeat makes any fatal condition repeat around the clock; at the login window overnight it also inflates the shared log, which then rotates and erases the interaction history the quiet period depends on.
- Triplicated resolver amplifies S1. Fixing S1 in the runtime alone leaves the Pending OS Update EAs reporting forgeable inventory; R6 makes the fix land once.
Scope
Scope: 022a8da (main) — 27 files analyzed, about 64% direct read of the main runtime
| Field | Value |
|---|---|
| Date | 2026-10-04 19:22 EDT |
| Target | https://github.com/dan-snelson/DDM-OS-Reminder (GitHub repo) |
| Ref | 022a8da44b820ba3e74e0beef2095c89db137781 (main, v5.0.0) |
| Generated by | Claude Opus 5.5 (claude-opus-5-5) |
| Language(s) | zsh (all scripts #!/bin/zsh, most with --no-rcs); GitHub Actions YAML; XML plists |
| Files analyzed | 27 — reminderDialog.zsh, launchDaemonManagement.zsh, assemble.zsh, Resources/Jamf-getDDMstatusFromCSV.zsh, Resources/createSelfExtracting.zsh, Resources/createPlist.zsh, Resources/reminderDialogPreferenceTest.zsh, 7 Jamf EAs, Artifacts dev .zsh, and 12 more (see caveats) |
| Automated scan | semgrep 1.177.0 — p/r2c-security-audit, p/secrets, p/ci — 0 results (0 confirmed), 4 parse errors, 4 files skipped (3 size, 1 parser) |
| Scope caveats | See below |
Scope caveats:
- Oversized target. ~18,000 lines of zsh across the repo, over the small-repo limit; entry points and high-risk files read first.
- reminderDialog.zsh (5,475 lines) read directly: 1–430, 470–600, 686–900, 1354–1540, 1775–2045, 2094–2260, 2361–2430, 2584–2660, 2696–2815, 2964–3210, 3322–3560, 3681–3915, 4044–4100, 4244–4445, 4542–4625, 4677–5475 — 3,531 lines, about 64%. Pattern-scanned the rest, including date/locale formatting, scheduler threshold helpers (1000–1353),
candidateHasConflictingEvidence, andresolvePaddedEnforcementDateForCandidate. - launchDaemonManagement.zsh: read in full.
- Read by a delegated sub-review (read-only), then spot-checked:
Resources/Jamf-getDDMstatusFromCSV.zsh: 1–1039, 1110–1409, 1555–1664, 1939–2228, 2840–3259, 3420–3539, 3700–4220 read; remainder pattern-scanned.assemble.zsh: 1–110, 150–449, 564–720, 980–1059, 1290–1862 read; remainder pattern-scanned.Resources/createSelfExtracting.zsh: read in full.Resources/createPlist.zshandResources/reminderDialogPreferenceTest.zsh: header, cleanup, and sink regions read; remainder pattern-scanned.
- Extension Attributes: the five small EAs read in full;
JamfEA-Pending_OS_Update_Date.zshandJamfEA-Pending_OS_Update_Version.zshpattern-scanned (structure matches the runtime resolver). - Other files:
Resources/monitorRemoteSession.zsh,Resources/localizationFilter.zsh,Resources/checkUserFocusDisplayAssertions.zshscanned or read;.github/workflows/security-scan.ymlscanned for pins, permissions, and triggers; README, SECURITY.md, AGENTS.md, and agent config read. - Artifacts. The tracked dev artifact was diffed against both sources: identical except the runtime’s
tee -ais commented out (logging reaches the file through the LaunchDaemon’sStandardOutPath) and demo mode is stripped. The tracked plist and unsigned mobileconfig were covered by semgrep only. - Semgrep. The 4 parse errors are on
.github/workflows/security-scan.yml(embedded bash), a scanner limitation; 3 images skipped for size. Semgrep has no zsh parser, so 0 results doesn’t indicate clean code. - Not reproduced. S1, S4, and the fatal-exit relaunch loop were traced from the code; nothing in the target was executed. The
install.logforgery primitive is cited from Monocle’s Known Apple platform behaviors. - Untracked files. Fresh shallow clone; no local-only or gitignored files present.
Attestation:
monocle_attestation: v1
skill_repo: https://github.com/dan-snelson/Monocle
skill_commit: unknown
skill_ref: copied install
skill_tree: unavailable
skill_sha256: c2bb20f34568f6fe0103705ff21aa1151781dc886a9526819476d724ceaf51a3
skill_dirty: unknown
target: https://github.com/dan-snelson/DDM-OS-Reminder (GitHub repo)
target_ref: 022a8da44b820ba3e74e0beef2095c89db137781 (main, v5.0.0)
score_raw: 79
score_final: 79
score_alt: 76
band: Good
generated_by: Claude Opus 5.5 (claude-opus-5-5)
timestamp: 2026-10-04 19:22 EDT
Mac Health Check
Monocle Report: Mac-Health-Check
Monocle Score
Monocle Score: 80/100 (🔵 Good) — Approve with conditions
Score: 80/100 (🔵 Good) at the documented-deployment baseline — 4 Low, 1 Info, 4 non-security, or 72/100 (🔵 Good) if any Jamf Pro policy populates Parameter 5 or 8 with a reporting secret
Overall risk: 🔵 Low, or 🟡 Medium if any Jamf Pro policy populates Parameter 5 or 8 with a reporting secret
Recommendation: Approve with conditions — the code is low risk and carefully hardened; deliver the Splunk HEC token and webhook URL only through the root-only secrets file, with Parameters 5 and 8 blank in every policy.
Generated by: Claude Opus 5.5 (claude-opus-5-5) · Skill: monocle
| Source | IDs | Count | Each | Deduction |
|---|---|---|---|---|
| 🔴 Critical | — | 0 | 40 | 0 |
| 🟠 High | — | 0 | 20 | 0 |
| 🟡 Medium | — | 0 | 8 | 0 |
| 🔵 Low | S1, S2, S3, S4 | 4 | 3 | 12 |
| ⚪ Info | S5 | 1 | 0 | 0 |
| Non-security | Unvalidated Parameter 4; Network Quality false success; home-directory parse; early exits bypass the log | 4 | 2 (max 20) | 8 |
| Not scored | — | 0 | 0 | 0 |
Total: 100 − 20 = 80 → 80/100 (🔵 Good)
Alternate: with S5 at 🟡 Medium (a policy populates Parameter 5 or 8), 100 − 28 = 72, within the Medium range (50–89), no clamp → 72/100 (🔵 Good).
Operator baseline:
- The Splunk HEC token and webhook URL are delivered only in
/Library/Management/org.churchofjesuschrist/MacHealthCheck-Secrets.plist(root:wheel,600), and Parameters 5 and 8 are blank in every policy (S5 → 🟡 Medium if not). allowParameterSecretsstays"false"(S5 → 🟡 Medium if set to"true"and a parameter is populated).
Executive View
Executive View: Approve with conditions — low risk; keep reporting secrets out of policy settings
In one sentence: Gives employees a self-service health check of their Mac (updates, encryption, security agents, network, management status) and sends the same compliance results to the security team’s reporting system every night.
- Low risk overall. It reads settings and reports on them; it does not change security settings or remediate anything. The few local changes it makes (a nightly background job, an updated dialog tool, a log file) are documented.
- Runs with full administrator access on every Mac in scope, plus a nightly background job. The code protects that job well: it only installs a copy of itself from locations ordinary users cannot change.
- Reporting credentials are safe only if administrators store them as documented. If a Splunk token or chat-webhook address is typed into the policy’s script settings, any user on that Mac can read it while the check runs. The tool now refuses such values by default and warns about them.
- A user or a nearby Wi-Fi network can disrupt or skew reporting on one Mac. A Wi-Fi name containing a quotation mark stops every run on that Mac, and on some older setups a user can make their own Mac look more up to date than it is. Fleet-wide data and enforcement are not affected.
- One person maintains almost all of it (86% of commits), though the project is active, documented, and has automated security scanning.
Monocle Score: 80/100 (🔵 Good), or 72/100 (🔵 Good) if any policy still puts the Splunk token or chat webhook in its script settings
Recommendation: Approve with conditions — the code is low risk and carefully hardened; deliver the Splunk HEC token and webhook URL only through the root-only secrets file, with Parameters 5 and 8 blank in every policy.
Security View
Security View: 🔵 Low risk — 4 Low findings, 1 Info
Execution context: root via MDM policy (Jamf Pro Self Service or Silent policy, a self-extracting wrapper, or the pkg postinstall), and root via the nightly LaunchDaemon copy; user-facing work (swiftDialog, Homebrew, bioutil, Inspect summary) drops to the console user with launchctl asuser … sudo -u (Mac-Health-Check.zsh:2377).
Overall risk: 🔵 Low — no finding gives a local user root or exposes a secret at the documented baseline; 🟡 Medium if a policy populates Parameter 5 or 8.
Findings
| ID | Severity | Title | Location |
|---|---|---|---|
| S1 | 🔵 Low | Unescaped Wi-Fi name and identity values can abort every run or inject swiftDialog keys | Mac-Health-Check.zsh:1664 |
| S2 | 🔵 Low | Some compliance results fall back to user-writable evidence | Mac-Health-Check.zsh:7925 |
| S3 | 🔵 Low | swiftDialog install check parses spctl text and ignores its verdict |
Mac-Health-Check.zsh:7131 |
| S4 | 🔵 Low | Inspect summary assets expose the last user’s identity and results to every local account | Mac-Health-Check.zsh:6176 |
| S5 | ⚪ Info | Jamf policy parameters expose reporting secrets to local users (🟡 Medium if a policy populates Parameter 5 or 8) | Mac-Health-Check.zsh:163 |
S1 — Unescaped Wi-Fi name and identity values can abort every run or inject swiftDialog keys · 🔵 Low
- Location:
Mac-Health-Check.zsh:1628(helpmessage),Mac-Health-Check.zsh:1664,Mac-Health-Check.zsh:1676–1680 - Origin: Code —
helpmessageconcatenates${ssid},${computerName}and${loggedInUserFullname}raw into a JSON string literal; the script’s ownjsonEscape()andjq --arghelpers are not used here. - Evidence:
"helpmessage" : "'"${helpmessage}"'",followed byif ! validateJson "${mainDialogJSON}"; then … exit 1 - Impact: A Wi-Fi network name containing
"(any network the Mac joins, so attacker-chosen in a café or hotel) makes validation fail, and the script exits 1 before any check, report write, cached Splunk upload or nightly refresh, in every operation mode, includingSilent. A crafted SSID within the 32-byte limit can instead close the string and append keys such asinfobuttonaction;jqkeeps the last duplicate key, so the help button could open an attacker URL. Traced from code, not reproduced. A computer name or full name containing"causes the same abort. - Fix: Encode the value with
jqbefore building the template:helpmessageJSON=$( printf '%s' "${helpmessage}" | jq -Rs . ), then"helpmessage" : '"${helpmessageJSON}"',(see Engineer R1).
S2 — Some compliance results fall back to user-writable evidence · 🔵 Low
- Location:
Mac-Health-Check.zsh:7925(install.logDDM resolver),Mac-Health-Check.zsh:8069andMac-Health-Check.zsh:8096(per-user App Auto-Patch log),getEntraJamfAADPlistPath()(per-user JamfAAD plist) - Origin: Platform + Code — any local user can append lines, sender tag included, to
/var/log/install.log(Known Apple platform behaviors: install.log is user-writable); the code already prefers root-written sources (SoftwareUpdateDDMStatePersistence.plistwith an owner check atMac-Health-Check.zsh:7604–7606, the system App Auto-Patch logs) and falls back only when they are missing or unrecognized. - Evidence:
info "DDM Resolver: softwareupdated state plist unavailable or unrecognized; falling back to install.log" - Impact: On Macs without the state plist, or without a system App Auto-Patch log, a standard user can make their own Mac report “Up-to-date” for a pending DDM update or a recent App Auto-Patch run, and those values reach Splunk. DDM enforcement itself is unaffected; Apple installs at the deadline regardless. Limited to the user’s own device.
- Fix: Record the evidence source per check in the report (for example
evidenceSource: "user-writable") and downgrade fallback-sourced success towarning, so dashboards can filter it.
S3 — swiftDialog install check parses spctl text and ignores its verdict · 🔵 Low
- Location:
Mac-Health-Check.zsh:7131,Mac-Health-Check.zsh:7109,Mac-Health-Check.zsh:7136 - Origin: Code — the download is HTTPS-only and the Team ID is compared, but the comparison uses the
origin=text ofspctloutput whilespctl’s accept or reject result and exit status are discarded; the URL check accepts anyhttps://github.com/path. - Evidence:
teamID=$(spctl -a -vv -t install "$tempDirectory/Dialog.pkg" 2>&1 | awk '/origin=/ {print $NF }' | tr -d '()') - Impact: A package that
spctlrejects still installs as root whenever itsorigin=line ends in(PWA5E9TQ59). Exploiting this requires substituting the download (a GitHub API or release compromise, or TLS interception), so reachability is low. Inferred from the code;spctloutput for a forged certificate was not reproduced. - Fix: Require
spctl -a -t installto exit 0 and checkpkgutil --check-signatureforDeveloper ID Installer: … (PWA5E9TQ59); pin the URL prefix tohttps://github.com/swiftDialog/swiftDialog/releases/download/.
S4 — Inspect summary assets expose the last user’s identity and results to every local account · 🔵 Low
- Location:
Mac-Health-Check.zsh:6176,Mac-Health-Check.zsh:3853(writeReadableTextFile()),buildInspectUserInformationItemsJSON()andbuildInspectComputerInformationItemsJSON()(Mac-Health-Check.zsh:5726–5758) - Origin: Code — the config and compliance plist are deliberately
root:wheel 0644in/Library/Application Support/org.churchofjesuschrist/Inspectso swiftDialog can read them as the console user; the same release restricts the client log toroot:admin 640for exactly this data (Mac-Health-Check.zsh:6993–6994). - Evidence:
if ! chown root:wheel "${inspectFileToPrepare}" 2>/dev/null || ! chmod 644 "${inspectFileToPrepare}" 2>/dev/null; then - Impact: On shared Macs, any local account (or any process running as one) can read the last user’s full name, short name, UID, Platform SSO address, Wi-Fi name, IP address, VPN state and every health result. Silent and nightly runs refresh the file. Disclosure only; no integrity impact.
- Fix: Write the files
640 root:wheeland grant the console user read access with an ACL, as the script already does for the dialog files (Mac-Health-Check.zsh:1360–1363):chmod +a "${loggedInUser} allow read" "${inspectConfigPath}".
S5 — Jamf policy parameters expose reporting secrets to local users · ⚪ Info
- Alternate severity: 🟡 Medium while any policy populates Parameter 5 or 8 (SKILL.md Rule 11)
- Location:
Mac-Health-Check.zsh:108,Mac-Health-Check.zsh:163,enforceReportingSecretsSource()(Mac-Health-Check.zsh:320–340),Mac-Health-Check.zsh:473–478 - Origin: Platform + Deployment — Jamf Pro passes policy parameters as process arguments, and macOS lets any local user read them (observed on the analysis host, Darwin 25: a non-root
ps -axww -o user=,args=lists root processes’ full arguments). The code already does what it can: it rejects parameter secrets unlessallowParameterSecrets="true", loads them from a root-only600plist with owner, mode and symlink checks (Mac-Health-Check.zsh:290–297), exitsSilent+ production runs early when the only token was rejected, logs a warning, and hands secrets tocurlon stdin. - Evidence:
splunkHECToken="${8:-""}";allowParameterSecrets="false" - Impact: At the documented baseline there is no exposure. If a policy populates Parameter 5 or 8, the value stays readable in
argvfor the whole run (minutes for an interactive Self Service run) even when the script rejects it, and in the Jamf policy UI. The HEC token lets the holder inject forged events into the compliance index; the webhook URL lets the holder post to the channel. Both are narrow, write-only scopes, hence Medium. - Fix: Keep Parameters 5 and 8 blank, deliver both values in the secrets file, restrict the HEC token to the Mac Health Check index and sourcetype, and rotate any value that was ever set in a parameter.
Low / Info roll-up (credits): PATH excludes /usr/local/bin (Mac-Health-Check.zsh:35); isTrustedRootPath() checks every path component, sticky bit included (Mac-Health-Check.zsh:37–65), and gates the self-copy into the LaunchDaemon (Mac-Health-Check.zsh:4230); the sanitized copy must pass zsh -n and keep the Silent default (Mac-Health-Check.zsh:4278); jq is accepted only from root-owned paths; per-run mktemp -d with an EXIT trap (Mac-Health-Check.zsh:242–248); root-owned state with atomic mktemp + mv writes (writeSecureJSONFile()); cached reports, Inspect replay and the force-fresh trigger are trusted only when root-owned and not symlinks; Test and Development reports are isolated from the canonical report and HEC (Mac-Health-Check.zsh:4118), and the cache rejects non-production reports (Mac-Health-Check.zsh:396); an unrecognized Splunk mode fails safe to test (Mac-Health-Check.zsh:439–443); set -x starts after parameter parsing and secret-handling functions use noxtrace; HEC and webhook delivery use --proto '=https' --tlsv1.2, --max-time 15 and --fail-with-body; the Electron check validates version-shaped content so hard links cannot leak root-only files (Mac-Health-Check.zsh:10578); the self-extracting wrapper decodes into a root-only mktemp -d and forwards "$@" (Resources/createSelfExtracting.zsh:30–33); external checks set a fixed system PATH and call vendor tools by absolute path; CI uses SHA-pinned actions with permissions: read-all. Agent configuration (AGENTS.md, CLAUDE.md, .github/copilot-instructions.md, .github/agents/, .github/instructions/) contains coding guidance only, with no session hooks and no reviewer-steering text (Info).
Privilege map
- Health checks, discovery (
profiles,bputil,sysadminctl -secureTokenStatus,systemsetup,visudo -c,log show) — throughout — root ipconfig setverbose 1then0, restored only if it changed it —Mac-Health-Check.zsh:938–940— root- swiftDialog download and
installer -pkg—Mac-Health-Check.zsh:7136— root - Dock-named swiftDialog copy with ad hoc
codesign --force --sign -—prepareDockNamedDialogApp()— root killProcess "Dialog"(quits every swiftDialog window, documented) —Mac-Health-Check.zsh:7218— root- Self-copy to
/Library/Management/org.churchofjesuschrist/MHC.zshandlaunchctl bootstrap system—Mac-Health-Check.zsh:4375— root jamf policy -event <trigger>(external checks, each run as root by Jamf) andjamf recon—Mac-Health-Check.zsh:10157,updateComputerInventory()— rootchown "${loggedInUser}"of the per-user Inspect directory (inside a root-owned0755parent, so not swappable) —Mac-Health-Check.zsh:6216— root- swiftDialog, Inspect summary, Homebrew,
bioutil,security find-certificate—runAsUser(),runHomebrewAsUser()— console user (or the last user on nightly runs,Mac-Health-Check.zsh:969–978) CrowdStrike Falcon Status.bashwritesAppleLocaleto/Library/Preferences/.GlobalPreferences.plistand root’s preferences, restored by anEXITtrap —external-checks/CrowdStrike Falcon Status.bash:66–74— root
Secrets inventory
- Splunk HEC token — root-only secrets plist (documented) or Jamf Parameter 8 (rejected by default) —
Mac-Health-Check.zsh:163,Mac-Health-Check.zsh:301— sent in acurl --config -header on stdin (Mac-Health-Check.zsh:3926,Mac-Health-Check.zsh:3942); never logged. See S5. - Teams or Slack webhook URL (a bearer credential) — secrets plist or Jamf Parameter 5 (rejected by default) —
Mac-Health-Check.zsh:108,Mac-Health-Check.zsh:307— sent asurl = …on stdin (Mac-Health-Check.zsh:6528); never logged. See S5. - No hardcoded secrets. The Jamf Cloud icon URLs (
Mac-Health-Check.zsh:571) are public asset links.
Network egress
- Splunk HEC (Parameter 7) — POST —
https://enforced, TLS 1.2+, token on stdin —Mac-Health-Check.zsh:3919–3950 - Teams or Slack webhook — POST —
https://enforced, TLS 1.2+ —Mac-Health-Check.zsh:6427,sendWebhookPayload() api.github.com(swiftDialog and Homebrew release metadata) andgithub.com(swiftDialog pkg) — GET — default TLS —getLatestSwiftDialogPkgURL(),Mac-Health-Check.zsh:10394sofafeed.macadmins.io(macOS release feed) — GET with ETag,--fail --max-time 10—Mac-Health-Check.zsh:7311- Dock icon and overlay icon URLs (organization-configured) — GET as root into the per-run directory —
resolveDockIcon(),Mac-Health-Check.zsh:1406 - Apple service and Jamf hosts (
ncorcurl), ApplenetworkQuality, clock-skew comparison —checkNetworkHosts(),Mac-Health-Check.zsh:10317,checkClockSkew()(pattern-scanned) - Jamf Pro (policy triggers and inventory) — through the
jamfbinary
Persistence
- LaunchDaemon
org.churchofjesuschrist.MHC—/Library/LaunchDaemons/org.churchofjesuschrist.MHC.plistruns/Library/Management/org.churchofjesuschrist/MHC.zshas root daily at 00:53 with ±30 minutes of per-device jitter; stdout and stderr go to/dev/null—installClientSideScript()(Mac-Health-Check.zsh:4291–4328) - swiftDialog app (installed or updated outside
Silent) —/Library/Application Support/Dialog/Dialog.app—dialogInstall() - Root-only state: canonical report, SOFA and
networkQualitycaches, 14-day memory-pressure history —/Library/Management/org.churchofjesuschrist/ - Inspect assets —
/Library/Application Support/org.churchofjesuschrist/Inspect/(see S4)
Manager View
Manager View: Production-grade; one primary maintainer (86% of commits)
Ownership: Dan K. Snelson (@dan-snelson) — script header and SECURITY.md; 273 of 317 commits on GitHub, next contributor 16. Bus factor: effectively 1, with an active contributor community.
Maturity: Production-grade — versioned, extensively documented (README, SECURITY.md, Diagrams/, changelog), five operation modes, structured JSON reporting, CI security scanning, and a 5.0.0 release focused on hardening; a few input edge cases remain.
Change risk: Medium — root on every scoped Mac plus a nightly root job, in an 11,491-line single file with no automated functional tests; mitigated by zsh -n gates, mode isolation and fail-safe defaults.
What it depends on
- swiftDialog 3.1.1.4997+ — auto-installed from GitHub outside
Silent; GitHub downloads must be reachable. jq—/usr/bin/jqon macOS 15+, otherwise a root-owned install; a user-owned Homebrewjqis rejected.- Jamf Pro policies with custom triggers for external checks (
symvBeyondTrustPMfM,symvCiscoUmbrella,symvCrowdStrikeFalcon,symvGlobalProtect) — enabled by default on Jamf Pro; a missing policy reportsErroron every run. - Splunk HEC endpoint, index and sourcetype, plus the root-only secrets plist — required for compliance reporting.
- SOFA feed (
sofafeed.macadmins.io) — decides OS compliance. - Undocumented Apple internals:
SoftwareUpdateDDMStatePersistence.plistlayout andinstall.logwording; Apple can change either in any release. - Organization values hardcoded in source:
org.churchofjesuschristdomain, support contacts, branding URLs, VPN vendor.
Fragility hotspots
- A Wi-Fi name, computer name or full name containing
"stops every run on that Mac, including nightly refreshes; the error prints to stdout only, so you would notice only a stale Splunk record (S1) —Mac-Health-Check.zsh:1676. - A misspelled operation mode in Parameter 4 (
silent,Developer) runs the full interactive suite, writes the canonical report and installs the nightly job; the README warns about it, but the code does not reject it —Mac-Health-Check.zsh:105. - On Macs without
/usr/bin/jq(macOS 14 and earlier) and no root-ownedjq, the script exits with a misleading “mainDialogJSON is invalid JSON” before its own clearjqerror, and nothing reaches the log —Mac-Health-Check.zsh:1676vsMac-Health-Check.zsh:7005. - The nightly job discards stdout and stderr, so early exits during the 00:53 run leave no trace —
Mac-Health-Check.zsh:4322–4325. - A failed Network Quality test is reported as healthy with a blank speed and cached for 4 hours —
Mac-Health-Check.zsh:10346. - DDM detection depends on undocumented Apple file formats; a layout change silently moves results to the
install.logfallback (S2).
Change & rollback
- Testing: CI runs Semgrep, Gitleaks,
zsh -nand ShellCheck (.github/workflows/security-scan.yml); the deployment instructions require a five-mode regression on a test Mac. No automated functional tests. - Rollback: Clean. Remove the LaunchDaemon (
launchctl bootout system/org.churchofjesuschrist.MHC, delete the plist),/Library/Management/org.churchofjesuschrist/and/Library/Application Support/org.churchofjesuschrist/; swiftDialog can stay. No security settings are changed. - Deploy path: Jamf Pro script policy (Self Service or Silent), self-extracting wrapper (
Resources/createSelfExtracting.zsh), or a pkg fromResources/Makefilewhosepostinstallruns Self Service mode at install time; Fleet ships osquery policies only (Resources/mac-health-check-fleet-policies.yml).
Action items
| # | Action | Owner role | Effort | Priority |
|---|---|---|---|---|
| 1 | Confirm every Mac Health Check policy leaves Parameters 5 and 8 blank and uses the secrets plist; rotate any token that was ever in a parameter (S5) | Jamf admin + Security | S | P1 |
| 2 | JSON-encode helpmessage so Wi-Fi, computer and user names cannot break or inject into the dialog (S1) |
Mac engineer | S | P2 |
| 3 | Reject unrecognized Parameter 4 values and move the jq and root pre-flight ahead of the first JSON use, logging early exits |
Mac engineer | S | P2 |
| 4 | Restrict Inspect assets to the console user with an ACL (S4) | Mac engineer | S | P2 |
| 5 | Require spctl acceptance plus pkgutil Team ID verification for swiftDialog installs; pin the release URL (S3) |
Mac engineer | S | P2 |
| 6 | Tag fallback-sourced results (install.log, per-user logs) in the report and filter them in the Splunk dashboard (S2) |
Mac engineer + Splunk owner | M | P3 |
| 7 | Report Network Quality failures as error and fix the home-directory parse |
Mac engineer | S | P3 |
| 8 | Name a second maintainer with release rights | Service owner | M | P3 |
Engineer View
Engineer View: Strong trust boundaries; fix unescaped dialog JSON and early-exit ordering
Shape: zsh (#!/bin/zsh --no-rcs), 11,491 lines, about 220 functions, single top-level script; invoked by Jamf Pro ($4–$11), a self-extracting wrapper, a pkg postinstall (Resources/postInstall.zsh:6), or the LaunchDaemon (no arguments, launchDaemonRun=true).
Inputs → Outputs: Parameters 4–11, launchDaemonRun env, secrets plist, MDM profiles, system and user preference files, install.log, external Jamf policy output, network responses → swiftDialog UI, /var/log/org.churchofjesuschrist.log, canonical JSON report, Splunk HEC event, Teams/Slack message, Inspect assets, LaunchDaemon, exit code (0 healthy or warning, 1 failure; in Silent + production, delivery success).
Control flow
- Harden
PATH, resolve a root-ownedjq, parse Parameters 4–11, compute secret-free flags, then enableset -xfor Debug —Mac-Health-Check.zsh:35–184. - Create the per-run
mktemp -ddirectory with anEXITtrap; load the secrets plist and reject parameter secrets —Mac-Health-Check.zsh:242–343. - Normalize the Splunk mode (unknown →
test);Silent+ production with only a rejected Parameter 8 exits 1 —Mac-Health-Check.zsh:429–478. - Cache gate (
Silent+ production): a root-owned force-fresh trigger or Parameter 11 forces a full run; otherwise a matching clientscriptVersionplus a valid root-owned cached report setsclientSideSkipChecks—Mac-Health-Check.zsh:481–553. - Discovery: MDM vendor from
profiles(Jamf requiresjamf.log, else exit 1), hardware, user, SSID, boot policies, VPN —Mac-Health-Check.zsh:768–1314. - Create the dialog command and JSON files (
600plus a read ACL), buildmainDialogJSONand the per-MDM list items, exit 1 if any fails validation —Mac-Health-Check.zsh:1352–1680. - Pre-flight: create the log, sleep the jitter on LaunchDaemon runs, require root, secure the state directories, require
jq, install or refresh the client copy and LaunchDaemon (skipped for Test and Development), then upload the cached report and exit when the cache gate passed —Mac-Health-Check.zsh:6905–7059. - Outside
Silent: install or update swiftDialog and quit other swiftDialog windows —Mac-Health-Check.zsh:7206–7219. - Build
combinedJSONper vendor (or the Development subset); in Self Service, a recent unhealthy full-run baseline narrows the run to the failed checks plus inventory, and a healthy one replays the cached Inspect summary and exits —Mac-Health-Check.zsh:10927–10989. - Launch swiftDialog through the Dock-named copy, with fallback to
dialogcli—Mac-Health-Check.zsh:11026–11093. - Run the checks through
runConfiguredHealthCheck; Test mode marks every itemsuccesswithout running checks —Mac-Health-Check.zsh:11101–11483. quitScript(): compute overall status, send webhooks (not on nightly runs), generate, merge and lock-write the report, upload to HEC, write or launch the Inspect summary, run the countdown, clean up and exit —Mac-Health-Check.zsh:6702–6866.
Footguns
- Unescaped values in dialog JSON —
Mac-Health-Check.zsh:1628,Mac-Health-Check.zsh:1664—${ssid},${computerName}and${loggedInUserFullname}go raw into a JSON string; one"aborts the run in every mode (see S1). - Missing
jqreported as invalid JSON —Mac-Health-Check.zsh:1676— with no root-ownedjq,validateJsonfails becausejqis not found, so the script prints “mainDialogJSON is invalid JSON” to stdout and exits before the explicitjqfatal atMac-Health-Check.zsh:7009and before anything is written toscriptLog. - Unvalidated Parameter 4 —
Mac-Health-Check.zsh:105— any value other than the five names takes every!= "Silent"branch: it shows the dialog, writes the canonical report, uploads when Splunk is in production and installs the client copy (Mac-Health-Check.zsh:7041), but skips Self Service-only logic. Documented in README, not enforced. - Network Quality false success —
Mac-Health-Check.zsh:10346–10347— whennetworkQualityfails,dl_throughputis empty,bcprints “Parse error: bad expression” to stderr (observed in isolation),mbpsis empty, and the list item is stillstatus: success; the bad result file is reused for 4 hours. - Home-directory parse —
Mac-Health-Check.zsh:985—dsclprints a value containing a space on its own line, soawk '{print $2}'returns a blank line plus the last word (isolated check:dscl . read /Users/root RealNamegives[]then[Administrator]). OneDrive, Homebrew, App Auto-Patch and Entra checks then read the wrong path. - Shared swiftDialog log removed —
Mac-Health-Check.zsh:6859—rm -f /var/tmp/dialog.logalso removes the log of any other swiftDialog-based tool running at the same time.
Edge cases not handled
- Nightly LaunchDaemon run hits an early exit (invalid dialog JSON, missing
jamf.log, missingjq) → messages go to stdout, which the plist sends to/dev/null; no log entry —Mac-Health-Check.zsh:4322–4325. - External check exceeds 120 s →
captureCommandOutputWithTimeout()sends TERM, then KILL after 5 s, to the subshell runningjamf(Mac-Health-Check.zsh:2418–2426); a CrowdStrike check killed mid-run may leave the systemAppleLocaleaten_USif itsEXITtrap never runs (inferred; signal delivery to Jamf’s child script not reproduced). - Mosyle plus a webhook →
computerMdmURLstays empty, so the Slack buttonurlis"", which Slack rejects; the README already notes webhooks are effectively Jamf Pro-only —webHookMessage(). - Dock integration on → the ad hoc re-sign drops swiftDialog’s Team ID, so PPPC and notification profiles keyed to it do not match (documented in README).
Refactor suggestions
R1 — JSON-encode the help message · Quick win
Mac-Health-Check.zsh:1664
# before
"helpmessage" : "'"${helpmessage}"'",
# after (compute before mainDialogJSON)
helpmessageJSON=$( printf '%s' "${helpmessage}" | jq -Rs . )
…
"helpmessage" : '"${helpmessageJSON}"',
jq -Rs . emits a quoted, escaped JSON string (checked with /usr/bin/jq), which closes S1. Apply the same pattern to infobuttonaction and bannerimage if they ever become configurable.
R2 — Validate jq and root before the first JSON use · Quick win
Mac-Health-Check.zsh:76
# before
if [[ -n "${jqBinary}" ]] && [[ "${jqBinary}" != "/usr/bin/jq" ]]; then
function jq() { "${jqBinary}" "$@"; }
fi
# after
if [[ -z "${jqBinary}" ]]; then
echo "jq is required; install a root-owned jq (macOS 15+ ships /usr/bin/jq). Exiting."
exit 1
elif [[ "${jqBinary}" != "/usr/bin/jq" ]]; then
function jq() { "${jqBinary}" "$@"; }
fi
Reports the real cause instead of “mainDialogJSON is invalid JSON”. Also consider sending early-exit messages to scriptLog and pointing the LaunchDaemon’s StandardErrorPath at the log.
R3 — Reject unknown operation modes · Quick win
Mac-Health-Check.zsh:105
# before
operationMode="${4:-"Self Service"}"
# after
operationMode="${4:-"Self Service"}"
case "${operationMode}" in
"Debug" | "Development" | "Self Service" | "Silent" | "Test" ) ;;
* ) echo "Unrecognized operationMode '${operationMode}' (Parameter 4); exiting."; exit 1 ;;
esac
Fails closed on typos instead of running production behavior under an unknown mode. The client-copy sed at Mac-Health-Check.zsh:4251 matches only the assignment line, so it is unaffected.
R4 — Report Network Quality failures · Quick win
Mac-Health-Check.zsh:10346
# before
mbps=$( echo "scale=2; ( $dlThroughput / 1000000 )" | bc )
# after
if [[ "${dlThroughput}" != <-> ]]; then
rm -f "${networkQualityTestFile}"
dialogUpdate "listitem: index: ${1}, icon: SF=$(printf "%02d" $(($1+1))).circle.fill weight=bold colour=${statusColorError}, iconalpha: 1, status: error, statustext: Unable to measure"
warning "${humanReadableCheckName}: networkQuality returned no throughput"
return
fi
mbps=$( echo "scale=2; ( $dlThroughput / 1000000 )" | bc )
Stops reporting a failed measurement as healthy and drops the bad cache file (zsh <-> matches only non-empty integers, checked in isolation).
R5 — Parse the home directory from plist output · Quick win
Mac-Health-Check.zsh:985
# before
loggedInUserHomeDirectory=$( dscl . read "/Users/${loggedInUser}" NFSHomeDirectory 2>/dev/null | awk -F ' ' '{print $2}' )
# after
loggedInUserHomeDirectory=$( dscl -plist . read "/Users/${loggedInUser}" NFSHomeDirectory 2>/dev/null \
| plutil -extract 'dsAttrTypeStandard:NFSHomeDirectory.0' raw -o - - 2>/dev/null )
Handles values with spaces (checked with RealName on root, which returns System Administrator).
R6 — Grant Inspect assets to the console user only · Quick win
Mac-Health-Check.zsh:6176
# before
if ! chown root:wheel "${inspectFileToPrepare}" 2>/dev/null || ! chmod 644 "${inspectFileToPrepare}" 2>/dev/null; then
# after
if ! chown root:wheel "${inspectFileToPrepare}" 2>/dev/null || ! chmod 640 "${inspectFileToPrepare}" 2>/dev/null \
|| { [[ -n "${loggedInUser}" ]] && ! chmod +a "${loggedInUser} allow read" "${inspectFileToPrepare}" 2>/dev/null; }; then
Mirrors the dialog-file ACL pattern and closes S4; replay already regenerates for a different user (Mac-Health-Check.zsh:6389).
Quick wins vs deeper work
- Quick wins (< 1 hr): R1, R2, R3, R4, R5, R6.
- Deeper work: S2 evidence tagging (report schema and Splunk dashboard change) and S3 installer verification (needs testing against current swiftDialog releases).
Cross-cutting notes
Cross-cutting notes: one unescaped value can silently stop nightly compliance reporting
- S1 plus the nightly job’s discarded output. The JSON abort happens before logging is set up, and the LaunchDaemon sends stdout and stderr to
/dev/null, so a Mac on a network whose name contains"stops refreshing its compliance report with no local trace. The cached report then ages out (36 hours) and Silent uploads fall back to full runs that fail the same way. Splunk staleness alerts are the only signal; R1 and R2 together remove both halves. - Prior hardening is real. The 5.0.0 security changes claimed in
CHANGELOG.mdandSECURITY.md(root-owned state, parameter-secret rejection, trusted self-copy,/usr/local/binremoval, wrappermktemp -d, Electron content validation,Not Runningtreated as failure) were each confirmed in code. Earlierinstall.log-based or/var/tmp-based weaknesses now remain only as the fallbacks in S2. - Unattended schedule. The nightly job can run
networkQualityandsoftwareupdate --liston whatever network the laptop is on; the ±30-minute deterministic jitter spreads fleet load but not across networks. Not a defect; worth knowing for bandwidth planning.
Scope
Scope: 174b061 (GitHub repo) — 21 code/config files; main script about 56% read directly
| Field | Value |
|---|---|
| Date | 2026-10-04 19:10 EDT |
| Target | https://github.com/dan-snelson/Mac-Health-Check (GitHub repo, B) |
| Ref | 174b061fbbb9ad0bc8461dd9035651914eda436d (main, v5.0.0) |
| Generated by | Claude Opus 5.5 (claude-opus-5-5) |
| Language(s) | zsh (main script, wrapper, postinstall, two external checks), bash (ten external checks), Make, GitHub Actions YAML, osquery YAML |
| Files analyzed | 21 — Mac-Health-Check.zsh, Resources/createSelfExtracting.zsh, Resources/postInstall.zsh, Resources/Makefile, 12 scripts in external-checks/, Skills/mac-health-check-selector/scripts/build-artifact.zsh, .github/workflows/security-scan.yml, Resources/mac-health-check-fleet-policies.yml, AGENTS.md, CLAUDE.md |
| Automated scan | semgrep 1.177.0 — p/r2c-security-audit, p/secrets, p/ci — 0 results (0 confirmed), 7 errors on one file, 13 files skipped (12 PNGs over 1 MB, 1 parse failure) |
| Scope caveats | See below |
Scope caveats:
- Oversized main script.
Mac-Health-Check.zshis 11,491 lines; about 56% (6,463 lines) was read directly.- Read directly: 1–1659, 1672–1680, 2150–2989, 3700–4389, 5726–5760, 6040–7247, 7270–7349, 7586–8195, 8546–8612, 8840–8900, 8960–9000, 10127–10466, 10470–10649, 10840–11491.
- Pattern-scanned only (privileged commands, network, temp paths,
chown/chmod,eval,(P),log show,install.log): 1660–2149 (list-item JSON), 2990–3699 (report JSON build and merge), 4390–6039 (Inspect builders), 7350–7585 (checkOS()remainder,checkStagedUpdate()), 8196–8545 (SIP, SSV, Gatekeeper, firewall, uptime, disk), 8613–8839 (memory pressure, user directories, MDM profile), 8901–8959 and 9001–10126 (Entra, APNs, network hosts, MDM certificate, Jamf check-in and inventory, clock skew, Mosyle, FileVault, Touch ID, Wi-Fi, VPN), 10650–10839 (Bluetooth, password hint, AirPlay, AirDrop).
- Other files. All 12 external checks, the wrapper,
postinstalland Makefile were read in full.build-artifact.zsh(maintainer and admin tooling, not scored), the CI workflow and the Fleet policy YAML were read in part and pattern-scanned. Agent configuration,SECURITY.md, the 5.0.0CHANGELOG.mdsection and relevant README sections were read for claims. - Semgrep. No zsh parser; zero results is not evidence of safety. The 7 errors are
p/ciparse failures on embedded shell insecurity-scan.yml. - Isolated checks (no target code run).
ps -axww -o user=,args=as uid 502 listed root process arguments (Darwin 25.6, macOS 26.7.1);dscl . read /Users/root RealNamepiped to the script’sawkpattern;bcwith an empty operand;jq -Rs .,plutil -extract … -and the zsh<->pattern for refactor snippets. - Not reproduced. S1 injection and abort, S3
spctloutput for a forged certificate, and the CrowdStrike locale edge case were traced from code only. - Ownership data. Shallow clone (50 commits); contributor counts come from the GitHub API.
Attestation:
monocle_attestation: v1
skill_repo: https://github.com/dan-snelson/Monocle
skill_commit: unknown
skill_ref: copied install
skill_tree: unavailable
skill_sha256: c2bb20f34568f6fe0103705ff21aa1151781dc886a9526819476d724ceaf51a3
skill_dirty: unknown
target: https://github.com/dan-snelson/Mac-Health-Check (GitHub repo, B)
target_ref: 174b061fbbb9ad0bc8461dd9035651914eda436d (main, v5.0.0)
score_raw: 80
score_final: 80
score_alt: 72
band: Good
generated_by: Claude Opus 5.5 (claude-opus-5-5)
timestamp: 2026-10-04 19:10 EDT
Microsoft 365 Reset
Monocle Report: Microsoft-365-Reset.zsh
Monocle Score
Monocle Score: 87/100 (🔵 Good) — Approve with conditions
Score: 87/100 (🔵 Good) at the operator-stated deployment context — 3 Low, 2 Info, 2 non-security, or 65/100 (🟡 Fair) if a policy runs test or debug mode with a blank $5 allowlist and more than one user is logged in at once
Overall risk: 🔵 Low, or 🟠 High if a policy runs test or debug mode with a blank $5 allowlist and more than one user is logged in at once
Recommendation: Approve with conditions — the code has no serious defects at your deployment, but each Self Service policy needs a list of allowed actions, leaving out Defender removal unless security approves, before its next run, since without one every run stops at startup; re-review if the deployment changes.
Generated by: Claude Opus 5.5 (claude-opus-5-5) · Skill: monocle
Deployment context: Operator-stated (answers in this session, 2026-10-23)
- Mode and allowlist:
$4="self-service" ; $5 is unset - Concurrent sessions: Single-user only
- Interpretation:
$4="self-service"puts thetest,debug, andsilentmodes out of scope. - Interpretation:
$6wasn’t stated, so it takes the documented baseline: allow-all only on admin-only policies (README.md:404). With$5unset and$6off, version 3.0.0 exits 10 during preflight on every self-service run (Microsoft-365-Reset.zsh:3169–3171). If your Self Service policies set$6totrue, every user sees all 20 operations; that is a Rule 14 gate choice and doesn’t change the score. - Interpretation: “Single-user only” puts concurrent user sessions (fast user switching) out of scope. It doesn’t say whether other local accounts exist.
- Effect: Mitigated by deployment context — S5 (🔵 Low at the documented baseline → ⚪ Info; 🟠 High outside it), and X4 (unscoped process matching, not scored:
context; scored in the alternate); raised — none; independent of deployment model — S1, S2, S3, S4, N1, N2.
| Source | IDs | Count | Each | Deduction |
|---|---|---|---|---|
| 🔴 Critical | — | 0 | 40 | 0 |
| 🟠 High | — | 0 | 20 | 0 |
| 🟡 Medium | — | 0 | 8 | 0 |
| 🔵 Low | S1, S2, S3 | 3 | 3 | 9 |
| ⚪ Info | S4, S5 | 2 | 0 | 0 |
| Non-security | N1 failure accounting skips single keychain deletes, sqlite3, and mv; N2 one spelling of the Startup folder | 2 | 2 (max 20) | 4 |
| Not scored | X1 org constants (config); X2 dead code (unreachable); X3 swiftDialog bootstrap (dependency-handled); X4 unscoped process matching (context); X5 destructive operations (capability); X6 direct keychain-database edit (inferred-unverified); X7 single maintainer (ownership) | 7 | 0 | 0 |
Total: 100 − 13 = 87 → 87/100 (🔵 Good)
Alternate: 100 − 35 = 65, inside the High range (25–69) → 65/100 (🟡 Fair), if a policy runs test or debug mode with a blank $5 allowlist and more than one user is logged in at once (S5 → 🟠 High; X4 scored as a non-security issue).
Operator baseline:
- Every policy runs Mode
$4asself-service, nevertestordebug(operator-stated) (S5 → High if not). - Only one user is logged in at a time (operator-stated) (X4 → scored non-security issue if not).
- Each Self Service policy sets a
$5allowlist that excludesremove_defenderunless the security team approves (README.md:404) (Rule 14 gate; not scored). $6(allow all operations) is set only on admin-only policies (README.md:404) (Rule 14 gate; not scored).- Silent policies list only the operations they intend, because silent mode skips the destructive confirmation (README.md:218) (Rule 14 gate; not scored).
Executive View
Executive View: Approve with conditions — each Self Service policy needs an action list
In one sentence: Lets Mac users fix Microsoft 365 problems themselves from Self Service by repairing, resetting, or removing Microsoft apps and their settings, without a help desk visit.
- As you described it, the tool does nothing yet. Version 3.0.0 refuses to start a Self Service run that has no list of allowed actions, so each policy needs one before users can use it.
- It can permanently delete a user’s local data and remove the security agent. Local mail, unsynced notes, saved sign-ins, and Microsoft Defender can all be removed, with no undo. Administrators choose which actions each policy offers, and users must confirm the most destructive ones.
- Some failures are reported as success. If a saved sign-in can’t be deleted, for example because the user’s keychain is locked, the run can still say “Completed”. Help desk staff may then assume a reset worked when it didn’t.
- Fully removing Microsoft 365 also removes Microsoft’s updater, which Defender likely relies on. Defender keeps protecting the Mac but could fall behind on updates until the updater is reinstalled.
- Downloads are checked for Microsoft’s signature, but not for Apple’s notarization or a minimum version. The risk is low: every download starts on a secure connection.
- One person maintains it.
Deployment context: You described Self Service policies in self-service mode, without a list of allowed actions, on Macs where only one person is logged in at a time. That removes two risks: a testing mode showing every action, and closing another person’s apps. The download checks, the updater removal, and the success-reporting gap remain whatever the deployment.
Monocle Score: 87/100 (🔵 Good), or 65/100 (🟡 Fair) if a policy uses a testing mode without a list of allowed actions and more than one person is logged in at once
Recommendation: Approve with conditions — the code has no serious defects at your deployment, but each Self Service policy needs a list of allowed actions, leaving out Defender removal unless security approves, before its next run, since without one every run stops at startup; re-review if the deployment changes.
Security View
Security View: 🔵 Low risk — 3 Low, 2 Info findings
Execution context: root via Jamf Pro policy (Self Service). It drops to the console user for home-folder, keychain, and preference work.
Overall risk: 🔵 Low, or 🟠 High if a policy runs test or debug mode with a blank $5 allowlist and more than one user is logged in at once — the scored findings are defense-in-depth gaps in download checks and removal scope; the High alternate needs a test or debug policy with no allowlist.
Deployment context: Operator-stated — policies run $4 as self-service only, and one user is logged in at a time. That mitigates S5 (test and debug modes are out of scope; 🟠 High outside it) and puts X4 (unscoped process matching) out of scope. Independent of deployment model: S1, S2, S3, S4.
Findings
| ID | Severity | Title | Location |
|---|---|---|---|
| S1 | 🔵 Low | Microsoft packages are checked for publisher only | Microsoft-365-Reset.zsh:704–707 |
| S2 | 🔵 Low | HTTPS isn’t enforced across download redirects | Microsoft-365-Reset.zsh:712 |
| S3 | 🔵 Low | remove_office removes Microsoft AutoUpdate, which other Microsoft apps use |
Microsoft-365-Reset.zsh:1685–1689 |
| S4 | ⚪ Info | Client log is world-readable | Microsoft-365-Reset.zsh:60 |
| S5 | ⚪ Info | Test and Debug modes skip the allowlist requirement | Microsoft-365-Reset.zsh:116 |
S1 — Microsoft packages are checked for publisher only · 🔵 Low
- Location:
Microsoft-365-Reset.zsh:704–707(verifyMicrosoftPkgSignature); the custom-manifest reinstall at:925–927 - Origin: Code — the check pins an Apple-issued Developer ID chain and the Microsoft signer. It ignores the
Notarization:line thatpkgutil --check-signatureprints, runs no Gatekeeper assessment, and sets no version floor for a manifest-chosen package. - Context: Independent of deployment model
- Severity basis: Q2: a network attacker or a compromised custom manifest server, holding a package signed by Microsoft’s Developer ID Installer certificate, gets an older or unnotarized Microsoft build installed as root. Definitions, Weak integrity check: the code pins the vendor’s identity, so the missing notarization and Gatekeeper verdict is 🔵 Low. The missing version floor belongs to the same integrity check (distinct-issue test 1). Likelihood: Expected (network attacker).
- Evidence:
[[ "${signatureOutput}" == *"Status: signed by a developer certificate issued by Apple for distribution"* ]] || return 1and[[ "${signing}" == "Microsoft Corporation (UBF8T346G9)" ]]. On the analysis host,pkgutil --check-signatureprintedNotarization: trusted by the Apple notary servicefor a local Developer ID package; the code never reads that line. - Impact: A revoked or unnotarized Microsoft-signed package, or an older Microsoft build with known vulnerabilities, would pass and install as root. SECURITY.md:44 describes the check accurately; it doesn’t claim notarization.
- Fix: Require
*"Notarization: trusted by the Apple notary service"*insignatureOutput. Alternatively, runspctl -a -vv -t install "$pkgPath"and requireorigin=Developer ID Installer: Microsoft Corporation (UBF8T346G9), asdialogInstallalready does for swiftDialog atMicrosoft-365-Reset.zsh:1000–1002. Before a custom-manifest reinstall, refuse acustomVersionbelow the script’s own minimum (is-at-least 16.73 "${customVersion}", the threshold at:916).
S2 — HTTPS isn’t enforced across download redirects · 🔵 Low
- Location:
Microsoft-365-Reset.zsh:712,:721,:760,:773,:873,:880,:978,:991 - Origin: Code — every download starts on HTTPS, and the custom manifest’s two URLs must start with
https://(Microsoft-365-Reset.zsh:867,:875). Redirect hops and the resolved package URL are not restricted, and bothnscurlandcurl -Lfollow https→http redirects by default. - Context: Independent of deployment model
- Severity basis: Q4: matches the 🔵 Low example “no
--proto '=https'on an HTTPS URL”. Signature pins still gate every install (S1; Credits). Likelihood: Expected (network attacker), once a server redirects to plain HTTP. - Evidence:
dialogURL="$(curl -L --silent --fail --connect-timeout 10 --max-time 30 \sets no--proto-redir.pkgURL="$(downloadResolvedPkgURL "${downloadURL}")"takes the lastLocation:header (Microsoft-365-Reset.zsh:712–716) with nohttps://check. Isolated checks (Scope caveats):nscurlloadedhttp://neverssl.com/and followed an https→http redirect;curl -Lfollowed it;--proto '=https' --proto-redir '=https'stopped it. - Impact: If any redirect hop ever points to plain HTTP, an on-path attacker can replace the package or the manifest. That covers Microsoft’s fwlink chain, GitHub’s asset CDN, and a custom manifest server. Combined with S1, it could deliver an older Microsoft-signed build.
- Fix: Add
--proto '=https' --proto-redir '=https' --tlsv1.2to bothcurlcalls. IndownloadResolvedPkgURL, reject the result unless everyLocation:hop starts withhttps://, and check[[ "${pkgURL}" == https://* ]]atMicrosoft-365-Reset.zsh:763.
S3 — remove_office removes Microsoft AutoUpdate, which other Microsoft apps use · 🔵 Low
- Location:
Microsoft-365-Reset.zsh:1685–1689,:1702,:1705,:1727,:1733–1734,:1848 - Origin: Code — this matches MOFA Office Removal (README.md:46), but parity isn’t evidence. The script itself registers Microsoft Defender, Company Portal, and Remote Desktop with MAU (
Microsoft-365-Reset.zsh:2703–2707). Yet the documentation calls MAU2.0 Office-owned (README.md:46) and saysremove_officedoes not remove Defender (README.md:160). - Context: Independent of deployment model
- Severity basis: Q0, Rule 14 checklist: C5 is yes, because the removal reaches a shared updater that the documentation describes as Office-owned. It is therefore not a capability. Q2: there is no attacker. On any Mac that keeps Defender after
remove_office, Defender’s product updates through MAU stop until MAU is reinstalled (inferred from Microsoft’s Defender for Endpoint on macOS update documentation). Q5: Defender keeps running and protecting the Mac, so the control itself isn’t lost → 🔵 Low. Likelihood: n/a (no deliberate actor; it happens on every such run). - Evidence:
safeRemove "/Library/Application Support/Microsoft/MAU2.0"andregisterMAUStaticApplicationIfPresent "/Applications/Microsoft Defender.app" "{ 'Application ID' = 'WDAV00'; LCID = 1033 ; }" - Impact: Defender, Company Portal, and Remote Desktop stay installed but no longer receive MAU updates. They could fall behind on security fixes without anyone noticing.
- Fix: Before removing
MAU2.0, its helper daemon and tool, and thecom.microsoft.package.Microsoft_AutoUpdate.appreceipt, check for MAU clients that the run keeps (Microsoft Defender.app,Company Portal.app,Microsoft Remote Desktop.app). If any remain, keep MAU and log that it was kept. Document the result next to README.md:160.
S4 — Client log is world-readable · ⚪ Info
- Location:
Microsoft-365-Reset.zsh:60,:270,:3129,:3154 - Severity basis: Q2: the root-created log takes the default
0644mode. It holds usernames, full names, UIDs, home paths, and removed paths, which local users can already read through Directory Services. Keychain output never reaches it (Microsoft-365-Reset.zsh:569–571) → ⚪ Info.
S5 — Test and Debug modes skip the allowlist requirement · ⚪ Info
- Location:
Microsoft-365-Reset.zsh:116,:1207–1214,:3169 - Origin: Code + Deployment — the preflight allowlist check applies only to
self-service.testanddebugshow all 20 operations when$5is blank; README.md:112 documents this, and README.md:134 describestestas operator testing. - Context: Mitigated by deployment context — policies run
$4asself-serviceonly; 🟠 High outside it. - Severity basis:
- Q0, Rule 14 checklist:
- C1–C3 are yes (README.md:7; the operations table at README.md:144–165; the
$5gate atMicrosoft-365-Reset.zsh:56). - C4–C6 are no.
- C7 offers everything in
testanddebug(Microsoft-365-Reset.zsh:1207–1214; the check at:3169covers onlyself-service). - C8 rejects invalid values (
Microsoft-365-Reset.zsh:119–122). - Outcome: a 🔵 Low secure-default gap at the documented baseline.
- C1–C3 are yes (README.md:7; the operations table at README.md:144–165; the
- Q3: the operator’s context never runs
testordebug→ ⚪ Info. - Alternate: Q5. In a Self Service policy set to
testordebugwith a blank$5, a standard user runs root-only removals, including Microsoft Defender. That is rated as privilege escalation for that operation → 🟠 High.
- Q0, Rule 14 checklist:
- Evidence:
if [[ "${operationMode}" == "self-service" && "${allowAllOperations}" != "true" ]] && operationCSVIsEmpty; then - Impact: An admin who pilots a Self Service policy in
testordebugmode without$5offers every user all 20 operations, includingremove_defenderandremove_office. They get these without the$6opt-in thatself-servicerequires. - Fix: Apply the check in every interactive mode:
[[ "${operationMode}" != "silent" && "${allowAllOperations}" != "true" ]] && operationCSVIsEmpty. Then update README.md:112.
Credits
PATHpinned to system directories, with--no-rcsin the shebang —Microsoft-365-Reset.zsh:1,:28- Root-private
mktemp -dstaging set to0700, plus regular-file and root-owner checks beforeinstaller—Microsoft-365-Reset.zsh:747–754,:775–783,:986–996 - swiftDialog: Gatekeeper assessment and Team ID check before install; a codesign requirement and an ownership walk; execution pinned to the validated resolved path —
Microsoft-365-Reset.zsh:1000–1002,:1015–1040 - Microsoft signer pinned to
Microsoft Corporation (UBF8T346G9)under an Apple-issued distribution certificate, rejecting the weaker “trusted by macOS” status —Microsoft-365-Reset.zsh:698–707 - An existing bundle moves aside only after its replacement verifies, and is restored on failure —
Microsoft-365-Reset.zsh:799–839 - Deletions under the user’s home folder run as the console user, after a parent-symlink check —
Microsoft-365-Reset.zsh:345–367,:387–399 - Vendor uninstallers run only when both the literal and the resolved paths are root-owned all the way up to
/—Microsoft-365-Reset.zsh:1044–1073 - Keychain helpers suspend xtrace and discard
securityoutput —Microsoft-365-Reset.zsh:559–571 - Home and per-user temp folders are validated before use —
Microsoft-365-Reset.zsh:3146–3151,:3157–3167 - Inputs fail closed:
- an invalid mode exits 10, and
$6defaults to off —Microsoft-365-Reset.zsh:119–132; - unknown operation IDs are fatal —
Microsoft-365-Reset.zsh:1177–1184; self-servicerequires an allowlist —Microsoft-365-Reset.zsh:3169–3171.
- an invalid mode exits 10, and
launchctl asuserplussudo -H -u, with no fallback re-run —Microsoft-365-Reset.zsh:338- Custom MAU manifest URLs must use
https://—Microsoft-365-Reset.zsh:867–878 - Partial removals fail the operation, and the run exits 20 —
Microsoft-365-Reset.zsh:3260–3274,:3283–3285
Privilege map
- Whole run —
Microsoft-365-Reset.zsh:3134–3136— root; refuses to run otherwise - Package installs (
installer -pkg) —Microsoft-365-Reset.zsh:816,:1004— root - Deletions outside the home folder (
/Applications,/Library,/Users/Shared) —Microsoft-365-Reset.zsh:398— root - Vendor uninstallers (Defender, Zoom, WebEx) —
Microsoft-365-Reset.zsh:2903,:2991,:3033— root, after the trust check - System preferences (
defaults write /Library/Preferences/com.microsoft.autoupdate2) —Microsoft-365-Reset.zsh:1893,:2672,:2688— root - Package receipts (
pkgutil --forget) —Microsoft-365-Reset.zsh:1866,:2887–2888,:2933–2935— root - launchd jobs (
bootout,bootstrap) —Microsoft-365-Reset.zsh:435,:446— root, in thesystemdomain and the user’sgui/<uid>domain - Licensing file move —
Microsoft-365-Reset.zsh:2752— root - swiftDialog windows —
Microsoft-365-Reset.zsh:1123,:1383— root, in the console session - Deletions in the home and per-user temp folders —
Microsoft-365-Reset.zsh:396— console user, throughlaunchctl asuser … sudo -H -u - Keychain deletes and keychain-database edits —
Microsoft-365-Reset.zsh:569,:2375,:2822— console user - User preferences, the Teams TCC reset, and Teams background moves —
Microsoft-365-Reset.zsh:2779–2789,:2525,:2396,:2470— console user - Restart request —
Microsoft-365-Reset.zsh:1503— console user, through loginwindow’s own confirmation
Secrets inventory
No secrets observed. The script deletes Microsoft sign-in items from the user’s keychain but never reads their values: find-generic-password runs without -w, and all output is discarded (Microsoft-365-Reset.zsh:533, :569–571). Debug mode’s xtrace (Microsoft-365-Reset.zsh:111) carries usernames and paths only.
Network egress
api.github.com/repos/swiftDialog/swiftDialog/releases/latest— GET — TLS verified, unauthenticated; redirects aren’t limited to HTTPS (S2) —Microsoft-365-Reset.zsh:978–980- GitHub release asset (must start with
https://github.com/, checked atMicrosoft-365-Reset.zsh:983) — GET — TLS verified; Gatekeeper and Team ID gate the install —Microsoft-365-Reset.zsh:991 go.microsoft.com/fwlink/?linkid=…and its redirect targets — HEAD and GET throughnscurl— TLS verified on the first hop; the signer pin gates the install (S1, S2) —Microsoft-365-Reset.zsh:712,:721,:773- Custom MAU
ManifestServer, read fromcom.microsoft.autoupdate2— GET —https://required —Microsoft-365-Reset.zsh:861–880 - Icon URLs on
usw2.ics.services.jamfcloud.comandswiftdialog.app— fetched by swiftDialog —Microsoft-365-Reset.zsh:40,:43,:230–248
Persistence
No persistence is created. reset_autoupdate reloads the MAU launchd jobs it booted out (Microsoft-365-Reset.zsh:2627–2629). remove_office boots out and deletes Microsoft launchd jobs (Microsoft-365-Reset.zsh:1685–1691, :1723–1731).
Manager View
Manager View: Production-grade; one maintainer (Dan K. Snelson)
Ownership: Dan K. Snelson — script header Microsoft-365-Reset.zsh:15; 55 of 55 commits. Bus factor: 1.
Maturity: Production-grade — validates inputs, fails closed, logs to a known path, has versions and tags, and is documented in detail. A few cleanup failures still report success (N1).
Change risk: High — runs as root, makes irreversible deletions (mail, unsynced notes, keychain items, Defender), and is a single 3,290-line file with one maintainer.
What it depends on
- Jamf Pro policy parameters
$4–$6(mode, allowlist, allow-all opt-in). As stated ($5unset,$6not stated), every Self Service run exits 10 at startup. - swiftDialog 3.0.1.4955 or later, Team ID PWA5E9TQ59. Installed or upgraded on demand from GitHub’s latest release.
- Microsoft fwlink download URLs, hardcoded per app. A retired link breaks that app’s auto-repair.
- Full Disk Access for the Jamf binary through a PPPC profile (README.md:94). Without it, container cleanup fails with exit 20.
- MOFA as the behavior baseline (README.md:329). Upstream changes need review.
- The org log path and Jamf-hosted icon URLs. Adopters edit them (README.md:99).
- One maintainer.
- Release status. The analyzed ref is tag
v3.0.0itself, so installed 3.0.0 copies match this review. - The stated deployment model (self-service mode only, one user logged in at a time) — re-run Monocle if it changes.
Fragility hotspots
- A sign-in item that a single delete can’t remove, for example from a locked login keychain, still reports “succeeded” and exits 0. That contradicts README.md:374 —
Microsoft-365-Reset.zsh:577–579(N1) - The Word, Excel, PowerPoint, and Outlook resets skip system-level startup add-ins and
NormalEmail.dotmwhen the folder is namedStartup, as it is on the analysis Mac. Nothing is logged —Microsoft-365-Reset.zsh:2021(N2) - Full removal leaves Defender without its MAU update channel —
Microsoft-365-Reset.zsh:1705(see S3) - The swiftDialog bootstrap depends on the unauthenticated GitHub API. A rate limit or outage stops interactive runs with exit 10 —
Microsoft-365-Reset.zsh:978–983(not scored: dependency-handled) - On a Mac with two logged-in users, app stops close the other user’s Office apps without saving. The Acrobat add-in wait would also loop forever on another user’s Word —
Microsoft-365-Reset.zsh:1574(not scored: context) - The OneDrive and sign-in resets edit the keychain’s SQLite database directly while
securitydis running. The effect on keychain consistency is unverified —Microsoft-365-Reset.zsh:2375(not scored: inferred-unverified)
Change & rollback
- Testing: The maintainer’s workflow runs
zsh -n, Semgrep, and Gitleaks (SECURITY.md:59–62). No functional tests were found in this scope.testmode is not a dry run (README.md:134). - Rollback: Partial. Apps can be reinstalled, and a failed repair install restores the original bundle (
Microsoft-365-Reset.zsh:825–839). Deleted mail, unsynced notes, keychain items, logs, and a removed Defender can’t be recovered without backups or reinstallation (README.md:406). - Deploy path: Jamf Pro policy in Self Service, using
$4–$6(operator-stated; README.md:117–127).
Action items
| # | Action | Owner role | Effort | Priority |
|---|---|---|---|---|
| 1 | Add an operations allowlist ($5) to each Self Service policy, leaving out remove_defender unless security approves; as described, every run exits 10 before doing anything |
Jamf admin | S | P1 |
| 2 | Count failed single keychain deletes, sqlite3 edits, and licensing moves as operation failures (N1) |
Mac engineer | S | P2 |
| 3 | Keep MAU when Defender, Company Portal, or Remote Desktop remain after remove_office (S3) |
Mac engineer | S | P2 |
| 4 | Require notarization and HTTPS on every download hop; add a version floor for custom-manifest pins (S1, S2) | Mac engineer | M | P2 |
| 5 | Clean both Startup and Startup.localized, and the .localized Add-Ins and Themes folders, in app resets (N2) |
Mac engineer | S | P3 |
| 6 | Require the allowlist in test and debug modes too (S5) (mitigated by deployment context) |
Mac engineer | S | P3 |
| 7 | Scope pkill and pgrep to the console user (X4) (mitigated by deployment context) |
Mac engineer | M | P3 |
| 8 | Name a second maintainer for a root tool with irreversible operations (X7) | Service owner | M | P3 |
Engineer View
Engineer View: some keychain and folder cleanups fail or skip without failing the run
Shape: zsh (#!/bin/zsh --no-rcs), 3,290 lines, 117 functions, entry point main "$@" (Microsoft-365-Reset.zsh:3290). It runs as a Jamf policy script ($4–$6) or from the CLI as root (--mode, --operations, --allow-all-operations).
Inputs → Outputs: Jamf $4–$6 or CLI flags, the console user’s identity, MAU preferences, and Microsoft download servers → deletions, Microsoft package installs, keychain deletions, preference writes, launchd job changes, /var/log/org.churchofjesuschrist.log, and exit codes 0, 2, 10, and 20.
Control flow
- The shebang
#!/bin/zsh --no-rcsand thePATHpin;$4–$6read with defaults (self-service, empty,false) —Microsoft-365-Reset.zsh:1,:28,:55–57 - CLI flags override; leading positionals are skipped until the first flag, and unknown flags exit 10 —
Microsoft-365-Reset.zsh:64–104 - Mode normalized:
debugturns onset -x, and an invalid mode exits 10;$6parsed fail-closed —Microsoft-365-Reset.zsh:106–132 - The work directory and the swiftDialog command file are created with
mktemp; thecleanupEXIT trap logs a summary and removes both —Microsoft-365-Reset.zsh:134–141,:279–290 maincallspreflightChecks—Microsoft-365-Reset.zsh:3190–3191,:3128–3176:- creates the log and requires root;
- resolves the console user through
scutil; - validates the home and per-user temp folders;
- enforces the self-service allowlist;
- validates or installs swiftDialog, except in
silentmode.
- Intro and selection dialogs;
silentskips them and parses$5directly. A cancel exits 0 —Microsoft-365-Reset.zsh:3193–3207,:1120–1259 - Validate IDs, then expand dependencies, then sort into four phases —
Microsoft-365-Reset.zsh:3209–3211,:1261–1326,:3103–3126. Dependency rules:reset_factoryadds nine resets;remove_officeadds Skype for Business and drops resets.
- Destructive confirmation for five operations, in interactive modes only —
Microsoft-365-Reset.zsh:3212–3218,:1328–1366 - Progress dialog. If
remove_officeis selected, its teardown phase runs first, and a failure there exits 20 at once —Microsoft-365-Reset.zsh:3222–3252 - Operation loop:
removalFailuresresets for each operation. An operation fails when it returns non-zero, or when anysafeRemoveor keychain loop left something behind —Microsoft-365-Reset.zsh:3256–3277 - App resets: stop the app, then run
maybeRepairOfficeAppfor the version and codesign checks, then do path and keychain cleanup —Microsoft-365-Reset.zsh:886–964,:1994–2035. A repair returns 2 and defers cleanup to a later run. repairFromMicrosoftPkg, in order —Microsoft-365-Reset.zsh:728–846:- resolve the URL;
- download to root-private staging;
- check owner, size, and signature;
- move the old bundle aside;
- install, with an optional codesign check;
- restore the old bundle on failure.
- Completion dialog and restart prompt; exit 20 if any operation failed, otherwise 0 —
Microsoft-365-Reset.zsh:3279–3287
Footguns
- Single keychain deletes don’t count —
Microsoft-365-Reset.zsh:577–579- When
securityfails with anything other than “not found” (for example, on a locked login keychain),runKeychainDeleteonly warns and doesn’t incrementremovalFailures. - As a result,
reset_outlook,reset_license, andreset_credentialsreport success while sign-in items remain. - The
sqlite3DELETE (Microsoft-365-Reset.zsh:2375,:2822) and the licensingmv(Microsoft-365-Reset.zsh:2752,:2759) ignore their exit codes the same way. (N1)
- When
- One spelling of
Startup—Microsoft-365-Reset.zsh:2021- The Word, Excel, PowerPoint, and Outlook resets target only
Startup.localizedin the system Office content root (Microsoft-365-Reset.zsh:2021,:2064,:2112,:2165). remove_acrobat_addinhandles both names (Microsoft-365-Reset.zsh:2956). On the analysis Mac the system root usesStartup, so those four removals do nothing there.- The user-level PowerPoint
Add-InsandThemespaths (Microsoft-365-Reset.zsh:2123,:2125) exist asAdd-Ins.localizedandThemes.localizedon the analysis Mac (host evidence). (N2)
- The Word, Excel, PowerPoint, and Outlook resets target only
- Process matching ignores the user —
Microsoft-365-Reset.zsh:1574— everypkillandpgrep -xmatches every user’s processes. With fast user switching, a reset closes another user’s Word without saving.waitForInteractiveAppQuitwould also wait forever for an app the console user can’t quit. (not scored: context) - Dead code —
Microsoft-365-Reset.zsh:1493–1501promptForRestartalways passes"Restart Confirm"(Microsoft-365-Reset.zsh:1538), so the rootshutdownbranch never runs.operationDescription(Microsoft-365-Reset.zsh:206–226) is defined but never displayed; the picker shows titles only (:1217). (not scored: unreachable)
Edge cases not handled
- Login keychain locked (a password out of sync, which is a common reason to run
reset_credentials) → single deletes fail and the operation still reports success —Microsoft-365-Reset.zsh:578(N1) - Office content root uses
Startuprather thanStartup.localized→ startup add-ins andNormalEmail.dotmstay in place —Microsoft-365-Reset.zsh:2165(N2) - Another logged-in user has Word open during interactive
remove_acrobat_addin→ endless wait, and the policy never finishes —Microsoft-365-Reset.zsh:1574(not scored: context) sqlite3DELETE onkeychain-2.dbwhilesecuritydholds it → the effect on its caches and consistency is unverified —Microsoft-365-Reset.zsh:2375(not scored: inferred-unverified)- GitHub API rate limit or outage while swiftDialog is missing → fatal exit 10 —
Microsoft-365-Reset.zsh:982(not scored: dependency-handled)
Refactor suggestions
R1 — Count every failed keychain delete · Quick win
Microsoft-365-Reset.zsh:577–579
# before
elif [[ ${deleteRC} -ne ${notFoundRC} ]]; then
warning "Unable to delete keychain item: ${description} (security exit ${deleteRC})"
fi
# after
elif [[ ${deleteRC} -ne ${notFoundRC} ]]; then
warning "Unable to delete keychain item: ${description} (security exit ${deleteRC})"
(( removalFailures += 1 )) # fails the current operation (see main)
fi
This makes README.md:374’s exit-20 promise true (N1). Wrap the sqlite3 calls at Microsoft-365-Reset.zsh:2375 and :2822, and the moves at :2752 and :2759, in if ! …; then warning …; (( removalFailures += 1 )); fi the same way. A loop variant can count one item twice, which is harmless, because any non-zero count fails the operation.
R2 — Clean both Startup folder spellings · Quick win
Microsoft-365-Reset.zsh:2021
# before
safeRemove "/Library/Application Support/Microsoft/Office365/User Content.localized/Startup.localized/Word"
# after
local startupName
for startupName in Startup Startup.localized; do
safeRemove "/Library/Application Support/Microsoft/Office365/User Content.localized/${startupName}/Word"
done
safeRemove returns 0 for a missing path, so trying both names is safe (N2). Repeat this for Excel (Microsoft-365-Reset.zsh:2064), PowerPoint (:2112), NormalEmail.dotm (:2165), and the user-level copies. Apply the same pattern to Add-Ins and Themes with their .localized variants (:2122–2125).
R3 — Keep every download hop on HTTPS · Quick win
Microsoft-365-Reset.zsh:991
# before
curl -L --silent --fail --connect-timeout 10 --max-time 60 "${dialogURL}" -o "${pkgPath}" \
|| fatal "Failed to download swiftDialog package"
# after
curl -L --proto '=https' --proto-redir '=https' --silent --fail --connect-timeout 10 --max-time 60 "${dialogURL}" -o "${pkgPath}" \
|| fatal "Failed to download swiftDialog package"
In the isolated check, curl 8.7.1 with these flags stopped at an https→http redirect with exit 1 (see S2). Add the same flags at Microsoft-365-Reset.zsh:978. nscurl has no protocol filter, so check every Location: hop in downloadResolvedPkgURL and the resolved pkgURL (:763) for https://.
R4 — Require notarization for Microsoft packages · Quick win
Microsoft-365-Reset.zsh:705
# before
[[ "${signatureOutput}" == *"Status: signed by a developer certificate issued by Apple for distribution"* ]] || return 1
# after
[[ "${signatureOutput}" == *"Status: signed by a developer certificate issued by Apple for distribution"* ]] || return 1
[[ "${signatureOutput}" == *"Notarization: trusted by the Apple notary service"* ]] || return 1
The line format matches pkgutil --check-signature output on Darwin 25 (host check; see S1). Before shipping, confirm that current Microsoft packages print that line; an unnotarized package would otherwise fail every repair.
R5 — Require the allowlist in every interactive mode · Quick win
Microsoft-365-Reset.zsh:3169
# before
if [[ "${operationMode}" == "self-service" && "${allowAllOperations}" != "true" ]] && operationCSVIsEmpty; then
# after
if [[ "${operationMode}" != "silent" && "${allowAllOperations}" != "true" ]] && operationCSVIsEmpty; then
This closes S5. silent mode already exits 2 on an empty list (Microsoft-365-Reset.zsh:3181–3182). Update the fatal message at :3170, and update README.md:112.
R6 — Scope app stops to the console user · Deeper
Microsoft-365-Reset.zsh:1612–1613
# before
pkill "$@" 2>/dev/null && sleep 2
pkill -9 "$@" 2>/dev/null
# after
pkill -u "${loggedInUserID}" "$@" 2>/dev/null && sleep 2
pkill -9 -u "${loggedInUserID}" "$@" 2>/dev/null
This keeps another session’s unsaved work safe (X4). Apply -u "${loggedInUserID}" in the following places, about 30 sites in total, which is why it needs testing:
- the
signal*Processesuser-app helpers; - the direct
pkill -9calls; pgrep -xinwaitForInteractiveAppQuit(Microsoft-365-Reset.zsh:1563,:1574).
Leave root-owned MAU helper stops in signalAutoUpdateProcesses unscoped.
Quick wins vs deeper work
- Quick wins (< 1 hr): R1, R2, R3, R4, R5
- Deeper work: R6 — touches every process stop, and root-owned helpers must stay unscoped, so it needs a test pass on a Mac with fast user switching.
Cross-cutting notes
Cross-cutting notes: as stated, every Self Service run exits 10 before doing anything
- As stated, the policies run nothing.
- In
self-servicemode with$5unset and$6off, version 3.0.0 exits 10 during preflight (Microsoft-365-Reset.zsh:3169–3171; README.md:373). - If your policies actually set
$6totrue, every Self Service user sees all 20 operations, includingremove_defenderandremove_office. That is an admin gate choice under Rule 14 (README.md:404) and isn’t scored, but it makes Manager action 1 urgent rather than routine.
- In
- The download gaps compound (S1 + S2). An http hop chosen by any server in a redirect chain would let an on-path attacker swap the package. The Microsoft signer pin still blocks foreign packages. Without a notarization check or a version floor, though, an older Microsoft-signed build would install as root. This requires a server to redirect to plain HTTP, which Microsoft’s and GitHub’s chains don’t appear to do today (inferred).
- Self Service users drive root deletions. The
$5allowlist is the only control between a standard user and root-run removals, and the code enforces it well inself-servicemode. S5 is the one path where the code skips it, and the operator’s deployment doesn’t use that path.
Scope
Scope: 46b556c (v3.0.0) — 1 file, full coverage; README and SECURITY read as docs only
| Field | Value |
|---|---|
| Date | 2026-10-23 09:56 EDT |
| Target | /Users/danksnelson/Documents/GitHub/dan-snelson/Microsoft-365-Reset/Microsoft-365-Reset.zsh (local file in a git repo, analyzed as a single file) |
| Ref | 46b556cf1ed464a92a7f990c512f51c0ffb70d55 (development, tag v3.0.0, clean) |
| Generated by | Claude Opus 5.5 (claude-opus-5-5) |
| Language(s) | zsh 5.9 (#!/bin/zsh --no-rcs), embedded JXA (osascript -l JavaScript), SQLite SQL |
| Files analyzed | 1 — Microsoft-365-Reset.zsh (3,290 lines, read in full) |
| Automated scan | semgrep 1.177.0 — p/r2c-security-audit, p/secrets, p/ci — 0 results (0 confirmed), 0 parse errors, 0 files skipped |
| Scope caveats | See below |
Scope caveats:
- Script only. The operator limited scope to this file. README.md and SECURITY.md were read as documentation only, with the operator’s approval, to cite the documented baseline; they weren’t analyzed or scored.
- Not reviewed. CHANGELOG.md, AGENTS.md,
.codex/,.github/,Resources/,scripts/, and.deployMicrosoft365Reset.zshwere not reviewed. Agent configuration wasn’t scanned for embedded instructions (Rule 5). - Semgrep coverage. Semgrep has no zsh parser, so 0 results is not evidence of a clean script. The full manual Step 4 review was done. The scan ran on a scratch copy of the file.
- Host evidence (2026-10-23, Darwin 25.7.1 arm64). Read-only checks on the analysis Mac:
ls -ldshowed/Library/Application Support/Microsoft/Office365/User Content.localized/Startup(no.localized), allroot:wheel 755.- The user root contains
Startup.localized,Add-Ins.localized, andThemes.localized. /Library/Logs/Microsoftexists,/usr/local/binisroot:wheel, and/usr/local/bin/dialogresolves intoDialog.app.pkgutil --check-signatureon a local Developer ID package printed aNotarization:line.
- Isolated checks (Rule 4).
nscurl --head http://neverssl.com/returnedHTTP/1.1 200 OK, so there is no ATS block.nscurl --location --headon an httpbin.org redirect followed it tohttp://neverssl.com/and timed out there.curl -sIL(8.7.1) followed the same redirect tohttp://neverssl.com/(200).- With
--proto '=https' --proto-redir '=https', curl stopped at the 302 with exit 1. - Side effects: outbound requests to httpbin.org and neverssl.com only.
- Inferred. S3’s effect on Defender’s product updates comes from Microsoft’s Defender for Endpoint on macOS documentation, not from code in scope. The S1 and S2 downgrade path is traced from the code but not reproduced. X6 is unverified.
- Deployment context. Taken from the operator’s answers in this session.
$6wasn’t stated, so it takes the documented baseline.
Attestation:
monocle_attestation: v2
skill_repo: https://github.com/dan-snelson/Monocle
skill_commit: ac479aef5fc9c656a716baaecf16b02ee47fbfb8
skill_ref: b-as-in-bdellium
skill_tree: 538ef4b8c104033f7962f41bf065d6d9cf496583
skill_sha256: f15faec8c64c9ad16413d9076cd181c52094ef26cd1eb2f2c26b19c0b63f2feb
skill_dirty: false
target: /Users/danksnelson/Documents/GitHub/dan-snelson/Microsoft-365-Reset/Microsoft-365-Reset.zsh (local file in a git repo, analyzed as a single file)
target_ref: 46b556cf1ed464a92a7f990c512f51c0ffb70d55 (development, tag v3.0.0, clean)
score_raw: 87
score_final: 87
score_alt: 65
band: Good
deployment_context: operator
generated_by: Claude Opus 5.5 (claude-opus-5-5)
timestamp: 2026-10-23 09:56 EDT
SYM-Lite
Monocle Report: SYM-Lite
Monocle Score
Monocle Score: 89/100 (🔵 Good) — Approve
Score: 89/100 (🔵 Good) at the operator-stated deployment context — 3 Low, 3 Info, 1 non-security, or 67/100 (🟡 Fair) if organizationInstallomatorFile is reached through a symlinked parent directory that a standard user can write and another person has an account on the release Mac; up from 84 at 0ab93ea (1.4.0 working tree)
Overall risk: 🔵 Low, or 🟠 High if organizationInstallomatorFile is reached through a symlinked parent directory that a standard user can write and another person has an account on the release Mac
Recommendation: Approve — no serious findings remain at the stated deployment, and every item from the previous review is fixed; make mistyped on/off settings fail safe in the next release, and re-review if the deployment changes.
Generated by: Claude Opus 5.5 (claude-opus-5-5) · Skill: monocle
Deployment context: Operator-stated (inline answers in this session, 2026-10-10)
- Data location (Installomator): “Default AAP path — /Library/Application Support/AppAutoPatch/Installomator/Installomator.sh, no symlinks, root-owned at every level”
- Trust boundary (release Mac): “No other accounts — Single-user Mac; only you log in”
- Install model: “Self Service / scoped — Self Service and/or policies scoped to developer groups”
- Interpretation: each answer was chosen from offered options and maps only to the field named; the trust-boundary answer covers the Mac that runs
.deploySYMLite.zsh, not endpoints. - Effect: Mitigated by deployment context — S1 (🟡 Medium → 🔵 Low), S2 (🟠 High → 🔵 Low); raised — none (scoped, not fleet-wide, so no raise); independent of deployment model — S3, S4, S5, S6, N1.
| Source | IDs | Count | Each | Deduction |
|---|---|---|---|---|
| 🔴 Critical | — | 0 | 40 | 0 |
| 🟠 High | — | 0 | 20 | 0 |
| 🟡 Medium | — | 0 | 8 | 0 |
| 🔵 Low | S1, S2, S3 | 3 | 3 | 9 |
| ⚪ Info | S4, S5, S6 | 3 | 0 | 0 |
| Non-security | N1 Homebrew validation prefix follows CPU, not brew |
1 | 2 (max 20) | 2 |
| Not scored | X1 release-helper eval (maintainer); X2 unpinned CI pip install semgrep (maintainer); X3 README drift (docs); X4 configured installs (capability); X5 Firefox ESR shares Firefox’s path (config); X6 otter needs a recent Installomator (config); X7 | inside a field (malformed-config); X8 duplicate item IDs (malformed-config); X9 swiftDialog bootstrap needs GitHub (dependency-handled); X10 dialogs launched as root (inferred-unverified); X11 Command Line Tools install (capability); X12 softwareupdate --list has no timeout (inferred-unverified); X13 third-party tap auto-trust (capability); X14 quarantine removal (capability) |
14 | 0 | 0 |
Total: 100 − 11 = 89 → 89/100 (🔵 Good)
Alternate: with S1 at Medium and S2 at High, 100 − (20 + 8 + 3 + 2) = 67, inside the High range (25–69), so no clamp → 67/100 (🟡 Fair) when organizationInstallomatorFile is reached through a symlinked parent directory a standard user can write and another person has an account on the release Mac.
Score change: +5 from 84 at 0ab93ea with uncommitted 1.4.0 edits. That report covered SYM-Lite.zsh alone at the documented baseline; this one covers the whole repository with operator context, so the release helper and agent configuration are now in scope.
- Closed: prior S2 (swiftDialog Gatekeeper verdict, now required at
SYM-Lite.zsh:1536); prior S4 (log mode,SYM-Lite.zsh:1729); prior N2 (Homebrew user pinned,SYM-Lite.zsh:889); prior N4 (rotated-log pruning,SYM-Lite.zsh:1747); prior N5 (Jamf items removed when the binary is missing,SYM-Lite.zsh:1879); prior X9 (unreachable root restart branch removed). - Persisting: prior S1 as S2, narrowed — the walk to
/and the pre-execution re-check closed both original gaps, and only symlinked parent directories remain; prior S3 as S5 (icons); prior N1 (now warned atSYM-Lite.zsh:1101, still mis-validates); prior X1–X8 as X3–X7, X9, X10, X13 (renumbered; X3’s content changed — the old drift is fixed and new drift appeared). - Re-rated: prior N3 (cross-type ID collisions) is X8
malformed-config:README.md:428now forbids duplicate IDs and pre-flight warns (SYM-Lite.zsh:1263) (+2). - New: S1 (release helper, present at the prior ref but outside that report’s single-file scope); S3 (the Jamf and Homebrew toggles fell through to
trueat6dda995— previously missed; the Command Line Tools toggle was introduced in 1.6.0); S6, X11, and X12 (introduced by the 1.6.0 Command Line Tools bootstrap); X14 (quarantine removal, present at the prior ref and not listed then); S4, X1, and X2 (previously out of scope).
Operator baseline:
- No other person has an account on the Mac that runs
.deploySYMLite.zsh(operator-stated) (S1 → Medium if not) organizationInstallomatorFilestays at the default App Auto-Patch path with no symlinked directories and root ownership at every level (operator-stated) (S2 → High if not)- The item arrays (
installomatorLabels,jamfPolicyItems,homebrewItems) list only approved software, and Parameter 5 limits each policy to its items (Rule 14 gate; not scored) homebrewAutoInstallCommandLineToolsis set deliberately; whentrue, any Homebrew work on a Mac withoutgitinstalls Apple’s Command Line Tools as root (Rule 14 gate; not scored)homebrewAutoTrustItemstrusts only configured, fully qualified third-party tap items (README.md:108) (Rule 14 gate; not scored)homebrewAutoRemoveQuarantinestaysfalseunless Gatekeeper-accepted casks should open without the first-launch prompt (README.md:394) (Rule 14 gate; not scored)
Executive View
Executive View: Approve — prior issues fixed; mistyped settings should fail safe
In one sentence: Gives developers (or administrators, unattended) one approved menu for installing developer tools and running management tasks, with on-screen progress and a results summary.
- Runs with full administrator access, but only installs what the organization has pre-approved. Users choose from a fixed list, and each Self Service policy can narrow that list further.
- A mistyped on/off setting turns a feature on rather than off. If an administrator misspells “false” for Jamf items, Homebrew items, or the new developer-tools install, that feature runs anyway; the effect stays within the approved list.
- New in this release: can install Apple’s developer command-line tools automatically. It’s a large download that can add several minutes when Homebrew needs it; administrators can turn it off.
- Every issue from the previous review is fixed, including the installer-approval check, the protected-folder check, and handling of Macs without Jamf.
- Restarts only with the user’s consent, through the normal macOS restart prompt.
- One person maintains it. All 41 commits come from a single author, and this release isn’t tagged yet.
Deployment context: You described the default protected Installomator folder, a release Mac only you use, and Self Service or developer-scoped policies. That removes the two folder-related risks; the mistyped-setting gap remains whatever the deployment.
Monocle Score: 89/100 (🔵 Good), or 67/100 (🟡 Fair) if Installomator is reached through a linked folder that standard users can change and the release Mac is shared
Recommendation: Approve — no serious findings remain at the stated deployment, and every item from the previous review is fixed; make mistyped on/off settings fail safe in the next release, and re-review if the deployment changes.
Security View
Security View: 🔵 Low risk — 3 Low findings
Execution context: root via Jamf policy (Self Service or scoped) or manual sudo; drops to the console user for Inspect Mode, the completion dialog, every Homebrew command, quarantine removal, and the restart request. The release helper runs as the maintainer.
Overall risk: 🔵 Low, or 🟠 High if organizationInstallomatorFile is reached through a symlinked parent directory that a standard user can write and another person has an account on the release Mac — the 1.4.0 hardening holds, the 1.6.0 Command Line Tools path is carefully built, and the remaining gaps are defense-in-depth at the stated deployment.
Deployment context: Operator-stated — the default App Auto-Patch path mitigates S2, and a single-user release Mac mitigates S1; scoped deployment raises nothing. Independent of deployment model: S3–S6.
Findings
| ID | Severity | Title | Location |
|---|---|---|---|
| S1 | 🔵 Low | Release helper writes notes to a fixed /tmp name |
.deploySYMLite.zsh:189 |
| S2 | 🔵 Low | Installomator trust walk doesn’t resolve symlinked parent directories | SYM-Lite.zsh:734–762 |
| S3 | 🔵 Low | Invalid feature-toggle values fall through to true |
SYM-Lite.zsh:865–869 |
| S4 | ⚪ Info | Agent instructions shipped in the repository | .github/copilot-instructions.md:2 |
| S5 | ⚪ Info | Dialog icons fetched from third-party hosts at runtime | SYM-Lite.zsh:124 |
| S6 | ⚪ Info | A FIFO raced into the Command Line Tools trigger path can stall that step | SYM-Lite.zsh:2788–2799 |
S1 — Release helper writes notes to a fixed /tmp name · 🔵 Low
- Location:
extract_current_version_changelog()at.deploySYMLite.zsh:189(path),.deploySYMLite.zsh:213(write),.deploySYMLite.zsh:347(read bygh release create) - Origin: Code + Deployment — maintainer tooling (untracked, local only) builds
/tmp/release_notes_${version}.mdfrom a public, predictable version;/tmpis shared and sticky (Known Apple platform behaviors: sticky shared directories), and only a single-user release Mac keeps other accounts away from it. - Context: Mitigated by deployment context — no other accounts on the release Mac; 🟡 Medium outside it.
- Severity basis: Q2: another local account gains the ability to make the maintainer overwrite a maintainer-owned file through a planted symlink, or to swap the notes of a draft release by pre-creating the file; Q3: operator context removes other accounts → Low; alternate Medium (Q5: local access plus timing).
- Evidence:
local temp_notes="/tmp/release_notes_${version}.md" - Impact: On a shared Mac, the
awk … > "$temp_notes"redirect follows a planted symlink and truncates its target, and a file the other user owns stays theirs, so they can rewrite it beforeghreads it. The release is created as a draft, which limits the notes-tampering case. Traced from code, not reproduced. - Fix:
temp_notes="$(mktemp -t "release_notes_${version}")" || return 1(Engineer R3), which uses the per-user$TMPDIRand a random name with mode0600.
S2 — Installomator trust walk doesn’t resolve symlinked parent directories · 🔵 Low
- Location:
validateInstallomatorOwnership()atSYM-Lite.zsh:734–762; called atSYM-Lite.zsh:813(pre-flight) andSYM-Lite.zsh:2570(before each label); root executes the path atSYM-Lite.zsh:2585. - Origin: Code + Deployment — the walk rejects a relative or symlinked file and checks owner and mode at every textual level up to
/, butstat -fwithout-Lreports a symlinked directory’s ownroot 755, not its target’s parent; the default path contains no symlinks (operator-stated; host evidence agrees). - Context: Mitigated by deployment context — default App Auto-Patch path, no symlinks, root-owned at every level; 🟠 High outside it.
- Severity basis: Q2: a non-admin local user gets root code execution if a parent component is a root-owned symlink into a directory they can write; Q3: operator context closes the precondition → Low; alternate High (Q5: local privilege escalation).
- Evidence:
installomatorCheckPath="${installomatorCheckPath:h}" - Impact: If
…/AppAutoPatchwere a symlink to a user-writable directory, the real parent ofInstallomator/is never checked, so that user could rename a directory of their own into place between the re-check and the run. Isolated check: the walk reported755for the symlink and never visited the777target. The chain is from reading the code; it hasn’t been reproduced as root. - Fix: Reject any path whose
${path:A}differs from the path before walking, or walk${path:A}and execute that resolved path (Engineer R2).
S3 — Invalid feature-toggle values fall through to true · 🔵 Low
- Location:
normalizeJamfPolicyItems()atSYM-Lite.zsh:865–869;normalizeHomebrewItems()atSYM-Lite.zsh:1060–1064andSYM-Lite.zsh:1066–1069 - Origin: Code + Deployment —
enableJamfPolicyItems,enableHomebrewItems, and (new in 1.6.0)homebrewAutoInstallCommandLineToolsare admin gates; any value other thantrue/false, including a blank, logs a warning and enables the feature.homebrewAutoTrustItemsandhomebrewAutoRemoveQuarantinetreat bad values as off, so the two patterns disagree. - Context: Independent of deployment model.
- Severity basis: Q0: Rule 14 checklist — C1–C3 yes (
README.md:148,README.md:160,README.md:417), C4–C6 no, C7 and C8 fall through totrue→ 🔵 Low secure-default gap; alternate (typo in a policy the audience can run) stays Low, because the enabled items still come from the admin’s arrays. - Evidence:
warning "Invalid enableJamfPolicyItems value '${enableJamfPolicyItems}'; defaulting to true" - Impact: An admin who types
flaseornoto disable Jamf items, Homebrew items, or the rootsoftwareupdatestep gets the opposite; the only signal is a log line. Normalization rewrites the variable totrue, so every later check (for exampleSYM-Lite.zsh:993andSYM-Lite.zsh:2906) follows it. - Fix: Default invalid values to
falseand say so in the warning (Engineer R1).
S4 — Agent instructions shipped in the repository · ⚪ Info
- Location:
.github/copilot-instructions.md:2,AGENTS.md:22 - Origin: Code — contributor tooling that sets a terse reply style for coding agents and lists edit boundaries (
AGENTS.md:56–75). - Context: Independent of deployment model.
- Severity basis: Q2: no text addresses reviewers, verdicts, or scoring, and the
.codex/hooks.jsonsession hook from 1.4.0 has been removed → Info. - Evidence:
Default user-facing communication mode: \$caveman full“ - Impact: None on endpoints; ignored for this report (Rules 5 and 12).
- Fix: None needed.
S5 — Dialog icons fetched from third-party hosts at runtime · ⚪ Info
- Location:
SYM-Lite.zsh:124,SYM-Lite.zsh:127, and the icon fields atSYM-Lite.zsh:153–189 - Origin: Code — swiftDialog loads icons over HTTPS from Jamf icon hosts,
raw.githubusercontent.com, andswiftdialog.app. - Context: Independent of deployment model.
- Severity basis: Q2: the gain is a cosmetic feature’s availability plus run timing and IP address seen by the hosts → Info.
- Evidence:
mainDialogIcon="https://raw.githubusercontent.com/setup-your-mac/Setup-Your-Mac/refs/heads/main/images/SYM_icon.png" - Impact: A failed fetch blanks an icon.
- Fix: Optionally host icons on organization infrastructure or use
SF=symbols.
S6 — A FIFO raced into the Command Line Tools trigger path can stall that step · ⚪ Info
- Location:
installCommandLineTools()atSYM-Lite.zsh:2788–2799 - Origin: Code + Platform — the code removes any existing
/tmp/.com.apple.dt.CommandLineTools.installondemand.in-progress, creates it withNO_CLOBBER, and verifies a root-owned regular file; zsh’sNO_CLOBBERstill opens an existing non-regular file, and/tmplets any user create a name (Known Apple platform behaviors: sticky shared directories). - Context: Independent of deployment model.
- Severity basis: Q2: a local user who wins the race between
rmand the redirect with a FIFO (or a symlink to one) blocks the root run onopen()until they open a reader, after which the-fcheck skips the install; the gain is the availability of a non-security step → Info. - Evidence:
if ! ( setopt NO_CLOBBER; : > "${commandLineToolsTriggerFile}" ) 2>/dev/null; then - Impact: Isolated check (zsh 5.9):
NO_CLOBBERrefused a dangling symlink and a symlink to a regular file, but opened a symlink to a FIFO and blocked. Root never follows a symlink to write data. - Fix: Optional: create the file with
mktempin/tmpandmv -fit over the fixed name, so a rename replaces whatever is there without opening it.
Low / Info roll-up (credits): strict PATH without /usr/local/bin (SYM-Lite.zsh:44); swiftDialog from the root-owned bundle (SYM-Lite.zsh:203) and jamf from /usr/local/jamf/bin (SYM-Lite.zsh:97); per-run mktemp -d runtime directory set to 0755 before user hand-off files are chowned into it (SYM-Lite.zsh:1623–1628, SYM-Lite.zsh:1648); swiftDialog installed only after Gatekeeper reports accepted and Notarized Developer ID and the Team ID matches (SYM-Lite.zsh:1536, SYM-Lite.zsh:1543); Installomator ownership re-checked right before each label (SYM-Lite.zsh:2570); Parameter 4 allowlisted and fail-closed (SYM-Lite.zsh:1778–1781); Parameter 6 normalized to a positive integer before it reaches unquoted JSON (SYM-Lite.zsh:1783–1789); Homebrew user pinned for the run (SYM-Lite.zsh:889–893); log created 0640 with rotation capped at three files (SYM-Lite.zsh:1729, SYM-Lite.zsh:1743–1751); the 1.6.0 trigger file is removed, created exclusively, and verified before use, and the softwareupdate label goes in as one argument (SYM-Lite.zsh:2788–2799, SYM-Lite.zsh:2827); git detection uses -x tests and never runs the /usr/bin/git stub (SYM-Lite.zsh:974–979); quarantine removal is off by default, Gatekeeper-gated, and runs as the user (SYM-Lite.zsh:121, SYM-Lite.zsh:3035–3045); tap trust only for configured, fully qualified, non-official tokens (SYM-Lite.zsh:2980); CI actions pinned by SHA (.github/workflows/security-scan.yml:41); the maintainer’s .envrc reads its API key from 1Password at load time rather than storing it. Each security claim in the 1.4.0–1.6.0 CHANGELOG entries (CHANGELOG.md:6–43) was checked against the code and holds.
Privilege map
- Create and rotate
/var/log/org.churchofjesuschrist.log—SYM-Lite.zsh:1727,SYM-Lite.zsh:1742— root - Download and
installer -pkgswiftDialog —SYM-Lite.zsh:1525,SYM-Lite.zsh:1545— root - Run
Installomator.sh <label>—SYM-Lite.zsh:2585— root - Run
jamf policy -event <trigger>—SYM-Lite.zsh:2631— root - Create the
/tmptrigger file,softwareupdate --listand--install,xcode-select --switch—SYM-Lite.zsh:2789,SYM-Lite.zsh:2804,SYM-Lite.zsh:2827,SYM-Lite.zsh:2844— root - Create the runtime directory and
chownhand-off files to the console user —SYM-Lite.zsh:1623,SYM-Lite.zsh:1648,SYM-Lite.zsh:2145,SYM-Lite.zsh:2165— root - Selection, no-items, and restart dialogs —
SYM-Lite.zsh:2473,SYM-Lite.zsh:2396,SYM-Lite.zsh:3458— root launchingdialogcli - Gatekeeper assessment of an installed cask app —
SYM-Lite.zsh:3035— root, read-only - Inspect Mode and completion dialog —
SYM-Lite.zsh:3219,SYM-Lite.zsh:3416— console user vialaunchctl asuser+sudo -u brew update,brew trust,brew install, completion-directory and~/Applicationsmkdir,xattr -drs—SYM-Lite.zsh:2694,SYM-Lite.zsh:2987,SYM-Lite.zsh:3137,SYM-Lite.zsh:2740,SYM-Lite.zsh:3127,SYM-Lite.zsh:3045— console user, withHOMEBREW_NO_SUDO=1forbrew- Restart request to
loginwindow—SYM-Lite.zsh:3439— console user, after the user confirms
Secrets inventory
No secrets in shipped code. Parameters 4–6 are a mode, an item list, and a height. Maintainer-local only: .envrc:1 exports OPENAI_API_KEY from a 1Password reference ($(op…), gitignored and absent from history.
Network egress
https://api.github.com/repos/swiftDialog/swiftDialog/releases/latest— GET — TLS verified (curl default), unauthenticated —SYM-Lite.zsh:1499–1501- The swiftDialog release asset on
github.com— GET — TLS verified, Gatekeeper and Team ID checks —SYM-Lite.zsh:1525 - Apple’s software update catalog and CDN, through
softwareupdate(new in 1.6.0) —SYM-Lite.zsh:2804,SYM-Lite.zsh:2827 - Icon hosts (Jamf icon CDNs,
raw.githubusercontent.com,swiftdialog.app) — GET by swiftDialog —SYM-Lite.zsh:124,SYM-Lite.zsh:127 - Indirect, out of scope: Installomator vendor downloads, the Jamf Pro server, and Homebrew’s API and bottle hosts.
Persistence
No persistence mechanisms observed. Lasting system changes are by design: swiftDialog, selected apps, Apple’s Command Line Tools with the active developer directory set when none was (SYM-Lite.zsh:2844), and per-user Homebrew trust entries.
Manager View
Manager View: Production-grade; one maintainer (Dan K. Snelson)
Ownership: Dan K. Snelson, under the Setup-Your-Mac organization — script header (SYM-Lite.zsh:19) and 41 of 41 commits. Bus factor: 1.
Maturity: Production-grade — validates inputs, fails closed on bad modes, logs to a known path, exits non-zero on failure, is versioned and documented, and has CI scanning plus a parser test.
Change risk: Medium — root execution in one 3,534-line file with one narrow test; 1.6.0 adds a root softwareupdate path, though its effects are additive installs.
What it depends on
- The stated deployment model — default App Auto-Patch path, single-user release Mac, Self Service or developer-scoped policies. Re-run Monocle if it changes.
- Release state —
HEAD(f9f8f98, “1.6.0”) is four commits past the latest tag,v1.6.0b3; the release helper hasn’t tagged 1.6.0 yet. - swiftDialog 3.1.0.4994 or newer — auto-installed from GitHub’s “latest” release on any Mac without it, silent runs included.
- Installomator from App Auto-Patch — the reviewer’s copy (10.10beta) has every configured label, including
otter,mysqlworkbenchce, andoutsystemsservicestudio. - Apple’s software update service — new in 1.6.0; offline Macs, a blocked CDN, or MDM-deferred updates leave Homebrew without
git(logged as a warning). - Jamf Pro policy with custom trigger
appleXcode(SYM-Lite.zsh:175) — not visible in code; renaming it breaks that item. - Hardcoded organization log path
/var/log/org.churchofjesuschrist.log(SYM-Lite.zsh:58) — other organizations must edit it.
Fragility hotspots
- Homebrew validation paths follow the CPU, not the
brewin use. On Apple silicon with only a Rosetta Homebrew in/usr/local, or a custombrewPath, installed items aren’t recognized and finished ones end as “Needs review”; pre-flight now logs a warning but still uses the wrong paths —SYM-Lite.zsh:144–148(N1). - A mistyped on/off setting enables the feature. Found only by reading the log —
SYM-Lite.zsh:865–869(see S3). - The Command Line Tools step can add minutes and can hang.
softwareupdate --listruns with no timeout, so a stuck software update service would hold a Self Service run open —SYM-Lite.zsh:2804(not scored: inferred-unverified). - swiftDialog bootstrap needs GitHub. Rate limits or blocked GitHub end a run on a Mac without swiftDialog with a logged fatal error —
SYM-Lite.zsh:1499–1506(not scored: dependency-handled). - Documentation drift.
README.md:50promises a 30-second shutdown on interrupt (code waits 5 seconds,SYM-Lite.zsh:1666),README.md:370names a “Close” button that now reads “Continue” (SYM-Lite.zsh:2107), andREADME.md:433dates 1.6.0 to 08-Oct-2026 while the header says 10-Oct-2026 (not scored: docs).
Change & rollback
- Testing:
tests/installomator-label-parser.zshcovers the Installomator label parser and the untrusted-file branch; CI runs Semgrep, Gitleaks,zsh -n, and the test. Nothing covers the Command Line Tools bootstrap, the toggles, or the Homebrew paths. - Rollback: Partial. Apps can be removed by hand; swiftDialog, the Command Line Tools, the developer-directory selection, and Homebrew trust entries stay. Restarts need the user’s confirmation.
v1.5.1is the last stable tag. - Deploy path: Jamf Pro policy with Parameters 4–6 (README), or manual
sudofor interactive runs; releases through the local.deploySYMLite.zsh.
Action items
| # | Action | Owner role | Effort | Priority |
|---|---|---|---|---|
| 1 | Make invalid toggle values default to false (S3) |
Mac engineer | S | P2 |
| 2 | Derive Homebrew validation paths from the detected brew (N1) |
Mac engineer | S | P3 |
| 3 | Reject or resolve symlinked parents in the Installomator check (S2, mitigated by deployment context) | Mac engineer | S | P3 |
| 4 | Use mktemp for release notes in .deploySYMLite.zsh (S1, mitigated by deployment context) |
Maintainer | S | P3 |
| 5 | Bound the softwareupdate --list scan with a watchdog |
Mac engineer | M | P3 |
| 6 | Fix README drift at README.md:50, README.md:370, and README.md:433 |
Maintainer | S | P3 |
| 7 | Pre-stage swiftDialog with its own pkg policy ahead of mass enrollment | Jamf admin | S | P3 |
Engineer View
Engineer View: 1.6.0 CLT bootstrap is careful; make toggles fail closed
Shape: zsh (#!/bin/zsh --no-rcs), 3,534 lines, 85 functions, single entry point; run as a Jamf policy script or with sudo.
Inputs → Outputs: Parameter 4 (interactive | silent), Parameter 5 (CSV of item IDs: silent run list or interactive allowlist), Parameter 6 (dialog height), in-file item arrays and toggles → installed apps and packages (casks in ~/Applications for standard users), Command Line Tools, /var/log/org.churchofjesuschrist.log, swiftDialog UI, exit 0 / 1 (any failed item, or swiftDialog Team ID failure) / 10 (fatal) / 130 (interrupted).
Control flow
- Set
PATH, read Parameters 4–6, derivehomebrewPrefixfromhw.optional.arm64, and build the item arrays —SYM-Lite.zsh:44,SYM-Lite.zsh:79–82,SYM-Lite.zsh:144–192 - Register the
EXITcleanup trap, which removes the trigger file only if this run created it —SYM-Lite.zsh:308,SYM-Lite.zsh:281–284 - Create or rotate the log (
0640, three.oldfiles kept) —SYM-Lite.zsh:1726–1755 - Require root, fail closed on any mode but
interactive/silent, normalize Parameter 6 —SYM-Lite.zsh:1772–1789 dialogCheck→dialogInstallwhen missing or old: GitHub API,spctlaccepted + notarized, Team ID,installer—SYM-Lite.zsh:1797,SYM-Lite.zsh:1497–1570- Jamf toggle; interactive only: wait up to 120 s for a real console user —
SYM-Lite.zsh:1805,SYM-Lite.zsh:1819–1845 normalizeHomebrewItems: detectbrew, warn on prefix mismatch, loggitavailability, pin the Homebrew user and admin status —SYM-Lite.zsh:1853,SYM-Lite.zsh:1085–1121normalizeInstallomatorLabels: file checks, ownership walk, parsecase $label inarms, drop missing labels —SYM-Lite.zsh:1867,SYM-Lite.zsh:788–853- Empty
jamfPolicyItemsif the binary is missing; warn on duplicate IDs —SYM-Lite.zsh:1875–1891 - Selection: silent →
parseOperationsCSV; interactive → optional Parameter 5 allowlist, checkbox dialog until something is chosen, Cancel exits 0 —SYM-Lite.zsh:2415–2506 - Interactive: build Inspect JSON (adds a Command Line Tools row when
isCommandLineToolsBootstrapExpected), validate withplutil, hand off to the user, launch Inspect Mode as the user —SYM-Lite.zsh:1941–1945,SYM-Lite.zsh:3205–3228 - Per item, in selection order: Installomator (skip if present → ownership re-check → Command Line Tools before
homebrew→ run → Command Line Tools after), Jamf (policy -event), or Homebrew (pinned user → Command Line Tools → optionalbrew update→ completion directories → trust →brew install→ optional quarantine removal) —SYM-Lite.zsh:3231–3250 installCommandLineTools: once per run if nogit: remove, exclusively create, and verify the trigger file; scan; pick the newest non-beta label withsort -V; install; select the developer directory if none —SYM-Lite.zsh:2764–2857- Wait up to 30 s for Inspect Mode, then send
quit:and kill if needed —SYM-Lite.zsh:3252–3270 - Interactive: completion dialog as the user, then the restart prompt unless everything was already installed;
quitScript 1if any item failed —SYM-Lite.zsh:3510–3534
Footguns
- Toggles fail open —
SYM-Lite.zsh:865–869,SYM-Lite.zsh:1060–1069— a blank or misspelledenableJamfPolicyItems,enableHomebrewItems, orhomebrewAutoInstallCommandLineToolsis rewritten totrue, whiletrustHomebrewItemIfNeeded()(SYM-Lite.zsh:2976) andremoveHomebrewQuarantineIfNeeded()(SYM-Lite.zsh:3017) treat any non-truevalue as off (see S3). - Trust walk follows the text, not the inode —
SYM-Lite.zsh:749–759—stat -fwithout-Lon a symlinked directory reports the link itself, and${path:h}keeps walking the textual path, so the symlink target’s real parent is never checked (see S2). - Validation prefix fixed before
brewis found —SYM-Lite.zsh:144–148builds every${homebrewPrefix}path from the CPU, butdetectHomebrewBinary()(SYM-Lite.zsh:922–941) can return/usr/local/bin/breworbrewPathon Apple silicon; the warning atSYM-Lite.zsh:1101doesn’t change the paths (N1). NO_CLOBBERopens non-regular files —SYM-Lite.zsh:2789— a FIFO placed after thermblocks the root redirect until a reader appears (see S6).- Mixed dialog contexts —
SYM-Lite.zsh:2396,SYM-Lite.zsh:2473, andSYM-Lite.zsh:3458rundialogclias root, whileSYM-Lite.zsh:3219andSYM-Lite.zsh:3416use the user context; this likely works becausedialogclipresents in the console session (not verified from swiftDialog source) (not scored: inferred-unverified).
Edge cases not handled
- Software update service stuck →
softwareupdate --listnever returns, the run and Inspect Mode stay open, and the Self Service policy never finishes —SYM-Lite.zsh:2804(not scored: inferred-unverified). - GitHub API rate limit or blocked GitHub on a Mac without swiftDialog →
dialogURLempty → fatal, silent mode too —SYM-Lite.zsh:1504–1506(not scored: dependency-handled). - Firefox installed, Firefox ESR selected → disabled as “Already installed” (documented at
README.md:80) —SYM-Lite.zsh:158(not scored: config). - Installomator without
otter→ item hidden with an ERROR line each run (documented atREADME.md:81) —SYM-Lite.zsh:164(not scored: config). - An ID in two arrays → warned, first array wins —
SYM-Lite.zsh:1263–1283(not scored: malformed-config). - A display name containing
|→ the four-field split shifts every later field —SYM-Lite.zsh:412(not scored: malformed-config).
Refactor suggestions
R1 — Fail closed on invalid toggle values · Quick win
SYM-Lite.zsh:865–869
# before
if [[ "${jamfPolicyItemsSetting}" != "true" && "${jamfPolicyItemsSetting}" != "false" ]]; then
warning "Invalid enableJamfPolicyItems value '${enableJamfPolicyItems}'; defaulting to true"
enableJamfPolicyItems="true"
jamfPolicyItemsSetting="true"
fi
# after
if [[ "${jamfPolicyItemsSetting}" != "true" && "${jamfPolicyItemsSetting}" != "false" ]]; then
warning "Invalid enableJamfPolicyItems value '${enableJamfPolicyItems}'; defaulting to false"
enableJamfPolicyItems="false"
jamfPolicyItemsSetting="false"
fi
Closes S3; apply the same change to SYM-Lite.zsh:1060–1064 and SYM-Lite.zsh:1066–1069, which also matches how homebrewAutoTrustItems and homebrewAutoRemoveQuarantine already behave. Checked in isolation: flase now yields false.
R2 — Refuse symlinked parents before walking · Quick win
SYM-Lite.zsh:744–747
# before
if [[ -L "${installomatorCheckPath}" ]]; then
installomatorOwner="symlink"
return 1
fi
# after
if [[ -L "${installomatorCheckPath}" ]]; then
installomatorOwner="symlink"
return 1
fi
if [[ "${installomatorCheckPath:A}" != "${installomatorCheckPath}" ]]; then
installomatorOwner="symlinked parent"
return 1
fi
Closes S2. Checked in isolation: passes the default App Auto-Patch path and fails a path through a symlinked directory; paths under /var or /tmp must be written as /private/….
R3 — Use a private temp file for release notes · Quick win
.deploySYMLite.zsh:189
# before
local temp_notes="/tmp/release_notes_${version}.md"
# after
local temp_notes
temp_notes="$(mktemp -t "release_notes_${version}")" || return 1
Closes S1. Declaring and assigning separately keeps mktemp’s exit status; checked in isolation, it creates a 0600 file under the per-user $TMPDIR.
R4 — Take the validation prefix from the brew that will run · Quick win
SYM-Lite.zsh:144–148
# before
if [[ "$( /usr/sbin/sysctl -in hw.optional.arm64 )" == "1" ]]; then
homebrewPrefix="/opt/homebrew"
else
homebrewPrefix="/usr/local"
fi
# after
if [[ -n "${brewPath}" && -x "${brewPath}" ]]; then
homebrewPrefix="${brewPath:h:h}"
elif [[ -x "/opt/homebrew/bin/brew" ]]; then
homebrewPrefix="/opt/homebrew"
elif [[ -x "/usr/local/bin/brew" ]]; then
homebrewPrefix="/usr/local"
elif [[ "$( /usr/sbin/sysctl -in hw.optional.arm64 )" == "1" ]]; then
homebrewPrefix="/opt/homebrew"
else
homebrewPrefix="/usr/local"
fi
Closes N1. It mirrors detectHomebrewBinary()‘s order (brewPath is set at SYM-Lite.zsh:100), skips :A so Intel’s /usr/local/bin/brew symlink still maps to /usr/local, and falls back to the CPU when Homebrew isn’t installed yet. Checked with zsh -n and on Apple silicon with and without brewPath.
Quick wins vs deeper work
- Quick wins (< 1 hr): R1, R2, R3, R4
- Deeper work: a watchdog for
softwareupdate --list(macOS has notimeout(1); background the scan and kill it after a limit), and tests for the toggle normalization,resolveHomebrewGitPath(), and the Command Line Tools label selection.
Cross-cutting notes
Cross-cutting notes: the new 1.6.0 toggle inherited the fail-open pattern
- The newest gate copied the oldest flaw.
homebrewAutoInstallCommandLineToolscontrols the only new rootsoftwareupdatepath in 1.6.0, and it reuses the fail-open normalization of the long-standing Jamf and Homebrew toggles (S3). A typo meant to keep a multi-minute Apple install off Self Service runs turns it on. - S2 matters most where nobody watches. Silent mode runs Installomator as root unattended, so a symlinked-parent misconfiguration would be exploited with no one present. The stated default path closes it today; R2 makes that independent of the path.
- The release helper protects the supply chain for everyone. S1 lives on the maintainer’s Mac, but its output is the public release notes; the single-user release Mac closes it, and R3 removes the dependence.
- Every claim in the 1.4.0–1.6.0 CHANGELOG held up. The previous review’s six fixes are all present in code, which is why the score rose despite a larger scope.
Scope
Scope: f9f8f98 (development) — 17 files, full coverage
| Field | Value |
|---|---|
| Date | 2026-10-10 18:55 EDT |
| Target | /Users/danksnelson/Documents/GitHub/SYM-Lite (local directory) |
| Ref | development @ f9f8f987de899eebcf28f276d48bd31818780f15 (clean working tree; scriptVersion 1.6.0, untagged) |
| Generated by | Claude Opus 5.5 (claude-opus-5-5) |
| Language(s) | zsh 5.9 (#!/bin/zsh --no-rcs), GitHub Actions YAML, Markdown |
| Files analyzed | 17 — SYM-Lite.zsh, tests/installomator-label-parser.zsh, .github/workflows/security-scan.yml, README.md, CHANGELOG.md, SECURITY.md, AGENTS.md, .github/copilot-instructions.md, .gitignore, and 8 more (see caveats) |
| Automated scan | semgrep 1.177.0 — p/r2c-security-audit, p/secrets, p/ci — 0 results (0 confirmed), 6 parse errors, 2 files skipped (1 under tests/ by semgrep’s default ignore list, 1 parser failure), 3 gitignored files not scanned |
| Scope caveats | See below |
Scope caveats:
- Input type. Local git directory on
development, as requested;git statusclean. 41 commits, all by Dan K. Snelson. - Files analyzed. Tracked and read in full:
SYM-Lite.zsh(3,534 lines),tests/installomator-label-parser.zsh,.github/workflows/security-scan.yml,README.md,CHANGELOG.md,SECURITY.md,AGENTS.md,.github/copilot-instructions.md,.github/FUNDING.yml,.github/ISSUE_TEMPLATE/config.yml,.gitignore. Issue templates (bug_report.yml,documentation.yml,feature_request.yml): field labels, descriptions, and free text read; option lists skimmed. Untracked, local only:.deploySYMLite.zsh(read in full),VERSION.txt,.envrc(value redacted). Skipped: 11 PNGs underimages/andLICENSE. - Deployment context. Operator-stated through three structured questions in this session; quoted verbatim in the Monocle Score section. No saved context file existed.
- Automated scan limits. Semgrep has no zsh parser, so
SYM-Lite.zshgot secrets and generic rules only. All 6 parse errors come from embedded bash in.github/workflows/security-scan.ymlrun:blocks. - Host evidence (2026-10-10, macOS 26.7.1).
- Default Installomator path:
/Libraryroot:wheel 755,Application SupportandAppAutoPatchroot:admin 755,InstallomatorandInstallomator.shroot:wheel 755; no symlinked component. InstallomatorVERSION="10.10beta"hascodex,mysqlworkbenchce,otter, andoutsystemsservicestudioarms. - Log
0640 root:admin;/tmp→private/tmp,1777.
- Default Installomator path:
- Isolated checks (Rule 4). zsh 5.9
NO_CLOBBER: refused a dangling symlink and a symlink to a regular file, opened and blocked on a symlink to a FIFO. Astat -fwalk through a symlinked directory reported the link’s755and never visited its777target./usr/bin/sort -Vorders26.10after26.9. R1–R4 run against scratch files. Side effects: scratch files only; no target code executed or sourced, andsoftwareupdatewas not run. - Inferred items. That a stuck software update service hangs
softwareupdate --list(X12); Apple’s* Label: Command Line Tools…line format (from the adapted Rich Trouton logic); thatdialogclipresents in the console session when run as root (X10). - Prior reports. Four earlier reports: three repository runs at
6dda995and one single-file run at0ab93eawith uncommitted 1.4.0 edits. The ref differs, so they were used as checklists; every prior item has a disposition in the Score change line.
Attestation:
monocle_attestation: v2
skill_repo: https://github.com/dan-snelson/Monocle
skill_commit: 782ddc7e720ebdf4ebf9d4f175806cfb5325f0ae
skill_ref: development
skill_tree: 5566662a4a4f6fab1eac81ff2e9521a3d5cbb692
skill_sha256: 3195fc8db9a228886513c94d235ab0c4ef7a374b8ace5e59f9de6d39af4dab97
skill_dirty: false
target: /Users/danksnelson/Documents/GitHub/SYM-Lite (local directory)
target_ref: development @ f9f8f987de899eebcf28f276d48bd31818780f15 (clean working tree; scriptVersion 1.6.0, untagged)
score_raw: 89
score_final: 89
score_alt: 67
band: Good
deployment_context: operator
generated_by: Claude Opus 5.5 (claude-opus-5-5)
timestamp: 2026-10-10 18:55 EDT
Self-improvement
Monocle includes two, optional, maintenance passes, helping the skill become sharper after each run (and hopefully without getting bloated):
post-chat-refine
Every report generation ends with a one-line offer to run post-chat-refine. Once manually approved, Monocle folds that run’s durable, widely applicable lessons back into SKILL.md and its references/.
Before anything is written, Monocle sanitizes target names, organizations, paths, and other identifying details so each lesson reads as general guidance.
Note: Edits land in-place; review the diff before committing.
binge-and-purge
Each refine pass makes SKILL.md a little larger (the “binge”). This pass is the counterweight (the “purge”): it moves conditional content into references/ without changing meaning, so SKILL.md still fits in a single 25,000-token Read.
Run it on-demand; Monocle offers it when headroom drops below about 3,000 tokens.
Related Posts
Support
Best-effort support is available on the Mac Admins Slack (free, registration required) — sans a dedicated channel for this script — or you can open an issue (after reviewing the README.md).