macOS - Security- Create System Certificate Bundle

What the macOS CA trust bundle deployer does

This Automox Worklet™ exports every root and intermediate certificate from the macOS System Keychain and the SystemRootCertificates keychain, concatenates them into a single PEM-encoded bundle at /opt/proxy/cabundle.pem, and exports the SSL trust environment variables that command-line tooling reads at process start. The Worklet does not modify the keychain itself; it surfaces what the keychain already trusts to applications that do not consult Apple's Security framework.

The Worklet appends export statements to /etc/bashrc, /etc/zshrc, and /etc/profile for six variables: REQUESTS_CA_BUNDLE (Python requests), WEBSOCKET_CLIENT_CA_BUNDLE (websocket-client), NODE_EXTRA_CA_CERTS (Node.js), AWS_CA_BUNDLE (AWS CLI and SDKs), SSL_CERT_FILE (OpenSSL and most libraries that link against it), and CURL_CA_BUNDLE (cURL). All six point to the same /opt/proxy/cabundle.pem path, so a single bundle update propagates to every consumer the next time the shell sources its profile.

The remediation script also supports a tmp_certs array of inline PEM blocks, useful for stapling a proxy CA, an internal root, or a self-signed staging certificate into the bundle without first installing it into the keychain. Certificates added this way are appended after the system roots and are available to tooling even on freshly imaged endpoints that have not yet received your enterprise PKI deployment.

Why deploy a fleet-wide TLS trust bundle

macOS ships with a well-maintained trust store, but the store is only useful to applications that call Apple's Security framework. Python's requests library, Node.js, AWS CLI, kubectl, Terraform, Docker, and most other developer tooling on a Mac do not. They walk a chain of environment variables and built-in defaults instead, and on a fresh macOS install those defaults point at paths like /etc/ssl/cert.pem that may not include the certificates your fleet actually trusts. When an organization runs an SSL inspection proxy or an internal certificate authority, every one of those tools fails TLS verification until an admin manually exports a bundle and sets the right variables. That manual step does not survive a reimage.

The trust bundle is also fragile in three predictable ways. A reimage wipes /opt/proxy/ unless the deployment workflow recreates it, a Homebrew or system update can rewrite /etc/zshrc and drop the export lines, and an OS major-version upgrade frequently resets /etc/profile back to a vendor stub. The Worklet greps the three init files for each of the six export variables on every evaluation, regenerates the bundle with security find-certificate when the file is missing, and re-appends any missing exports before a developer files a ticket about pip install hanging on SSL errors.

How macOS CA trust bundle deployment works

1. Evaluation phase: The Worklet checks for the bundle file at /opt/proxy/cabundle.pem and confirms it is non-empty. It then greps /etc/bashrc, /etc/zshrc, and /etc/profile for each of the six SSL_CERT_FILE, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE, NODE_EXTRA_CA_CERTS, AWS_CA_BUNDLE, and WEBSOCKET_CLIENT_CA_BUNDLE export lines. If the bundle is missing or any expected export is absent in any of the three shell init files, the endpoint is flagged non-compliant and remediation is scheduled. The check is idempotent, so already-configured endpoints exit 0 without making changes.

2. Remediation phase: The remediation script sets umask 022, runs security find-certificate -a -p against /System/Library/Keychains/SystemRootCertificates.keychain and /Library/Keychains/System.keychain in a single call to export every certificate in PEM form into a temporary file. If the optional tmp_certs array is populated, each entry is appended to the temporary file. The script then creates /opt/proxy/ with sudo mkdir -p, applies read and execute permissions, and moves the bundle into place at /opt/proxy/cabundle.pem. It writes export lines for all six variables to /etc/bashrc, /etc/zshrc, and /etc/profile, guarded by a grep test so reruns do not duplicate entries. For organizations enrolling a private CA, security add-trusted-cert -d -k /Library/Keychains/System.keychain can be paired with this Worklet to land the certificate in the keychain first; this Worklet then surfaces it to tooling.

macOS CA trust bundle requirements

• macOS endpoint (Intel or Apple Silicon, workstation or server) with the Automox agent running as root

• Write access to /opt/proxy/ and to /etc/bashrc, /etc/zshrc, /etc/profile (the default agent context already meets this)

• Any custom CA certificates already loaded into the System keychain via security add-trusted-cert -d -k /Library/Keychains/System.keychain, or pasted into the tmp_certs array in the remediation script

• Awareness that this Worklet does not replace /etc/ssl/cert.pem; some legacy tools that hard-code that path still need a symlink or a separate override

• An understanding that users need a new shell session (logout/login or a new Terminal window) for the exports to take effect; running processes do not pick up environment changes mid-flight

Expected TLS trust state after deployment

On a successful run, /opt/proxy/cabundle.pem exists and contains every certificate present in the System and SystemRootCertificates keychains in PEM form, plus any tmp_certs additions. The three shell init files each carry six export lines pointing at that file. New shell sessions inherit the variables; Python requests, Node.js, AWS CLI, cURL, websocket-client, and any OpenSSL-linked tool now consult the bundle instead of their built-in defaults. Subsequent policy runs report the endpoint as compliant and skip remediation, because the evaluation phase finds the bundle and all six exports already in place.

Validate by opening a new Terminal and running echo $SSL_CERT_FILE, which should return /opt/proxy/cabundle.pem. Then test an outbound HTTPS call through your proxy or internal CA: curl -v https://internal.example.com should complete without a certificate verification error, and python3 -c "import requests; print(requests.get('https://internal.example.com').status_code)" should return 200. For audit evidence, capture the SHA-256 of cabundle.pem with shasum -a 256 /opt/proxy/cabundle.pem and the count of certificates with grep -c 'BEGIN CERTIFICATE' /opt/proxy/cabundle.pem, then store both alongside the Automox policy run identifier. The bundle is regenerated on every remediation, so a keychain change made by another policy (or by security add-trusted-cert in a companion Worklet) propagates to the bundle on the next evaluation cycle that finds drift.