Read the latest issue (#314) of the the MacAdmins news summary over on MacAdmins.news!
Tag: Mac
Prefs CLI Tools for Mac Admins
Recently I have been working on some… well… “stuff” that uses custom configuration profiles. Very custom, and since I am testing things, they need to be updated a lot.
The issue with defaults
When you are working with defaults/preferences/settings/property lists on macOS, you will be familiar with the defaults
command line tool. But, as useful as defaults
can be, it has some downsides.
One of the great advantages of macOS’ preference system is that settings can be provided on multiple levels or domains. In my book “Property Lists, Preferences and Profiles for Apple Administrators, I have identified 19 different levels where settings for a single application can originate.
You will be most familiar with plist files in /Library/Preferences
(system), ~/Library/Preferences
(user), and managed configuration profiles (managed). When an app or tool requests a setting, the preferences system will merge all those levels together and present only the most relevant value. When the developer uses the system APIs (correctly), they do not have to worry about all the underlying levels, domains and mechanisms very much, but automatically gain support for things like separated system and user level settings files and support for management through configuration profiles.
The macOS defaults
command line tool can work with settings on different levels or domains, but will only show the settings from one at a time. By default it only works with the user domain settings stored in ~/Library/Preferences/
. When you have settings in multiple levels or from configuration profiles, you may be able to point defaults
directly at the files. Or in the case of managed settings from profiles, you have to use a different tool. Either way, you have to determine which setting might override another and which final value might be visible to the app or process.
A new prefs
tool
Years back, I had built a python script, called prefs.py
, which would not only show the coalesced set of settings but their origin level. When macOS removed Python 2 in macOS 12.3, this tool obviously broke.
While working with preferences and profiles recently, this feature would have been quite useful to debug and verify preferences. I could have adapted the existing tool to work with MacAdmins Python 3, but felt I would learn something from recreating it in Swift. I had already started down that road just a bit for my sample project in this post.
So, you can find the new Swift-based prefs
command line tool on GitHub. You can also download a signed and notarized pkg which will install the binary in /usr/local/bin/
.
If its most basic form, you run it with a domain or application identifier. It will then list the merged settings for that preference domain, showing the level where the final value came from.
% prefs com.apple.screensaver
moduleDict [host]: {
moduleName = "Computer Name";
path = "/System/Library/Frameworks/ScreenSaver.framework/PlugIns/Computer Name.appex";
type = 0;
}
PrefsVersion [host]: 100
idleTime [host]: 0
lastDelayTime [host]: 1200
tokenRemovalAction [host]: 0
showClock [host]: 0
CleanExit [host]: 1
I find this useful when researching where services and applications store their settings and also to see if a custom configuration profile is set up and applying correctly. There is a bit of documentation in the repo’s ReadMe and you can get a description of the options with prefs --help
.
plist2profile
Another tool that would have been useful to my work, but that was also written in python 2 is Tim Sutton’s mcxToProfile
. Back in the day, this tool was very useful when transitioning from Workgroup Manager and mcx based management to the new MDM and configuration profile based methods. If you have a long-lived management service, you will probably find some references to mcxToProfile in the custom profiles.
Even after Workgroup Manager and mcx based settings management was retired, Tim’s tool allowed to create a custom configuration profile from a simple property list file. Configuration Profiles require a lot of metadata around the actual settings keys and values, and mcxToProfile
was useful in automating that step.
Some management systems, like Jamf Pro, have this feature built in. Many other management systems, however, do not. (Looking at you Jamf School.) But even then creating a custom profile on your admin Mac or as part of an automation, can be useful.
So, you probably guessed it, I also recreated mcxToProfile in Swift. The new tool is called plist2profile
and available in the same repo and pkg. I have focused on the features I need right now, so plist2profile
is missing several options compared to mcxToProfile. Let me know if this is useful and I might put some more work into it.
That said, I added a new feature. There are two different formats or layouts that configuration profiles can use to provide custom setting. The ‘traditional’ layout goes back all the way to the mcx data format in Workgroup Manager. This is what mcxToProfile would create as well. There is another, flatter format which has less metadata around it. Bob Gendler has a great post about the differences.
From what I can tell, the end effect is the same between the two approaches. plist2profile
uses the ‘flatter’, simpler layout by default, but you can make it create the traditional mcx format by adding the --mcx
option.
Using it is simple. You just need to give it an identifier and one or more plist files from which it will build a custom configuration profile:
% plist2profile --identifier example.settings com.example.settings.plist
You can find more instructions in the ReadMe and in the commands help with plist2profile --help
Conclusion
As I had anticipated, I learned a lot putting these tools together. Not just about the preferences system, but some new (and old) Swift strategies that will be useful for the actual problems I am trying to solve.
I also learnt more about the ArgumentParser package to parse command line arguments. This is such a useful and powerful package, but their documentation fails in the common way. It describes what you can do, but not why or how. There might be posts about that coming up.
Most of all, these two tools turned out to be useful to my work right now. Hope they will be useful to you!
zsh scripts and Root Escalations
There was an update for the Support.app this week which fixed a CVE. There is an argument to be had about whether this CVE deserves its high rating, but it is worth discussing the underlying issue and presenting some solutions. (Erik Gomez has some great comments on Mac Admins Slack.)
zsh is far more configurable than most other shells, most certainly more configurable than the aging bash 3.2 that comes with macOS. One aspect of being more configurable is that it has multiple different configuration files that are loaded at different times when the shell starts. The most common configuration file you will have encountered is ~/.zshrc
which is loaded for all interactive shells.
Another, less commonly used, configuration file, ~/.zshenv
(and its global sibling /etc/zshenv
) is loaded every time a zsh process launches, including script launches. That means, when you (or something else in the system) launches a script with a #!/bin/zsh
shebang, the zsh process will read the files /etc/zshenv
and ~/.zshenv
when they exist, and execute their code.
Update 2024-03-22: some links for further reading:
- Root3: Support App 2.5.2 resolves unexpected code execution
- Matteo Bolognini: zsh_checker.sh
- Matteo Boognini: custom Jamf Protect analytic
- Scripting OS X: pkgcheck (can be used to scan shebangs in scripts in pkgs)
- Dan Snelson: SQL Update Statement to Address CVE-2024-27301
The Setup
We can see this in action.
First, create a simple zsh “hello.sh” type script with this content:
#!/bin/zsh
echo "Hello, $(whoami)"
Make the script file executable (chmod +x hello.sh
) and run it. You should see output like
% ./hello.sh
Hello, armin
where armin
is replaced with your current username.
Next, create a new file ~/.zshenv
(~/
means at the root of your home directory) with your favored text editor and add the following line:
echo "zshenv: as $(whoami) called from $0"
If you already have a ~/.zshenv
you will want to rename it for now so we don’t modify that. (mv ~/.zshenv ~/.zshenv_old
)
Note that the configuration file neither has a shebang, nor does it need to be executable.
When you open a new Terminal window, you should see the line
zshenv: as armin called from -zsh
among the other output at the top of the Terminal window, since ~/.zshenv
is read and evaluated every time a zsh process starts. The shebang at the beginning of the script ensures a new zsh environment is created for it, even when your interactive shell is not zsh.
When you run hello.sh
you will see that ~/.zshenv
is executed as well:
% ./hello.sh
zshenv: as armin called from /bin/zsh
Hello, armin
So far, so good. This is how zshenv
is supposed to work. It’s purpose is to contain environment variables and other settings that apply to all processes on the system. On macOS this is undermined by the fact that most apps and process are not started from a shell, so they don’t see environment variables set anywhere in the zsh (or another shell’s) configuration files, so .zshenv
is rarely used. .zshrc
is far more useful.
But now we come to escalation aspect: run hello.sh
with root privileges using sudo
:
% sudo ./hello.sh
zshenv: as root called from /bin/zsh
Hello, root
We see that both our script and ~/.zshenv
are run with root privileges. Again, that is how sudo
and .zshenv
are supposed to work.
Since the zshenv
configuration files are evaluated every time a zsh is launched, it is far more likely that they will eventually run with elevated privileges, than the other configuration files. Other shells, like bash and sh have no equivalent configuration file that gets run on every launch.
The Escalation
The potential danger is the following: a process only needs user privileges to create or modify ~/.zshenv
. A malicious attacker can inject code into your .zshenv
, wait patiently for a script with a zsh shebang to be run with root privileges, and then execute some malicious code with root privileges on your system.
This can also occur with preinstall
or postinstall
scripts with a zsh shebang in installation package files (pkg files) when the installation is initiated by the user. A malicious attacker could scan your system for apps where they know the installer package contains zsh scripts, which makes the chance that eventually a zsh script is run with root permissions quite certain. Then all they have to do is be patient and wait…
As root escalations go, this is not a very efficient one. The attacker is at the mercy of the user to wait when they execute a zsh script with escalated root privileges. On some Macs, that may very well be never.
This also only works when the user can gain administrative privileges. Standard users cannot use sudo
to gain root privileges, or run installation packages.
There are more effective means of escalating from user to root privileges on macOS. Most easily by asking the user directly for the password with a dialog that appears benign. However, if you are a frequent user or author of zsh scripts, it is important to be aware.
From what I can tell so far, this does not affect scripts launched from non-user contexts, such as scripts from Munki, Jamf Pro or other management solutions, though there may be odd, unexpected edge cases.
As an organization, you can monitor changes to all shell configuration files with a security tool (such as Jamf Protect). There are more shenanigans an attacker could achieve by modifying these files. There are, however, many legit reasons to change these files, so most changes will not indicate an attack or intrusion. Nevertheless, the information could be an important puzzle piece in combination with other behaviors, when putting together the progress or pattern of an intrusion.
Update 2024-03-22: Matteo Bolognini has added a custom analytic for Jamf Protect to detect changes to the zshenv file.
Configuration file protection
This weakness is fairly straightforward to protect against. First, since the attack requires modification of ~/.zshenv
, you can protect that file.
If you did not have a ~/.zshenv
, create an empty file in its place or remove the line of code from our sample .zshenv
before. Then apply the following flag:
% sudo chflags schg ~/.zshenv
This command sets the system immutable flag (schg
, ‘system change’), which makes it require root privileges to modify, rename or delete the file.
If you want to later modify this file, you can unlock it with
% sudo chflags noschg ~/.zshenv
Just remember to protect it again when you are done.
Script protection
Since most Mac users will never open terminal and never touch any shell configuration file, relying on protecting the configuration file is not sufficient. However, it is quite easy to protect the zsh scripts you create from this kind of abuse.
One solution is to use a $!/bin/sh
shebang instead of #!/bin/zsh
. Posix sh does not have a configuration file which gets loaded on every launch, so this problem does not exist for sh
.
If you are using zsh features that are not part of the POSIX sh standard you will need to change the script. In my opinion, installation scripts that are too complex to use POSIX sh, are attempting to do too much and should be simplified, anyway. So, this can also work as an indicator for “good” installation scripts.
In addition, installer packages might be used in situations where zsh is not available. Installation tools that install package files when the Mac is booted to Recovery (where there is no zsh) are used far less than they used to, but it is still possible and making your installer pkgs resilient to all use cases is generally a good choice.
I believe for installation package scripts, using an sh
shebang is a good recommendation.
Some scripts popular with Mac Admins, like Installomator, do not usually run from installer packages, but are regularly run with root privileges. For these cases, (or for installation scripts, where cannot or do not want to use sh) you can protect from the above escalation, by adding the --no-rcs
option to the shebang:
#!/bin/zsh --no-rcs
echo "Hello, $(whoami)"
zsh’s --no-rcs
option suppresses the launch of user level configuration files. The rc
stands for ‘Run Command’ files and is the same rc
that appears in zshrc
or bashrc
or several other unix configuration files.
That allows you to keep using zsh and zsh features, but still have safe scripts. This is the solution that Support.app and the latest version of Nudge have implemented. I have also created a PR for Installomator, which should be merged in the next release.
Conclusion
Modifying ~/.zshenv
is not a very effective means of gaining root privileges, but it is something developers and Mac admins that create zsh script that may be run with root privileges should be aware of. Switch to an sh shebang or add --no-rcs
to the zsh shebang of scripts that might be run with root privileges to protect.
Using desktoppr in a managed environment
A few years back, I built and released a small tool to simplify the deployment of macOS desktop pictures (also known as “wallpapers” since macOS Ventura and on other platforms) without actually locking them down or needing privacy (PPPC) exemptions. The tool is desktoppr and is quite popular among Mac admins.
I haven’t updated desktoppr in the last three years, and even that last update was just a re-compile to make the binary universal. It was always meant to do one thing and it has done that well, so there was no need for updates.
Recently however, I have been thinking about the workflows to install and set a custom desktop picture or wallpaper in a managed environment.
Note: my thoughts here are for Macs that are owned and managed by organizations and given out to employees to work with. They do not really apply to shared devices in classrooms, carts, labs or kiosk style deployments or even 1:1 devices in an education setting. Other rules (figurative, literal, and legal) apply in these scenarios and you probably want to set and lock a desktop picture/wallpaper with a configuration profile.
Why do it at all?
This is a fair question. My general recommendation for Mac Admins regarding pre-configuring, or even locking down settings in user space is to only do it when you absolutely need to for compliance and security reasons.
I often get the argument that it makes the lives of Mac Admins and tech support easier when you pre-configure settings that “everyone wants anyway.” However, I believe, from my own experience, that “tech geeks” (and I include myself here) are poor judges for which settings should be a general preset and which are just our geeky personal habits and preferences.
This holds especially true when macOS updates change default settings. There have been examples for this throughout macOS history, such as the “natural scrolling” on trackpads, whether to use dark mode, or more recently, the “click to desktop” behavior in macOS Sonoma.
You may be able to generate the statistics from your support ticketing system that tells you which pre-configuration would cut down a significant number of incidents and then, by all means, apply those. (I’d be very interested in those stats and which settings those are.)
But generally, a more hands-off approach is less intrusive, and also less effort in management and maintenance.
So, why configure the wallpaper?
Given my lecture above, this is a fair question. The desktop picture/wallpaper is special. It gives you a chance for a great first impression.
The desktop picture/wallpaper is the first thing a user sees when they log in to a new Mac. Apple understands this, and creates new, beautiful images for each major release of macOS to emphasize its branding. Likewise, when you are managing Macs, this is a very compelling opportunity to present your organization’s branding. This will also demonstrate to end users that this Mac is different. This will identify this Mac as a managed Mac from your organization.
Of course, many users will go ahead and change the desktop picture/wallpaper immediately, or eventually. And so they should. The ability to configure and setup the device the way they like it will make it “theirs,” i.e. more personal, and also might encourage some to learn a bit more about macOS and the device they are working with. Limiting a power user in how they can configure “their” device and how they work with it will be a cause for much frustration, friction and complaints. This is why desktoppr exists: to set the desktop picture/wallpaper once, but then allow the user to change it later.
But first impressions are important. There are very few ways Apple lets Mac admins customize the first use experience. The desktop picture/wallpaper is fairly simple to manage and can leave a big impression.
Ok, but how?
That said, there a few considerations to get this first impression just right. In general, to set a customized wallpaper you need to:
- install the image file(s)
- install desktoppr
- run desktoppr to set the wallpaper
The challenge is to get the timing right on these steps. In this case the first two steps can (and should) happen right after enrollment. The third step configures user space, so it cannot happen before the user account is created and the user logs in. If you run it too late, the user will see the default macOS wallpaper for a while and then switch to the new one, which is not really ideal to create a good first impression.
In Jamf Pro (the management system I have most experience with) you can put the packages for the image file and desktoppr in the PreStage or enroll them with policies triggered at enrollmentComplete
. Since these pkgs usually are not very large, the image files and the desktoppr binary are ready to go when the user finishes setting up their account and gets to the desktop for the first time.
Jamf Pro provides an option to run policies at login, but that also has few seconds delay before it actually runs, giving the user a “flash” of the default macOS wallpaper.
The good news is, that when you run desktoppr with a LaunchAgent, it runs early enough in the login process, that the user does not get “flashed” by Apple’s default wallpaper.
That extended our workflow to:
- install the image file(s)
- install desktoppr
- install LaunchAgent plist
- desktoppr runs as LaunchAgent at login to set the wallpaper
The LaunchAgent will run on every login, and reset the wallpaper even if the user changed a different one. This might be desirable for some deployments, but in general this goes against the notion to leave the user in control. There are workarounds to this. You can build a script that sets the wallpaper and creates a flag file somewhere in the user’s home directory. On subsequent runs, the script would check for that flag file and skip re-setting the wallpaper.
Also, since macOS Ventura, the system warns users about background items in the system. We can manage these warnings with a configuration profile. Since the desktoppr binary is signed, this works quite well. But if you insert a custom shell script as the LaunchAgent to perform all this extra logic, you need to sign this script and managing the background item profile gets a lot more messy.
This works, but now our workflow is:
- install the image file(s)
- install desktoppr
- install LaunchAgent plist
- install signed custom script
- configure and deploy managed Background Item profile
- script runs at login and sets the wallpaper, when necessary
If any of the pieces in step 1–5 change, you need to update at least one installation pkg, upload them to your management system and deploy them down to the clients. Neither of these are very complicated, but the number of moving pieces will make this very tedious quickly.
These workflow steps will not vary much from one deployment to another. So I thought it would be nice if I could integrate some of these steps in desktoppr and find some means to make the pieces less volatile.
Manage the arguments
The first moving piece I wanted to fix was the LaunchAgent plist file. This needs to contain the path to the image file as the first argument to the desktoppr binary, which will be different for every deployment. This value might even change over time for a single given deployment as the org wants to updated and “fresh” desktop pictures/wallpapers with new branding.
For a managed environment, we can also provide this information with a configuration profile. This separates the ‘data’ (the path to the image file) from the logic (the other information in the launchd plist file, that controls when it runs).
I added a new verb manage
to desktoppr that tells it to get configuration from a preference domain or configuration profile instead of the arguments. Now, we can put desktoppr
with the single argument manage
in the LaunchAgent plist. This means the LaunchAgent will not have to change when you update image paths or other settings. Instead, the admin updates the configuration profile in the MDM server. The LaunchAgent plist file is still required, but it won’t need frequent updates any more. (Step 3 is now less volatile)
Setting once
The next step is some new logic in desktoppr to only set the wallpaper once. For that, desktoppr now “remembers” when it last set the wallpaper and to which file. When it is called again to set it to the same file, it does nothing, even if the user changed the desktop picture/wallpaper. Some deployments might still want to reset the wallpaper every time the LaunchAgent triggers, so I added a key to the configuration profile to enable or disable this behavior. This flag only takes effect when desktoppr manage
is run, other invocations of desktoppr will set the desktop picture/wallpaper regardless.
This removes the requirement for a custom script that determines whether desktoppr should set the wallpaper or not. (Step 4) Since we are now running desktoppr manage
directly from the LaunchAgent, and the desktoppr
binary is signed, it is easy to create the PPPC profile to designate this as a managed background item. (Step 5 is less volatile)
There is a sample configuration profile in the repo which has the settings payload and the payload for the background item pre-approval.
Fetch image files
The last volatile bit is the image file itself. So far, you have to create an installation pkg for the image file and install that before desktoppr runs.
To avoid this, I taught desktoppr to download an image file from a URL and use that. So now, you can upload a file to a web server (or AWS, or some file sync service that can provide a static URL) and use that as your desktop.
Since images can be a vector for malware, we add the option to verify the downloaded file with an sha256 hash given in the configuration profile.
Since the download can take a few seconds, this re-introduces the “flash” of the default wallpaper. I don’t really see a way to avoid this and if this really upsets you, you will have to fall back to pre-installing an image file. Nevertheless, I found the option to have desktoppr download an image file to be useful and left it in there.
The new workflow
- create and deploy a desktoppr configuration profile
- install desktoppr with a LaunchAgent plist (these shouldn’t change very often)
- desktoppr runs, downloads the image file and sets the wallpaper, when necessary
All the custom configuration is now in the configuration profile. You will only need to update the desktoppr installation pkg when the binary is an updated.
New use cases
This shortened workflow enables some new workflows. First of all, since there is logic in desktoppr to only change when necessary, we don’t really have to wait until the next login any more. (Most users only “log in” after a reboot for a software update.) We can change the LaunchAgent plist to run in the background every few hours or so. That way, new settings in the configuration profile should be picked up by all the clients within a few hours after coming online and receiving the new profile from the MDM.
Introducing desktoppr 0.5beta
I have been playing around with this and testing for a bit now. It has been working well for me, but I know there will some edge cases and workflows out there that I am not anticipating. For this reason, I am releasing the new manage
feature as a beta, so you can start testing it and reporting any improvements, issues, or challenges.
I am curious to see what you are going to do with it.
Installomator v10.5
We have released an update for installomator which brings it to v10.5. You can can see the details in its release notes page.
With an astounding 78 new labels and updates to 42 existing labels, this brings Installomator to 733 labels. The project has also reached 100 contributors who have put in at least one pull request!
Many thanks to everyone who contributed, whether through pull requests, or by filing issues or by joining in the discussion in the #installomator channel on the Mac Admins Slack.
Weekly News Summary for Admins — 2023-10-06
Just a short news summary this week, as I am busy presenting today at MacSysAdmin in Gothenburg!
(Sponsor: SentinelOne)
Bloated Binaries | How to Detect and Analyze Large macOS Malware Files
Massive malware binaries are becoming more common on macOS and can cause problems for detection and analysis. Here’s how we can successfully deal with them.
If you would rather get the weekly newsletter by email, you can subscribe to the Scripting OS X Weekly Newsletter here!! (Same content, delivered to your Inbox once a week.)
📰News and Opinion
- Interview with HRTech – Tom Bridge
- Apple Memory Holes OCSP Preference – Michael Tsai
- iPhone 15 Pro Max Camera Review: Depth and Reach – Sebastiaan de With, Halide
⚙️macOS and iOS Updates
🔨Support and HowTos
- How to ‘clean’ install modern macOS – Howard Oakley
- On the topic of Slack & Slack EMM for BYO mobile devices – Dr. K
- How Apple Admins Name the Devices They Manage – Kandji Blog
🤖Scripting and Automation
- swiftDialog: Get the Exit Code of a Background Process – Trevor Sysock
- Removing Jamf Remote policies using an API script – Elliot Jordan
- Automating Munki with munki-promoter – Jacob Burley
🍏Apple Support
♻️Updates and Releases
- SF Symbols 5
- JamfCheck v1.3
- SimpleMDM account-driven enrollment – SimpleMDM
- uberAgent 7.1
- LowProfile 4.0.1
🎧To Listen
- Just Us on Sonoma and iOS 17 – Mac Admins Podcast
- We’ve got 81 problems, but compliance isn’t one of them – Apple @ Work Podcast, 9to5Mac
🎈Just for Fun
📚Support
If you are enjoying what you are reading here, please spread the word and recommend it to another Mac Admin!
Weekly News Summary for Admins — 2023-09-29
Release week part 2! We got macOS Sonoma 14.0 release. If you were running the RC2, that is the same as the release. We also got the first round of iOS 17.1 and macOS Sonoma 14.1 betas! (It’ll be good to have the minor update numbers for iOS and macOS in sync for a change.
(Sponsor: Mosyle)
The only Apple Unified Platform for Business
Mosyle is the only solution that fully integrates Enhanced MDM, Endpoint Security, Internet Privacy & Security, Single Sign-On, and Application Management on a single Apple-only platform.
Click here to learn why Mosyle is all you need to work with Apple.
If you would rather get the weekly newsletter by email, you can subscribe to the Scripting OS X Weekly Newsletter here!! (Same content, delivered to your Inbox once a week.)
macOS Sonoma
- macOS Sonoma 14.0 (23A344): About, Developer Release Notes, Security, Enterprise
- How to upgrade to macOS Sonoma
- macOS Sonoma is compatible with these computers
- macOS User Guide for macOS Sonoma
- Safari 17.0: WebKit Features, Developer Release Notes, Security
Reviews
- macOS Sonoma: The MacStories Review – John Voorhees, MacStories
- macOS 14 Sonoma: The Ars Technica review – Andrew Cunningham, Ars Technica
- Apple has released macOS 14 Sonoma – Howard Oakley
- Sonoma in the Spotlight: What’s New and What’s Missing in macOS 14 – Phil Stokes, SentinelOne
MacAdmins
- Suspicious Package FAQ on strange dialogs in macOS Sonoma
- The Mac Hardware/Software Obsolescence Chart – Anthony Reimer
- Managing the “Click wallpaper to reveal desktop” setting in macOS Sonoma – Rich Trouton
- Xsan Ventura & Sonoma upgrade failures and a workaround using profile “Magic” – Eric Hemmeter
- Suppressing undesired local account password policy notifications on macOS Sonoma – Rich Trouton
- Enabling Touch ID for sudo in macOS Sonoma – Jacob Burley
- Retroactive Automated Device Enrollment in macOS Sonoma – Kevin M. Cox
- Do you use iCloud Drive? Are you intending to upgrade to Sonoma? – Howard Oakley
Security and Privacy
- Beyond the good ol’ LaunchAgents 32: Dock Tile Plugins – Csaba Fitzl
- macOS Service Management: The SMAppService API, Quick Notes – Csaba Fitzl
Support and HowTos
Scripting and Automation
Apple Support
Updates and Releases
- erase-install 31.0
- Jamf Compliance Editor 1.2.1
- What’s new in Microsoft Intune (2309) September edition – Ramya Chitrakar, Microsoft Intune Blog
- LowProfile 4.0
- AutoPkg 3.0 RC2
- super v4.0.0-beta3
- Setup Your Mac (1.13.0-b5) with SYM-Helper
- Latest Version of SoftRAID for Mac Adds Support for macOS Sonoma – OWC Blog
To Watch
To Listen
- What’s new at Apple with Jeremy Butcher – Mac Admins Podcast
- What does a car need to know about your sex life? – Lock and Code, Malwarebytes Labs
- Why Macs are becoming the preferred platform for IT professionals – Apple @ Work Podcast, 9to5Mac
- Jamf at Black Hat and Security Trends Report – Jamf After Dark Podcast
Just for Fun
Support
If you are enjoying what you are reading here, please spread the word and recommend it to another Mac Admin!
If you want to support me and this website even further, then consider buying one (or all) of my books. It’s like a subscription fee, but you also get a useful book or two extra!
Weekly News Summary for Admins — 2023-09-15
The Apple event this week, brought the expected iPhone 15 and Apple Watch updates. You can read all about them on Apple’s event page and the usual suspects.
(Sponsor: Mosyle)
The only Apple Unified Platform for Business
Mosyle is the only solution that fully integrates Enhanced MDM, Endpoint Security, Internet Privacy & Security, Single Sign-On, and Application Management on a single Apple-only platform.
Click here to learn why Mosyle is all you need to work with Apple.
More importantly for Mac and iOS Admins: iOS 17, iPadOS 17, and watchOS 10 will be released September 18. macOS Sonoma 14.0 will be released September 26. This is four weeks earlier than the release of macOS Ventura. There were RC releases for all beta platforms this week.
JNUC is next week, safe travel and a fun conference for everyone who is going!
If you would rather get the weekly newsletter by email, you can subscribe to the Scripting OS X Weekly Newsletter here!! (Same content, delivered to your Inbox once a week.)
Focus
News and Opinion
- Half of young women will leave their tech job by age 35, study finds – Erin Carson, CNET
- How quickly can Apple release a security update? – Howard Oakley
- Unexpected Moments – Tom Bridge
- Thunderbolt 5 is Officially on the Way. How the Best Port is Getting Even Better – Wayne G, OWC Blog
macOS Sonoma and iOS 17
- New Features available with macOS Sonoma (PDF)
- New Features available with iOS 17 (PDF)
- New Features available with iPadOS 17 (PDF)
macOS and iOS Updates
- Security content of macOS Monterey 12.6.9 (21G726)
- Security content of macOS Big Sur 11.7.10 (20G1427)
- Security content of iOS 15.7.9 and iPadOS 15.7.9
- Apple has released security updates to Big Sur and Monterey – Howard Oakley
Social Media
- David Nelson: “When reading what’s changed in the latest iPhone we tend to get comparisons to the immediate previous model. Not so helpful if you’re coming from a device that’s two or more years old. The “Compare iPhone Models” page helps. It includes devices all the way back to the iPhone 6 and the original SE. For example, I can see the weight and dimensions of my 12 Pro compared to a 15 Pro Max.
Security and Privacy
- macOS MetaStealer: New Family of Obfuscated Go Infostealers Spread in Targeted Attacks – Phil Stokes, SentinelOne
- iPhone 15 launch: Wonderlust scammers rear their heads – Christopher Boyd, Malwarebytes Labs
Support and HowTos
- Technical Paper: Device Compliance with Microsoft Intune and Jamf Pro – Jamf
- How to Upgrade macOS Using erase-install and Jamf Pro – HCS Technology Group
- Jamf Pro: Configure SMTP Server Integration with Microsoft 365 Per App Password – HCS Technology Group
- Upgrading your iPhone? Read this first – Pieter Arntz, Malwarebytes Labs
- Why cloning a System volume isn’t a good idea any more – Howard Oakley
- UseAdditionalHttpHeaders preference for MunkiReport 5.8.0 – Alan Siu
Scripting and Automation
- red5coder/jamf-return-to-service: Simple POC to demonstrate the Return to Service added to Jamf Pro 10.50
- Obtaining a Bearer Token Using API Role Authentication with Jamf – Lazy MacAdmin
- Automated Jamf Patch Workflows – Lazy Macadmin
Updates and Releases
- Privileges 1.5.4
- txhaflaire/JamfCheck: A native SwiftUI macOS application that check’s Jamf Pro, Jamf Connect and Jamf Protect on it’s state
- Introducing iMazing 3 (Mac Beta)
To Listen
- GitHub Actions and Automating MDM Infrastructure – Mac Admins Podcast
- Unpacking Black Hat and the Security Findings Report – Jamf After Dark
- The future of mobile payments? – Apple @ Work Podcast, 9to5Mac
Support
If you are enjoying what you are reading here, please spread the word and recommend it to another Mac Admin!
If you want to support me and this website even further, then consider buying one (or all) of my books. It’s like a subscription fee, but you also get a useful book or two extra!
Weekly News Summary for Admins — 2023–09–08
The news summary is back! And right in time for the Apple event next week (Tuesday, Sep 12, 10am PDT)! This is a big heavy summary to catch up on the last eight weeks. If you believe I missed something, let me know and I will add it next week.
(Sponsor: Mosyle)
The only Apple Unified Platform for Business
Mosyle is the only solution that fully integrates Enhanced MDM, Endpoint Security, Internet Privacy & Security, Single Sign-On, and Application Management on a single Apple-only platform.
Click here to learn why Mosyle is all you need to work with Apple.
We got macOS 13.5 and iOS 16.6 right at the beginning of the break and a few security updates since then. The macOS Sonoma beta is on the seventh incarnation, iOS 17 and watchOS on the eighth, and, oddly, tvOS is on the ninth.
But aside from the betas and looming system releases, there were many updates for popular MacAdmins tools and software. I myself used the break to write up a few tutorials that have been rattling around in my head for a while.
We have three more big MacAdmin conferences this year: Jamf Nation User Conference (JNUC) in Austin, Texas, USA, Sep 19–21, MacSysAdmin in Göteborg, Sweden, Oct 3–6 and Objective-by-the-Sea 6.0, in Spain, Oct 9–13.
This year, I will be presenting at MacSysAdmin in Göteborg! I have the closing session on Friday, and will be talking about “MacAdmin Tools” so do not leave early. If you are there, too, be sure to say ‘Hi!’ and you will be rewarded with with some Scripting OS X stickers.
Eight weeks of summer hiatus was a long time. There were several scheduling requirements that lead to the long break this year. I plan to organize this differently next year.
If you would rather get the weekly newsletter by email, you can subscribe to the Scripting OS X Weekly Newsletter here!! (Same content, delivered to your Inbox once a week.)
News and Opinion
- One Mac Admin’s tips on maintaining a popular Open Source project – Graham R. Pugh
- Jamf announces its acquisition of dataJAR, a leading Apple – Jamf
- Time (For You) To Give A Presentation! – Pam Lefkowitz, Radical Admin Blog
- Facebook Says Apple is Too Powerful. They’re Right. – Cory Doctorow, Electronic Frontier Foundation
- ‘Windows is a declining ecosystem,’ Jamf CEO says – Jonny Evans, Computerworld
- You Decided to Change Platforms: Now What? – Pam Lefkowitz, Radical Admin Blog
- Backblaze Drive Stats for Q2 2023 – Andy Klein, Backblaze
- Positive Changes to Apple Business Manager Signup Flows! – Tom Bridge
- Coming Soon: Platform SSO for macOS – Brian Melton-Grace, Microsoft Community Hub
- Survey: Why Apple Is Booming in the Enterprise – Kandji Blog
- The Mac Admins Community Groups Map – Dr. K
macOS Sonoma and iOS 17
- Why it is Finally Time to use Managed Apple IDs for Work – Jordan Miller
- An Alerting Vista of Sonoma – Craig Hockenberry
- Uncovering weaknesses in Apple macOS and VMWare vCenter: 12 vulnerabilities in RPC implementation – Aleksandar Nikolic, Dimitrios Tatsis, Talos
- Auditd: the logs we need, not the logs we deserve – Bob Gendler
- Testing…123…Testing – Pam Lefkowitz, Radical Admin Blog
macOS and iOS Updates
- macOS Ventura 13.5 and iOS 16.6 – Armin Briegel
- macOS Ventura 13.5.2 (22G91): About, Security
- About the security content of iOS 16.6.1 and iPadOS 16.6.1
- About the security content of watchOS 9.6.2
- Apple has released Ventura 13.5.2, an urgent security update – Howard Oakley
- macOS Ventura 13.5.2 Update (22G91) What’s New? – Mr. Macintosh
Social Media
- Aaron on X: “New in macOS Sonoma: You can now use one Mac to revive or restore another Mac that’s in DFU mode right from Finder. Previously you needed to install Apple Configurator to do this but now it’s built in! Accidentally stumbled upon this while playing around with some stuff.”
Security and Privacy
- BlueNoroff: How DPRK’s macOS RustBucket Seeks to Evade Analysis and Detection – Phil Stokes, SentinelOne
- Demo: Brute-forcing a macOS user’s real name from a browser using mDNS – Konstantin Darutkin
- ShadowVault is the latest Mac data-stealer malware, reportedly – Joshua Long, The Mac Security Blog
- Security Update: June 20 Incident Details and Remediation – Bob Phan, JumpCloud
- JumpCloud Intrusion: Attacker Infrastructure Links Compromise to North Korean APT Activity -– Tom Hegel, SentinelOne
- Apple Crimeware: Massive Rust Infostealer Campaign Aiming for macOS Sonoma Ahead of Public Release – Phil Stokes, SentinelOne
- An Apple Malware-Flagging Tool Is ‘Trivially’ Easy to Bypass – Lily Hay Newman, Wired
- Jamf Threat Labs explains their discovery of a post-exploit UI hack of Airplane Mode – Jamf Threat Labs
- XLoader’s Latest Trick: New macOS Variant Disguised as Signed OfficeNote App – Dinesh Devadoss and Phil Stokes, SentinelOne
- Bypassing App Management With TextEdit – Michael Tsai
- Bloated Binaries: How to Detect and Analyze Large macOS Malware Files – Phil Stokes, SentinelOne
- Mac users targeted in new malvertising campaign delivering Atomic Stealer – Jérôme Segura, MalwwarebytesLabs
- AI and Cybersecurity: What You Need to Know – Kandji Blog
Support and HowTos
- Git Commit Template – Clayton Burlison
- Disabling in-app review requests for apps installed from the macOS App Store – Rich Trouton
- Signing PowerShell Scripts on macOS – John C. Welch
- Gather logs with a Munki NoPkg – Kevin M. Cox
- How to Configure Escrow Buddy to Escrow a FileVault Personal Recovery Key (PRK) in Jamf Pro – HCS Technology Group
- How to turn off Activation Lock – Andrea Pepper, SimpleMDM
- RAID and macOS – Scripting OS X
- My AutoPkg Authoring Enviroment – Anthony Reimer
- Moving a user’s home or CloudStorage wants a lot of space – Eric Hemmeter
- Secure Token, Bootstrap Token, and Mac Security: How They Fit Together – Mike Boylan, Kandji
- macOS Screenshots during Setup Assistant – Jim Zajkowski
- Managing login mechanisms in the macOS authorization database – Elliot Jordan
- Finding Balance While Working Remotely – Mike Solin
- Using patch title policies + installers for different architectures – Dr. K
- What are configuration profiles? – Andrea Pepper, SimpleMDM
- LAPS Enhancements and Changes to the UIE Management Account – Tom Koehler, Jamf Tech Thoughts
- What is the Mac Evaluation Utility tool? – Jonny Evans, Computerworld
- How to build a custom macOS VM on Apple silicon – Howard Oakley
- Notes on Jamf Pro API Roles and Clients – Bryson Tyrell
- mg Text Editor – Michael Tsai
- How to Configure Account Driven Enrollment and Enroll a Personal Device in Jamf Pro – HCS Technology Group
- A Guide to Installing and Using Pantone Connect in Adobe Creative Cloud – HCS Technology Group
- Starting a sole proprietorship business to get a DUNS number for Apple Business Manager – Rich Trouton
- Jamf Protect integrates with Microsoft Sentinel – Thijs Xhaflaire
- Apple Configurator: No Space Left on Device — Mac Lovin’
- Handling a QR Code on your iPhone – Steve Hayman
- Apple Silicon and Virtual Machines: Beating the 2 VM Limit – Mykola Grymalyuk
- Jamf Pro: Organization – Rob J Schroeder
Scripting and Automation
- PowerShell version of Rich Trouton’s “Listing and downloading available macOS installers…” script – John C. Welch
- dhcav/ShortcutsForJamfPro: A collection of Shortcuts for iOS, iPadOS, macOS and even watchOS to be used with Jamf Pro
- Exploring Unicode in macOS with clui – Joel Bruner
- Intune Uploader – Tobias Almen
- Deploying Xcode on managed devices – Armin Briegel, Jamf Blog
- Jamf Pro LAPS: Retrieving Password via Terminal – Dan K. Snelson
- Generation gap: Using Shortcuts with Folder Actions – Jason Snell, Six Colors
- Build a macOS Application to Run a Shell Command with Xcode and SwiftUI: Part 2 – Armin Briegel
- Updating management status in Jamf Pro computer inventory records on Jamf Pro 10.49.0 and later – Rich Trouton
- Unmanage mobile devices & computers in Jamf Pro – Smashism
- Introduction to Shell Scripting – HCS Technology Group
- Build a notarized package with a Swift Package Manager executable – Armin Briegel
- Introducing JCDS 2.0 for uploading packages to Jamf Pro Cloud distribution points – Graham R. Pugh
- Working with osquery Data in Snowflake – t-lark.github.io
- notverypc/AutoPromo: Promote apps in a munki repo
- Removing Oracle Java from macOS – Rich Trouton
- Blocking Oracle Java Rich Trouton
- Jamf Pro: Get Mac Warranty Information – Rob J Schroeder
- khronokernel/py_sip_xnu: Python module for querying SIP status on XNU-based systems
Updates and Releases
- Jamf Pro 10.50.0
- Passkeys Public Beta – GitHub Blog
- SimpleMDM introduces scheduled scripts and auto attributes – SimpleMDM
- jeremybessard/sumb: Scheduled Updates Menu Bar
- Munki 6.3.3 Release (signed and notarized)
- jessepeterson/kmfddm v0.4.1
- Support 2.5
- MDS 5 Administrator Guide – Twocanoes Software
- swiftDialog v2.3.2 (v2.3 release notes)
- AutoPkg 3.0 RC1
- Setup Your Mac (1.12.6) via swiftDialog (2.3.2) – Dan K. Snelson
- facebookincubator/sado: A macOS signed-app shim for running daemons with reliable capabilities
- Visual Studio for Mac Retirement Announcement – Anthony Cangialosi, Visual Studio Blog (Don’t panic! This is NOT Visual Studio Code but the “Visual Studio for Mac IDE”)
- mac-ibm-notifications 3.0.3
- Baseline 1.3 Beta1
- Outset 4.0.4
- Mist 0.9.1
- erase-install 30.2
- Script2Pkg 1.1.1
- Mac Admins Open Source announces Jamf Pro SDK for Python – Nate Walck, MacAdmins.org
To Watch
- MacAD.UK 2023 Videos
- PSU MacAdmins Conference 2023 Videos
- August 2023: MacAdmins Meeting Archived Presentations and Slides Online – Marriott Library, Apple Infrastructure
To Listen
- Interview With Mr. Macintosh of MrMacintosh.com – Command-Control-Power
- Support App continues to be a must-have with latest 2.5 release – Apple@Work Podcast, 9to5Mac
- HomeKit Panel Part 2 – Mac Admins Podcast
- An influx of Elons, a hospital visit, and magic men Lock and Code S04E18
Just for Fun
Support
If you are enjoying what you are reading here, please spread the word and recommend it to another Mac Admin!
If you want to support me and this website even further, then consider buying one (or all) of my books. It’s like a subscription fee, but you also get a useful book or two extra!
Build a notarized package with a Swift Package Manager executable
One of the most popular articles on this blog is “Notarize a Command Line Tool with notarytool.” In that post I introduced a workflow for Xcode to build and notarize a custom installer package for a command line tool. This workflow also works with apps and other projects that require a customized installer package building workflow. I use it in many of my own projects.
But Xcode is not the only way to build Swift binaries. Especially for command line tools, you can also use Swift Package Manager. This provides a mostly command line based interface to building and organizing your project, which you might prefer if you want to use an IDE that is not Xcode, or have Swift projects that need to run cross-platform.
I also have an older article on building a command line tool with Swift Package Manager. But then, I did not create an installer package or notarize the resulting binary.
Placing the binary in an installer package file is the best way to distribute a binary as you can control where in the file system the binary is installed. Notarizing the pkg file is necessary when you are distributing a command line tool, since it enables installations without scary dialogs or handling quarantine flags.
Also, some of the behavior of Swift Package Manager (SPM) and Xcode have changed since the previous posts. So, this article will introduce an updated workflow using Swift Package Manager tools and how to sign, package and notarize a command line tool for distribution.
Note on nomenclature: Swift Package Manager projects are called ‘packages.’ On macOS, installer files (with the pkg
file extension) are also called ‘packages.’ We will be using SPM to build a notarized installation package (a pkg file) from a Swift package project. This is confusing. There is not much I can do about that other than using ‘installer package’ and ‘Swift package project’ to help distinguish.
Prerequisites
I wrote this article using Xcode 14.3.1 and Swift 5.8.1. It should also work with somewhat older or newer versions of Xcode and Swift, but I have not tested any explicitly.
Since I said earlier that using Swift Package Manager allows us to not use Xcode and maybe even build a cross-platform project, you may be wondering why we need Xcode. While we don’t need Xcode for our project, it is one way of installing all the tools we need, most importantly the swift
and notarytool
binaries. You get those from Developer Command Line tools, as well. We will also see that we can combine Xcode with the command line Swift Package Manager workflow, which I find a very useful setup.
To submit a binary to Apple’s notarization process you will need a Personal or Enterprise Apple Developer account, and access to the Developer ID Application
and Developer ID Installer
certificates from that account. A free Apple Developer account does not provide those certificates, but they are necessary for notarization
You can follow the instructions in the Xcode article on how to get the certificates and how to configure notarytool
with an application specific password. If you had already done this previously you should be able to re-use all of that here. When you reach the ‘Preparing the Xcode Project’ section in that article, you can stop and continue here. Apple also has some documentation on how to configure notarytool
.
The sample code we will be using will only work on macOS as it uses CoreFoundation functions. Installer packages and notarization are features of macOS, too, so this is not really a problem here. You can use this workflow to build macOS specific signed binaries and notarized installation pkg files from a cross-platform Swift package project. This will work as long as you keep in mind that the tools to sign, package and notarize only exist and/or work on macOS.
The sample code
We will build the same simple sample tool as in the last article. The prf
command (short for ‘pref’ or ‘preference’) reads a default setting’s effective value using the CFPreferencesCopyAppValue
function.
The macOS defaults
command will read preferences, but only from the user level, or from a specified file path. This ignores one of the main features of macOS’ preferences system as it will not show if a value is being managed by a different preference level, such as the global domain, a file in /Library/Preferences
, or (most importantly for MacAdmins) a configuration profile.
You can learn all about preferences and profiles in my book “Property Lists, Preferences and Profiles for Apple Administrators.”
We will build a really simple command line tool, named prf
which shows the effective value of a setting, no matter where the value comes from. You could make this tool far more elaborate, but we will keep it simple, since the code is not the actual topic for this article.
We will also be using the Swift Argument Parser package to parse command line arguments and provide a help message. We could build this simple tool without using Argument Parser, but using an external package module is one of the strengths of using Swift Package Manager.
Create the Swift Package project
With all the preparations done, it is time to create our Swift package. We will do all the work in the shell, so open Terminal or your other favorite terminal app and navigate to the directory where you want to create the project.
> cd ~/Projects
Then create a new directory with the name swift-prf
. This will contain all the files from the Swift package project. Change directory into that new directory. All following commands will assume this project directory is the current working directory.
> mkdir swift-prf
> cd swift-prf
Then run the swift
tool to setup the template structure for our command line tool or ‘executable.’
> swift package init --type executable
Creating executable package: swift-prf
Creating Package.swift
Creating .gitignore
Creating Sources/
Creating Sources/main.swift
You can inspect the hierarchy of files that the init
tool created in the Finder (open .
) or in your preferred editor or IDE.
.gitignore
Package.swift
Sources
main.swift
`
You can open this package project in Xcode. In older versions of Xcode you had to run a special swift package command to generate the Xcode project, but now, Xcode can open Swift package projects directly. Use xed
(the ‘Xcode text editor invocation tool’) to open the current directory in Xcode.
> xed .
There is a pre-filled .gitignore
(which will be hidden in Finder and probably your IDE), a Package.swift
, and a Sources
directory with a single main.swift
inside. If you want to use git (or another version control) system, now is the time to initialize with git init
.
Build the project with swift build
and/or run it with swift run
. Not surprisingly, the template prints Hello, world!
.
> swift build
Building for debugging...
[3/3] Linking swift-prf
Build complete! (0.92s)
> swift run
Building for debugging...
Build complete! (0.11s)
Hello, world!
After building, there will also be a .build
directory (also hidden in Finder, unless you toggle the visibility of invisible files using shift-command-.
) which contains all the interim files. In the debug
folder, you can find the swift-prf
executable. You can run it directly:
> .build/debug/swift-prf
Hello, world!
You can clean all the generated pieces from the .build
directory with swift package clean
. This will leave some empty folders behind but remove all the interim and final products. This means the next build is going to take much longer, but this can be helpful after reconfiguring the Package.swift file or when the compiler gets confused.
Sidenote: when you use Xcode to edit your Swift package project, and choose Build
or Run
from the Xcode interface, then it will build and run in a different location (~/Library/Developer/Xcode/DerivedData/swift-prf-<random-letters>/Build
). You need to be aware of this when you alternate between Xcode and the command line.
Configuring the Package
The Package.swift
file contains the configuration for a Swift package project. You can see that the executable package template has a single target named swift-prf
that builds from the files in Sources
.
To change the name of the executable file, change the value of the name:
of the .executableTarget
to just prf
. There is another name:
earlier in the file, that sets the name of the entire project, you can leave that being swift-prf
. They do not have to match.
Then build the project in the command line and run it directly:
> swift build
Building for debugging...
[3/3] Linking prf
Build complete! (0.51s)
> .build/debug/prf
Hello, world!
We want to add the Swift Argument Parser package to our project as a dependency, so we can use its functionality in our code. For that, we will have to add a ‘dependency’ to the project and then to the target, as well. Modify the Package.swift
file to match this:
// swift-tools-version: 5.8
// The swift-tools-version declares the minimum version of Swift required to build this package.
import PackageDescription
let package = Package(
name: "swift-prf",
products: [
.executable(name: "prf", targets: ["prf"]),
],
dependencies: [
.package(url: "https://github.com/apple/swift-argument-parser", from: "1.2.0"),
],
targets: [
.executableTarget(
name: "prf",
dependencies: [.product(name: "ArgumentParser", package: "swift-argument-parser")],
path: "Sources")
]
)
This means that our project uses the package available at the given URL, and our target is going to use the specific product (or module or framework) named ArgumentParser
from that package. Some packages have several products combined out of several targets.
You can find more information on the format of the Package.swift file in this overview, and the full documentation.
The next time you build after this change, it will download the repository, build and link to toward your executable. That might take a while. The next build should be much faster again. Also, a Package.resolved
file will appear in the project. This file caches the current versions of the included packages protecting you from unexpected changes when a package repo dependency updates. You can force Swift Package Manager to update the file with swift package update
.
Sprinkle some code
Now that we have the Swift package project prepared, we can add the code to actually do something.
First, let’s keep the ‘Hello, world!’ for a moment, but put it in the right struct
to use ArgumentParser
. Change main.swift
to:
import Foundation
import ArgumentParser
@main
struct PRF: ParsableCommand {
func run() {
print("Hello, world!")
}
}
This should build and run fine from the command line with swift build
and swift run
. However, when you open this now in Xcode, you will see an error: 'main' attribute cannot be used in a module that contains top-level code
This comes from a long-running issue in Swift. In older versions of Swift it appears on the command line, as well. The work-around is easy though. It only seems to appear when the @main
designator is the main.swift
file. We can rename our main file to PRF.swift
.
You may want to close the Xcode project window before you do this because this can confuse Xcode. If you manage to get Xcode into a confused state where the project in Xcode does not match what is on disk any more, quit Xcode and delete the .swiftpm/xcode
directory, which is where Xcode keeps its generated files.
> mv Sources/main.swift Sources/PRF.swift
Now the project should build and run the same with the Swift Package Manager tools and in Xcode.
Now we can add the ‘full’ code for our tool. Keep in mind that the goal of this tutorial is not to learn how to write complex swift code for command line tools, but to learn the infrastructure requires to create and distribute them, so this code is intentionally simple and basic.
import Foundation
import ArgumentParser
@main
struct PRF: ParsableCommand {
static var configuration = CommandConfiguration(
commandName: "prf",
abstract: "read effective preference value",
version: "1.0"
)
@Argument(help: "the preference domain, e.g. 'com.apple.dock'")
var domain: String
@Argument(help: "the preference key, e.g. 'orientation'")
var key: String
func run() {
let plist = CFPreferencesCopyAppValue(key as CFString, domain as CFString)
print(plist?.description ?? "<no value>")
}
}
When you compare that to the code from the last article, there are a few differences. We are using the @main
attribute to designate the main entry point for the code (this was added in Swift 5.3) and I have added some help text to the tool and argument declarations.
When you use Swift Argument Parser, you should study the documentation on adding help to [commands](I have added some help text to the tool and argument declarations. ) and flags, arguments and options. (To be honest, you should read the entire documentation, a lot has changed since the last article.)
When you now run the tool:
> swift run
Building for debugging...
[3/3] Linking prf
Build complete! (0.54s)
Error: Missing expected argument '<domain>'
OVERVIEW: read effective preference value
USAGE: prf <domain> <key>
ARGUMENTS:
<domain> the preference domain, e.g. 'com.apple.dock'
<key> the preference key, e.g. 'orientation'
OPTIONS:
--version Show the version.
-h, --help Show help information.
We get the help text generated by Swift Argument Parser with the extra information we provided in the code.
If you want to provide the arguments to the swift run
you have to add the executable name, as well:
> swift run prf com.apple.dock orientation
Building for debugging...
Build complete! (0.11s)
left
Or you can run the executable directly from the .build/debug
directory. (This will not automatically re-build the command like swift run
does.
> .build/debug/prf com.apple.dock orientation
left
Since we provided a version
in the CommandConfiguration
, ArgumentParser
automatically generates a --version
option:
> .build/debug/prf --version
1.0
Now that we have a simple but working tool, we can tackle the main part: we will package and notarize the tool for distribution.
Preparing the binary
When you run swift build
or swift run
it will compile the tool in a form that is optimized for debugging. This is not the form you want to distribute the binary in. Also, we want to compile the release binary as a ‘universal’ binary, which means it will contain the code for both Intel and Apple silicon, no matter which CPU architecture we are building this on.
The command to build a universal release binary is
> swift build --configuration release --arch arm64 --arch x86_64
When that command is finished, you will find the universal binary file in .build/apple/Products/Release/prf
. we can check that it contains the Intel (x86_64
) and Apple silicon (arm64
) with the lipo
tool:
> lipo -info .build/apple/Products/Release/prf
Architectures in the fat file: .build/apple/Products/Release/prf are: x86_64 arm64
For comparison, the debug version of the binary only contains the platform you are currently on:
> lipo -info .build/debug/prf
Non-fat file: .build/debug/prf is architecture: arm64
Apple’s notarization process requires submitted binaries to fulfill a few restrictions. They need a timestamped signature with a valid Developer ID and have the ‘hardened runtime’ enabled.
Xcode will always sign code it generates, but the swift
command line tool does not. We will have to sign it ourselves using the codesign
tool. You will need the full name of your “Developer ID Application” certificate for this. (Don’t confuse it with the “Developer ID Installer” certificate, which we will need later.)
You can list the available certs with
> security find-identity -p basic -v
and copy the entire name (including the quotes) of your certificate. Then run codesign
:
> codesign --sign "Developer ID Application: Your Name (ABCDEFGHJK)" --options runtime --timestamp .build/apple/Products/Release/prf
You can verify the code signature with
> codesign --display --verbose .build/apple/Products/Release/prf
Build the installation package
Now that we have prepared the binary for distribution, we can wrap it in an package installer file.
To cover all deployment scenarios, we will create a signed ‘product archive.’ You can watch my MacDevOps presentation “The Encyclopedia of Packages” for all the gory details.
First, create a directory that will contain all the files we want put in the pkg. Then we copy the binary there.
> mkdir .build/pkgroot
> cp .build/apple/Products/Release/prf .build/pkgroot/
Then build a component pkg from the pkgroot:
> pkgbuild --root .build/pkgroot --identifier com.scriptingosx.prf --version 1.0 --install-location /usr/local/bin/ prf.pkg
The --identifier
uses the common reverse domain notation. This is what the installer system on macOS uses to determine whether an installation is an upgrade, so you really need to pay attention to keep using the same identifier across different versions of the tool. The --version
value should change on every update.
The --install-location
determines where the contents of the payload (i.e. the contents of the pkgroot
directory) get installed to. /usr/local/bin/
is a useful default for macOS, but you can choose other locations here.
Next, we need to wrap the component pkg inside a distribution package.
> productbuild --package prf.pkg --identifier com.scriptingosx.prf --version 1.0 --sign "Developer ID Installer: Your Name (ABCDEFGHJK)" prf-1.0.pkg
It is important that you use the “Developer ID Installer” certificate here. The --identifier
and --version
are optional with productbuild
but this data required for some (admittedly rare) deployment scenarios, and we want to cover them all.
You can inspect the installer pkg file with a package inspection tool such as the amazing Suspicious Package. The package file should as a signed “Product Archive.”
We don’t need the component pkg anymore, and it’s presence might be confusing, so let’s remove it:
> rm prf.pkg
Note: If you want to learn more about building installation packages, check out my book “Packaging for Apple Administrators”
Notarization
We are nearly there, just two more steps.
It is important to notarize pkgs that will be installed by a user, because otherwise they will get a scary warning that Apple can’t verify the pkg for malicious software.
notarytool
submits the installer package to Apple’s Notarization process and returns the results. Use the keychain profile name you set up, following the instructions in the previous article or the instructions from the Apple Developer page.
> xcrun notarytool submit prf-1.0.pkg --keychain-profile notary-example.com --wait
This will print a lot of logging, most of which is self-explanatory. The process might stall at the “waiting” step for a while, depending on how busy Apple’s servers are. You should eventually get status: Accepted
.
If you got a different status, or if you are curious, you can get more detail about the process, including rejection reasons, with notarytool log
. You will need the ‘Submission ID’ from the submission output:
xcrun notarytool log <submission-uuid> --keychain-profile notary-example.com
As the final step, you should ‘staple’ the notarization ticket to the pkg. This means that the (signed) notarization information is attached to the pkg-file, saving a round trip to Apple’s servers to verify the notarization status when a system evaluates the downloaded installer package file.
xcrun stapler staple prf-1.0.pkg
Processing: /Users/armin/Desktop/swift-prf/prf-1.0.pkg
Processing: /Users/armin/Desktop/swift-prf/prf-1.0.pkg
The staple and validate action worked!
And with that, we have a signed and notarized installation pkg file! You can verify this with spctl
:
> spctl --assess --verbose -t install prf-1.0.pkg
prf-1.0.pkg: accepted
source=Notarized Developer ID
Automation
While it is instructive to do this process manually, it is also quite complex and error-prone. If you have been following this blog for any time, you will know that I don’t stop at detailed step-by-step instructions with explanations.
You can find a script to automate all of these steps here. The enclosing repository includes the entire project (all three files) for your reference.
There is a section at the beginning with variables to modify with the information specific to your environment and project, such as your developer ID information and the name of the credential profile for notarytool
. Then there are a few variables, such as the product name, and the installation package identifier.
Run the pkgAndNotarize.sh
script from the root of the Swift package project directory.
./pkgAndNotarize.sh
The script creates the installer pkg file in the .build
directory. The last line of output is the path to the final, signed, notarized and stapled pkg file.
The script mostly follows the process described above, with a few extras. For example, the script determines the version dynamically by running the tool with the --version
option. It also uses the modern compression options I described in this post.
If any of the steps in the script fail, you can determine what exactly failed from the output, error message and error code.
(I belief that this could probably be a makefile, but I have no experience with that (yet). I guess I will need to ‘make’ time for this…)
Conclusion
Apple provides developers and MacAdmins with amazing platforms and tools to build all kinds of powerful apps, tools and automations. But then they don’t really document any of the processes or best practices at all. The amount of searching, guesswork, and frustrating trial and error necessary to piece all of this together for a workflow like this one is quite the shocking condemnation of Apple’s documentation.
There are glimmers of hope. The documentation for the notarization process and notarytool
are exemplary.
But they only cover one piece of this puzzle. A developer building a tool has to still figure out how to
- sign all the binaries properly
- assemble the binaries and resources necessary into an installation package payload
- how (and when, and when not) to use pre- and postinstall scripts
- which kind of package installer to build and which tools to use
- securely manage the Developer ID certificates (this is especially challenging for developer teams)
- automate this workflow with Xcode or Swift Package Manager or a CI/CD system
MacAdmins often complain about poorly built installer pkgs, and often for good reasons. But to be fair, there are no best practices and little to no documentation for this from Apple. How are developers supposed to know all of this? Most MacAdmins can define what an installer package should do and not do, but wouldn’t be able to explain to a developer how to build such an installer package, let alone integrate that into their build automations. And most developers don’t even know a MacAdmin to ask about this.
Apple requires that developers create signed and notarized archives for software distribution. And I agree wholeheartedly with their motivations and goals here. But when impose requirements for distribution, you have to make the process of creating the installers the correct way easy, or at least well documented, whether you use Xcode or a different tool set, whether you want to distribute a simple self-contained app, a single command line tool, or a complex suite of tools and resources.
Apple has their work cut out to improve this. Official best practices and sample workflows for installer creation and distribution that consider and respect the requirements of MacAdmins for deployment, have been disgracefully lacking for a long time. The more requirements and security Apple piles on to application and tool distribution, the more desperately they need to provide documentation, best practices and guidance.
Until that happens, you have my paltry scripts.