Moving Automation & Scripting from Manual to Managed with Bash

#Current Method

Many macOS administrators rely on ad-hoc Bash

The KBY Lexicon

Bash

Bash is the POSIX-compatible shell and scripting language used to run commands, automate tasks and control Unix-like systems.

Read Full Context

scripts executed manually via Terminal or SSH. These scripts often lack consistent error handling, logging

The KBY Lexicon

Logging

Logging is the practice of recording timestamped system events to durable storage for later diagnosis, correlation and audit.

Read Full Context

, or version control. Operators copy-paste commands from documentation or previous incidents, leading to variability in outcomes. Without a structured framework, debugging failures requires recreating the environment, which is time-consuming and risky in production. This approach assumes perfect operator memory and ignores the complexity of modern macOS security features such as Full Disk Access (FDA) and Privacy Preferences Policy Control (PPPC).

The primary friction points include:

• Inconsistent execution contexts due to missing environment variables.
• Lack of audit trails for who ran what script and when.
• No automated rollback mechanism if a script partially fails.
• Difficulty in scaling scripts across multiple devices without an MDM integration strategy.

#Improved Workflow

The improved workflow treats Bash scripts as managed artifacts. Each script is version-controlled, linted, and tested in an isolated environment before deployment. Execution is triggered via a controlled mechanism, such as an MDM command or a local launch daemon, rather than interactive shell sessions. The workflow emphasizes observability: every script must log its start, end, and any errors to a centralised location or local syslog. Success is defined by observable state changes, not just exit code 0.

This approach shifts the operational model from “run and hope” to “deploy, verify, and recover”. It aligns with Apple Platform Deployment guidelines which advocate for predictable, automated device management. By encapsulating logic in reusable functions and enforcing strict variable scoping, we reduce the risk of side effects.

#Implementation

Implementing managed Bash automation requires three layers: script structure, execution context, and validation. Below is a bounded example of a script that checks for a specific configuration file and creates it if missing, with full logging and rollback capability.

#

Script Structure

Use set -euo pipefail to ensure the script exits on error, undefined variables, or pipeline failures. Define a cleanup function to handle temporary files or partial states.

Terminal

1#!/bin/bash
2set -euo pipefail
3
4# Configuration
5LOG_FILE="/var/log/my_automation.log"
6CONFIG_DIR="/Library/Preferences/MyApp"
7CONFIG_FILE="${CONFIG_DIR}/config.plist"
8
9# Logging function
10log() {
11    echo "$(date '+%Y-%m-%d %H:%M:%S') - $1" | tee -a "$LOG_FILE"
12}
13
14# Cleanup function
15cleanup() {
16    if [[ -f "${CONFIG_FILE}.bak" ]]; then
17        log "Restoring backup if needed..."
18        # Rollback logic here if necessary
19    fi
20}
21trap cleanup EXIT
22
23# Main logic
24main() {
25    log "Starting configuration check"
26    
27    if [[ ! -d "$CONFIG_DIR" ]]; then
28        log "Creating directory: $CONFIG_DIR"
29        mkdir -p "$CONFIG_DIR"
30    fi
31
32    if [[ ! -f "$CONFIG_FILE" ]]; then
33        log "Config file missing. Creating default."
34        # Create a simple plist or touch file
35        touch "$CONFIG_FILE"
36        log "Default config created."
37    else
38        log "Config file exists. No action taken."
39    fi
40    
41    log "Script completed successfully."
42}
43
44main "$@"

#

Execution Context

Scripts should run with the minimum necessary privileges. Avoid running as root unless absolutely required by the task. Use sudo sparingly and only for specific commands. When deploying via MDM, ensure the script is signed and notarized if required by your security policy. For local testing, use a non-production user account with limited permissions to verify behaviour.

#Guardrails

Safety boundaries are critical in managed automation. The following guardrails prevent unintended consequences:

• Least Privilege: Scripts run as the current user or a dedicated service account, not root, unless modifying system-level configurations.
• Idempotency: Scripts must be safe to run multiple times. Checking for existing state before making changes ensures this.
• Timeouts: Long-running operations should have timeouts to prevent hanging processes. Use timeout command where available.
• Input Validation: Never trust external input. Validate all variables and arguments before use.

#Validation

Validation confirms the script achieved its intended outcome. Do not rely solely on exit codes. Check the actual state of the system.

1. Pre-check: Verify the initial state (e.g., config file does not exist).
2. Execution: Run the script and capture output.
3. Post-check: Verify the final state (e.g., config file exists and has correct permissions).
4. Log Review: Check /var/log/my_automation.log for expected messages and no errors.

#Common Mistakes

Avoid these pitfalls when transitioning to managed Bash automation:

• Ignoring Exit Codes: Failing to check return values of commands leads to silent failures.
• Hardcoding Paths: Use variables for paths to make scripts portable and easier to maintain.
• No Error Handling: Without set -e, scripts continue after errors, potentially corrupting state.
• Over-privileging: Running everything as root increases the blast radius of any bug.

#Recovery

If a script fails, recovery depends on the rollback strategy defined in the script. For the example above, if the config file creation fails, the cleanup trap can restore a backup

The KBY Lexicon

Backup

A causally disconnected, point-in-time copy of system state, tagged with a consistency marker, that lets you recover from logical corruption or data loss independent of the source system's health.

Read Full Context

if one was made. In more complex scenarios, maintain a snapshot of the pre-change state. If the script modifies a plist, back it up before editing. If the script fails, restore the backup manually or via a companion rollback script.

Explicit rollback steps:

1. Identify the failed operation from logs.
2. Restore any backed-up files to their original location.
3. Verify the system returns to the pre-execution state.
4. Document the failure for future prevention.

#Measurable Outcome

Success is measured by the reduction in manual intervention and incident recurrence. Track the following metrics:

• Script Success Rate: Percentage of executions completing without error.
• Mean Time to Recovery (MTTR): Time taken to restore service after a script failure.
• Audit Compliance: Number of devices with verified configuration vs. total devices.

Review these metrics monthly to identify trends and improve script reliability.

#Checklist

Use this checklist before deploying any Bash automation to production:

• [ ] Script is version-controlled and tagged.
• [ ] Script uses set -euo pipefail.
• [ ] All variables are quoted and validated.
• [ ] Logging is implemented and tested.
• [ ] Rollback mechanism is defined and tested.
• [ ] Script runs with least privilege.
• [ ] Pre- and post-validation steps are documented.
• [ ] Script has been tested in a non-production environment.

#Prerequisites and Permissions

Before any managed script leaves a development branch, confirm the target fleet holds the correct entitlements. Devices enrolled via Automated Device Enrollment must have a PPPC profile granting Full Disk Access to the script’s parent process (typically /bin/bash or a wrapping launch daemon binary), otherwise file operations against protected paths such as ~/Library/Mail or /Library/Application Support will silently no-op rather than error. Confirm the signing identity used for any accompanying installer package matches an entry in your organisation’s Developer ID certificate, and check expiry with security find-identity -v -p codesigning on the build machine. For scripts triggered by MDM custom commands, verify the device record shows a recent check-in timestamp; a stale check-in beyond the push interval configured in your MDM server usually indicates an APNs token problem rather than a script fault.

#

Service Account and Sudoers Scoping

Where elevated rights are unavoidable, create a narrowly scoped sudoers entry rather than granting blanket root access. For example, add a drop-in file under /etc/sudoers.d/ containing a line such as svc_automation ALL=(root) NOPASSWD: /usr/local/bin/managed_config.sh, then validate syntax with visudo -cf /etc/sudoers.d/managed_automation before deployment. This confines privilege escalation to a single named script and prevents the service account from being repurposed for unrelated root actions.

#Execution Scheduling and Launch Daemon Detail

For recurring checks, prefer a signed launch daemon plist placed in /Library/LaunchDaemons with RunAtLoad and a bounded StartInterval rather than cron, since cron’s environment differs from an interactive shell and frequently lacks expected PATH entries. Load the daemon with launchctl bootstrap system /Library/LaunchDaemons/com.kby.automation.plist and confirm registration using launchctl print system/com.kby.automation, checking the reported state is running and the last exit status is zero. If the daemon shows a non-zero last exit code, inspect StandardErrorPath output before re-triggering, as repeated crash-relaunch cycles will be throttled by launchd after several failures within a short window.

#Expected Evidence of Correct Operation

A successful managed run should leave three forms of evidence: a log entry set matching the pre-check, execution, and post-check phases described earlier; a file or plist with an updated modification timestamp consistent with the run window; and, where applicable, an MDM inventory attribute reflecting the new state on the next inventory collection cycle. Cross-reference the log timestamp against stat -f

#Prerequisites and Permissions

Before any managed script leaves a development branch, confirm the target fleet holds the correct entitlements. Devices enrolled via Automated Device Enrollment must have a PPPC profile granting Full Disk Access to the script's parent process (typically /bin/bash or a wrapping launch daemon binary), otherwise file operations against protected paths such as ~/Library/Mail or /Library/Application Support will silently no-op rather than error. Confirm the signing identity used for any accompanying installer package matches an entry in your organisation's Developer ID certificate, and check expiry with security find-identity -v -p codesigning on the build machine. For scripts triggered by MDM custom commands, verify the device record shows a recent check-in timestamp; a stale check-in beyond the push interval configured in your MDM server usually indicates an APNs token problem rather than a script fault.

#

Service Account and Sudoers Scoping

Where elevated rights are unavoidable, create a narrowly scoped sudoers entry rather than granting blanket root access. For example, add a drop-in file under /etc/sudoers.d/ containing a line such as svc_automation ALL=(root) NOPASSWD: /usr/local/bin/managed_config.sh, then validate syntax with visudo -cf /etc/sudoers.d/managed_automation before deployment. This confines privilege escalation to a single named script and prevents the service account from being repurposed for unrelated root actions.

#Execution Scheduling and Launch Daemon Detail

For recurring checks, prefer a signed launch daemon plist placed in /Library/LaunchDaemons with RunAtLoad and a bounded StartInterval rather than cron, since cron's environment differs from an interactive shell and frequently lacks expected PATH entries. Load the daemon with launchctl bootstrap system /Library/LaunchDaemons/com.kby.automation.plist and confirm registration using launchctl print system/com.kby.automation, checking the reported state is running and the last exit status is zero. If the daemon shows a non-zero last exit code, inspect StandardErrorPath output before re-triggering, as repeated crash-relaunch cycles will be throttled by launchd after several failures within a short window.

#Expected Evidence of Correct Operation

A successful managed run should leave three forms of evidence: a log entry set matching the pre-check, execution, and post-check phases described earlier; a file or plist with an updated modification timestamp consistent with the run window; and, where applicable, an MDM inventory attribute reflecting the new state on the next inventory collection cycle. Cross-reference the log timestamp against stat -f "%Sm" /Library/Preferences/MyApp/config.plist to confirm the file was actually touched during the expected window rather than left over from an earlier manual run.

#Monitoring and Alerting Thresholds

Feed the centralised log location into a lightweight tail-based monitor, or forward entries to your existing log aggregation pipeline using a syslog relay. Set an alerting threshold so that any device reporting more than two consecutive script failures within a 24-hour window is flagged for manual review, rather than alerting on every single non-zero exit, which produces noise during routine transient network issues. Track daemon restart counts separately; more than three restarts in an hour against a single bundle identifier typically signals a logic fault rather than an environmental one and should be escalated immediately rather than left for the monthly review cycle.

#Realistic Failure Symptoms

Common failure patterns include a script that exits zero but leaves the configuration file unchanged, usually caused by a permissions denial that Bash swallows silently when FDA has not been granted. Another pattern is a launch daemon that appears loaded in launchctl print output but never fires, often traced to an incorrect StartInterval value or a missing ProgramArguments key. Watch also for scripts that behave correctly under an interactive test account but fail under the service account context, which points to a PATH or environment variable discrepancy rather than a scripting logic error.

#Change Control and Escalation

Record every script revision against a change ticket referencing the git commit hash, the tested macOS versions, and the rollback plan agreed before deployment. Require a second reviewer's sign-off for any script touching system-level plists or launch daemons. If a deployed script causes unexpected state changes across more than five per cent of the targeted fleet, halt further rollout immediately, notify the change owner, and revert affected devices using the retained backup files referenced in the recovery section rather than attempting an in-place fix under time pressure.