Reducing Automation & Scripting Rework with Bash on macOS

#Current Method

Many macOS

The primary friction points include:

• Ambiguous success criteria: Scripts exit with code 0 even when partial failures occur.
• Missing pre-flight checks: Assumptions about file existence, permissions, or network connectivity are not verified before execution.
• No rollback path: State-changing operations, such as file deletion or permission modification, cannot be easily reversed if the outcome is unexpected.

#Improved Workflow

A robust Bash automation workflow on macOS must incorporate three core principles: explicit validation, bounded scope, and reversible actions. By treating every script as a transactional operation, administrators can ensure that either the full intended change occurs, or the system remains in its original state.

The improved workflow follows this sequence:

1. Pre-flight Validation: Verify environment prerequisites, such as macOS version, user privileges, and target resource availability.
2. State Snapshot: Record the current state of any resources that will be modified, enabling precise rollback if needed.
3. Bounded Execution: Perform the intended operation within strict limits, using stop conditions to halt if unexpected behaviour is detected.
4. Post-execution Verification: Confirm that the outcome matches the expected evidence, such as file presence, permission bits, or log entries.
5. Rollback Readiness: If verification fails, execute the predefined rollback procedure to restore the initial state.

#Implementation

The following example demonstrates a bounded Bash script that archives old log files in /var/log while preserving the ability to restore them. This script avoids destructive operations by moving files to a staging directory before permanent deletion.

1#!/bin/bash
2set -euo pipefail
3
4# Configuration
5LOG_DIR="/var/log"
6STAGING_DIR="/tmp/log_staging_$$"
7MAX_AGE_DAYS=30
8TIMESTAMP=$(date +%Y%m%d_%H%M%S)
9
10# Pre-flight validation
11if [[ $EUID -ne 0 ]]; then
12  echo "Error: Root privileges required." >&2
13  exit 1
14fi
15
16if [[ ! -d "$LOG_DIR" ]]; then
17  echo "Error: Log directory $LOG_DIR does not exist." >&2
18  exit 1
19fi
20
21# Create staging directory
22mkdir -p "$STAGING_DIR"
23
24# State snapshot: list files to be processed
25find "$LOG_DIR" -name "*.log" -mtime +"$MAX_AGE_DAYS" -print0 > /tmp/file_list_$$
26
27# Bounded execution: move files to staging
28while IFS= read -r -d '' file; do
29  mv "$file" "$STAGING_DIR/" || {
30    echo "Error: Failed to move $file. Aborting." >&2
31    # Rollback: move already moved files back
32    find "$STAGING_DIR" -type f -exec mv {} "$LOG_DIR/" ;
33    rm -rf "$STAGING_DIR"
34    exit 1
35  }
36done < /tmp/file_list_$$
37
38# Post-execution verification
39MOVED_COUNT=$(find "$STAGING_DIR" -type f | wc -l)
40echo "Successfully staged $MOVED_COUNT log files."
41
42# Cleanup staging directory after confirmation
43rm -rf "$STAGING_DIR"
44rm -f /tmp/file_list_$$

This script uses set -euo pipefail to ensure immediate exit on error, undefined variables, or pipeline failures. It creates a unique staging directory using the process ID to avoid collisions. Files are moved rather than deleted, allowing for easy restoration if the verification step reveals issues.

#Guardrails

To prevent unintended consequences, apply these guardrails to all Bash automation on macOS:

• Least Privilege: Run scripts with the minimum necessary permissions. Avoid running as root unless absolutely required, and use sudo sparingly.
• Scope Limitation: Define explicit boundaries for file operations, such as specific directories or filename patterns. Never use recursive wildcards like rm -rf / or chmod -R 777 /.
• Dry-Run Mode: Implement a --dry-run flag that prints intended actions without executing them, allowing administrators to verify logic before applying changes.
• Logging: Log all actions to a dedicated audit log, including timestamps, user context, and outcomes. This aids in diagnosis and compliance.

#Validation

After executing the script, verify the outcome using these steps:

1. Check that the staging directory is empty or removed, indicating successful cleanup.
2. Confirm that old log files are no longer present in /var/log.
3. Review the audit log for any error messages or warnings.
4. Ensure that active log files (younger than MAX_AGE_DAYS) remain untouched.

Expected evidence includes a clean /var/log directory for old files, an empty or non-existent staging directory, and accurate audit logs.

#Common Mistakes

Avoid these frequent errors when writing Bash automation for macOS:

• Ignoring Exit Codes: Failing to check the return value of commands like mv, cp, or rm can lead to silent failures.
• Hardcoding Paths: Using absolute paths without verifying their existence can cause scripts to fail on different macOS versions or configurations.
• Overlooking Permissions: Assuming the script has write access to target directories without checking can result in permission denied errors.
• Neglecting Race Conditions: Not accounting for concurrent processes accessing the same files can lead to data corruption or inconsistent states.

#Recovery

If the script fails during execution, follow these recovery steps:

1. Identify the Failure Point: Check the audit log and terminal output for error messages.
2. Restore from Staging: If files were moved to the staging directory but not yet deleted, move them back to their original locations.
3. Verify System State: Ensure that no partial changes remain, such as empty directories or modified permissions.
4. Re-run with Dry-Run: Execute the script in dry-run mode to identify the root cause before attempting again.

Rollback instructions are embedded in the script itself, ensuring that partial failures do not leave the system in an inconsistent state.

#Measurable Outcome

Success is defined by the following observable criteria:

• Zero manual interventions required after script execution.
• All old log files are archived or removed according to policy.
• No active log files are affected.
• Audit logs confirm successful execution with no errors.

Track these metrics

#Checklist

Before deploying any Bash automation on macOS, complete this checklist:

• [ ] Pre-flight validation checks are implemented.
• [ ] State snapshot mechanism is in place for rollback.
• [ ] Bounded execution with stop conditions is defined.
• [ ] Post-execution verification steps are documented.
• [ ] Rollback procedure is tested and verified.
• [ ] Audit logging is enabled and configured.
• [ ] Dry-run mode is available for testing.
• [ ] Least privilege principles are applied.

#Prerequisites and Permissions

Before any staged rollout of the archiving script, confirm the operator account holds the correct entitlements. On managed fleets, Full Disk Access must be granted to /bin/bash or the wrapping launch agent via the MDM's Privacy Preferences Policy Control payload; without this grant, TCC will silently block reads on certain log paths beneath /var/log even when the effective user is root. Confirm the executing account's group membership includes wheel where sudo escalation is required, and check /etc/sudoers.d/ for any NOPASSWD directives that might allow unattended execution under a scheduled job. Where the script is invoked via launchd, inspect the associated property list for UserName and GroupName keys to ensure the job does not silently run as an unintended identity.

#

Filesystem and SIP Considerations

System Integrity Protection may prevent modification of certain system-owned log paths regardless of privilege level. Run csrutil status during pre-flight to confirm SIP state, and avoid targeting any directory under /System even indirectly through symlink traversal, since find will follow symlinks unless -P is explicitly set.

#Change Control and Documentation

Every deployment of this script into a production fleet should be recorded in the change log with the following fields: script version hash (via shasum -a 256), target host group, scheduled execution window, approving engineer, and rollback owner. Store the change record alongside the audit log retention policy so that a failed run can be cross-referenced against the exact script revision that produced it. Where the script is distributed via configuration management, tag the commit that introduced or modified MAX_AGE_DAYS or staging path logic, as silent parameter drift between environments is a common source of unexpected behaviour during audits.

#

Version Pinning

Pin the script to a specific commit or package version in any deployment manifest rather than referencing a mutable branch. This prevents a mid-cycle edit to shared automation from altering behaviour on hosts that have already passed change approval.

#Monitoring and Alerting Thresholds

Instrument the audit log with a lightweight tail-based monitor, or ingest it into an existing log pipeline, and configure alerting on the following thresholds:

• Zero files staged across three consecutive runs: may indicate the find predicate is no longer matching due to a path or naming convention change upstream.
• Staging directory age exceeding one scheduled interval: suggests the cleanup step failed silently or the script exited before reaching final removal.
• Non-zero exit code frequency above one in twenty runs: warrants immediate review of pre-flight assumptions, as this suggests environmental drift rather than a one-off fault.
• Unexpected UID in audit log entries: flags a possible misconfiguration in the scheduling mechanism or a permissions escalation outside expected bounds.

Where monitoring is centralised, forward the audit log via a lightweight forwarder rather than relying on local retention alone, since a failed run may also corrupt or truncate the local log file it is meant to explain.

#Realistic Failure Symptoms

In practice, failures rarely present as a clean non-zero exit. More commonly, administrators observe one of the following patterns:

• The staging directory exists but contains fewer files than the pre-flight file list recorded, indicating the loop was interrupted mid-iteration, possibly by a system sleep event or an external process terminating the script.
• Files reappear in /var/log after a rollback, but with altered ownership or mode bits, because the mv operation on an APFS volume can behave differently across volume boundaries than within a single volume.
• The script reports success, but subsequent log rotation by newsyslog or a third-party logging daemon conflicts with the staging window, producing duplicate or missing entries that only surface days later.
• Disk space exhaustion in /tmp causes the staging mkdir to succeed but subsequent mv operations to fail intermittently, since /tmp on macOS is typically backed by the same volume as the root filesystem rather than a dedicated tmpfs.

#

Diagnosing Intermittent Failures

When failures are inconsistent rather than deterministic, capture the output of df -h /tmp /var/log and iostat alongside the audit log timestamp of the failure. Correlate against any concurrent Time Machine backup window, since local snapshot creation can transiently lock files that the script attempts to move.

#Escalation Thresholds

Define escalation tiers before deployment rather than improvising during an incident. A single failed run with successful rollback should be logged but does not require escalation beyond the automation owner. Two consecutive failed runs on the same host warrant escalation to the platform engineering lead, with the host removed from the scheduling group pending investigation. Any failure affecting more than one host in the same execution window should be escalated immediately to change management, as this pattern suggests a shared dependency fault, such as a distributed configuration profile pushing an incorrect MAX_AGE_DAYS value, rather than an isolated host issue.

#Safe Rollback Actions

Beyond the in-script rollback, maintain a documented manual rollback procedure for cases where the script itself has terminated abnormally, for example following a kill -9 or unexpected reboot. This procedure should specify: locating any residual staging directories matching the /tmp/log_staging_* pattern, verifying file counts against the corresponding /tmp/file_list_* snapshot before restoration, restoring ownership with chown matching the original log owner (typically root:wheel on macOS), and confirming restored file modification times are preserved using mv rather than cp, since a copy operation will reset the mtime and could interfere with subsequent age-based selection logic on the next scheduled run.