Root Certificate Installation

What the root certificate trust Worklet does

This Automox Worklet™ adds a custom root certificate authority to the System.keychain on macOS endpoints running Catalina (10.15.x) or earlier. The Worklet reads a certificate string from the rootCert script variable and a friendly identifier from the certName variable, writes the certificate content to a temporary file under /var/tmp/, and registers it as a trusted root using security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain. The staging file is removed after the keychain import completes.

The evaluation phase gates the policy by Darwin kernel version. The script runs uname -r and extracts the major version number. If the major version is 20 or higher (Big Sur or later), the endpoint exits 0 and is considered out of scope. Endpoints on Catalina (Darwin 19) or earlier exit 1 and are flagged for remediation on every run. The remediation script applies the same Darwin version check before proceeding, then writes the certificate and runs the keychain import. A non-zero exit from the security command surfaces as a remediation failure in Automox activity logs.

Because trust changes propagate to every framework that consumes the system trust store, the import affects Safari, Chrome on macOS, curl, and any app linked against Secure Transport or Network.framework. Multiple Worklet deployments can stack distinct certificates by varying the certName variable, which is useful for staged rollouts of an internal CA, a partner CA, or a developer-only intermediate.

Why standardize root CA trust across the Mac fleet

Internal certificate authorities, partner CAs, and TLS-inspection proxies all rely on every endpoint trusting a specific root. When that root is missing from a Mac's System.keychain, Safari blocks the page, curl fails with certificate verification errors, and VPN or proxy clients reject inspected sessions. End users learn to click through warnings, which trains the exact behavior that undermines the rest of the security stack. Manual installs via Keychain Access scale to a single laptop, not to a fleet, and Apple's MDM payload requires full MDM enrollment, which not every Automox-managed Mac fleet has.

Trust drift on Mac endpoints surfaces as the kind of intermittent failure that is hardest to diagnose: a TLS-terminated internal service that worked yesterday, an enrollment that fails mid-flight, or an outbound proxy that suddenly serves certificate errors. Scheduling this Worklet against the Mac estate enforces the trust baseline on every in-scope endpoint. A new developer laptop, a refurbished lab Mac built from a stale image, and a kiosk Mac in a branch office all converge on the same System.keychain trust chain in the same policy run.

How root certificate trust deployment works

1. Evaluation phase: The Worklet runs uname -r and extracts the Darwin major version number. If the value is 20 or higher, the endpoint exits 0 and is out of scope; Big Sur and later require a Profiles-based trust step that this script does not perform. On Catalina and earlier, the script exits 1, flagging the endpoint non-compliant so the remediation script runs.

2. Remediation phase: The remediation script applies the same Darwin version check, then writes the rootCert variable content to /var/tmp/<certName> using a heredoc, and runs security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /var/tmp/<certName> to register the certificate as a trusted root. After the import completes, the script removes the staging file with rm -f /var/tmp/<certName>. A non-zero exit from the security command surfaces as a remediation failure in Automox activity logs.

Root CA deployment requirements

• macOS endpoint running Catalina (10.15.x) or earlier; the evaluation gate skips Big Sur and later, where Apple requires a Profiles payload for full SSL trust

• Root or sudo privileges for the Automox agent to write to /Library/Keychains/System.keychain (the default agent context already meets this)

• Certificate content pasted into the rootCert script variable before deployment; the script writes this value directly to disk using a heredoc

• Friendly identifier set in the certName script variable; this string is used as both the staging filename under /var/tmp/ and passed to the security command

• Write access to /var/tmp/ on the endpoint; the script cleans up after itself but requires the directory to exist with default permissions

• For an internal CA, embed the public root certificate only; never paste a private key or intermediate signing key into the rootCert variable

Expected trust state after deployment

After a clean remediation, the certificate is present in /Library/Keychains/System.keychain with a trust setting of Always Trust for SSL and X.509 Basic policies. Confirm by running security find-certificate -c <certName> -p /Library/Keychains/System.keychain, which prints the PEM block when the cert is registered, or security dump-trust-settings -d, which lists the System trust overrides. End-user-facing checks include opening an internal HTTPS resource in Safari (no warning page) and running curl -v https://<internal-host>/ (no certificate errors). Subsequent Automox policy runs evaluate the endpoint as Catalina or earlier and run the remediation script again; the keychain import is idempotent for the same certificate.

The certificate persists across reboots, user logins, and OS minor-version upgrades, and remains in the keychain until an administrator removes it with security delete-certificate -c <certName> /Library/Keychains/System.keychain or the endpoint is reimaged. Once an endpoint upgrades to Big Sur or later, the evaluation script exits 0 and the Worklet stops running the remediation, leaving the previously imported certificate in place. For audit evidence, export the trust state with security dump-trust-settings -d and review the output, which names every root registered as Always Trust.