MacBlog

Use AutoPkg to package GitHub repositories with no binary assets

Mon, 06 Nov 2023 00:00:00 +0000

GitHub is a popular channel for software distribution, and AutoPkg simplifies the task of packaging GitHub-released apps. AutoPkg's GitHubReleasesInfoProvider</code> processor is the standard method for identifying the latest version of software released using GitHub's Releases</a> feature, but it has one key requirement - a binary asset must be attached to the release.

However, not all software adheres to this convention. Some repositories might only contain simple shell scripts or other non-binary assets. 

To work around this requirement of GitHubReleasesInfoProvider</code>, you can use AutoPkg's URLTextSearcher</code> and URLDownloader</code> processors to download the release in the form of a zip archive. 

Every GitHub release automatically provides compressed archives of repository contents in both zip and tar formats. You can access the URLs of these archives via GitHub's REST API at the following endpoint:

https://api.github.com/repos/{OWNER}/{REPOSITORY}/releases/latest
</span></code></pre>
The JSON response contains a key called "zipball_url" which points to the zip archive:</p>
{
  ...
  "zipball_url": "https://api.github.com/repos/{OWNER}/{REPOSITORY}/zipball/v1.0.0"
  ...
}
</span></code></pre>
Extracting this URL is straighforward using the URLTextSearcher</code> processor and the regular expression zipball_url\": \"(.*)\"</code>.
Once extracted, you can download the archive using the URLDownloader processor.</p>
With an archive of the repository downloaded, you can proceed with additional processors as needed to package the repository contents.</p>
Example</h2>
Consider an example repository that contains a shell script named example.sh</code>, and your goal is to create an installer package that places an executable copy of this script in the default path.
Below is a complete example recipe process:</p>
Process</span></span>:</span>
  -</span> Processor</span></span>:</span> URLTextSearcher</span>
    Arguments</span></span>:</span>
      url</span></span>:</span> https://api.github.com/repos/{OWNER}/{REPOSITORY}/releases/latest</span>
      re_pattern</span></span>:</span> "</span>zipball_url\"</span>: \"</span>(.*)\"</span>"</span></span>
      result_output_var_name</span></span>:</span> "</span>zipball_url"</span></span>
      request_headers</span></span>:</span>
        Accept</span></span>:</span> application/vnd.github+json</span>
        X-GitHub-Api-Version</span></span>:</span> "</span>2022-11-28"</span></span>

  -</span> Processor</span></span>:</span> URLDownloader</span>
    Arguments</span></span>:</span>
      url</span></span>:</span> "</span>%zipball_url%"</span></span>
      filename</span></span>:</span> "</span>%NAME%.zip"</span></span>

  -</span> Processor</span></span>:</span> Unarchiver</span>
    Arguments</span></span>:</span>
      archive_path</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/downloads/%NAME%.zip"</span></span>

  -</span> Processor</span></span>:</span> PkgRootCreator</span>
    Arguments</span></span>:</span>
      pkgdirs</span></span>:</span> {</span>}</span></span>
      pkgroot</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/scripts"</span></span>

  -</span> Processor</span></span>:</span> PkgRootCreator</span>
    Arguments</span></span>:</span>
      pkgdirs</span></span>:</span>
        usr</span></span>:</span> "</span>0755"</span></span>
        usr/local</span></span>:</span> "</span>0755"</span></span>
        usr/local/bin</span></span>:</span> "</span>0755"</span></span>
      pkgroot</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/pkgroot"</span></span>

  -</span> Processor</span></span>:</span> Copier</span>
    Arguments</span></span>:</span>
      destination_path</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/pkgroot/usr/local/bin/example"</span></span>
      overwrite</span></span>:</span> true</span>
      source_path</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/%NAME%/*/example.sh"</span></span>

  -</span> Processor</span></span>:</span> FileCreator</span>
    Arguments</span></span>:</span>
      file_path</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/scripts/postinstall"</span></span>
      file_mode</span></span>:</span> "</span>0755"</span></span>
      file_content</span></span>:</span> |</span>
        #!/bin/bash
        /bin/chmod +x /usr/local/bin/example

</span>  -</span> Processor</span></span>:</span> PkgCreator</span>
    Arguments</span></span>:</span>
      pkg_request</span></span>:</span>
        pkgname</span></span>:</span> "</span>%NAME%"</span></span>
        pkgdir</span></span>:</span> "</span>%RECIPE_CACHE_DIR%"</span></span>
        id</span></span>:</span> "</span>org.macblog.githubexample"</span></span>
        options</span></span>:</span> purge_ds_store</span>
        scripts</span></span>:</span> scripts</span>
        version</span></span>:</span> "</span>1.0.0"</span></span>
        chown</span></span>:</span>
          -</span> path</span></span>:</span> usr</span>
            user</span></span>:</span> root</span>
            group</span></span>:</span> admin</span>
</span></code></pre>
First, the recipe will locate the latest release of the target repository and its associated zipball_url</code> using URLTextSearcher</code>.
Next, it will download the archive using URLDownloader</code>.</p>
Following that, the recipe will extract the archive and create a root directory for building an installer package.
It will then copy the target shell script example.sh</code> from the extracted repository contents to the package root directory at the required location (e.g., /usr/local/bin/example</code>). 
Finally, a postinstall</code> script is created to ensure that the file is executable after installation, and everything is packaged into a .pkg</code>.</p>
Authentication for private repos</h2>
This recipe pattern is also handy for accessing releases without assets in private repositories. 
To do this, you'll need to create a personal access token</a> and set the GITHUB_TOKEN</code> environment variable as described here</a>.
Then, simply add an Authorization</code> header using Bearer authentication to the URLTextSearcher</code> and URLDownloader</code> processors as follows:</p>
-</span> Processor</span></span>:</span> URLTextSearcher</span>
  Arguments</span></span>:</span>
    url</span></span>:</span> https://api.github.com/repos/{OWNER}/{REPOSITORY}/releases/latest</span>
    re_pattern</span></span>:</span> "</span>zipball_url\"</span>: \"</span>(.*)\"</span>"</span></span>
    result_output_var_name</span></span>:</span> "</span>zipball_url"</span></span>
    request_headers</span></span>:</span>
      Accept</span></span>:</span> application/vnd.github+json</span>
      X-GitHub-Api-Version</span></span>:</span> "</span>2022-11-28"</span></span>
      Authorization</span></span>:</span> "</span>Bearer %GITHUB_TOKEN%"</span></span>

-</span> Processor</span></span>:</span> URLDownloader</span>
  Arguments</span></span>:</span>
    url</span></span>:</span> "</span>%zipball_url%"</span></span>
    filename</span></span>:</span> "</span>%NAME%.zip"</span></span>
    request_headers</span></span>:</span>
      Authorization</span></span>:</span> "</span>Bearer %GITHUB_TOKEN%"</span></span>
</span></code></pre>
This approach keeps your options open for packaging a variety of GitHub releases, whether they include binary assets or not.</p>



Manage and enforce custom Login and Background items in macOS Ventura
Mon, 24 Oct 2022 00:00:00 +0000
macOS Ventura introduces a new feature that provides users an interface to selectively enable and disable Login and Background items.</p>
You may be familiar with "Login Items" – those apps, documents, or server connections you've configured in System Preferences > Users & Groups > Login Items</em> to automatically open when you log in.
The feature and interface has remained largely unchanged since Mac OS X Tiger.</p>
macOS Ventura extends this idea to encompass any</em> process configured to automatically launch in the background.
launchd</code> jobs like LaunchDaemons and LaunchAgents can now be toggled on or off in the new System Settings app.</p>
This means non-apps, like any custom scripts you deploy to your managed Macs, can be easily turned off.
Depending on how you manage your Macs, the ability to trivially disable management processes can have compliance, audit, and user support implications.</p>
Along with the new functionality, Apple is providing a new Configuration Profile payload to manage or "lock on" your organization's login items on MDM-enrolled Macs.
Login and Background items managed by this new payload cannot be disabled by users within the System Settings</p>
This guide will demonstrate how you can sign, package, and "lock on" a custom script.</p>
</span>

Official documentation from Apple is currently sparse</a>.
Rather than attempting to fully document all aspects of "service management" features, this guide focuses on managing custom shell scripts you might run on your organization's Macs.</p>
First, I'll offer my observations on how managed Login and Background Items work in practice.</p>
Applications configured to run in the background at login appear in System Settings > General > Login Items</em> under the Allow in Background</em> heading.</p>



    
    

Two apps configured to run in the background at login.</figcaption></figure>
Things are more complicated with items that are not apps, such as a shell script executed by a launchd</code> job.</p>
Running a shell script via a LaunchDaemon or LaunchAgent is a common pattern used by administrators to automatically perform management tasks on managed Macs.</p>
As a minimal example, the following LaunchDaemon plist will run a script at path /opt/pretendco/example-startup-script.sh</code> when the Mac starts up:</p>
<?</span>xml</span> version</span>=</span>"</span>1.0"</span></span> encoding</span>=</span>"</span>UTF-8"</span></span>?></span></span>
<!</span>DOCTYPE</span> plist</span> PUBLIC</span> "</span>-//Apple//DTD PLIST 1.0//EN"</span></span> "</span>http://www.apple.com/DTDs/PropertyList-1.0.dtd"</span></span>></span></span>
<</span>plist</span> version</span>=</span>"</span>1.0"</span></span>></span></span>
<</span>dict</span>></span></span>
    <</span>key</span>></span></span>Label</</span>key</span>></span></span>
    <</span>string</span>></span></span>com.pretendco.startup</</span>string</span>></span></span>
    <</span>key</span>></span></span>ProgramArguments</</span>key</span>></span></span>
    <</span>array</span>></span></span>
        <</span>string</span>></span></span>/opt/pretendco/example-startup-script.zsh</</span>string</span>></span></span>
    </</span>array</span>></span></span>
</</span>dict</span>></span></span>
</</span>plist</span>></span></span>
</span></code></pre>
If a launchd task executes a script using the Program</code> or ProgramArguments</code> key, that script's filename appears as the display value in System Settings.</p>



    
    

A shell script run by a LaunchDaemon lists that script's filename in System Settings > General > Login Items.</figcaption></figure>
Either of the following launchd</code> job configurations results in System Settings listing the item by filename:</p>
<</span>key</span>></span></span>Program</</span>key</span>></span></span>
<</span>string</span>></span></span>/opt/example.zsh</</span>string</span>></span></span>
</span></code></pre>
<</span>key</span>></span></span>ProgramArguments</</span>key</span>></span></span>
<</span>array</span>></span></span>
    <</span>string</span>></span></span>/opt/example.zsh</</span>string</span>></span></span>
</</span>array</span>></span></span>
</span></code></pre>
Items are listed according to what they run.
The details of how macOS determines a login item's attribution chain are complex and poorly documented.</p>
The gist is that scripts are attributed by filename in the absence of additional identity information.
I will explain a method to provide that identity information by code signing the script later in this guide.</p>
Before that, let's look at how to enforce Login and Background items via Configuration Profile.</p>

Manage items using MDM</h2>
We can use the new com.apple.servicemanagement</code> Configuration Profile payload to automatically enable, allow, and "lock on" our launchd</code> jobs and associated scripts.</p>
This payload allows you to configure rules to control which Login Items cannot be disabled by a user in System Settings > General > Login Items</em>.
Administrative users can still use launchctl</code> to unload a launchd</code> job.</strong>
Managing an item via MDM only disables the GUI control to easily toggle an item off.</p>
Rules are defined as an array of dictionaries within a Configuration Profile.
Each rule defines one of five RuleTypes</code> that control different items:</p>
Rule type</th> Manages</th></tr></thead>

TeamIdentifier</code></td> Any item signed by that team's certificate(s)</td></tr>
BundleIdentifier</code></td> Single item exactly matching a bundle identifier, e.g. org.macblog.exampleapp</code></td></tr>
Label</code></td> Single launchd</code> job definition with exactly matching label, e.g. org.macblog.startup</code></td></tr>
BundleIdentifierPrefix</code></td> Any item with a bundle identifier starting with the provided value, e.g. org.macblog</code> matches
- org.macblog.example</code>
- org.macblog.somethingelse</code></td></tr>
LabelPrefix</code></td> Any launchd</code> job definition with a label starting with the provided value, e.g. org.macblog</code> matches
- org.macblog.example</code>
- org.macblog.somethingelse</code></td></tr>
</tbody></table>
In general, you should use the most explicit rule type applicable to a particular login item.
It may be tempting to use broad TeamIdentifier</code> rules for convenience, but if we're getting new controls, I want to use them correctly.
I may not want to manage and "lock on" any</em> process a vendor might install, making a TeamIdentifier</code> rule inappropriate.</p>
Here's a complete example Configuration Profile to manage two specific LaunchDaemons by label:</p>
<?</span>xml</span> version</span>=</span>"</span>1.0"</span></span> encoding</span>=</span>"</span>UTF-8"</span></span>?></span></span>
<!</span>DOCTYPE</span> plist</span> PUBLIC</span> "</span>-//Apple//DTD PLIST 1.0//EN"</span></span> "</span>http://www.apple.com/DTDs/PropertyList-1.0.dtd"</span></span>></span></span>
<</span>plist</span> version</span>=</span>"</span>1.0"</span></span>></span></span>
    <</span>dict</span>></span></span>
        <</span>key</span>></span></span>PayloadDisplayName</</span>key</span>></span></span>
        <</span>string</span>></span></span>Example Login and Background Item Management</</span>string</span>></span></span>
        <</span>key</span>></span></span>PayloadIdentifier</</span>key</span>></span></span>
        <</span>string</span>></span></span>com.apple.servicemanagement.CA085574-9E75-4049-AACF-B7546F8B1378.privacy</</span>string</span>></span></span>
        <</span>key</span>></span></span>PayloadUUID</</span>key</span>></span></span>
        <</span>string</span>></span></span>E572AD76-1AA0-48CA-872F-3A59784148F4</</span>string</span>></span></span>
        <</span>key</span>></span></span>PayloadType</</span>key</span>></span></span>
        <</span>string</span>></span></span>Configuration</</span>string</span>></span></span>
        <</span>key</span>></span></span>PayloadScope</</span>key</span>></span></span>
        <</span>string</span>></span></span>System</</span>string</span>></span></span>
        <</span>key</span>></span></span>PayloadContent</</span>key</span>></span></span>
        <</span>array</span>></span></span>
            <</span>dict</span>></span></span>
                <</span>key</span>></span></span>PayloadDescription</</span>key</span>></span></span>
                <</span>string</span>></span></span>Configures managed Login and Background items.</</span>string</span>></span></span>
                <</span>key</span>></span></span>PayloadDisplayName</</span>key</span>></span></span>
                <</span>string</span>></span></span>Example Login and Background Item Management</</span>string</span>></span></span>
                <</span>key</span>></span></span>PayloadIdentifier</</span>key</span>></span></span>
                <</span>string</span>></span></span>A2EF9B5B-C13F-432C-8645-8FFE1C2024B7</</span>string</span>></span></span>
                <</span>key</span>></span></span>PayloadUUID</</span>key</span>></span></span>
                <</span>string</span>></span></span>023BAA5C-29D4-4CAB-8042-64832AD3E6BB</</span>string</span>></span></span>
                <</span>key</span>></span></span>PayloadType</</span>key</span>></span></span>
                <</span>string</span>></span></span>com.apple.servicemanagement</</span>string</span>></span></span>
                <</span>key</span>></span></span>PayloadOrganization</</span>key</span>></span></span>
                <</span>string</span>></span></span>Pretendco</</span>string</span>></span></span>
                <</span>key</span>></span></span>Rules</</span>key</span>></span></span>
                <</span>array</span>></span></span>
                    <</span>dict</span>></span></span>
                        <</span>key</span>></span></span>RuleType</</span>key</span>></span></span>
                        <</span>string</span>></span></span>Label</</span>string</span>></span></span>
                        <</span>key</span>></span></span>RuleValue</</span>key</span>></span></span>
                        <</span>string</span>></span></span>com.pretendco.example-startup-script</</span>string</span>></span></span>
                        <</span>key</span>></span></span>Comment</</span>key</span>></span></span>
                        <</span>string</span>></span></span>LaunchDaemon that runs a shell script at startup.</</span>string</span>></span></span>
                    </</span>dict</span>></span></span>
                    <</span>dict</span>></span></span>
                        <</span>key</span>></span></span>RuleType</</span>key</span>></span></span>
                        <</span>string</span>></span></span>Label</</span>string</span>></span></span>
                        <</span>key</span>></span></span>RuleValue</</span>key</span>></span></span>
                        <</span>string</span>></span></span>com.pretendco.second-example</</span>string</span>></span></span>
                        <</span>key</span>></span></span>Comment</</span>key</span>></span></span>
                        <</span>string</span>></span></span>Another, different, example LaunchDaemon.</</span>string</span>></span></span>
                    </</span>dict</span>></span></span>
                </</span>array</span>></span></span>
            </</span>dict</span>></span></span>
        </</span>array</span>></span></span>
    </</span>dict</span>></span></span>
</</span>plist</span>></span></span>
</span></code></pre>
Apple has provided a new command line tool in Ventura to help discover the values you might need to include in a com.apple.servicemanagement</code> profile.
You can run sudo sfltool dumpbtm</code> to view a verbose listing of all loaded Login and Background items.</p>
Here, however, I'm focused here on demonstrating how to manage custom background items you create.
Next, I'll walk through preparing a script for deployment.</p>

Packaging a startup script from scratch</h2>
Let's step through a complete example of creating a script and LaunchDaemon designed to run at startup.
We'll use munkipkg</a> to package these components for deployment. If you're not familiar with munkipkg, Elliot Jordan's You Might Like MunkiPkg guide</a> is an excellent resource.</p>
Setup</h3>
Create a new project and scaffold out the structure with the following commands.</p>
munkipkg --create macblog-example
mkdir -p macblog-example/payload/Library/LaunchDaemons
mkdir -p macblog-example/payload/opt/macblog
</span></code></pre>
The project folder will look like this:</p>
macblog-example
├── build
├── build-info.plist
├── payload
│   ├── Library
│   │   └── LaunchDaemons
│   └── opt
│       └── macblog
└── scripts
</span></code></pre>
The script</h3>
For this example, we'll create a simple script that will write a log file when run.</p>
Save the following to payload/opt/macblog/example-startup-script.zsh</code>:</p>
#!/bin/zsh
echo "$( /bin/date ): example script execution" >> /Library/Logs/example.log
exit 0
</span></code></pre>
The LaunchDaemon</h3>
Next, create a LaunchDaemon to run the script every time the computer starts up.
There are many options for launchd job definitions</a> but we'll keep it very minimal.</p>
Save the following to payload/Library/LaunchDaemons/org.macblog.example.plist</code>:</p>
<?</span>xml</span> version</span>=</span>"</span>1.0"</span></span> encoding</span>=</span>"</span>UTF-8"</span></span>?></span></span>
<!</span>DOCTYPE</span> plist</span> PUBLIC</span> "</span>-//Apple//DTD PLIST 1.0//EN"</span></span> "</span>http://www.apple.com/DTDs/PropertyList-1.0.dtd"</span></span>></span></span>
<</span>plist</span> version</span>=</span>"</span>1.0"</span></span>></span></span>
<</span>dict</span>></span></span>
    <</span>key</span>></span></span>Label</</span>key</span>></span></span>
    <</span>string</span>></span></span>org.macblog.example</</span>string</span>></span></span>
    <</span>key</span>></span></span>ProgramArguments</</span>key</span>></span></span>
    <</span>array</span>></span></span>
        <</span>string</span>></span></span>/opt/macblog/example-startup-script.zsh</</span>string</span>></span></span>
    </</span>array</span>></span></span>
</</span>dict</span>></span></span>
</</span>plist</span>></span></span>
</span></code></pre>
The postinstall</code> script</h3>
In order to set the proper file ownership and permissions, create a postinstall</code> script.
This script will run during installation of the package, after the files are in place.</p>
Save the following to scripts/postinstall</code> - note the lack of a file extension on this file; you must follow this convention:</p>
#!/bin/zsh
/bin/chmod 0744 /opt/macblog/example-startup-script.zsh
/usr/sbin/chown root:wheel /opt/macblog/example-startup-script.zsh
/bin/chmod 0644 /Library/LaunchDaemons/org.macblog.example.plist
/usr/sbin/chown root:wheel /Library/LaunchDaemons/org.macblog.example.plist
/bin/launchctl bootstrap system /Library/LaunchDaemons/org.macblog.example.plist
</span></code></pre>
This script also loads the LaunchDaemon after installation, so you won't need to reboot the system for the startup script to run for the first time.</p>
Sign the startup script</h3>
I recently wrote a full guide to signing custom scripts</a>, so I won't detail the entire process again here.
Go read that guide first.</p>
Use a Developer ID Application</strong> certificate issued by Apple to code sign the startup script:</p>
/usr/bin/codesign --sign "Developer ID Application: MacBlog.org (SHJS42SFS32S)" \
    --identifier "org.macblog.example" \
    payload/opt/macblog/example-startup-script.zsh
</span></code></pre>
By signing the script, we provide identity information to macOS about the authorship of the code.
These details are used to display the attribution of the item in System Settings > General > Login Items</em>.</p>
This is the key to properly managing the login item.
Signing the script provides the idenity information macOS needs to attribute the login item correctly.</mark></p>
Edit build-info.plist</code></h3>
build-info.plist</code> controls various options for how the package is built.
The MunkiPkg readme details all available build-info keys</a> and offers guidance on their use.</p>
I suggest you sign the package</a> by including signing_info</code>.
If we're code signing the deployed startup script, we might as well code sign the deployment package too, right?
You'll need a Developer ID Installer</strong> certificate from Apple to sign the package.</p>
Package it all up and test</h3>
The full project layout now looks like this:</p>
macblog-example
├── build
├── build-info.plist
├── payload
│   ├── Library
│   │   └── LaunchDaemons
│   │       └── org.macblog.example.plist
│   └── opt
│       └── macblog
│           └── example-startup-script.zsh
└── scripts
    └── postinstall
</span></code></pre>
Make sure you're in the directory containing the macblog-example</code> project, then run:</p>
munkipkg macblog-example
</span></code></pre>
This outputs your completed package to the macblog-example/build</code> directory.</p>
If you install the finalized package, you'll notice sudo launchctl list</code> will now report the the org.macblog.example</code> job running, and /Library/Logs/example.log</code> will show an entry.</p>
More importantly, System Settings > General > Login Items</em> will list a new item attributed to the signing identity you used to sign the script!</p>



    
    

A signed script attributed to the signing identity.</figcaption></figure>
The UI displays the attribution of what's ultimately being executed</em> – in this case, the example-startup-script.zsh</code> file.
Since that file is signed, the identity information tied to that certificate is shown in System Settings</em>.</p>
The LaunchDaemon does not determine the attribution shown in the interface.</strong>
Think about it this way: the interface displays identity information about what's running, not what "causes" it to run.</mark></p>
Manage the script using MDM</h3>
Create a Configuration Profile using the example above.
The specific rule to manage the custom script should look like this:</p>
<</span>array</span>></span></span>
    <</span>dict</span>></span></span>
        <</span>key</span>></span></span>RuleType</</span>key</span>></span></span>
        <</span>string</span>></span></span>Label</</span>string</span>></span></span>
        <</span>key</span>></span></span>RuleValue</</span>key</span>></span></span>
        <</span>string</span>></span></span>org.macblog.example</</span>string</span>></span></span>
        <</span>key</span>></span></span>Comment</</span>key</span>></span></span>
        <</span>string</span>></span></span>Example rule</</span>string</span>></span></span>
    </</span>dict</span>></span></span>
</</span>array</span>></span></span>
</span></code></pre>
Note that the RuleValue</code> must match the Label</code> of the LaunchDaemon we created earlier.</p>
For the sake of completeness, a full example Configuration Profile will look like this:</p>
<?</span>xml</span> version</span>=</span>"</span>1.0"</span></span> encoding</span>=</span>"</span>UTF-8"</span></span>?></span></span>
<!</span>DOCTYPE</span> plist</span> PUBLIC</span> "</span>-//Apple//DTD PLIST 1.0//EN"</span></span> "</span>http://www.apple.com/DTDs/PropertyList-1.0.dtd"</span></span>></span></span>
<</span>plist</span> version</span>=</span>"</span>1.0"</span></span>></span></span>
    <</span>dict</span>></span></span>
        <</span>key</span>></span></span>PayloadDisplayName</</span>key</span>></span></span>
        <</span>string</span>></span></span>Example Login and Background Item Management</</span>string</span>></span></span>
        <</span>key</span>></span></span>PayloadIdentifier</</span>key</span>></span></span>
        <</span>string</span>></span></span>com.apple.servicemanagement.CA085574-9E75-4049-AACF-B7546F8B1378.privacy</</span>string</span>></span></span>
        <</span>key</span>></span></span>PayloadUUID</</span>key</span>></span></span>
        <</span>string</span>></span></span>E572AD76-1AA0-48CA-872F-3A59784148F4</</span>string</span>></span></span>
        <</span>key</span>></span></span>PayloadType</</span>key</span>></span></span>
        <</span>string</span>></span></span>Configuration</</span>string</span>></span></span>
        <</span>key</span>></span></span>PayloadScope</</span>key</span>></span></span>
        <</span>string</span>></span></span>System</</span>string</span>></span></span>
        <</span>key</span>></span></span>PayloadContent</</span>key</span>></span></span>
        <</span>array</span>></span></span>
            <</span>dict</span>></span></span>
                <</span>key</span>></span></span>PayloadDescription</</span>key</span>></span></span>
                <</span>string</span>></span></span>Configures managed Login and Background items.</</span>string</span>></span></span>
                <</span>key</span>></span></span>PayloadDisplayName</</span>key</span>></span></span>
                <</span>string</span>></span></span>Example Login and Background Item Management</</span>string</span>></span></span>
                <</span>key</span>></span></span>PayloadIdentifier</</span>key</span>></span></span>
                <</span>string</span>></span></span>A2EF9B5B-C13F-432C-8645-8FFE1C2024B7</</span>string</span>></span></span>
                <</span>key</span>></span></span>PayloadUUID</</span>key</span>></span></span>
                <</span>string</span>></span></span>023BAA5C-29D4-4CAB-8042-64832AD3E6BB</</span>string</span>></span></span>
                <</span>key</span>></span></span>PayloadType</</span>key</span>></span></span>
                <</span>string</span>></span></span>com.apple.servicemanagement</</span>string</span>></span></span>
                <</span>key</span>></span></span>PayloadOrganization</</span>key</span>></span></span>
                <</span>string</span>></span></span>Pretendco</</span>string</span>></span></span>
                <</span>key</span>></span></span>Rules</</span>key</span>></span></span>
                <</span>array</span>></span></span>
                    <</span>dict</span>></span></span>
                        <</span>key</span>></span></span>RuleType</</span>key</span>></span></span>
                        <</span>string</span>></span></span>Label</</span>string</span>></span></span>
                        <</span>key</span>></span></span>RuleValue</</span>key</span>></span></span>
                        <</span>string</span>></span></span>org.macblog.example</</span>string</span>></span></span>
                        <</span>key</span>></span></span>Comment</</span>key</span>></span></span>
                        <</span>string</span>></span></span>Example rule</</span>string</span>></span></span>
                    </</span>dict</span>></span></span>
                </</span>array</span>></span></span>
            </</span>dict</span>></span></span>
        </</span>array</span>></span></span>
    </</span>dict</span>></span></span>
</</span>plist</span>></span></span>
</span></code></pre>
When deployed to your endpoints via MDM, the Configuration Profile applies the rules provided.
Since we signed the script being executed, its identity information is shown in Login Items.
The script is flagged as "managed by your organization" and is "locked on."</p>



    
    

Managed login item locked on, with proper identity information.</figcaption></figure>
All done!</p>
Avoid pitfalls</h3>
I've seen some launchd configurations that use the ProgramArguments</code> array to first specify the path to an interpreter, then the path to a script, like so:</p>
<</span>key</span>></span></span>ProgramArguments</</span>key</span>></span></span>
<</span>array</span>></span></span>
    <</span>string</span>></span></span>/bin/zsh</</span>string</span>></span></span>
    <</span>string</span>></span></span>/opt/example.zsh</</span>string</span>></span></span>
</</span>array</span>></span></span>
</span></code></pre>
This tells macOS that /bin/zsh</code> (or bash, or Python, etc) is the process your LaunchDaemon is launching, which your script as an argument.
That's wrong, and it causes macOS to attribute the interpretter as the launched process.</p>



    
    

Listing a script's interpretter in the launchd plist will lead to an incorrect attribution in System Settings.</figcaption></figure>
Don't do this.</strong>
You should set the path to the script's interpreter in its shebang, then make the script itself executable.</p>
Future</h2>
Managing legacy launchd plists works fine for now in Ventura, but there's a reason they're marked legacy</strong></a>.</p>
The concept of "login items" and the new SMAppService</a> API signals a transition in Apple's recommended application design process.</mark>
All helper resources should live inside an app bundle, and macOS will increasingly expect items to be deployed this way.</p>
In a future version of macOS, it will likely be the only</strong> method to automatically launch a process.
Deleting an app bundle would delete all associated resources and automated processes.
That's a win for the end user.</p>
With this clear signal toward a future without LaunchDaemons and LaunchAgents, I'm personally going to invest more time in learning Swift.</p>


How to sign scripts and other custom code
Tue, 04 Oct 2022 00:00:00 +0000
Code signing is a method of certifying that a program or script was created by a specific party, and has not been altered since it was signed.</p>
While code signing is typically discussed in the context of apps (.app bundles), the same concept applies to almost any file stored on disk.
You can easily code sign custom scripts and other files you deploy on your managed Macs.</p>
This article provides an overview of why and how you might want to do that.</p>
Why sign your code as a Mac administrator?</h2>
Signing your code provides a few benefits.</p>
First, it certifies authenticity</strong>.
Signed code provides macOS (and your users) a mechanism to verify that a program was created by a specific trusted entity, and deployed to the Mac without modification.</p>
Second, it verifies code integrity</strong>.
If a user or malicious process modifies the code, a code signature check will fail.
As an administrator, you can leverage code signature verification to detect when custom programs have been altered or tampered with.</p>
Third, macOS continues to surface security- and privacy-related information within the macOS interface.
Things that used to be "behind the scenes," like programs an administrator might run an organizationally managed Mac, are becoming more visible.</p>
This increased visibility is good for end users, and means we need to take an extra step as administrators to supply identity information about the programs we deploy.</p>
Signed scripts are not necessarily secure scripts</h2>
It's important to note that the presence of a code signature does not mean a script is "safe."
Code signing does not evaluate a script for security vulnerabilities, malicious behavior, or code correctness.</mark>
The signature only assures that the script was provided by some entity and has not been changed since it was provided.</p>
For app bundles, Gatekeeper assesses the code signature when a user opens that app for the first time.
Changes to the bundle's contents after the time of signing will invalidate that signature.
If the signature is invalid, Gatekeeper prevents the app from running.</p>
Gatekeeper does no such assessment for code signed scripts you might run by automation (like via launchd</code>) on a managed Mac.
It offers no protection against scripts with invalid signatures.</p>
A malicious actor could modify external files referenced by a script, alter its interpreter, or try a number of other attacks – all without invalidating that script's signature.
macOS makes no attempt to validate a script's contents or referenced resources.</p>
Signed scripts are certainly no less</em> secure to run or deploy than unsigned scripts, but please do not mistake code signing as a security practice</strong>.</p>
What can I sign?</h2>
You can sign just about any "flat" file.
Text files; shell scripts; Python modules; photo files; PDFs; XML property list files like LaunchDaemons and LaunchAgents.</p>
Shell scripts are the most relevant file type for most administrators, but the steps below are the same for any file type you might sign.</p>
Get a signing certificate</h2>
A foundational element of all public key infrastructure is trust.
A code signing certificate needs to be issued by a certificate authority that macOS trusts in order to be considered valid.</p>
The best place to get a trusted code signing certificate is from Apple.
Members of the Apple Developer Program</a> can generate one of several different certificate types suitable for code signing.</p>
I recommend the Developer ID Application</strong> certificate.
This certificate type includes the Code Signing extended key usage object identifier 1.3.6.1.5.5.7.3.3</code> required to sign code.</p>

Sign in to the Apple Developer Program account portal.</li>
Click "Certificates, IDs & Profiles".</li>
Click the dropdown menu near the upper left labeled "iOS, tvOS, watchOS" then select "macOS".</li>
Click "All" under the "Certificates" heading, then click the plus button near the upper right.</li>
When prompted "What type of certificate do you need?", select "Developer ID", click Continue, then select "Developer ID Application</strong>."</li>
Follow Apple's on-screen instructions to generate a Certificate Signing Request (CSR) and install the resultant certificate in your login keychain.</li>
</ol>
Other certificates available from Apple may also work, but the Developer ID Application</strong> certificate is the best choice for this task.</p>
If you do not participate in the Apple Developer Program, other vendors may provide code signing certificates.
You can also easily generate a self-signed code signing certificate</a> on your Mac.
However, self-signed or third-party certificates are unlikely to be trusted by default on your client Macs.</p>
Make your life easier and use an Apple-provided code signing certificate.</p>
How to sign a file</h2>
You'll need to know the common name of the certificate you wish to use for code signing.
You can list the certificates installed in your keychain that are suitable for code signing with the following command:</p>
/usr/bin/security find-identity -p codesigning -v
</span></code></pre>
A list of code signing certificates will be displayed on screen.</p>
  1) {hash} "Developer ID Application: MacBlog.org (TEAMID)"
     1 valid identities found
</span></code></pre>
The SHA-1 fingerprint and common name is displayed for each valid code signing certificate in your login keychain.
Note the common name (in quotes) of the certificate you'd like to use.
You'll need to provide that exact common name as an argument to the codesign</code> binary.</p>
/usr/bin/codesign --sign "{signing identity}" \
    --identifier "{reverse-DNS string}" \
    /path/to/file.zsh
</span></code></pre>
In practice, this would look something like:</p>
/usr/bin/codesign --sign "Developer ID Application: MacBlog.org (SHJS42SFS32S)" \
    --identifier "org.macblog.example" \
    ~/Code/example.zsh
</span></code></pre>
The first option, --sign</code>, tells codesign</code> we wish to sign a file.
We follow that option with the full name of the signing identity we wish to use.
This is one of the valid signing identities we listed earlier using the security</code> command.
Typically, this will be the common name of the Developer ID certificate you generated in the Apple Developer portal.</p>
The second option, --identifier</code>, is optional but recommended.
By convention, the identifier should be a reverse-DNS formatted</a> string that uniquely identifies your program.</p>
If you omit the --identifier</code> option, the file's name (minus extension) is used as a default identifier value.
Again, the option is not required, but it helps reduce confusion.</p>
Finally, pass the path to the file you want to sign.
After executing the command you will be prompted to provide your keychain password (assuming your signing identity is stored in the login keychain).
This authorizes the codesign</code> utility to access the private key for that certificate stored in your keychain.</p>
The file is now signed!</p>
Where is the signature stored?</h2>
When developing and signing a full app bundle, the resultant .app</code> will contain a MyApp.app/Contents/_CodeSignature</code> folder containing information about the code signature.</p>
Single files like scripts, however, don't have a directory structure.</p>
Instead, the signature is stored in the file's extended attributes.
To quote Apple's macOS Code Signing in depth article</a>:</p>

...code signing uses extended attributes to store signatures in non-Mach-O executables such as script files.
If the extended attributes are lost then the program's signature will be broken.
Many file transfer techniques do not preserve extended attributes...</p>
</blockquote>
You can list a file's extended attributes using xattr</code>:</p>
xattr -l /path/to/file.pdf
</span></code></pre>
Note the com.apple.cs.CodeDirectory</code> and com.apple.cs.CodeRequirements</code> attributes listed in the output.
These store the components of the single file's code signature.</p>
Verify a code signature</h2>
The codesign</code> binary can also verify the integrity of a file's code signature with the -v</code> or --verify</code> flag.
This tool frustratingly interprets the short -v</code> flag as either "verify" or "verbose" depending on the context of other passed flags.
I stick with the longer form --verify</code> to avoid confusion.</p>
/usr/bin/codesign --verify /path/to/script.zsh
</span></code></pre>
No output (and a 0</code> return code) means the signature is valid and the file is unaltered since being signed.
If you're interested in output, adding a second v</code> flag will provide more detail.</p>
$ /usr/bin/codesign --verify -v /path/to/script.zsh
script.zsh: valid on disk
script.zsh: satisfies its Designated Requirement
</span></code></pre>
Otherwise, specifics of the problem with a signature will be displayed, and the command returns an error code.</p>
Because codesign</code>'s verify</code> function returns proper success or failure status codes, it's easy to validate a code signature within the context of another shell script.
Here is a small example:</p>
if /usr/bin/codesign -v "/path/to/file.zsh"; then
    echo "Code signature is valid."
else
    echo "Code signature is invalid!"
fi
</span></code></pre>
Your configuration management system can run checks like the above to validate the integrity of custom scripts deployed on your endpoints.
If the signature check fails, you know you need to redeploy the script.</p>
Delivery</h2>
Source control systems like Git will drop extended attributes from files when committed.
If you sign a script, then commit it to a Git repository, it will no longer be signed.</p>
Additionally, your configuration management tool may or may not be able to distribute files with extended attributes – and thus code signing – intact.</p>
Because of these limitations, I recommend you package any signed code as a final step before distribution.
Signed scripts will</strong> retain extended attributes and remain signed when delivered to managed Macs if you package them. </p>
Common signing problems</h2>
I mentioned you can code sign pretty much any file type.
This includes images, PDFs, text files – almost anything (though in some cases, I'm not sure why you would want to).</p>
If you try to sign an incompatible file – like a directory – you'll get an error message stating bundle format unrecognized, invalid, or unsuitable</code>.</p>
If you receive the error resource fork, Finder information, or similar detritus not allowed</code>, this indicates the file has extended attributes that are incompatible with computing a code signature hash.
You may be able to discard these attributes if they are not essential to the file type. For example, the most common incompatible extended attribute is the legacy "Finder Info" stored in the com.apple.FinderInfo</code> attribute. This attribute contains metadata like Finder tags and other information that is unlikely relavent for files mass deployed by an administrator.</p>
Again, list the file's extended attributes using xattr</code>:</p>
xattr -l /path/to/file.pdf
</span></code></pre>
Note the com.apple.FinderInfo</code> attribute in the ouput.</p>
Removing the "Finder Info" attribute is as simple as xattr -d com.apple.FinderInfo /path/to/file.pdf</code>.
Or, remove all</em> extended attributes via xattr -c /path/to/file.pdf</code>.
You should then be able to code sign the file.</p>
But remember – do not strip all extended attributes after</em> signing the file.
That would remove the signature!</p>
Further reading</h2>
I've covered the basics here, but will close with a few recommended resources for more information on code signing within macOS.</p>

Apple - TN3127: Inside Code Signing: Requirements</a></li>
Apple - About Code Signing</a></li>
Apple - TN2206 macOS Code Signing In Depth</a></li>
</ul>


How to examine the network traffic of MDM enrollment during Setup Assistant
Sat, 28 May 2022 00:00:00 +0000
Part of my job is to test (and re-test) first-time setup workflows for new and
repurposed Macs.</p>
I recently needed to analyze the flow of network traffic during initial MDM
enrollment to confirm an on-premise network was permitting all required traffic.</p>
The tcpdump</code> tool – included with macOS – is a powerful utility that allows you
to record all network traffic passing through any interface on the Mac. It
requires elevated privileges to run, however. This presents a problem, since we
do not yet have an account capable of running elevated processes during Setup
Assistant. We haven't even created a local account yet!</p>
To work around this, we need to enable the root</code> account before</em> proceeding
through Setup Assistant</strong>.</p>
</span>
I strongly recommend doing these sorts of analyses on a dedicated test Mac
that you don't mind erasing.</mark> Gather the data you need, then erase it.</p>
Reinstall macOS</h2>
First, we need to return the Mac to a "fresh" state by reinstalling macOS.</p>
Apple provides complete instructions on reinstalling the operating system</a>.</p>
If you're using a Mac with an Apple Silicon chip, you can very</em> quickly
restore the Mac using Apple Configurator</a>.</p>
Enable root</code> from macOS Recovery</h2>
Next, we need to temporarily</em> enable the root</code> account by setting a
password for it. We'll disable it later, but this is required</strong> to be able to
run privileged processes during Setup Assistant.</p>


Start up the Mac in Recovery mode</a>.</p>
</li>

Once Recovery loads, select Utilities > Terminal</em> on the top menu to open a
Terminal window.</p>
</li>

Initiate a password reset for the root</code> account using the following command,
depending on whether the Mac has an Apple Silicon or Intel chip:</p>
For a Mac with an Apple Silicon chip...</em></p>
dscl -f /Volumes/Data/private/var/db/dslocal/nodes/Default localhost -passwd /Local/Default/Users/root
</span></code></pre>
For a Mac with an Intel chip...</em></p>
dscl -f /Volumes/Macintosh\ HD\ -\ Data/private/var/db/dslocal/nodes/Default localhost -passwd /Local/Default/Users/root
</span></code></pre>
</li>

When prompted to enter a New password:</code>, type in the password you wish to
use with the root</code> account. The value will not be displayed on screen, and
you will not</em> be prompted to confirm it, so use caution.</p>
</li>

Restart the Mac by typing reboot</code> then pressing Return</kbd>.</p>
</li>
</ol>
Open a Terminal during Setup Assistant</h2>
When you start up the Mac, you'll see the "hello" screen and Setup Assistant
will begin. Select your language to continue.</p>
Next, press ⌃ Control</kbd> + ⌥ Option</kbd> + ⌘ Command</kbd> +
T</kbd> on the keyboard to open a Terminal window.</p>
Terminal will open in the background, and you'll be able to switch back and
forth between the Setup Assistant and Terminal windows.</p>
Setup Assistant runs under the temporary _mbsetupuser</code> user account. This is a
standard – rather than administrator – account. Elevate to root by typing su -</code>, then entering the password you previously set for the root account in macOS
Recovery.</p>



    
    

</figure>
Great, now we have a root</code> shell!</p>
Run tcpdump</code></h2>
With a root shell, we can run elevated processes like tcpdump</code>.</p>
Advance through Setup Assistant until you reach the Remote Management</strong>
screen. Switch focus to the Terminal window, then run:</p>
tcpdump -nn -i any | tee -a /Users/Shared/enrollment.dump
</span></code></pre>
This will display all traffic for all network interfaces, and will skip reverse
resolution of network addresses to DNS names. I find these options useful to see
where traffic is flowing, and the unresolved IP addresses and port numbers are
the relevant bits of information I'm after.</p>
I also use the tee</code> program to simultaneously print the traffic to standard
output and also save a log to a known location. Writing the output to a file
within /Users/Shared</code> ensures the file persists through any reboots and is
accessible once Setup Assistant completes. You could use tcpdump</code>'s -w</code> flag
to save the output to a file, but this creates a binary file that isn't
immediately readable. Using tee</code> is my personal preference.</p>
There are tons of options for tcpdump</code>, which is not the point of this post. I
recommend Apple's developer documentation on recording a packet
trace</a>, and Daniel Miessler's tcpdump tutorial</a> for
extensive help using the tool.</p>
Clean up</h2>
Once MDM enrollment completes, switch focus to the Terminal window and press
⌘ Command</kbd> + C</kbd> to quit the tcmpdump</code> process.</p>
The packet trace is displayed in the Terminal window for you to analyze. If
you've also tee</code>'d the output to a file, you'll be able to copy that
file to another system for analysis after you've completed Setup Assistant.</p>
The only thing left to do is disable root</code> login. Do this from your
administrator-level account by running:</p>
dscl . -create /Users/root UserShell /usr/bin/false
</span></code></pre>
Or – since you're doing this on a test device – erase the Mac and start over
fresh!</p>


Slides and video for the 'Solving problems with custom AutoPkg processors' session at the University of Utah Mac Admin Meeting
Fri, 20 May 2022 00:00:00 +0000
I recently presented at the monthly University of Utah Mac Admin Meeting</a>
about two of my custom AutoPkg processors: DatetimeOutputter</a> and
AppIconExtractor</a>.</p>
Here are links to a recording of the presentation and the associated slides:</p>

Solving problems with custom AutoPkg processors</a></li>
Slides (PDF)</a></li>
</ul>


Output the Date and Time in AutoPkg Recipes
Tue, 01 Mar 2022 00:00:00 +0000
I recently needed to use the date and time of an AutoPkg run from within the
context of recipe.</p>
While AutoPkg itself is aware of the date and time of a run, that information is
not accessible to other processors within the recipe.</p>
To fill this need, I wrote a new AutoPkg processor: DatetimeOutputter</strong>.</p>
DatetimeOutputter</strong> helps you reference the current date and time as a
variable within your AutoPkg recipes. Additionally, it can calculate future and
past dates to enhance advanced workflows.</p>
</span>Current date and time</h2>
At its core, DatetimeOutputter</strong> adds a datetime</code> variable to an AutoPkg
recipe execution. The datetime is outputted in ISO 8601 format relevant to the
local time of the computer running the recipe.</p>
Calling the processor using Shared Processor</a> syntax, with no
arguments, invokes this default behavior. Here are examples in both XML and YAML
recipe format.</p>
XML:</p>
<</span>key</span>></span></span>Process</</span>key</span>></span></span>
<</span>array</span>></span></span>
    <</span>dict</span>></span></span>
        <</span>key</span>></span></span>Processor</</span>key</span>></span></span>
        <</span>string</span>></span></span>com.github.haircut.processors/DatetimeOutputter</</span>string</span>></span></span>
    </</span>dict</span>></span></span>
</</span>array</span>></span></span>
</span></code></pre>
YAML:</p>
Process</span></span>:</span>
  -</span> Processor</span></span>:</span> com.github.haircut.processors/DatetimeOutputter</span>
</span></code></pre>
This will output a new datetime</code> variable you can use in subsequent processors.
datetime</code> will look something like 2022-03-01T09:45:45.544391</code> by default.</p>
You can control the output format by supplying a datetime_format</code> argument. The
processor accepts any strftime</a>-compatible format.</p>
Additionally, you can pass the use_utc</code> argument as True</code> to output the
datetime relative to UTC rather than your computer's local time.</p>
This example illustrates both concepts:</p>
Process</span></span>:</span>
  -</span> Processor</span></span>:</span> com.github.haircut.processors/DatetimeOutputter</span>
    Arguments</span></span>:</span>
      datetime_format</span></span>:</span> "</span>%A, %B %e, %Y at %l:%M %p"</span></span>
      use_utc</span></span>:</span> True</span>
</span></code></pre>
This would output something like Tuesday, March 1, 2022 at 1:45 PM</code> based on
UTC time.</p>
Past and future dates</h2>
It's handy to know when a recipe runs, but determining past and future dates –
e.g. one week from now, or 3 days ago – can augment many workflows.</p>
DatetimeOutputter</strong> can generate an arbitrary number of datetime "deltas." A
datetime delta adds or subtracts time from the current datetime and outputs a
variable in your preferred format.</p>
Outputting a delta requires specifying a few arguments.</p>

output_name</code>: the output variable name for the time delta. Whatever you set
here is the variable name you can use in subsequent processors.</li>
direction</code>: specify whether the generated datetime should be in the future</code>
or past</code>.</li>
format</code>: the strftime</a>-compatible format to output the datetime.</li>
interval</code>: a dictionary of keys specifying one or more values to add or
subtract from the current datetime. Valid keys are: weeks</code>, days</code>, hours</code>,
minutes</code>, seconds</code>, microseconds</code>, and milliseconds</code>.</li>
</ul>
The interval</code> argument accepts any number of keyword arguments compatible with
Python's timedelta object</a>, as listed above. This means you may need
to convert far-future or past intervals to "weeks" or "days;" e.g. instead of
specifying months: 2</code>, use weeks: 8</code>.</p>
Here's an example of outputting two deltas:</p>
-</span> Processor</span></span>:</span> com.github.haircut.processors/DatetimeOutputter</span>
  Arguments</span></span>:</span>
    deltas</span></span>:</span>
      -</span> output_name</span></span>:</span> one_week_in_future</span>
        direction</span></span>:</span> future</span>
        datetime_format</span></span>:</span> "</span>%Y-%m-%d 00:00:00"</span></span>
        interval</span></span>:</span>
          weeks</span></span>:</span> 1</span>
      -</span> output_name</span></span>:</span> two_days_six_hours_twelve_minutes_ago</span>
        direction</span></span>:</span> past</span>
        datetime_format</span></span>:</span> "</span>%A, %B %e, at %Y %H:%M:%S"</span></span>
        interval</span></span>:</span>
          days</span></span>:</span> 2</span>
          hours</span></span>:</span> 6</span>
          minutes</span></span>:</span> 12</span>
</span></code></pre>
This would output two new variables as follows:</p>

one_week_in_future</code> with the value 2022-03-08 00:00:00</code></li>
two_days_six_hours_twelve_minutes_ago</code> with the value Sunday, February 27, 2022 at 03:33:45</code></li>
</ul>
You can output as many deltas as you need by simply adding new dictionaries to
the deltas</code> array of the processor. Each will be available for use by later
processors via variable substitution.</p>
Deltas always respect the use_utc</code> option of the processor, if set. In a single
run of DatetimeOutputter</strong> you cannot output UTC- and non-UTC-based datetimes.
If you have a need for this, run DatetimeOutputter</strong> multiple times in your
recipe, setting use_utc</code> accordingly.</p>
Example use cases</h2>
Keep it simple with just the date and time</h3>
In the simplest use case, you might wish to note the date a package was uploaded
by JamfUploader</a> within the Jamf Pro package notes field. Call
DatetimeOutputter</strong> first to generate the datetime</code> variable, then reference
that variable as %datetime%</code> in the next processor like so:</p>
Process</span></span>:</span>
  -</span> Processor</span></span>:</span> com.github.haircut.processors/DatetimeOutputter</span>
  -</span> Processor</span></span>:</span> com.github.grahampugh.jamf-upload.processors/JamfPackageUploader</span>
    Arguments</span></span>:</span>
      pkg_notes</span></span>:</span> "</span>Uploaded via AutoPkg %datetime%"</span></span>
</span></code></pre>
Output a future datetime for use with Munki's "force install after date" feature</h3>
Munki includes a feature to force installation of a package after a specified
date</a>. Setting the force_install_after_date</code> key in a package's pkginfo</code>
dictionary will cause client Macs to forcefully logout or restart to install the
software after that (local) date and time.</p>
If you use this functionality, Munki recommends setting the
force_install_after_date</code> to at least 2 weeks in the future.</p>
DatetimeOutputter</strong> can help you generate this future date in the required
format:</p>
-</span> Processor</span></span>:</span> com.github.haircut.processors/DatetimeOutputter</span>
  Arguments</span></span>:</span>
    format</span></span>:</span> "</span>%Y-%m-%dT%H:%M:%SZ"</span></span>
    deltas</span></span>:</span>
      -</span> output_name</span></span>:</span> force_after</span>
        direction</span></span>:</span> future</span>
        interval</span></span>:</span>
          weeks</span></span>:</span> 2</span>

-</span> Processor</span></span>:</span> MunkiImporter</span>
  Arguments</span></span>:</span>
    MUNKI_REPO</span></span>:</span> <path to Munki repo></span>
    pkg_path</span></span>:</span> "</span>%pkg%"</span></span>
    pkginfo</span></span>:</span>
      force_install_after_date</span></span>:</span> "</span>%force_after%"</span></span>
</span></code></pre>
This will automate the calculation of a two-week window after uploading the
package during which users will be prompted – but not forced – to install the
package. After force_date</code> passes, users will be forced to install the
software.</p>
Output a future date for use with a Jamf Pro policy activation date</h3>
You might wish to delay the installation of an application update for some
number of days after release. One way to do this is to configure a Jamf Pro
policy to include the "Activation Date/Time" server-side limitation. This
prevents the policy from running before the configured date and time.</p>
DatetimeOutputter</strong> can generate a dynamic datetime stamp n</em> number of days
in the future. This means the new version of an application will be uploaded to
your Jamf Pro server, and the installation policy ready to go when the
Activation Date/Time rolls around. Automatically!</p>
First, we add an activation_date</code> key to the date_time_limitations</code> of a
policy template. We populate the key with an %activation_date%</code> substitution
variable we will later define within the associated AutoPkg recipe.</p>
Install-after-1-week.xml</code></p>
<?</span>xml</span> version</span>=</span>"</span>1.0"</span></span> encoding</span>=</span>"</span>UTF-8"</span></span>?></span></span>
<</span>policy</span>></span></span>
    <</span>general</span>></span></span>
        <</span>name</span>></span></span>Install %NAME% 1 Week After Release</</span>name</span>></span></span>
        <</span>enabled</span>></span></span>true</</span>enabled</span>></span></span>
        <</span>trigger</span>></span></span>CHECKIN</</span>trigger</span>></span></span>
        <</span>trigger_checkin</span>></span></span>true</</span>trigger_checkin</span>></span></span>
        <</span>frequency</span>></span></span>Once per computer</</span>frequency</span>></span></span>
        <</span>date_time_limitations</span>></span></span>
            <</span>activation_date</span>></span></span>%activation_date%</</span>activation_date</span>></span></span>
        </</span>date_time_limitations</span>></span></span>
    </</span>general</span>></span></span>
    <</span>scope</span>></span></span>
        <</span>all_computers</span>></span></span>false</</span>all_computers</span>></span></span>
        <</span>computer_groups</span>></span></span>
            <</span>computer_group</span>></span></span>
                <</span>name</span>></span></span>%UPDATE_GROUP_NAME%</</span>name</span>></span></span>
            </</span>computer_group</span>></span></span>
        </</span>computer_groups</span>></span></span>
    </</span>scope</span>></span></span>
    <</span>self_service</span>></span></span>
        <</span>use_for_self_service</span>></span></span>false</</span>use_for_self_service</span>></span></span>
    </</span>self_service</span>></span></span>
    <</span>package_configuration</span>></span></span>
        <</span>packages</span>></span></span>
            <</span>size</span>></span></span>1</</span>size</span>></span></span>
            <</span>package</span>></span></span>
                <</span>name</span>></span></span>%pkg_name%</</span>name</span>></span></span>
                <</span>action</span>></span></span>install</</span>action</span>></span></span>
            </</span>package</span>></span></span>
        </</span>packages</span>></span></span>
    </</span>package_configuration</span>></span></span>
</</span>policy</span>></span></span>
</span></code></pre>
Next, we'll use DatetimeOutputter</strong> to generate a datestamp 1 week in
the future from the time of the AutoPkg run, in the format Jamf Pro expects for
midnight on that date. We set the output_name</code> to activation_date</code> to match
what the policy template expects.</p>
-</span> Processor</span></span>:</span> StopProcessingIf</span>
  Arguments</span></span>:</span>
    predicate</span></span>:</span> "</span>pkg_uploaded == False"</span></span>

-</span> Processor</span></span>:</span> com.github.haircut.processors/DatetimeOutputter</span>
  Arguments</span></span>:</span>
    deltas</span></span>:</span>
      -</span> output_name</span></span>:</span> activation_date</span>
        direction</span></span>:</span> future</span>
        datetime_format</span></span>:</span> "</span>%Y-%m-%d 00:00:00"</span></span>
        interval</span></span>:</span>
          weeks</span></span>:</span> 1</span>

-</span> Processor</span></span>:</span> com.github.grahampugh.jamf-upload.processors/JamfPolicyUploader</span>
  Arguments</span></span>:</span>
    policy_name</span></span>:</span> "</span>Install %NAME% 1 Week After Release"</span></span>
    policy_template</span></span>:</span> "</span>Install-after-1-week.xml"</span></span>
</span></code></pre>
This will create a policy that installs the uploaded package, but remains
inactive until 1 week in the future. At that future date, the policy will
automatically activate and install on eligible Macs.</p>
More info</h2>
These are just a few of the potential use cases for this processor. Please check
the full details in the README</a>. And as always – pull requests are open
if you have an improvement or correction!</p>


Dynamically Add Dock Items with the Jamf Binary
Sun, 13 Feb 2022 00:00:00 +0000
Adding your organization's common tools or newly-installed items to a user's
Dock can minimize confusion for your colleagues, and is a common task for Mac
admins.</p>
For those managing their fleet with Jamf Pro, the jamf</code> binary includes a
modifyDock</code> command which allows you to apply certain Dock modifications. It
isn't a fully-featured Dock management tool, but it does include enough
functionality to add new items to a user's Dock.</p>
I was recently working on a project where I needed to conditionally add a Dock
item based on some scripted logic. I wanted to minimize external dependencies,
so I developed a method to leverage the jamf</code> binary's built-in Dock management
capability and its -file</code> flag to complete the task.</p>
</span>
First, here's the documentation for the modifyDock</code> command, which you can read
by running sudo jamf help modifyDock</code>:</p>
Usage:  jamf modifyDock -file <file name> [-leaveRunning] [-beginning] [-remove]
Usage:  jamf modifyDock -id <dock_item_id> [-leaveRunning] [-beginning] [-remove]

  -file          The file that contains the formatted dock items.
  -id            The dock_item_id of the dock item on the JSS.
  -leaveRunning  The Dock process will not be restarted.
  -beginning     The item will be placed at the beginning (left side) of the Dock.
  -remove        The item will be removed instead of added.
</span></code></pre>
Typical use of this command assumes use of the -id</code> flag, which requires
passing the ID of a "Dock Item" as configured within your Jamf Pro instance.</p>
Dock Items can be added to Jamf Pro</a> via the web console or by
using Jamf Admin. Once you've added a Dock Item to Jamf Pro, you can add it to a
Mac's dock by using the Dock Items payload within a Policy, or by calling sudo jamf modifyDock -id <Dock Item ID></code> on the Mac itself.</p>
However, the jamf</code> binary's modifyDock</code> command also accepts a -file</code> flag.
The built-in help states the flag expects The file that contains the formatted dock items.</code> – a little vague. Online searches didn't turn up much additional
information, and the official Jamf Pro documentation doesn't cover the binary in
great detail.</p>
With some experimentation, I found that the -file</code> flag expects an on-disk
path to a file that contains XML representing one or more Dock item entries.</p>
Roughly, the required format of that XML to add an app to the Dock is as
follows:</p>
<</span>dict</span>></span></span>
    <</span>key</span>></span></span>GUID</</span>key</span>></span></span>
    <</span>integer</span>></span></span>-91117049</</span>integer</span>></span></span>
    <</span>key</span>></span></span>tile-data</</span>key</span>></span></span>
    <</span>dict</span>></span></span>
        <</span>key</span>></span></span>file-data</</span>key</span>></span></span>
        <</span>dict</span>></span></span>
            <</span>key</span>></span></span>_CFURLString</</span>key</span>></span></span>
            <</span>string</span>></span></span>file://[path to app]/</</span>string</span>></span></span>
            <</span>key</span>></span></span>_CFURLStringType</</span>key</span>></span></span>
            <</span>integer</span>></span></span>15</</span>integer</span>></span></span>
        </</span>dict</span>></span></span>
        <</span>key</span>></span></span>file-label</</span>key</span>></span></span>
        <</span>string</span>></span></span>[item name]</</span>string</span>></span></span>
    </</span>dict</span>></span></span>
    <</span>key</span>></span></span>tile-type</</span>key</span>></span></span>
    <</span>string</span>></span></span>file-tile</</span>string</span>></span></span>
</</span>dict</span>></span></span>
</span></code></pre>
Note: The GUID key can be any value, but Jamf Pro uses a consistent value across
all instances, to my knowledge.</em></p>
That's easy enough to generate the required data on-the-fly within a shell
script, so I wrote a function to do just that.</p>
dockitem</span> (</span>)</span> {</span>
    if</span> [[</span> -</span>d</span> "</span>$</span>{</span></span>1</span></span>}</span></span>"</span></span> &&</span> "</span>$</span>{</span></span>1</span></span>:</span></span> -</span>4</span></span>}</span></span>"</span></span> !=</span> "</span>.app"</span></span> ]]</span></span>;</span> then</span> TYPE</span>=</span>"</span>directory"</span></span></span></span>;</span> else</span> TYPE</span>=</span>"</span>file"</span></span></span></span>;</span> fi</span>
    TMPFILE</span>=</span>$</span>(</span> /usr/bin/mktemp</span></span> </span>)</span></span></span>
    echo</span></span> "</span><dict><key>GUID</key><integer>-91117049</integer><key>tile-data</key><dict><key>file-data</key><dict><key>_CFURLString</key><string>file://$</span>{</span></span>1%%</span></span></span>/</span>}</span></span>/</string><key>_CFURLStringType</key><integer>15</integer></dict><key>file-label</key><string>$</span>(</span> /usr/bin/basename</span></span> "</span>$</span>{</span></span>1</span></span>}</span></span>"</span></span></span>)</span></span></string></dict><key>tile-type</key><string>$</span>{</span></span>TYPE</span></span>}</span></span>-tile</string></dict>"</span></span> ></span> "</span>$</span>{</span></span>TMPFILE</span></span>}</span></span>"</span></span></span>
    echo</span></span> "</span>$</span>{</span></span>TMPFILE</span></span>}</span></span>"</span></span></span>
}</span></span>
</span></code></pre>
This function requires a single argument: the path to the item you want to add
to the Dock.</p>
Stepping through the function, we first determine if the passed path is a
directory that exists on the Mac. If so – and that directory is not actually an
app bundle – the Dock item will be created as a "directory tile," which appears
with a folder icon on the Dock. Otherwise, we assume the path is an app or
individual file.</p>
Next, we generate a temporary file on disk to which we can write the XML
representing the new Dock item. The temporary file's path is captured.</p>
Then we populate a blob of XML with our custom values, and finally print out the
path to the that temporary file.</p>
Using the function is as simple as calling dockitem</code> within a script, then
passing a path as an argument.</p>
dockitem</span></span> "</span>/Applications/Safari.app"</span></span></span>
</span></code></pre>
Putting it all together, we can then feed that file to the jamf</code> binary's
modifyDock</code> command using command substitution like so:</p>
#</span></span>!/bin/zsh</span>
</span>
dockitem</span> (</span>)</span> {</span>
    if</span> [[</span> -</span>d</span> "</span>$</span>{</span></span>1</span></span>}</span></span>"</span></span> &&</span> "</span>$</span>{</span></span>1</span></span>:</span></span> -</span>4</span></span>}</span></span>"</span></span> !=</span> "</span>.app"</span></span> ]]</span></span>;</span> then</span> TYPE</span>=</span>"</span>directory"</span></span></span></span>;</span> else</span> TYPE</span>=</span>"</span>file"</span></span></span></span>;</span> fi</span>
    TMPFILE</span>=</span>$</span>(</span> /usr/bin/mktemp</span></span> </span>)</span></span></span>
    echo</span></span> "</span><dict><key>GUID</key><integer>-91117049</integer><key>tile-data</key><dict><key>file-data</key><dict><key>_CFURLString</key><string>file://$</span>{</span></span>1%%</span></span></span>/</span>}</span></span>/</string><key>_CFURLStringType</key><integer>15</integer></dict><key>file-label</key><string>$</span>(</span> /usr/bin/basename</span></span> "</span>$</span>{</span></span>1</span></span>}</span></span>"</span></span></span>)</span></span></string></dict><key>tile-type</key><string>$</span>{</span></span>TYPE</span></span>}</span></span>-tile</string></dict>"</span></span> ></span> "</span>$</span>{</span></span>TMPFILE</span></span>}</span></span>"</span></span></span>
    echo</span></span> "</span>$</span>{</span></span>TMPFILE</span></span>}</span></span>"</span></span></span>
}</span></span>

jamf</span></span> modifyDock -</span>leaveRunning</span> -</span>file</span> $</span>(</span> dockitem</span></span> "</span>/Applications/Safari.app"</span></span> </span>)</span></span></span>
jamf</span></span> modifyDock -</span>leaveRunning</span> -</span>file</span> $</span>(</span> dockitem</span></span> "</span>/Applications/BBEdit.app"</span></span> </span>)</span></span></span>
jamf</span></span> modifyDock -</span>file</span> $</span>(</span> dockitem</span></span> "</span>/Applications/Slack.app"</span></span> </span>)</span></span></span>
</span></code></pre>
For another example, let's determine the logged-in user's home directory and add
that to the Dock as a directory tile.</p>
#</span></span>!/bin/zsh</span>
</span>
dockitem</span> (</span>)</span> {</span>
    if</span> [[</span> -</span>d</span> "</span>$</span>{</span></span>1</span></span>}</span></span>"</span></span> &&</span> "</span>$</span>{</span></span>1</span></span>:</span></span> -</span>4</span></span>}</span></span>"</span></span> !=</span> "</span>.app"</span></span> ]]</span></span>;</span> then</span> TYPE</span>=</span>"</span>directory"</span></span></span></span>;</span> else</span> TYPE</span>=</span>"</span>file"</span></span></span></span>;</span> fi</span>
    TMPFILE</span>=</span>$</span>(</span> /usr/bin/mktemp</span></span> </span>)</span></span></span>
    echo</span></span> "</span><dict><key>GUID</key><integer>-91117049</integer><key>tile-data</key><dict><key>file-data</key><dict><key>_CFURLString</key><string>file://$</span>{</span></span>1%%</span></span></span>/</span>}</span></span>/</string><key>_CFURLStringType</key><integer>15</integer></dict><key>file-label</key><string>$</span>(</span> /usr/bin/basename</span></span> "</span>$</span>{</span></span>1</span></span>}</span></span>"</span></span></span>)</span></span></string></dict><key>tile-type</key><string>$</span>{</span></span>TYPE</span></span>}</span></span>-tile</string></dict>"</span></span> ></span> "</span>$</span>{</span></span>TMPFILE</span></span>}</span></span>"</span></span></span>
    echo</span></span> "</span>$</span>{</span></span>TMPFILE</span></span>}</span></span>"</span></span></span>
}</span></span>

CURRENTUSER</span>=</span>$</span>(</span> /usr/sbin/scutil</span></span> <<<</span> "</span>show State:/Users/ConsoleUser"</span></span></span> |</span> /usr/bin/awk</span></span> '</span>/Name :/ && ! /loginwindow/ { print $3 }'</span></span> </span>)</span></span></span>
HOMEDIR</span>=</span>$</span>(</span> /usr/bin/dscl</span></span> . read "</span>/Users/$</span>{</span></span>CURRENTUSER</span></span>}</span></span>"</span></span> NFSHomeDirectory </span>)</span></span></span>

jamf</span></span> modifyDock -</span>file</span> $</span>(</span> dockitem</span></span> "</span>$</span>{</span></span>HOMEDIR</span></span>}</span></span>"</span></span> </span>)</span></span></span>
</span></code></pre>
This script will read the NFSHomeDirectory</code> attribute of the
currently-logged-in user's account and add it to the Dock. Dynamically
determining the user's home directory path is not otherwise possible with a Jamf
Pro policy alone, so this method bridges that gap.</p>
Ultimately, you can probably file this method under "things you should probably
do a better way, but this is also kind of neat and you may find a use."</p>
A purpose-built tool like docklib</a> or dockutil</a> will offer
wildly more flexibility and control over the Dock.</p>
But... this will work in a pinch for simple needs.</p>


Automatically Export and Generate App Icons in AutoPkg Recipes
Mon, 31 Jan 2022 00:00:00 +0000
I'm a stickler for including icons for all policies available in Jamf Pro's Self
Service app. They help users find items in Self Service, and generally make the
app easier to use.</p>
However, I don't like manually extracting icons from apps. It's easy enough with
a tool like SAP's Icons app</a>, but if I'm automating package and
policy creation with AutoPkg, I should similarly be able to automate icon
creation, right?</p>
I created the AppIconExtractor</strong></a> AutoPkg processor to fully automate
this task.</p>
At it's core, AppIconExtractor</strong> examines an app and exports its icon as a PNG
image file.</p>
More technically, it reads the CFBundleIconFile</code> property from an app's
Info.plist</code> and saves that image as a PNG file at the path of your choice.</p>
Additionally, ApplIconExtractor</code> can create icon variations by compositing a
secondary image on top of the app's icon. This makes it simple to automatically
create a version of an icon with a destructive "red X" icon superimposed over
the app icon for use in uninstallation policies, or a version with an "update"
graphic for use in policies that update an app.</p>



    
    

</figure></span>Add my recipes and install the Pillow library</h2>
First, you'll need my recipe repository available to your local AutoPkg
installation. Add it with autopkg repo-add haircut-recipes</code>.</p>
AppIconExtractor</strong> requires installation of the Pillow</a> Python
library.</p>
Pillow is used to convert and composite icons, and can be easily installed on 
the Mac you use to run AutoPkg. Use this command:</p>
/usr/local/autopkg/python -m pip install --upgrade Pillow
</span></code></pre>
Note that this installs the Pillow library within the path of AutoPkg's Python
framework</em>. This is very important.</strong> If you just run pip</code> or pip3</code> without
the explicit path to AutoPkg's Python installation, AutoPkg won't be able to
find the library. Recipes will produce an error directing you to install Pillow
using the specifc command above.</p>

    The MunkiImporter
processor</a>, via munkilib, includes code to extract and convert icons from app
bundles. We could use features of this existing processor to accomplish some of
our needs. However, MunkiImporter does not provide any features to composite
images. Since AppIconExtractor</strong> is primarily targeted towards
folks managing Macs with tools other than Munki, it makes more sense to require
only a single external dependency – Pillow – that fulfills all our needs.</p>

</aside>
With Pillow installed, you're ready to go.</p>
Basic use</h2>
Using AppIconExtractor</strong> is as simple as including the processor as a step in a
recipe's Process dictionary. Use the shared processor</a> syntax
to call com.github.haircut.processors/AppIconExtractor</code>.</p>
It requires only one argument: source_app</code>, which is the path to the .app</code>
from which to extract an icon. If the path to the app points inside a disk
image, that .dmg will be mounted automatically.</p>
By default, the app's icon will be output to the recipe's cache directory as
%NAME%.png%</code>. You can optionally override this output path (and filename) by
setting the icon_output_path</code> argument.</p>
A simple example in XML format might look like:</p>
<</span>key</span>></span></span>Process</</span>key</span>></span></span>
<</span>array</span>></span></span>
    <</span>dict</span>></span></span>
        <</span>key</span>></span></span>Processor</</span>key</span>></span></span>
        <</span>string</span>></span></span>com.github.haircut.processors/AppIconExtractor</</span>string</span>></span></span>
        <</span>key</span>></span></span>Arguments</</span>key</span>></span></span>
        <</span>dict</span>></span></span>
            <</span>key</span>></span></span>source_app</</span>key</span>></span></span>
            <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/CoolApp/CoolApp.app</</span>string</span>></span></span>
        </</span>dict</span>></span></span>
    </</span>dict</span>></span></span>
</</span>array</span>></span></span>
</span></code></pre>
This will extract the icon from "CoolApp.app" and save it as a 256px square PNG
image to the recipe cache directory.</p>
As mentioned, adding the icon_output_path</code> argument will give you additional
control over the output path and filename. Here's an example in YAML format:</p>
Process</span></span>:</span>
  -</span> Processor</span></span>:</span> com.github.haircut.processors/AppIconExtractor</span>
    Arguments</span></span>:</span>
      source_app</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/CoolApp/CoolApp.app"</span></span>
      icon_output_path</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/Icons/Icon-%NAME%.png"</span></span>
</span></code></pre>
Generating composited variations</h2>
Beyond extracting the app's icon, AppIconExtractor</strong> can also create variation
images by compositing a "template image" on top of the app icon.</p>
The processor can output variations for an "uninstall," "update," and "install"
version of the app icon.</p>



    
    

</figure>
To generate a variation, add a processor argument to set an output path for that
variation. Use one or more of the following arguments:</p>

composite_install_path</code></li>
composite_update_path</code></li>
composite_uninstall_path</code></li>
</ul>
Omit any variations you don't want to generate. The processor will only create
the variations you request be specify an output path.</p>
If you specify only output paths for variations, AppIconExtractor</strong> will use
sensible defaults to composite suitable icons. The default templates are glyphs
from SF Symbols</a> that will work well in most situations. Each
template is 64px in size, and looks nice in the corner.</p>



    
    

</figure>
These templates are encoded within the processor; you don't need to do
anything to use these defaults!</mark></p>
Here's an example in YAML format:</p>
Process</span></span>:</span>
  -</span> Processor</span></span>:</span> com.github.haircut.processors/AppIconExtractor</span>
    Arguments</span></span>:</span>
      source_app</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/CoolApp/CoolApp.app"</span></span>
      icon_output_path</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/Icons/Icon-%NAME%.png"</span></span>
      composite_update_path</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/Icons/Update-%NAME%.png"</span></span>
      composite_uninstall_path</span></span>:</span> "</span>"</span></span>%RECIPE_CACHE_DIR%/Icons/Uninstall-%NAME%.png"</span>
</span></code></pre>
Notice that we included arguments for the "update" and "uninstall" variations,
but did not set the composite_install_path</code> argument. This would output the
"bare" app icon as well as variations for "update" and "uninstall" – but no
"install" variation, since we omitted that argument.</p>
Custom templates</h3>
If you don't like the default variation templates, you can use your own by
setting composite_install_template</code>, composite_update_template</code> and/or
composite_unsinstall_template</code>. Each argument should be the path to alternative
template image to use for that variation.</p>
AppIconExtractor</strong> will calculate the size of the template image at the path you
specify and correctly anchor that template to the composite_position</code> (see
"Padding and position" below).</p>



    
    

</figure>
Here's an example of using a custom template to generate an "uninstall"
variation in XML format:</p>
<</span>key</span>></span></span>Process</</span>key</span>></span></span>
<</span>array</span>></span></span>
    <</span>dict</span>></span></span>
        <</span>key</span>></span></span>Processor</</span>key</span>></span></span>
        <</span>string</span>></span></span>com.github.haircut.processors/AppIconExtractor</</span>string</span>></span></span>
        <</span>key</span>></span></span>Arguments</</span>key</span>></span></span>
        <</span>dict</span>></span></span>
            <</span>key</span>></span></span>source_app</</span>key</span>></span></span>
            <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/CoolApp/CoolApp.app</</span>string</span>></span></span>
            <</span>key</span>></span></span>composite_uninstall_template</</span>key</span>></span></span>
            <</span>string</span>></span></span>%RECIPE_DIR%/radical-flame.png</</span>string</span>></span></span>
            <</span>key</span>></span></span>composite_uninstall_path</</span>key</span>></span></span>
            <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/delete_%NAME%.png</</span>string</span>></span></span>
        </</span>dict</span>></span></span>
    </</span>dict</span>></span></span>
</</span>array</span>></span></span>
</span></code></pre>
Padding and position</h2>
AppIconExtractor</strong> includes a few additional options to customize your
composited icon variations.</p>

composite_padding</code>: sets the number of pixels from the edge of the image the
superimposed template image is offset. Defaults to 10</code> pixels.</li>
composite_position</code>: sets the corner to which the superimposed template image
for composited variations is anchored. Defaults to br</code> for the bottom-right
corner. You can change this to bl</code> (bottom left), ur</code> (upper right), or ul
(upper left) if you prefer.</li>
</ul>
Combinations of these options are shown below with the padding highlighted in
pink:</p>



    
    

</figure>
Clockwise from the upper left, this example shows:</p>

composite_padding</code> omitted (so it defaults to 10</code>) and composite_position</code> of ul</code>.</li>
composite_padding</code> of 20</code> and composite_position</code> of ur</code>.</li>
composite_padding</code> of 0</code> and composite_position</code> omitted (so it defaults to br</code>).</li>
composite_padding</code> of 5</code> and composite_position</code> of bl</code>.</li>
</ul>
Setting these options applies the same settings to all</em> composited variations.
This is an intentional design choice to keep the input arguments – and thus the
required code – more manageable.</p>
Output variables</h2>
AppIconExtractor</strong> sets the path(s) to the extracted app icon, and any
composited variations, as output variables during an AutoPkg run. This means you
can extract and generate icons, then immediately use those icons in subsequent
processors like JamfPolicyUploader</a>.</p>
The following output variables are set if (and only if) the associated
variations are requested:</p>

app_icon_path</code>: path to the extracted, unmodified app icon. Always set.</li>
install_icon_path</code> path to the composited "install" variation. Only set if
this variations is requested.</li>
update_icon_path</code> path to the composited "update" variation. Only set if this
variations is requested.</li>
uninstall_icon_path</code> path to the composited "uninstall" variation. Only set
if this variations is requested.</li>
</ul>
Example uses in recipes</h2>
Here are two examples of using AppIconExtractor</strong> in a child recipe or
override.</p>
Extract the icon from an available .app bundle</h3>
Greg Neagle's recipe for Sublime Text 4</a> leaves the unarchived
.app available in the recipe cache dir at %RECIPE_CACHE_DIR%/%NAME%/Sublime Text.app</code>. We'll use this to extract the Sublime Text icon using
AppIconExtractor's</strong> default settings.</p>
Process</span></span>:</span>
  -</span> Processor</span></span>:</span> com.github.haircut.processors/AppIconExtractor</span>
    Arguments</span></span>:</span>
      source_app</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/%NAME%/Sublime Text.app"</span></span>

  -</span> Processor</span></span>:</span> com.github.grahampugh.jamf-upload.processors/JamfPolicyUploader</span>
    Arguments</span></span>:</span>
      policy_template</span></span>:</span> "</span>%POLICY_TEMPLATE%"</span></span>
      policy_name</span></span>:</span> "</span>%POLICY_NAME%"</span></span>
      icon</span></span>:</span> "</span>%app_icon_path%"</span></span>
      replace_icon</span></span>:</span> True</span>
</span></code></pre>
This extracts Sublime Text's icon without generating any composite variations,
then feeds that extracted icon to the JamfPolicyUploader</code> processor. We set
replace_icon</code> to True</code> to ensure any change to the icon by the vendor is
automatically reflected within our Jamf policy.</p>
Unpacking a .pkg to extract an icon</h3>
The recipe for the Google Chrome Enterprise package</a> downloads a
.pkg directly from the vendor, so no repackaging is needed. And while the
AutoPkg recipe unpacks the package to performe code signature verification, it
then runs the PathDeleter</code> processor to clean up that operation. This means a
child recipe does not have access to a .app from which to extract an icon.</p>
That means we'll need to do a little more work to unpack the package again so
that we can get to the app bundle. We'll also generate a custom "uninstall"
variations and override the default composition position and padding.</p>
Here's the Process of this more complex example in XML format:</p>
<</span>key</span>></span></span>Process</</span>key</span>></span></span>
<</span>array</span>></span></span>
    <</span>dict</span>></span></span>
        <</span>key</span>></span></span>Processor</</span>key</span>></span></span>
        <</span>string</span>></span></span>FlatPkgUnpacker</</span>string</span>></span></span>
        <</span>key</span>></span></span>Arguments</</span>key</span>></span></span>
        <</span>dict</span>></span></span>
            <</span>key</span>></span></span>destination_path</</span>key</span>></span></span>
            <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/unpack</</span>string</span>></span></span>
            <</span>key</span>></span></span>flat_pkg_path</</span>key</span>></span></span>
            <</span>string</span>></span></span>%pkg_path%</</span>string</span>></span></span>
        </</span>dict</span>></span></span>
    </</span>dict</span>></span></span>
    <</span>dict</span>></span></span>
        <</span>key</span>></span></span>Processor</</span>key</span>></span></span>
        <</span>string</span>></span></span>PkgPayloadUnpacker</</span>string</span>></span></span>
        <</span>key</span>></span></span>Arguments</</span>key</span>></span></span>
        <</span>dict</span>></span></span>
            <</span>key</span>></span></span>destination_path</</span>key</span>></span></span>
            <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/unpack/pkgpayload</</span>string</span>></span></span>
            <</span>key</span>></span></span>pkg_payload_path</</span>key</span>></span></span>
            <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/unpack/GoogleChrome.pkg/Payload</</span>string</span>></span></span>
        </</span>dict</span>></span></span>
    </</span>dict</span>></span></span>
    <</span>dict</span>></span></span>
        <</span>key</span>></span></span>Processor</</span>key</span>></span></span>
        <</span>string</span>></span></span>com.github.haircut.processors/AppIconExtractor</</span>string</span>></span></span>
        <</span>key</span>></span></span>Arguments</</span>key</span>></span></span>
        <</span>dict</span>></span></span>
            <</span>key</span>></span></span>composite_padding</</span>key</span>></span></span>
            <</span>integer</span>></span></span>20</</span>integer</span>></span></span>
            <</span>key</span>></span></span>composite_position</</span>key</span>></span></span>
            <</span>string</span>></span></span>ul</</span>string</span>></span></span>
            <</span>key</span>></span></span>composite_uninstall_path</</span>key</span>></span></span>
            <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/Icon-Uninstall-%NAME%.png</</span>string</span>></span></span>
            <</span>key</span>></span></span>composite_uninstall_template</</span>key</span>></span></span>
            <</span>string</span>></span></span>/Users/haircut/Documents/delete.png</</span>string</span>></span></span>
            <</span>key</span>></span></span>icon_output_path</</span>key</span>></span></span>
            <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/Icon-%NAME%.png</</span>string</span>></span></span>
            <</span>key</span>></span></span>source_app</</span>key</span>></span></span>
            <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/unpack/pkgpayload/Google Chrome.app</</span>string</span>></span></span>
        </</span>dict</span>></span></span>
    </</span>dict</span>></span></span>
    <</span>dict</span>></span></span>
        <</span>key</span>></span></span>Processor</</span>key</span>></span></span>
        <</span>string</span>></span></span>PathDeleter</</span>string</span>></span></span>
        <</span>key</span>></span></span>Arguments</</span>key</span>></span></span>
        <</span>dict</span>></span></span>
            <</span>key</span>></span></span>path_list</</span>key</span>></span></span>
            <</span>array</span>></span></span>
                <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/unpack</</span>string</span>></span></span>
            </</span>array</span>></span></span>
        </</span>dict</span>></span></span>
    </</span>dict</span>></span></span>
    <</span>dict</span>></span></span>
        <</span>key</span>></span></span>Processor</</span>key</span>></span></span>
        <</span>string</span>></span></span>com.github.grahampugh.jamf-upload.processors/JamfPolicyUploader</</span>string</span>></span></span>
        <</span>key</span>></span></span>Arguments</</span>key</span>></span></span>
        <</span>dict</span>></span></span>
            <</span>key</span>></span></span>icon</</span>key</span>></span></span>
            <</span>string</span>></span></span>%app_icon_path%</</span>string</span>></span></span>
            <</span>key</span>></span></span>policy_name</</span>key</span>></span></span>
            <</span>string</span>></span></span>Install %NAME%</</span>string</span>></span></span>
            <</span>key</span>></span></span>policy_template</</span>key</span>></span></span>
            <</span>string</span>></span></span>Self-Service-Policy.xml</</span>string</span>></span></span>
            <</span>key</span>></span></span>replace_icon</</span>key</span>></span></span>
            <</span>true</span>/></span></span>
        </</span>dict</span>></span></span>
    </</span>dict</span>></span></span>
    <</span>dict</span>></span></span>
        <</span>key</span>></span></span>Processor</</span>key</span>></span></span>
        <</span>string</span>></span></span>com.github.grahampugh.jamf-upload.processors/JamfPolicyUploader</</span>string</span>></span></span>
        <</span>key</span>></span></span>Arguments</</span>key</span>></span></span>
        <</span>dict</span>></span></span>
            <</span>key</span>></span></span>icon</</span>key</span>></span></span>
            <</span>string</span>></span></span>%uninstall_icon_path%</</span>string</span>></span></span>
            <</span>key</span>></span></span>policy_name</</span>key</span>></span></span>
            <</span>string</span>></span></span>Uninstall %NAME%</</span>string</span>></span></span>
            <</span>key</span>></span></span>policy_template</</span>key</span>></span></span>
            <</span>string</span>></span></span>Uninstall-Policy.xml</</span>string</span>></span></span>
            <</span>key</span>></span></span>replace_icon</</span>key</span>></span></span>
            <</span>true</span>/></span></span>
        </</span>dict</span>></span></span>
    </</span>dict</span>></span></span>
</</span>array</span>></span></span>
</span></code></pre>
This unpacks the Google Chrome enterprise package, extracts the unmodified app
icon, and generates an "uninstall" composite version with a custom graphic in
the upper left corner with 20px of padding.</p>



    
    

</figure>
The outputs of AppIconExtractor</strong> are then used as inputs to
JamfPolicyUploader process runs to set the icons for two different policies.
Setting the replace_icon</code> argument to True</code> ensures that any changes to the
icons are reflected on the Jamf Pro policies.</p>

Hopefully this processor will help you extract icons without the manual work,
and spiff up those Self Service policies.</p>
Pull requests accepted</a> if you fix a bug or make an improvement!</p>


Stopping an AutoPkg Recipe if VirusTotal Detects Malware
Tue, 14 Dec 2021 00:00:00 +0000
Hannes Juutilainen's VirusTotalAnalyzer</a> is a fantastic AutoPkg
postprocessor. It automatically queries VirusTotal</a> to analyze items
downloaded by AutoPkg and detect potential malware.</p>
VirusTotalAnalyzer was designed to run as a postprocessor</a>.
AutoPkg postprocessors allow you to add extra "steps" to an AutoPkg recipe at
runtime without modifying the recipe itself. By this convention,
VirusTotalAnalyzer scans files after all other recipe steps have completed. This
means a recipe cannot conditionally act on the VirusTotal scan results; the
query happens after</em> the recipe has otherwise finished.</p>
In practice, code signature verification</a>, recipe trust
verification</a>, and after-the-fact VirusTotal scanning offer strong
protections against malicious software. Most Mac admins also report "never"
seeing VirusTotal flag a vendor package; or if they have seen it, investigation
revealed a false positive.</p>
However, many AutoPkg workflows directly upload or import software packages to a
Munki repository or Jamf Pro distribution point as part of a recipe run. If
VirusTotal engines flag an item, VirusTotalAnalyzer reports on the detection
after the item is already uploaded to your systems</em>. Further, most
highly-automated AutoPkg workflows begin deploying the newly-uploaded software
to a test group (or all endpoints) as soon as the recipe completes.</p>
You may require additional assurance that downloaded software is not flagged by
VirusTotal, and want to prevent any flagged files from being uploaded to your
software distribution points.</p>
You can do this by using a custom recipe that runs VirusTotalAnalyzer as a
regular processor – instead of as a postprocessor – combined with the
StopProcessingIf processor. This allows you to terminate a recipe if VirusTotal
reports any hits before</strong> subsequent recipe steps upload an item to your
systems.</p>
Here's how to do that.</p>
</span>
Create a Custom Recipe</h3>
While it's possible to append</em> additional processors to a recipe within a
recipe override</a>, or call multiple postprocessors on the command
line, I recommend creating a custom recipe for each application. This allows you
to very specifically define exactly</em> what you wish to happen during a recipe
run.</p>
Yes, this is additional overhead. However, it's not uncommon for an organization
to maintain custom recipes for all software to meet automation needs. And hey,
if you want this extra security layer, you'll have to work a little for it.</p>
I recommend creating an organization-specific child recipe for each app in your
catalog, and adding the required processors to that child recipe.</p>
Let's use Rectangle</a> as an example. Here's the shell of a new custom
recipe:</p>
Identifier</span></span>:</span> org.macblog.pkg.Rectangle</span>
ParentRecipe</span></span>:</span> com.github.dataJAR-recipes.pkg.Rectangle</span>
MinimumVersion</span></span>:</span> "</span>2.3"</span></span>
Input</span></span>:</span>
  NAME</span></span>:</span> Rectangle</span>
Process</span></span>:</span>
</span></code></pre>
Here, I've set a new Identifier</code> for the recipe specific to my organization. In
this example, I ultimately want a .pkg, so I set the ParentRecipe</code> as the
identifier of the pkg</code> version of the Rectangle recipe. Finally, since I'm
using YAML here, I set the MinimumVersion</code> to 2.3</code> to require the version of
AutoPkg that supports YAML-formatted recipes.</p>
I'm setting the NAME</code> key in the Input</code> dictionary to ensure AutoPkg
recognizes the file as a valid recipe. No additional Input keys are required for
this minimal example. You can, however, customize them to fit your needs.</p>
Since this is a child recipe it inherits all the output of the parent recipe.
That means we don't need to do anything to get the pkg output from the
parent, and the child recipe only needs to contain the additional processors we
want to run.</p>



    
    

Each child recipe receives and can act on the output of its parent recipe.</figcaption></figure>Add VirusTotalAnalyzer as a Regular Processor</h3>
Instead of running VirusTotalAnalyzer as a postprocessor, you can call it as a
"regular" processor inside the Process</code> dictionary of our custom recipe. Add it
like so:</p>
    
Identifier: org.macblog.pkg.Rectangle
ParentRecipe: com.github.dataJAR-recipes.pkg.Rectangle
MinimumVersion: "2.3"
Input:
  NAME: Rectangle
Process:
  - Processor: io.github.hjuutilainen.VirusTotalAnalyzer/VirusTotalAnalyzer</mark>
    </code>
</pre>
Since processors within a recipe run sequentially, you can run
VirusTotalAnalyzer immediately after downloading an item, but before subsequent
processors upload that item to your systems. It requires only that a pathname</code>
variable exists.</p>
In this example, the parent recipes have already handled downloading and
packaging the app. Our child recipe receives all the output of those previous
actions, and we're ready to use VirusTotalAnalyzer to scan the downloaded item
for threats.</p>
Add a StopProcessingIf Processor</h3>
Next, add the StopProcessingIf</a> processor. The StopProcessingIf processor
terminates a recipe execution if a condition is met. This is most commonly
used to stop processing a recipe if a vendor download has not changed, by
setting the predicate</code> to download_changed == FALSE</code>.</p>
Because StopProcessingIf accepts NSPredicate-style</a> conditions, we can
also test more complex conditions.</p>
VirusTotalAnalyzer outputs its findings to the
virus_total_analyzer_summary_result</code> output variable. Within that output is a
ratio</code> key that denotes the number of VirusTotal engines that flagged a file as
suspicious out of the total number of engines that scanned the file, e.g.
0/55</code>.</p>
We can use the NSPredicate test BEGINSWITH</code> to target the beginning of the
ratio</code> variable string. That variable is nested a couple levels deep, and we
use dot notation to access nested values. Combined with a NOT</code> negation, our
full predicate is:</p>
NOT virus_total_analyzer_summary_result.data.ratio BEGINSWITH '0/'
</span></code></pre>
This means: If the reported ratio from VirusTotal begins with anything other
than 0/</code>, e.g. 1/54</code> or 23/68</code>, stop processing the recipe.</em></p>
Add these items to the Input</code> and Process</code> dictionaries like so:</p>
    
Identifier: org.macblog.pkg.Rectangle
ParentRecipe: com.github.dataJAR-recipes.pkg.Rectangle
MinimumVersion: "2.3"
Input:
  NAME: Rectangle
  STOP_PREDICATE: "NOT virus_total_analyzer_summary_result.data.ratio BEGINSWITH '0'"</mark>  
Process:
  - Processor: io.github.hjuutilainen.VirusTotalAnalyzer/VirusTotalAnalyzer

  - Processor: StopProcessingIf
    Arguments:
      predicate: "%STOP_PREDICATE%"</mark>
    </code>
</pre>
Setting the predicate as an Input key allows you to override the predicate at
recipe runtime if you need to temporarily skip the StopProcessingIf
functionality. Manually passing --key STOP_PREDICATE=FALSEPREDICATE</code> will bypass the
StopProcessingIf processor and allow the recipe to complete, even if VirusTotal
reports a detection.</p>

    Update:</span> Thanks to Graham Pugh</a> for the suggestion to specify the predicate in the Input dictionary.
</p>
Add Your Other Processors</h3>
Add any additional processors after</em> the StopProcessingIf processor to suit
your needs.</p>
You might add JamfUploader</a> or MunkiImporter</a>
processors to copy a package to your distribution servers. Whatever you add
after the StopProcessingIf processor will be executed only if VirusTotal reports
no malware detections.</p>
This custom recipe can be used just like any other. You can (and should!) make
local overrides, run it in recipe lists, add chat-notifying postprocessors, and
commit it to your organization's private recipe repository. Run it manually, or
within AutoPkgr, or in your CI pipeline.</p>
Final Thoughts</h3>
There are a few caveats worth mentioning:</p>

You need to create a custom recipe for every app in your catalog. You may be
doing this already – if so, good for you! (Or, try this
alternative</a>)</li>
You might get false positives, where a single VirusTotal engine erroneously
reports a detection. You'll need to follow up manually, and perhaps
temporarily disable the VirusTotalAnalyzer (or StopProcessingIf) processor in
a recipe until VirusTotal or the vendor fixes the issue. As mentioned,
passing --key STOP_PREDICATE=FALSEPREDICATE</code> will disable the StopProcessingIf
behavior.</li>
You cannot set a "threshold" of a permissible number of potential detections.
The predicate used in the StopProcessingIf processor allows only zero</strong>
detections.</li>
</ol>
If you don't mind this overhead, and your organization requires this increased
assurance, you fit within the narrow band of utility this process provides. You
might even view the above caveats as good things. If so, enjoy!</p>
Alternative to a Custom Recipe</h3>
AutoPkg is flexible, and you can run multiple postprocessors sequentially.
Instead of creating a custom recipe, it's possible to "append" the required
postprocessors to an existing recipe on the command line as follows:</p>
autopkg</span></span> run com.github.dataJAR-recipes.pkg.Rectangle \
</span>--</span>post</span> io.github.hjuutilainen.VirusTotalAnalyzer/VirusTotalAnalyzer \
</span>--</span>post</span> StopProcessingIf \
</span>--</span>key</span> predicate="</span>NOT virus_total_analyzer_summary_result.data.ratio BEGINSWITH '0'"</span></span> \
</span>--</span>post</span> com.github.grahampugh.jamf-upload.processors/JamfPackageUploader</span>
</span></code></pre>
I personally prefer maintaining a custom recipe. I most frequently run multiple
recipes using the -l</code> or --recipe-list</code> flag, and adding postprocessors to a
recipe list run will call all those postprocessors for every recipe. For me,
that decreases the flexibility afforded by creating a very explicit custom
recipe, which is why I recommend that route.</p>
But the multiple-postprocessor option works fine if you prefer it.</p>
Complete Examples</h3>
Here is a complete recipe example in both YAML and XML formats. It demonstrates
uploading the example Rectangle package to Jamf Pro if VirusTotal engines find
no malware.</p>
YAML</h4>
Identifier</span></span>:</span> org.macblog.pkg.Rectangle</span>
ParentRecipe</span></span>:</span> com.github.dataJAR-recipes.pkg.Rectangle</span>
MinimumVersion</span></span>:</span> "</span>2.3"</span></span>
Input</span></span>:</span>
  NAME</span></span>:</span> Rectangle</span>
  STOP_PREDICATE</span></span>:</span> "</span>NOT virus_total_analyzer_summary_result.data.ratio BEGINSWITH '0'"</span></span>
Process</span></span>:</span>
  -</span> Processor</span></span>:</span> io.github.hjuutilainen.VirusTotalAnalyzer/VirusTotalAnalyzer</span>

  -</span> Processor</span></span>:</span> StopProcessingIf</span>
    Arguments</span></span>:</span>
      predicate</span></span>:</span> "</span>%STOP_PREDICATE%"</span></span>

  -</span> Processor</span></span>:</span> com.github.grahampugh.jamf-upload.processors/JamfPackageUploader</span>
</span></code></pre>
XML</h4>
<?</span>xml</span> version</span>=</span>"</span>1.0"</span></span> encoding</span>=</span>"</span>UTF-8"</span></span>?></span></span>
<!</span>DOCTYPE</span> plist</span> PUBLIC</span> "</span>-//Apple//DTD PLIST 1.0//EN"</span></span> "</span>http://www.apple.com/DTDs/PropertyList-1.0.dtd"</span></span>></span></span>
<</span>plist</span> version</span>=</span>"</span>1.0"</span></span>></span></span>
<</span>dict</span>></span></span>
  <</span>key</span>></span></span>Identifier</</span>key</span>></span></span>
  <</span>string</span>></span></span>org.macblog.pkg.Rectangle</</span>string</span>></span></span>
  <</span>key</span>></span></span>Input</</span>key</span>></span></span>
  <</span>dict</span>></span></span>
    <</span>key</span>></span></span>NAME</</span>key</span>></span></span>
    <</span>string</span>></span></span>Rectangle</</span>string</span>></span></span>
    <</span>key</span>></span></span>STOP_PREDICATE</</span>key</span>></span></span>
    <</span>string</span>></span></span>NOT virus_total_analyzer_summary_result.data.ratio BEGINSWITH '0'</</span>string</span>></span></span>
  </</span>dict</span>></span></span>
  <</span>key</span>></span></span>MinimumVersion</</span>key</span>></span></span>
  <</span>string</span>></span></span>2.3</</span>string</span>></span></span>
  <</span>key</span>></span></span>ParentRecipe</</span>key</span>></span></span>
  <</span>string</span>></span></span>com.github.dataJAR-recipes.pkg.Rectangle</</span>string</span>></span></span>
  <</span>key</span>></span></span>Process</</span>key</span>></span></span>
  <</span>array</span>></span></span>
    <</span>dict</span>></span></span>
      <</span>key</span>></span></span>Processor</</span>key</span>></span></span>
      <</span>string</span>></span></span>io.github.hjuutilainen.VirusTotalAnalyzer/VirusTotalAnalyzer</</span>string</span>></span></span>
    </</span>dict</span>></span></span>
    <</span>dict</span>></span></span>
      <</span>key</span>></span></span>Arguments</</span>key</span>></span></span>
      <</span>dict</span>></span></span>
        <</span>key</span>></span></span>predicate</</span>key</span>></span></span>
        <</span>string</span>></span></span>%STOP_PREDICATE%</</span>string</span>></span></span>
      </</span>dict</span>></span></span>
      <</span>key</span>></span></span>Processor</</span>key</span>></span></span>
      <</span>string</span>></span></span>StopProcessingIf</</span>string</span>></span></span>
    </</span>dict</span>></span></span>
    <</span>dict</span>></span></span>
      <</span>key</span>></span></span>Processor</</span>key</span>></span></span>
      <</span>string</span>></span></span>com.github.grahampugh.jamf-upload.processors/JamfPackageUploader</</span>string</span>></span></span>
    </</span>dict</span>></span></span>
  </</span>array</span>></span></span>
</</span>dict</span>></span></span>
</</span>plist</span>></span></span>
</span></code></pre>


Using JXA in Jamf Pro Scripts and Extension Attributes
Thu, 18 Nov 2021 00:00:00 +0000
Quick follow-up to my earlier guide on using JavaScript for Automation</a>.</p>
There must be something in the air that put the topic of JXA on the minds of
the Apple community. Armin Briegel shared a great roundup of recent JXA
work</a>, and the #scripting channel on the MacAdmins Slack team</a> is
full of folks discussing new and old discoveries.</p>
Here are a handful of additional tips.</p>
Excutable JXA scripts</h3>
You can run JXA directly by including the JavaScript language flag in a script's
shebang, like this:</p>
#!</span>/usr/bin/osascript -l JavaScript</span>

function</span> run</span></span>(</span>)</span></span> {</span>
	var</span> app</span></span> </span>=</span> Application</span>.</span>currentApplication</span></span>(</span>)</span></span>;</span>
	app</span>.</span>includeStandardAdditions</span> =</span> true</span>;</span>
	return</span> app</span>.</span>systemInfo</span></span>(</span>)</span>.</span>cpuType</span>;</span>
}</span></span></span>
</span></code></pre>
Save the file with a name and extension you like. I've been using .scpt</code>, which
is the convention suggested by Apple's own Script Editor application. Something
like cputype.scpt</code> will work just fine.</p>
Mark the file as executable by running chmod +x cputype.scpt</code>. Then, you can
run it on your system by simply calling ./cputype.scpt</code></p>
This will output the CPU architecture of the computer, for example ARM64E</code> or
Intel x86-64...</code></p>
JXA in Jamf Pro Scripts</h3>
You can drop a JXA script directly in Jamf Pro without any modification. As
long as you include the JavaScript shebang outlined above, you're good to go.</p>
You do not necessarily need to wrap JXA in a shell script.</strong> It might make
sense to "shell out" to a JXA function from a shell script for some use cases,
but it is not a requirement.</p>
Jamf supports non-compiled AppleScript files</a> natively, and you
can use them in your Policies like any other script.</p>
JXA in Jamf Pro Extension Attributes</h3>
Same deal; specify the Script type for the Extension Attribute, and include the
JavaScript language flag shebang. Ensure your function returns the required
<result></result></code> wrapper surrounding the output. You can do that with simple
string concatenation using the plus operator</a>, like this:</p>
#!</span>/usr/bin/osascript -l JavaScript</span>

function</span> run</span></span>(</span>)</span></span> {</span>
	var</span> app</span></span> </span>=</span> Application</span>.</span>currentApplication</span></span>(</span>)</span></span>;</span>
	app</span>.</span>includeStandardAdditions</span> =</span> true</span>;</span>
	return</span> "</span><result>"</span></span> +</span> app</span>.</span>systemInfo</span></span>(</span>)</span>.</span>cpuType</span> +</span> "</span></result>"</span></span>;</span>
}</span></span></span>
</span></code></pre>
This will output <result>ARM64E</result></code>, for example, which will show up on
your computer's inventory record during the next device inventory.</p>
--</p>
That's it. Hopefully this helps you store and run JavaScript for Automation
scripts.</p>


How to Parse JSON on the macOS Command Line Without External Tools Using JavaScript for Automation
Sun, 14 Nov 2021 00:00:00 +0000
JSON – JavaScript Object Notation</a> – is the lingua franca for
shipping data between systems. Everything from software APIs to web services
commonly support, and typically default to, outputting data in JSON format.</p>
Because of its ubiquity, you're bound to run into a need to manipulate a chunk
of JSON in the course of managing your fleet.</p>
For example, you might run a shell script on your Macs that instructs them to
read data from an external system via its API using curl</code>. That external system
returns a big ol' heap of JSON, but you need to extract only a single data point
from that payload, then act on that value.</p>
This is somewhat of a challenge in the shell because macOS does not include any
native or pre-installed tools to help you hack down that JSON. Administrators
often resort to workarounds like shelling out to Python or using sed</code> and awk</code>
to approximate parsing.</p>
However, another, native</strong> solution is right there in the name: use
JavaScript.</p>
</span>
JavaScript, JXA and Open Scripting Architecture</h3>
It seems appropriate to use JavaScript to parse JavaScript</em> Object Notation,
right? But how? Can you do that without relying on external tools?</p>
Since Mac OS X Yosemite, Apple has supported JavaScript as a language to
interact with the Open Scripting Architecture (OSA)</a>. OSA enables
interapplication communication for automation, and using JavaScript for this
purpose is known as JavaScript for Automation</em> (JXA).</p>
JXA is built right into macOS and lets you use JavaScript without any
additional tooling.</p>
You may be familiar with using the osascript</code> binary to execute AppleScript
snippets. While AppleScript is a more common choice for accessing OSA
functionality, you can trivially use JavaScript instead.</p>
On the command line, use the -l</code> (that's a lowercase L) flag  with osascript</code>
to specify JavaScript</code> as the scripting language. Without the flag, osascript</code>
defaults to expecting AppleScript. </p>
Here's a simple example derived from Apple's sample code</a>:</p>
osascript</span> -</span>l</span> '</span>JavaScript'</span></span> -</span>e</span> '</span>var app = Application.currentApplication(); app.includeStandardAdditions = true; app.displayDialog("Hello from JavaScript!");'</span></span>
</span></code></pre>
This will display a dialog window using JavaScript. Easy!</p>
Using JXA to read JSON in a shell script</h3>
Let's look at an example where we use the ip-api.com</a> service to query
the current geographic location of the system based on its IP address.</p>
#!</span>/bin/bash</span>

GEODATA</span>=</span>$</span></span>(</span> curl</span> -</span>s</span> http</span>://</span></span>ip-api.com/json/ )</span>

read</span> -</span>r</span> -</span>d</span> '</span>'</span></span> JXA</span> <<</span>EOF</span>
function</span> run</span></span>(</span>)</span></span> {</span>
	var</span> ipinfo</span></span> </span>=</span> JSON</span>.</span>parse</span></span>(</span>\`</span>$GEODATA\`</span>);
	return ipinfo.city;
}
EOF

CITY=$( osascript -l 'JavaScript' <<< "${</span></span>JXA</span></span>}</span></span>" )

echo "This computer is in ${</span></span>CITY</span></span>}</span></span>"
</span></span></span></span></span></code></pre>
First, we call the ip-api service by using curl</code> to send a GET</code> request to the
service's JSON endpoint. The results are stored in a variable called GEODATA</code>
via command substitution</a>.</p>
Next, we use the read -r -d '' VARIABLE_NAME <<LIMIT_STRING</code> "bashism" to store
a multi-line JavaScript program as a variable using here-document</a>
notation. This makes it easier to write and maintain the JavaScript code, rather
than trying to smoosh it into a single line.</p>
This (extremely basic) JavaScript program takes advantage of JXA's special
run()</code> function. run()</code> is automatically executed when the program is called,
and will print any output returned.</p>
Within the JavaScript code, notice the assignment of ipinfo</code> references the
GEODATA</code> variable defined in the outer shell script via variable expansion. The
JSON returned by ip-api.com is a native JavaScript data structure that could be
used directly, but for safety we treat it as a string and parse it using the
JSON.parse()</code></a> method. Since most JSON payloads are multi-line
strings, we wrap the variable expansion in ``</code> backticks to take
advantage of JavaScript's template literal</a> feature. And finally,
those backticks need to be escaped using \</code> backslashes since they're embedded
within a shall script. Whew!</p>
When I first published this article, I advised that you could reference and use
a JSON object received from a remote source directly, without running it through
JSON.parse()</code>.</p>
This is true, but it's not secure. I was assuming the safety of the external
data.</p>
Paul Galow wisely pointed out</a> that a malicious source could
potentially send JavaScript instead of JSON, which our script would dutifully
execute. RCEs are bad. Be like Paul and run payloads through
JSON.parse()</code>. This ensures things that aren't JSON cause the script
to error.</p>
</aside>
A quick aside on quoting and here-documents: Quoting the limit string (EOF</code> in
this case) will prevent</strong> variable expansion within the here-document.
<<'EOF'</code> would cause $GEODATA</code> to be interpretted literally rather than
replaced by the results of the curl</code> command. The unquoted <<EOF</code> allows the
variable to expand as expected.</p>
Next, we simply return the city</code> attribute of the ipinfo</code> object.</p>
Finally, we use the osascript</code> binary to run the JavaScript program.
osascript</code> can read input from stdin</code>, so we use <<<</code> to read the program
stored in the JXA</code> variable. Storing its output in the CITY</code> variable lets us
use it elsewhere in the shell script. In this case we're outputting a nice
message. Running the script will print This computer is in Atlanta</code> (or
your approximate location) to your terminal.</p>
That was an extremely verbose explanation of a very basic program! But,
hopefully it helps explain the patterns being used here. Now let's try something
more complex.</p>
Complex JSON manipulation</h3>
Our next example will demonstrate the power of JavaScript's native JSON
capabilities. It's a neat trick to pull a single attribute out of a simple JSON
payload – but it's actually useful</strong> to manipulate the data using
conditional logic.</p>
Here we'll pull the recent commit history of the AutoPkg GitHub repository, then
retrieve the commits whose commit message length is longer than the soft
50-character recommended maximum length.</p>
Here's the code:</p>
#!</span>/bin/bash</span>

GITHUB</span>=</span>$</span></span>(</span> curl</span> -</span>s</span> https</span>://</span></span>api.github.com/repos/autopkg/autopkg/commits )</span>

read</span> -</span>r</span> -</span>d</span> '</span>'</span></span> GITCOMMITS</span> <<</span>EOF</span>
function</span> run</span></span>(</span>)</span></span> {</span>
	const</span> commits</span></span> </span>=</span> JSON</span>.</span>parse</span></span>(</span>\`</span>$GITHUB\`</span>);
	const long_messages = [];
	for (const commit of commits) {
		if (commit.commit.message.length > 50) {
			var msg = "'" + commit.commit.message + "' - Commit " + commit.sha;
			long_messages.push(msg);
		}
	}
	return long_messages.join("\n</span>");
}
EOF

osascript -l "JavaScript" <<< "${</span></span>GITCOMMITS</span></span>}</span></span>"
</span></span></span></span></span></code></pre>
The basic structure is largely the same as in the previous example: use curl</code>
to gather data, then feed that into a JavaScript program.</p>
The cool part is being able to manipulate the JSON data in place. Here, we're
iterating through each commit and checking the string length of each commit
message. If that length is longer than 50 characters, we append that message to
an array, along with the commit's SHA hash. Finally, we return a newline-joined
string of those commits.</p>
The end result prints only those commit messages longer than 50 characters.</p>
This example would have been extremely</em> cumbersome to implement in pure shell.
With JXA, it's just some relatively simple JavaScript.</p>
Reading JSON files from disk</h3>
You can also read JSON files that exist on disk with just a tiny bit of extra
effort.</p>
#!</span>/bin/bash</span>

read</span> -</span>r</span> -</span>d</span> '</span>'</span></span> PARSE</span> <<</span>EOF</span>
var</span> app</span></span> </span>=</span> Application</span>.</span>currentApplication</span></span>(</span>)</span></span>;</span>
app</span>.</span>includeStandardAdditions</span> =</span> true</span>;</span>

function</span> parseJSON</span></span>(</span>path</span>)</span></span> {</span>
    const</span> data</span></span> </span>=</span> app</span>.</span>read</span></span>(</span>path</span>)</span></span>;</span>
    return</span> JSON</span>.</span>parse</span></span>(</span>data</span>)</span>;</span>
}</span></span></span>

function</span> run</span></span>(</span>)</span></span> {</span>
    const</span> parsed</span></span> </span>=</span> parseJSON</span></span>(</span>"</span>/path/to/some/file.json"</span></span>)</span></span>;</span>
    return</span> parsed</span>.</span>some</span>.</span>key</span>;</span>
}</span></span></span>

EOF</span>
</span></code></pre>
This time, we're using using JXA to get an instance of the "current
application." This lets us do useful things like access the file system. We
define a reusable function to parse a JSON file at a path supplied as a
parameter. Within the run()</code> function, we call that parseJSON()</code> function and
supply the full path to a JSON file. We can then access the parsed JSON
properties using standard dot notation</a>.</p>
Other tools and alternatives</h3>
Why go through the trouble of using JXA for these use cases?</p>
First, it's really not much "trouble." I'd be implementing similar logic in
another external language or tool. This is more or less adding a thin wrapper.
As long as you are comfortable writing JavaScript (or searching StackOverflow),
it's very little extra effort.</p>
But why not use another tool or method?</p>
When running code on client systems within a fleet, it's best to use the tools
those clients have available by default.</p>
Since Apple will soon stop shipping scripting runtimes</a> such as
Python, Perl, and Ruby, you should not</strong> rely on "shelling out" to those
languages. Sure, it might be easy enough to add a parse=$( python -c 'import json;...' )</code> call to your script; but at this point you'd just be creating new
technical debt. Don't do that.</p>
If you ship your own Python 3 runtime – such as with "macadmin
python</a>" – you could, of course, use that. Installing your own
Python 3 framework on your clients is a great idea if you routinely use Python
code to manage them. Otherwise, it is</em> another external dependency.</p>
Alternatively, you could</em> pull down jq</a> on your client systems. jq is
built specifically to handle JSON on the command line and in shell scripts. But
again – it's an external dependency.</p>
Using JXA requires no new installations or configuration changes. It will simply
run on your systems as they currently exist.</p>
For that reason, I think JXA a great tool to reach for when you need to work
with JSON.</p>
Plus, constraints are fun, right?!</p>
Further reading</h3>
Interacting with JSON is a common need, but these examples barely scratch the
surface of what you can achieve with JavaScript for Automation.</p>
JXA even includes an Objective-C bridge</a>, which allows you to use macOS
frameworks like AppKit and Foundation.</p>
The JXA Cookbook</a> on GitHub contains a wealth of information and
is an essential read on this topic. It's a great supplement to Apple's somewhat
sparse documentation</a>.</p>


How to Disable iCloud Private Relay in macOS Monterey
Wed, 27 Oct 2021 00:00:00 +0000
Apple recently introduced iCloud Private Relay</a> as an additional
benefit for iCloud+ subscribers. The feature routes Safari web browsing
(and some other insecure Internet traffic) through a semi-anonymizing service
to reduce third parties' ability to profile and track individual users.</p>
However, it may be necessary in some environments to disable iCloud Private
Relay. The feature may interfere with management controls, prevent required
traffic auditing, or complicate troubleshooting procedures.</p>
Apple provides a guide to prepare your network or service for iCloud Private
Relay</a>, but it's also possible to disable the feature using a
Restrictions</a> Configuration Profile.</p>
</span>
To disable iCloud Private Relay, set the allowCloudPrivateRelay</code> key to false</code>
in the com.apple.applicationaccess</code> domain. An example full Configuration
Profile is below:</p>
<?</span>xml</span> version</span>=</span>"</span>1.0"</span></span> encoding</span>=</span>"</span>UTF-8"</span></span>?></span></span>
<!</span>DOCTYPE</span> plist</span> PUBLIC</span> "</span>-//Apple//DTD PLIST 1.0//EN"</span></span> "</span>http://www.apple.com/DTDs/PropertyList-1.0.dtd"</span></span>></span></span>
<</span>plist</span> version</span>=</span>"</span>1.0"</span></span>></span></span>
    <</span>dict</span>></span></span>
        <</span>key</span>></span></span>PayloadContent</</span>key</span>></span></span>
        <</span>array</span>></span></span>
            <</span>dict</span>></span></span>
                <</span>key</span>></span></span>PayloadDisplayName</</span>key</span>></span></span>
                <</span>string</span>></span></span>Restrictions</</span>string</span>></span></span>
                <</span>key</span>></span></span>PayloadIdentifier</</span>key</span>></span></span>
                <</span>string</span>></span></span>com.apple.applicationaccess.E8C72ECD-7122-4C66-853F-3F3467D1AEF5</</span>string</span>></span></span>
                <</span>key</span>></span></span>PayloadType</</span>key</span>></span></span>
                <</span>string</span>></span></span>com.apple.applicationaccess</</span>string</span>></span></span>
                <</span>key</span>></span></span>PayloadUUID</</span>key</span>></span></span>
                <</span>string</span>></span></span>1953B7E6-DB5C-4FDA-A579-2EE05978F4B6</</span>string</span>></span></span>
                <</span>key</span>></span></span>PayloadVersion</</span>key</span>></span></span>
                <</span>integer</span>></span></span>1</</span>integer</span>></span></span>
                <</span>key</span>></span></span>allowCloudPrivateRelay</</span>key</span>></span></span>
                <</span>false</span> /></span></span>
            </</span>dict</span>></span></span>
        </</span>array</span>></span></span>
        <</span>key</span>></span></span>PayloadDescription</</span>key</span>></span></span>
        <</span>string</span>></span></span>Disables the iCloud Private Relay feature.</</span>string</span>></span></span>
        <</span>key</span>></span></span>PayloadDisplayName</</span>key</span>></span></span>
        <</span>string</span>></span></span>Disable iCloud Private Relay</</span>string</span>></span></span>
        <</span>key</span>></span></span>PayloadIdentifier</</span>key</span>></span></span>
        <</span>string</span>></span></span>E31B0811-3164-49CE-BAA9-67075398DE85</</span>string</span>></span></span>
        <</span>key</span>></span></span>PayloadOrganization</</span>key</span>></span></span>
        <</span>string</span>></span></span>Company Name</</span>string</span>></span></span>
        <</span>key</span>></span></span>PayloadScope</</span>key</span>></span></span>
        <</span>string</span>></span></span>System</</span>string</span>></span></span>
        <</span>key</span>></span></span>PayloadType</</span>key</span>></span></span>
        <</span>string</span>></span></span>Configuration</</span>string</span>></span></span>
        <</span>key</span>></span></span>PayloadUUID</</span>key</span>></span></span>
        <</span>string</span>></span></span>ECEB2ECA-B16F-41F8-9909-7DD36FA1609C</</span>string</span>></span></span>
        <</span>key</span>></span></span>PayloadVersion</</span>key</span>></span></span>
        <</span>integer</span>></span></span>1</</span>integer</span>></span></span>
    </</span>dict</span>></span></span>
</</span>plist</span>></span></span>
</span></code></pre>
This profile is also available on GitHub</a>.</p>
Once installed, this profile:</p>

Stops traffic from routing to mask.icloud.com</code> and mask-h2.icloud.com</code> at
the network level.</li>
Removes "Private Relay" from the list of services available to enable in
System Preferences > Apple ID</em>.</li>
Removes the "Use iCloud Private Relay" checkbox from the "Network" pane in
System Preferences.</li>
</ol>
Requirements</h3>
Unlike many Configuration Profiles payloads, the com.apple.applicationaccess</code>
payload is re-evaluated after initial installation.</p>
That means this profile can be pre-installed on systems running macOS versions
prior to Monterey. Go ahead and deploy this restriction to your fleet before
they upgrade to macOS Monterey so the configuration takes immediate effect. It
won't have any effect on macOS Big Sur (or previous systems), but will begin
working once the system is upgraded to Monterey.</p>
This restriction does not</em> require Supervision.</p>
Caveat</h3>
I've noted a small bug in macOS Monterey 12.0.1. If the Configuration Profile
restricting iCloud Private Relay is installed while the relay is active</em>, the
checkbox in System Preferences > Network</em> remains visible.</p>



    
    

</figure>
Private Relay is in fact disabled</mark>, and no traffic is routed through
the service. The "Private Relay" feature is</em> removed from the listing in
System Preferences > Apple ID</em>. This visual bug persists through reboots, but
only occurs when the profile is installed while iCloud Private Relay is already
running.</p>


Getting the currently logged-in user's ID (UID) for launchctl
Mon, 15 Mar 2021 00:00:00 +0000
Many scripted macOS workflows require determining the username of the currently logged-in user. Whether you wish to execute a command as that user via su</code> or you just want to log the username during your script's execution, you may need to query macOS for this information.</p>
This is a solved problem, and Armin Briegel's excellent article on Getting the current user in macOS</a> outlines the best method.</p>
In addition to determining the logged-in user's username, you may also need their user ID number, or UID. For example, loading a LaunchAgent as a specific user requires providing that user's UID. </p>
Previous solutions involved grabbing the logged-in user's username, then feeding that to id -u $loggedInUser</code> – but you can get the currently logged-in user's UID in one step.</p>
</span>
The code</h2>
A slight modification of Armin's recommendation for grabbing the username will give us the UID.</p>
For bash and zsh</h3>
loggedInUserID=$( scutil <<< "show State:/Users/ConsoleUser" | awk '/kCGSSessionUserIDKey :/ { print $3 }' )
</span></code></pre>
For shell</h3>
Vanilla shell does not support the <<<</code> here-string</a> used in the previous example, so instead we must pipe the show</code> statement to scutil</code>.</p>
loggedInUserID=$( echo "show State:/Users/ConsoleUser" | scutil | awk '/kCGSSessionUserIDKey :/ { print $3 }' )
</span></code></pre>
Both variants will return the UID of the currently logged-in user, or an empty string if the Mac is sitting at the login window.</p>
An example and a note on launchctl</code> syntax</h2>
With a UID in hand, you can now load a LaunchAgent as</em> that user:</p>
launchctl asuser <uid> launchctl load /Library/LaunchAgents/com.org.example.plist
</span></code></pre>
However! In macOS Big Sur, I'm finding launchctl</code> is more reliable using the launchctl 2.0 syntax (as documented by Balmes Pavlov</a>). This makes sense, as subcommands like asuser</code> have been marked as "legacy" for some time now.</p>
Switching from the "legacy" subcommand asuser</code> to bootstrap gui/"${loggedInUserID}"</code> consistently loads launchd tasks, and is my current recommendation.</p>
A complete example of loading a LaunchAgent as the currently logged-in user:</p>
loggedInUserID=$( scutil <<< "show State:/Users/ConsoleUser" | awk '/kCGSSessionUserIDKey :/ && ! /loginwindow/ { print $3 }' )
/bin/launchctl bootstrap gui/"${loggedInUserID}" /Library/LaunchAgents/com.org.example.plist
</span></code></pre>


Renaming Computers via Snipe-IT using Jamf Pro
Wed, 13 Jan 2021 00:00:00 +0000
A couple of years ago, I shared a method to set a Mac's hostname via a Google
Sheet</a>. It's worked well at my organization (as well as many others!) and
helped us keep our computer names consistent.</p>
We've since moved to using Snipe-IT</a> for asset management. Snipe is a
fantastic open-source tool that simplifies inventory tracking for our whole IT
shop. It also includes a robust API that allows us to integrate with external
systems and processes.</p>
I'm now using the Snipe API to script our computer naming process. We treat
Snipe as the system of record for all inventory, and any change made to a
computer's hostname in Snipe can be reflected on both</em> the client system and in
Jamf Pro. Here's how.</p>
</span>
Why Python?</h2>
For many years, Apple included Python 2.7 with the default installation of
macOS. With the 2019 release macOS Catalina, of Apple began warning</a> that
"future versions of macOS will not include" runtimes for popular languages
including Python.</p>
As of macOS Big Sur 11.1, the Python 2.7 runtime is still present. However,
Python 2 is no longer maintained</a> and is not a good choice for forward
compatibility. Many administrators are moving their system administration
processes to shell scripts, which mostly "run anywhere" and don't rely on any
runtime dependencies.</p>
Despite the convenience and portablity of shell scripts, I maintain a number of
complex Python workflows that are arduous or ill-suited to port to shell.</p>
This script interfaces with the Snipe API, which accepts and returns data in
JSON format. While tools and workarounds exist to work with JSON in shell
scripts, it's frankly painful.</p>
In my organization, I've taken to installing Python 3 to a known location using
Greg Neagle's Relocatable Python</a> tool. This allows me to use Python's
native JSON tooling and interact with the Snipe API without hassle.</p>
As such, this script is written in Python 3, and the shebang on line 1</code>
requires you to specify the path to the Python 3 runtime you've installed on the
client system.</p>
The script</h2>
I've published this script is as a project on Github at
haircut/jamf-snipe-rename</a>.</p>
The set_computer_name.py</code> script is what you're looking for.</p>
What it does</h3>
The script gathers the serial number of the computer upon which it's running,
then queries your Snipe instance via the API to discover its current Asset Name
as set within that system. Then, it sets the hostname of the computer using the
Jamf binary's setComputerName</code> command.</p>
As a fallback, if your Snipe instance does not have a record of the serial
number, the computer name will be set to that serial number. Setting the
hostname to the computer's serial number is a reasonable alternative, as it lets
us easily identify machines that could not be renamed by the script, then fix
the source data within Snipe. And, the serial number is much better than a bunch
of Macs named "Sarah's MacBook Pro!"</p>
Setting up Snipe</h2>
I recommend setting up a dedicated local user with restricted access in Snipe to
handle all requests associated with this workflow. </p>
The Snipe documentation explains creating users</a> and setting
permissions</a>. I name my user something relevant like "Jamf Computer Naming
User" or similar.</p>
Following the principle of least privilege, grant this local user only</em> the
View</strong> permission under Assets</strong> and Create API Keys</strong> under Self</strong>.</p>
Log in to Snipe as the new local user, and generate an API key</a>. This will
generate a (very long) bearer token</a> we'll use to authenticate our script's
requests.</p>
Using the script</h2>
Save a local copy of set_computer_name.py</code> and configure the SNIPE_SERVER</code>
value (near the top of the script) to point toward your Snipe installation. It's
important to only provide the base URL here, as the script will add the full
path to the API endpoint we need.</p>
Encrypting script parameters</h3>
Since we're using the sensitive API key in our script to authenticate requests
to Snipe, it's best not to hardcode that API key into the script. Nor is it wise
to pass the API key as a script parameter</a> in cleartext.</p>
While the restricted permissions of the Snipe user limit the potential damage
from a leaked key, it's still best to avoid the hazard by encrypting the user's
API key and passing it as a script paramter.</p>
I'm using Jamf's Encrypted Script Parameters</a> utility to securely pass the API token from Jamf Pro to the client system. A full explanation of the utility is beyond this article's scope, but briefly:</p>

Follow Jamf's README to encrypt your API key.</li>
Note the ecrypted value, salt, and passphrase. Save them all in your
organization's shared password manager :)</li>
Paste the salt and passphrase in the TOKEN_SALT</code> and TOKEN_PASSPHRASE</code>
constants near the top of your copy of the script.</li>
</ol>
Adding the script to Jamf Pro</h3>
Within your Jamf Pro instance, visit _Management Settings > Computer Management</p>

Scripts_, then add a new script. Name it something helpful, like "Set Computer
Name from Snipe" and then set the label for Parameter 4 to "Encrypted API Key."
Paste in your (configured) copy of the script, then save.</p>
</blockquote>
Running the script via policy</h3>
Create a new policy, then configure the "Script" payload. Add the "Set Computer
Name from Snipe" script, then fill in the "Encrypted API Key" script parameter
with the encrypted API key you created earlier.</p>
I recommend updating the computer's inventory after renaming it, so that your
Jamf instance is updated with the new hostname as soon as possible. If your
deployment is large, consider omitting the inventory update to save on the
processing burden inherent in updating inventory.</p>
How and when to run the script is largely dependent on your needs. I run the
renaming process early in our provisioning workflow using Jamf's "Enrollment
Complete" trigger.</p>
You could also create a secondary policy that runs on a routine basis – say,
weekly – to ensure Jamf data stays consistent with your inventory data in Snipe.</p>
Running the script outside of Jamf Pro</h3>
If your organization does not use Jamf Pro to manage Macs, you can still use
this script after a few modifications.</p>
As written, the script uses the Jamf binary's setComputerName</code> command. This is
a convenient shorthand for running the following three commands:</p>
sudo</span></span> scutil --</span>set</span> ComputerName "</span>name"</span></span></span>
sudo</span></span> scutil --</span>set</span> LocalHostName "</span>name"</span></span></span>
sudo</span></span> scutil --</span>set</span> HostName "</span>name"</span></span></span>
</span></code></pre>
Within this project's repository</a>, I've also shared
set_computer_name_non_jamf.py</code> which substitues the Jamf binary call for the
three commands above. This non-Jamf script expects an encrypted</em> Snipe API
token as its first positional parameter. If you're using this workflow with a
management platform other than Jamf, I've left it as an exercise to the reader
on passing the parameter. Even if you're not using Jamf, their encrypted script
parameters</a> project is platform agnostic.</p>
Conclusion</h2>
This transition from my previous Google Sheets-based workflow</a> has been a
big help in my organization. It allows us to treat our inventory system as our
source of truth for computer names, as it should be. Changes made in the
inventory system are reflected on the client system with no manual intervention.</p>


Don't disable accessibility options during Setup Assistant
Fri, 27 Nov 2020 00:00:00 +0000
macOS Big Sur includes a new screen during Setup Assistant: Accessbility. It
prompts users to explore the accessibility features of macOS to adapt their
computer to their vision, motor, hearing, and cognitive needs.</p>
You might want to disable or skip this setup screen. Don't.</p>
</span>


    
    

</figure>
The first time you boot a Mac, it runs through a process known as Setup
Assistant. This lets your users configure some basic options before they begin
using the computer. With each new macOS release, Apple adds additional screens
to Setup Assistant. Some are of dubious utility. </p>
Most popular MDMs allow you, as an administrator, to instruct Macs to skip
certain screens during Setup Assistant. In a corporate environment, your users
may not need to set up Apple Pay, or agree to the Terms and Conditions – so it
makes sense to simply skip these screens and streamline their first boot.</p>
If you support more humans than only yourself, how those humans
interact with their computer is not your decision.</strong></mark></p>
Even those who would not traditionally consider themselves in need of
accessibility features can still benefit. Putting these options front and center
allows everyone the opportunity to explore settings that might just make their
Mac a bit easier to use.</p>
Kudos to Apple for making accessibility a default</em> aspect of the macOS setup
process.</p>


Sending Autopkg and JSSImporter Notifications to Google Hangouts Chat
Mon, 29 Apr 2019 00:00:00 +0000
Although Slack</a> has seemingly taken over the world
of workplace chat, my organization is a G Suite</strong> shop and we use 
Hangouts Chat</a> for a majority
of our internal communication. It's included as a "core" G Suite app,
so why not use the product we already have, right?</p>
I wanted a way to post notifications to Hangsouts Chat rooms when
autopkg</a> downloads new software, or makes
changes to our Jamf Pro server via
JSSImporter</a>. No solution existed.
Building on the excellent Slack-centric work of both Graham R
Pugh</a> and
Rich
Trouton</a>,
I've made two different autopkg
postprocessors</a>
to send autopkg notifications to Google Hangouts Chat.</p>
</span>
HangoutsChatNotifier</code> - simple notifications</h3>
If you'd just like to know when your automated autopkg run downloads new
software, HangoutsChatNotifier</code> will send a simple note to a Hangouts
Chat room.</p>



    
    

</figure>HangoutsChatJSSNotifier</code> - going deeper with JSSImporter</code></h3>
If you're using JSSImporter</a> to
automate the process of adding the software autopkg downloads to your JSS,
HangoutsChatJSSNotifier</code> will send more detailed messages to a Hangouts Chat
room.</p>



    
    

</figure>
Both postprocessors leverage the existing data provided during an autopkg run to
send data to a Hangouts Chat incoming
webhook</a>.</p>
To set these up on your own G Suite domain, you'll need:</p>

Hangouts Chat</a> enabled for your
users</li>
Bots enabled</a> for all OUs in
your domain. If Bots are not enabled across the domain, your notifications
will
fail</a></li>
My haircut-recipes</a> autopkg
recipes present in your autopkg repository, which includes these Hangouts Chat
postprocessors</li>
An incoming
webhook</a>
configured for the Hangouts Chat room you wish to notify</li>
...and of course, a working autopkg setup</li>
</ul>
Setting up a webhook</h2>
In Hangouts Chat, open the room you'd like to notify, then click the room's name
near to top of the screen.</p>



    
    

</figure>
Click Configure webhooks</em>. Enter a name for the incoming webhook – I just
use "autopkg" – then click Save</em>. </p>



    
    

</figure>
You'll see a long URL displayed representing the API endpoint we can use to send
messages to this room. Copy that URL and save it for later.</p>



    
    

</figure>Which postprocessor should I use?</h2>
Whichever you like! </p>
HangoutsChatNotifier</code> sends simple messages to inform you when your autopkg
workflow has downloaded new software. The quick notifications might be useful to
send to your desktop support team Hangouts Chat room, or your QA group.</p>
If you're using JSSImporter</code> as part of your autopkg workflow, you may find the
expanded detail provided by HangoutsChatJSSNotifier</code> useful. Setting up
JSSImporter</code> is beyond the scope of this article – but if you're already there,
HangoutsChatJSSNotifier</code> will help you send notifications to Hangouts Chat.</p>
Running the postprocessor</h2>
You have two options to include the Hangouts Chat postprocessors in your autopkg
runs.</p>
Using a postprocessor at the command line</h3>
The simplest method is to include the --post</code> flag when running autopkg at the
command line. </p>
...for HangoutsChatNotifier</code></h4>
Specify the postprocessor name
com.github.haircut.HangoutsChatNotifier/HangoutsChatNotifier</code> and provide a
--key</code> in the form --key hangoutschat_webhook_url="<incoming webhook url>"</code>.
Replace <incoming webhook url></code> with the URL you noted earlier after creating
an incoming webhook in your Hangouts Chat room.</p>
A complete command might look like:</p>
autopkg run MyRecipe.recipe \
--post "com.github.haircut.HangoutsChatNotifier/HangoutsChatNotifier" \
--key hangoutschat_webhook_url="https://chat.googleapis.com/v1/spaces/XXX/messages?key=XXX-XXX&token=XXX-XXX"
</span></code></pre>
...for HangoutsChatJSSNotifier</code></h4>
Just like the simple notifier, add a --post</code> flag to your autopkg run and
specify com.github.haircut.HangoutsChatNotifier/HangoutsChatNotifier</code>, and a
--key hangoutschatjss_webhook_url="<incoming webhook url>"</code>.</p>
This example might look like:</p>
autopkg run MyRecipe.recipe \
--post "com.github.haircut.HangoutsChatJSSNotifier/HangoutsChatJSSNotifier" \
--key hangoutschatjss_webhook_url="https://chat.googleapis.com/v1/spaces/XXX/messages?key=XXX-XXX&token=XXX-XXX"
</span></code></pre>
...with a recipes text list</h4>
If you use a text file list of multiple
recipes</a>
the postprocessors are compatible and will send a Hangouts Chat message after
each recipe runs.</p>
For example:</p>
autopkg run --recipe-list /path/to/recipe_list.txt \
--post "com.github.haircut.HangoutsChatJSSNotifier/HangoutsChatJSSNotifier" \
--key hangoutschatjss_webhook_url="https://chat.googleapis.com/v1/spaces/XXX/messages?key=XXX-XXX&token=XXX-XXX"
</span></code></pre>
Using a postprocessor with a recipe property list</h3>
My preferred method of running multiple autopkg recipes is using a property
list
(plist)</a>.
A plist recipe list lets you set up declarative and robust autopkg
configurations that would otherwise require a messy string of command line
arguments.</p>
To include the Hangouts Chat postprocessor, add it as an array item under the
postprocessors</code> key. Then, add your incoming webhook url as a string under a
hangoutschat_webhook_url</code> key.</p>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>recipes</key>
    <array>
        <string>MyRecipe.recipe</string>
        <string>AnotherRecipe.recipe</string>
        <string>RadicalRecipe.recipe</string>
    </array>
    <key>hangoutschat_webhook_url</key>
    <string>https://chat.googleapis.com/v1/spaces/XXX/messages?key=XXX-XXX&amp;token=XXX-XXX</string>
    <key>postprocessors</key>
    <array>
        <string>com.github.haircut.HangoutsChatNotifier/HangoutsChatNotifier</string>
    </array>
</dict>
</plist>
</span></code></pre>

    Important!</strong> Hangouts Chat incoming webhook URLs
    include an ampersand (&</code>) in the query parameters, which
    is an illegal character within an XML <string></code>
    element. You must</strong> replace the ampersand with its
    character entity &amp;</code> when including the incoming
    webhook URL in a property list file – otherwise the postprocessor
    will fail to send a notification.
  </p>
  

    e.g. .../XXX/messages?key=XXX-XXX&amp;token=XXX-XXX</code>
</aside>
Now you can run your recipe list and send Hangouts Chat notifications using a
much less cumbersome command:</p>
autopkg run --recipe-list /path/to/recipe_list.plist
</span></code></pre>
Using both HangoutsChatNotifier</code> and HangoutsChatJSSNotifier</code> together</h2>
The namespace for each postprocessor is distinct, so you can</em> use both
simultaneously during a single autopkg run. For example, you might like to send
your helpdesk a brief notification that new software is available using
HangoutsChatNotifier</code>, and your engineering team managing Jamf Pro a more
detailed note showing the changes made to your JSS.</p>
For this example, you'd create one incoming webhook in your "helpdesk" Hangouts
Chat room and set its URL as the hangoutschat_webhook_url</code> key. Create a second
incoming webhook in your "Jamf Pro" Hangouts Chat room and set that URL as the
hangoutschatjss_webhook_url</code>. Add both postprocessors to your autpkg run –
done!</p>
Wrapping up</h2>
If you have need to customize the formatting or content of the Hangouts Chat
notifications, you can fork my postprocessors found at
autopkg/haircut-recipes/PostProcessor</a>.
Google has great
documentation</a>
around their message formats.</p>
Now go forth and notify your teams!</p>


Helping Your Users Reset TCC Privacy Policy Decisions
Mon, 10 Sep 2018 00:00:00 +0000
Taking a cue from iOS, Mac OS X 10.8 "Mountain Lion" introduced new systems to
help users manage access requests to potentially sensitive and private personal
information. When an app required access to a user's Contacts, for instance, a
consent prompt appeared on screen asking the user to allow or disallow this
access.</p>
Broadly, this system is known as TCC</code> or transparency, consent and control</em>.</p>
With each version of macOS, Apple broadens the scope of privacy controls. The
upcoming release of macOS Mojave expands these controls such that many
previously-permitted interactions will require user consent. Prompts for consent
appear only once</em> when an action first requires approval.</p>
With more to manage and only a single prompt to allow or disallow access, it can
be opaque for users to understand the state of their system. Actions may fail
with no clear indication as to why; a decision to disallow access is easily
forgotten after many weeks or months.</p>
Let's create an easy method to reset these decisions to allow for a fresh start.</p>
<!- -more --></p>
Background</h2>
Some brief background.</p>
The origins of TCC</code> are explained during the "How iOS Security Really Works</a></em>" session from WWDC 2016.</p>
During WWDC 2018 Apple hosted two sessions explaining the direction of their
privacy and security posture:</p>

Your Apps and the Future of macOS Security</a></li>
Better Apps through Better Privacy</a></li>
</ul>
Both sessions are insightful – check them out!</p>
For a deeper dive into changes around Privacy controls in macOS Mojave, I highly
recommend Rich Mogull's excellent article Mojave’s New Security and Privacy
Protections Face Usability
Challenges</a>.</p>
The Issue</h2>
When a user decides to allow or disallow an interaction via a user consent 
prompt, that decision should appear in _System Preferences > Security & Privacy</p>

Privacy_. In my testing of macOS Mojave, I noticed that some allowed or
disallowed interactions – namely certain "automation" decisions – did not appear
in a user-configurable capacity in System Preferences</em>. This effectively makes
affected decisions "permanent" unless a user is comfortable using a command line
utility.</p>
</blockquote>
Moreover, there is no GUI-based method to reset all privacy consent decisions
and "start from scratch." Apple does, helpfully, provide a command line utility
to programmatically un-configure consent decisions so that interactions may
prompt for approval again.</p>
Resetting Privacy Consent Decisions</h2>
macOS includes a utility called tccutil</code>. This tool allows you to manage the
privacy database and reset decisions you've made regarding TCC-protected
services.</p>
tccutil</code> is a simple utility, supporting one command: reset</code></p>
Resetting decisions made for a particular service is straightforward:</p>
tccutil reset <service name>
</span></code></pre>
And here's a list of known services:</p>
Accessibility
AddressBook
All
AppleEvents
Calendar
Camera
Facebook
LinkedIn
Liverpool
Location
MediaLibrary
Microphone
Photos
PhotosAdd
PostEvent
Reminders
ShareKit
SinaWeibo
Siri
SystemPolicyAllFiles
SystemPolicyDeveloperFiles
SystemPolicySysAdminFiles
TencentWeibo
Twitter
Ubiquity
Willow
</span></code></pre>
(Thanks to @opragel</a> for extracting the list of
services.)</p>
By way of example, the following command would reset all decisions you've made
regarding access to your calendar events. All apps that access your calendar
would then prompt you again for consent to access the data the next time you
launch them.</p>
tccutil reset Calendar
</span></code></pre>
In testing this utility I developed a quick script to automate the process of
resetting all</strong> the above-listed services. You can find tcc-reset.py on
GitHub</a>.</p>
I wanted to provide the same tool to my users as an easy-to-use troubleshooting
utility, so I've expanded it to make it available in Jamf Self Service. This
allows users to reset privacy consent decisions without needing to contact IT.</p>
Self Service Privacy Consent Reset</h2>
The goal here is to provide a mechanism for users to reset all their decisions
to allow or disallow apps to access protected services or files. We'll
accomplish this with a script and a policy.</p>
The Script</h3>
Self-Service-Reset-Privacy-Consent.py</a>
is an expansion of my original
tcc-reset.py</a>
script. Running the script with no parameters will reset all privacy consent
decisions for the currently-logged-in user. Optionally, you may pass the word
all</code> as Jamf Parameter 4 to reset privacy consent decisions for all users on a
system.</p>
Add a new Script to your JSS. Give the script a suitable name, then paste in the
contents of
Self-Service-Reset-Privacy-Consent.py</a>
in the "Script" tab.</p>
Jump to the "Options" tab. Leave the Priority set to "After", then add a label
for Parameter 4: "Reset all users? (Type 'all')"</p>



    
    

</figure>
Save the Script. Next, we'll set up a policy.</p>
The Policy</h3>
Create a new Policy. Give it an appropriate name; I've chosen "Reset Privacy
Consent Decisions" to be consistent with the language Apple uses to describe TCC
features. Leave all Triggers un-checked; this policy will only be available via
Self Service. I set the Execution Frequency to "Ongoing" to ensure users have
access to the utility whenever they need.</p>
Add your Self-Service-Reset-Privacy-Consent.py</code> script to the Scripts payload
of your policy. As mentioned, you can optionally set Parameter 4 to all</code> so
that privacy consent is reset for all users on a system. With single-user
systems this shouldn't be necessary. By default the script resets consent
decisions for the currently-logged-in user. However, I've included the option
for those managing labs or other multi-user systems.</p>



    
    

</figure>
Set an appropriate policy scope in the "Scope" tab. I use the "All Managed
Clients" computer group so the utility is available to all users.</p>
Next, open the "Self Service" tab and check the box to "Make policy available in
Self Service." I set the "Button Name Before Initiation" and "Button Name After
Initiation" to "Reset" so the button always displays the same text.</p>
I check "Ensure that users view the description" and set the following text as
the description:</p>

Resets your Privacy Consent decisions.</p>
If you experience application behavior where certain features like Camera, 
Microphone, or Disk Access do not work as expected, resetting your Privacy 
Consent decisions will allow applications to prompt you for consent to access
these features.</p>
</blockquote>
Finally, I upload an icon to spruce up the presentation of the policy when
viewed in Self Service. You're welcome to download the
icon</a> for use in
your organization.</p>



    
    

</figure>
And there we go! Our users can now reset or "undo" all the decisions they've
made regarding privacy consent. Apps will once again prompt for consent when
initiating a sensitive interaction.</p>
Wrapping Up</h2>
As the release date of macOS Mojave approaches, I'm hopeful Apple will provide
more detailed documentation around these features.  While I applaud their
apparent goal of increased visibility into access of potentially-sensitive user
data, I'm concerned this current implementation will only confuse users who may
not understand the effects of allowing or disallowing certain interactions.</p>
We shouldn't have to engineer scripts to help users manage Privacy features. If
Apple wants users to embrace these features, they must understand them and their
implications on how their Mac functions. Explicit and concise controls provided
in the GUI should display all</em> user decisions and allow for seamless
administration. Resetting these decisions shouldn't be relegated to a command
line tool. Users need clarity. I mean... "transparency" is right there in the
name "Transparency, Consent and Control", right?</p>
For more information, please join the #tcc</code> channel on the MacAdmins Slack
Team</a>.</p>


Signing Configuration Profiles
Fri, 03 Aug 2018 00:00:00 +0000
Apple has made it clear; MDM is the future.</p>
As the preferred method of device management moves more and more to
Configuration Profiles, administrators must turn their focus toward digital
security.</p>
Signing configuration profiles provides assurance of their origin, and an
assertion their contents have not been modified in transit.</p>
</span>
A profile signed with a trusted signing certificate appears in System
Preferences > Profiles with a green "Verified" label.</p>



    
    

</figure>
If the profile is signed by a certificate that was not issued by a certificate
authority trusted by the operating system – as is the case with a self-signed
certificate – the profile appears with a red "Unverified" label.</p>



    
    

</figure>
If the profile is not signed at all, it appears with a red "Unsigned" label.</p>



    
    

</figure>
    Note:</strong> While this guide focuses on signing Configuration Profiles for use with Jamf Pro, the concepts apply generally.</p>
</aside>
Jamf Pro includes a built-in certificate authority. It's a key piece of
functionality that allows Jamf Pro to generate digital certificates to
facilitate secure, trusted communication between your clients and your Jamf Pro
server.</p>
During setup, the Jamf Pro built-in certificate authority generates a signing
certificate for both macOS and iOS. This signing certificate is used to
digitally sign configuration profiles deployed by your Jamf Pro server. Each
enrolled client will have the "JSS Built-in Signing Certificate" installed to
its System keychain. This certificate is issued by your Jamf Pro server's
built-in certificate authority. Since your clients trust your Jamf Pro server's
root certificate, the signing certificate is also trusted; the chain is
complete.</p>
Profiles created using the Jamf Pro configuration profile interface are
automatically signed using the "JSS Built-in Signing Certificate" created during
installation of your Jamf Pro server.</p>



    
    

</figure>Why Sign Your Profiles?</h2>
If you only use Jamf Pro's configuration profile creation interface, Jamf Pro
handles all the signing for you.</p>
However, if you create custom profiles "from scratch," then upload them to Jamf
Pro for deployment, you should sign them.</p>
When you upload an unsigned configuration profile, the Jamf Pro server converts
it into a format you can edit using their interface. Unfortunately, this
conversion process often results in a finished profile that incorrectly manages
the settings you specified, or even manages settings that were not included in
the original source profile at all.</p>
Here's one example. Uploading a profile that manages the domain
com.apple.security.firewall</code> and sets the key EnableFirewall</code> to true</code>
results in a Jamf-converted profile that sets that key to false</code> – the exact
opposite of what you intended! This particular defect is filed as Product Issue
PI-004130, but no resolution is currently in place.</p>
Signing your custom configuration profiles before uploading them prevents
the Jamf Pro server from manipulating their contents.</mark> This ensures your
profile is delivered unaltered to your clients.</p>
When you upload a signed configuration profile, Jamf Pro warns you that the
profile is read-only and offers you the opportunity to remove the digital
signature.</p>



    
    

</figure>
Don't click the "Remove Signature" button. You won't be able to edit the profile
within the Jamf Pro web interface – but neither can Jamf! The profile is
delivered to client systems unmodified.</p>
If you do need to make edits to the profile, you'll need to do so in a text
editor, re-sign the profile, then upload it again to your Jamf Pro server. It's
a minor inconvenience, but ensures you don't accidentally manage unintended
preferences.</p>
Signing Profiles for Trust by Any Client</h2>
With an Apple Developer certificate you can easily sign profiles (and other
objects) to provide assurance of origin. So long as you abide by the terms of
the Apple Developer Program, your profiles will be trusted on any macOS or iOS
device.</p>
If you manage more than a handful of devices, you should really</strong> sign up for
the Apple Developer Program</a>. The
Developer Program will provide you with a number of certificates issued by Apple
that are trusted on all macOS and iOS devices. This is useful for signing your
Jamf Pro QuickAdd package, signing other installer packages, and signing
configuration profiles. When these objects are signed you avoid the hurdles of
your packages being quarantined by Gatekeeper, or your profiles appearing as
"unverified."</p>

Sign in to the Apple Developer Program account
portal</a>. </li>
Click "Certificates, IDs & Profiles".</li>
Click the dropdown menu near the upper left labeled "iOS, tvOS, watchOS" then
select "macOS".</li>
Click "All" under the "Certificates" heading, then click the plus button near
the upper right.</li>
When prompted "What type of certificate do you need?", select "Developer ID",
click Continue, then select "Developer ID Installer." While this type of
certificate may be the best choice, other certificates will also work. See
the note below for details.</li>
Follow Apple's on-screen instructions to generate a Certificate Signing
Request (CSR) and install the resultant certificate in your login keychain.</li>
</ol>
With your certificate installed in your keychain, use the security</code> tool to
sign a profile.</p>
/usr/bin/security cms -S -N "<common name of certificate>" -i <input path to unsigned profile> -o <output path for signed profile>
</span></code></pre>
A complete example might look like:</p>
/usr/bin/security cms -S -N "Mac Developer: Matthew Warren (XXXXXXXXXX)" -i ~/Documents/Unsigned.mobileconfig -o ~/Documents/Signed.mobileconfig
</span></code></pre>
When signing a Profile, you'll be asked to unlock your login keychain. Enter
your login keychain password and click "Allow".</p>



    
    

</figure>
You could also click "Always Allow" to avoid future prompts when signing
Profiles, but I tend to err on the side of security and just enter my password
each time.</p>
Note: What type of certificate should you choose?</em></h4>
Apple provides a number of different certificate types. While I recommend the
"Developer ID Installer," most (if not all) of the options Apple provides will
produce a certificate with the correct Key Usage attributes required to sign a
Configuration Profile.</p>
The choice is largely aesthetic, since the Common Name of the certificate will
be visible to end users when viewing a Configuration Profile in the Profiles</em>
pane within System Preferences.</p>
The visible name listed beside the "Signed" heading generally follows the
pattern <Certificate Type>: <Company or Individual Name> (<Team ID>)</code>. For
example:</p>



    
    

</figure>
Another consideration is the Apple ID used to create the certificate. If you're
signed in using the "parent" Apple ID of your organization's Apple Developer
Account you'll have the most options available, including the recommended
"Developer ID Installer" option. Generated certificates will include your
company or organization's</strong> name in their Common Name. If you're using an
Apple ID that has been granted delegated access to your organization's Developer
Program, generated certificates will instead have your name</strong> included in the
Common Name.</p>
Again, most if not all of the Apple's options are suitable for signing
Configuration Profiles – just keep in mind the differences in presentation.</p>
Next, let's take a look at an alternative way to generate a signing certificate
we can use to sign Configuration Profiles without</em> having access to Apple's
certificate portal.</p>
Signing Profiles for Trust Only by Jamf-enrolled Clients</h2>
If you do not (and/or cannot</em>) participate in the Apple Developer Program, you
can use Jamf Pro to generate a certificate to sign your custom configuration
profiles. Profiles signed with a Jamf Pro-generated certificate will be trusted
only</strong> by clients enrolled to your Jamf Pro instance; however, this is likely
sufficient for most use cases.</p>
Jamf Pro's Built-in CA allows you to generate arbitrary certificates of the
following types:</p>

Client Certificate</li>
Web Server Certificate</li>
SSO Certificate</li>
</ul>
During setup, the Jamf Pro built-in certificate authority generates a signing
certificate for both macOS and iOS. This signing certificate is used to
digitally sign configuration profiles deployed by your Jamf Pro server. Each
enrolled client will have the "JSS Built-in Signing Certificate" installed to
its System keychain. This certificate is issued by your Jamf Pro server's
built-in certificate authority. Since your clients trust your Jamf Pro server's
root certificate, the signing certificate is also trusted; the chain is
complete.</p>
While it might seem tempting to re-use these certificates to sign your
custom-crafted profiles, Jamf Pro does not present a GUI option to download
them. This is a good thing!</p>
If you could</em> download and use the private key of your "JSS Built-in Signing
Certificate" to sign arbitrary profiles it would present a larger security risk.
If that key was ever compromised, it would affect every item signed by that
certificate. This includes devices' MDM enrollment profiles. You'd have to
regenerate your Jamf Pro built-in certificate authority and re-enroll every
client. Let's avoid that!</p>
Instead, we'll generate our own certificate for signing configuration profiles.
First we'll need to generate a Certificate Signing Request (CSR) on your Mac.</p>
Create A CSR on Your Mac</h3>
Perform these steps on a client enrolled to your Jamf Pro server so that the
certificate trust chain is complete.</p>

Open the Keychain Access app.</li>
Click the Keychain Access</strong> menu in the menu bar, hover over Certificate
Assistant</em>, then select Request a Certificate From a Certificate
Authority...</em>.</li>
In the Certificate Assistant</strong> window that appears enter an email address
for your organization (I use a generic one) and a suitable Common Name, such
as " Profile Signing Certificate" or similar. For
the "Request is:" option, select "Saved to disk" then click Continue</em>.



    
    

</figure></li>
When prompted, choose a location to save the CSR.</li>
</ol>
Upload the CSR to your Jamf Pro Server</h3>

Open the CSR you saved to disk during the previous steps in a plain text
editor and copy the entire contents to your clipboard.



    
    

</figure></li>
Sign in to your Jamf Pro server and navigate to _Settings > Global Management

PKI Certificates_.</p>
</blockquote>
</li>
Click the "Management Certificate Template" tab near the top of the screen.</li>
Click the "Create Certificate from CSR" button.</li>
In the modal window, paste the contents of your CSR, then select a
Certificate Type</em> of "Web Server Certificate" and click the "Create" button. 



    
    

</figure></li>
After clicking "Create", a file with a name in the format of C=US,CN=<common name you chose>,E=<email you specified>.pem</code> will automatically download. In my
experience, the Jamf Pro GUI freezes at this point; simply click any link on the
page to navigate away – we've already got what we came for!</li>
Open the downloaded .pem</code> file. When prompted, choose to install the
certificate in your login keychain. 



    
    

</figure></li>
</ol>
The certificate is now installed to your login keychain and ready to reference
by name when signing Configuration Profiles.</p>
/usr/bin/security cms -S -N "<common name of certificate you just installed>" -i <input path to unsigned profile> -o <output path for signed profile>
</span></code></pre>
When prompted, enter unlock your login keychain to finish signing the profile.</p>
Finally, let's look at a third way to generate a certificate suitable for
signing Profiles.</p>
Signing a Profile – The Quick-and-Dirty, But Not Best Way</h2>
If for some reason you neither participate in the Apple Developer Program, nor
create a certificate within your Jamf Pro server, you do still have an option.
We can create a Self Signed Certificate suitable for signing profiles. The
resulting signed profile will not be trusted once deployed to a client system,
but its signature will</em> prevent Jamf Pro from modifying its contents. Once
installed, if the profile is viewed in the Profiles pane of System Preferences,
it will display the red "Unverified" notice.</p>
Create a Self Signed Code Signing Certificate</h3>

Open the Keychain Access app.</li>
Click the Keychain Access</strong> menu in the menu bar, hover over Certificate
Assistant</em>, then select Create a Certificate...</em>.</li>
In the Certificate Assistant</strong> window that appears, enter a sensible name.
Select the Identity Type</em> of "Self Signed Root" and Certificate Type</em> of "Code
Signing". Check the box beside "Let me override defaults". 



    
    

</figure></li>
Leave the Serial Number</em> set to "1", and increase the Validity Period</em> to
something like "1096" days (3 years) for convenience.



    
    

</figure></li>
On the next screen, enter relevant values for your organization. Make sure to
specify a descriptive Common Name</em> for the certificate, as this will be
viewable when inspecting Configuration Profiles signed by this certificate.



    
    

</figure></li>
Leave the default values of "2048 bits" for Key Size</em> and "RSA" for
Algorithm</em>.



    
    

</figure></li>
Ensure "Signature" is selected for the Key Usage Extension</em>.



    
    

</figure></li>
Ensure "Code Signing" is selected for the Extended Key Usage Extension</em>.</li>



    
    

</figure></li>
On the following screens, leave "Include Basic Contraints Extension" and
"Include Subject Alternate Name Extension" unchecked.</li>
When prompted, ensure the certificate is set to be stored in your "login"
keychain.



    
    

</figure></li>
</ol>
After clicking "Done" you should see the new certificate listed in your login
keychain.</p>



    
    

</figure>
You can now sign Configuration Profiles using the security</code> binary by
referencing the common name of your new self-signed certificate.</p>
/usr/bin/security cms -S -N "<common name of self-signed certificate>" -i <input path to unsigned profile> -o <output path for signed profile>
</span></code></pre>
Again, keep in mind that Configuration Profiles signed with a self-signed
certificate will be listed as "Unverified" in System Preferences. While this
won't affect the ability to install the profile, it could be a security concern
depending on your environment. "Unverified" profiles assure that their contents
have not been modified in transit, but provided no assurance of origin.</p>
GUI Tool</h2>
If you'd prefer a graphical tool to manage signing Configuration Profiles (or
packages), check out Hancock</a>. You'll
still need to correctly generate a signing certificate using a method outlined
above, but Hancock can save you some keystrokes if you prefer an app!</p>
Wrapping Up</h2>
We've covered three different methods – in order of preference – to generate a
signing certificate we can use to sign Configuration Profiles.</p>
Signing a Configuration Profile prevents an MDM system, like Jamf Pro, from
tampering with its contents; your hand-crafted profile is delivered to clients
unaltered. If your signing certificate is trusted by the client system, it also
provides verification that the Configuration Profile was created and delivered
by a trusted party.</p>
Regardless of how you generate your signing certificate, remember the command:</p>
/usr/bin/security cms -S -N "<common name of signing certificate>" -i <input path to unsigned profile> -o <output path for signed profile>
</span></code></pre>
That's it! Don't hesitate to reach out if you have any questions, feedback, or
corrections.</p>


Express Setup, Location Services, Time Zone, and High Sierra
Sun, 04 Feb 2018 00:00:00 +0000
I recently ran into a snag with our Device Enrollment Program (DEP) workflow.
Users were not being prompted to enable Location Services to automatically set the time zone, nor was the explicit Time Zone selection screen displayed during Setup Assistant.</p>
The result was that devices wound up configured with the default Cupertino, CA
location, and a Pacific time zone.
We're on the East coast – so we'd have to script a change of settings, or worse, have the user manually modify them.</p>
As it turns out, this is an effect of the new "Express Setup" option in macOS High Sierra.</p>
</span>Skipping Setup Assistant screens</h2>

    Update for macOS Monterey</strong></p>
As of macOS Monterey, Express Setup</em> will only display if the user is logged in to an Apple ID and has previously configured Siri, Location Services, and App Analytics settings while signed in to that Apple ID.</p>

</aside>
When first booted, if a Mac has network connectivity it contacts Apple to see if it should receive an enrollment configuration from an MDM solution.</p>
In most MDMs you can configure devices to skip any of a handful of Setup Assistant screens.
In Jamf Pro, the configuration looks like this:</p>



    
    

</figure>
If a screen is skipped, the default options for settings on the screen are configured.
In the case of Location Services, the default option is to disable</strong> Location Services.</p>
In macOS 10.13.3 and below, running sudo /usr/libexec/mdmclient dep nag</code> will output the device's "activation record."</p>
Activation record: {
    AllowPairing = 0;
    AnchorCertificates =     (
    );
    AwaitDeviceConfigured = 1;
    ConfigurationURL = "<enrollment url>";
    IsMDMUnremovable = 0;
    IsMandatory = 1;
    IsSupervised = 1;
    OrganizationAddress = "<organization address>";
    OrganizationAddressLine1 = "<organization address>";
    OrganizationCity = <organization city>;
    OrganizationCountry = <organization country>;
    OrganizationDepartment = "<organization department>";
    OrganizationEmail = "<organization email>";
    OrganizationMagic = <organization magic>;
    OrganizationName = "<organization name>";
    OrganizationPhone = "<organization phone>";
    OrganizationSupportPhone = "<organization phone>";
    OrganizationZipCode = <organization zipcode>;
    SkipSetup =     (
        Diagnostics,
        Biometric,
        Restore,
        Registration,
        TOS,
        Payment,
        AppleID,
        iCloudDiagnostics
    );
}
</span></code></pre>
Note:</strong> The mdmclient</code> command and some terminology are specific to macOS 10.13.3 and below. Future versions of macOS may change the command and/or terminology.</p>

</aside>
You'll notice the SkipSetup</code> dictionary contains the list of Setup Assistant screens to be skipped.</p>
In troubleshooting our issue with Location Services I was perplexed!
The activation record clearly showed that Location Services was not</em> configured to be skipped.
We should be seeing it during Setup Assistant.</p>
A couple of colleagues on the MacAdmins Slack team</a> provided me with the necessary clue to resolve the issue. 
Specifically, Nate Van Dam noted the new behavior</a>.</p>
Express Setup</h2>
macOS High Sierra introduces a new "Express Setup" workflow during Setup
Assistant. This screen consolidates the activation of Siri</strong>, Location
Services</strong>, and App Analytics</strong> into one screen.</p>



    
    

</figure>
All three of these screens must not</strong> be skipped in order for Express Setup to
appear. When you click "Continue" on the Express Setup screen, all three
settings will be activated for you.</p>
If you do configure any of these screens to be skipped, Express Setup will not
appear and the Mac may be configured in an undesired way.</p>
The dependency between these three settings is not currently documented in
Apple's Device Enrollment Program Profile
details</a>.</p>
Fixing it</h2>
Simple – just make sure Siri</strong>, Location Services</strong>, and App Analytics</strong>
are not skipped in your DEP configurations.</p>



    
    

</figure>
Now, when a you run through Setup Assistant the Express Setup screen will
appear. Accepting the default settings will turn Siri, Location Services, and
App Analytics on, and devices will be configured to use the correct time
zone of their current location.</mark></p>
Disabling undesired settings</h2>
Since the new Express Setup screen "bundles" these privacy-related options, it
has the side effect of obfuscating your ability to disable them individually.</p>
You can, however, click "Customize Settings" on the Express Setup screen to
invidually disable Siri, Location Services, or App Analytics. It's common to
disable the App Analytics telemetry options, and unfortunately this new workflow
adds several extra clicks accomplish that result.</p>
Hopefully Apple will document this change, and MDM solutions will update their 
interfaces to better clarify these Setup Assistant dependencies.</p>


Automatically Renaming Computers from a Google Sheet with Jamf Pro
Tue, 30 Jan 2018 00:00:00 +0000
In a post-imaging, DEP-only world, maintaining your organization's computer
naming convention can be a challenge.</p>
We can ease the pain with a little bit of Python, some clever interaction with
the jamf</code> binary, and a remotely-hosted Google Sheet.</p>
</span>
The problem</h2>
With DEP enrollments, your Macs are assigned a default computer hostname in the
format <user's first name>'s <Mac model></code>. DEP provides no facility to set
computer names, and Jamf Pro's PreStage Enrollments are similarly limited.</p>
You wind up with your devices having very consumer-centric names like "Susie's
MacBook Pro" and "Dave's iMac". Hostnames like that can cause compatibility
issues in some environments, and often don't fit an organization's device naming
convention.</p>
Helpfully, the jamf</code> binary includes a setComputerName</code> verb to aid in – as it
says on the tin – setting the computer's name. </p>
The -name</code> flag will set the computer name to whatever you provide.</p>
$ sudo jamf setComputerName -name ITDEPT-MAC14
Set Computer Name to ITDEPT-MAC14
</span></code></pre>
The -useSerialNumber</code> and -useMACAddress</code> flags will set the computer name to
either of those values.</p>
$ sudo jamf setComputerName -useMACAddress
Set Computer Name to 724f43aa12f
</span></code></pre>
You can also create more complex computer names with the optional -prefix</code> and
-suffix</code> flags.</p>
$ sudo jamf setComputerName -useMACAddress -prefix "Mac-" -suffix "-ITDEPT"
Set Computer Name to Mac-784f435ee12d-ITDEPT
</span></code></pre>
These options may be sufficient for you – so feel free to tune out now!</p>
However, your organization's naming scheme might include information that's not
easily discernable from the device. In my case, our hostnames include the name
of the department who owns the device and the asset tag.</p>
One workaround is to script a GUI prompt for an end user or IT staff to manually
enter the correct computer name. You can then feed this input to jamf setComputerName -name <input></code> – but that's error-prone and cumbersome to the
user.</p>
I want this automated!</mark></p>
The -fromFile</code> flag</h2>
The jamf</code> binary's setComputerName</code> command also includes the -fromFile</code> flag.
From the jamf</code> help:</p>
-fromFile
The path to a CSV file containing the computer's MAC Address or Serial Number followed by the desired name
</span></code></pre>
This little gem allows you to provide the path to a CSV file containing device
serial numbers or MAC addresses and those devices' associated desired hostnames.</p>
Some experimentation showed the required format of the CSV file is:</p>
<serial number or MAC address>,<desired hostname>
</span></code></pre>
A complete CSV using serial numbers might look like:</p>
C02S1234GTFZ,ACCOUNTING-123
C02S1232GTFZ,PURCHASING-432
C02S1252GTFZ,MARKETING-823
C02S1211GTFZ,PUBLICSAFETY-242
</span></code></pre>
After saving that CSV file to /var/tmp/serials.csv</code> for example, you can then 
run:</p>
sudo jamf setComputerName -fromFile /var/tmp/serials.csv
</span></code></pre>
If the device running this command has a serial number listed in the specified
CSV file, the jamf</code> binary will find it and set the computer name to the
provided value. If the serial number (or MAC address) of the device is not</em>
found in the specific CSV file, the jamf</code> binary will print an error and the
computer name remains unchanged.</p>
Using the CSV file allows you to assign more complex hostnames to your devices,
but that CSV file must exist on the client in order to be used. You could create
a policy to install the file on your fleet, but this is very</strong> messy and would
quickly lead to stale data.</p>
Instead, we'll host the CSV on a web server in a central location. This way, you
can easily update the data without having to re-install any files on your
clients.</p>
For ease, we'll use a Google Sheet.</p>
Create a Google Sheet</h2>
You'll need a Google account with the Drive service available. If your
organization uses G Suite, you're good to go, though any Google account will
work.</p>
Create a new Google Sheet document. Populate column A with your computer serial
numbers or MAC address, and column B with their associated desired hostnames.</p>



    
    

</figure>
Click "Share" in the upper right corner, then click "Advanced" in the lower
right of the modal Share window. Under the "Who has access" heading, you'll
likey see "Private - Only you can access". </p>



    
    

</figure>
Click the "Change..." link here, then select the Link Sharing option "On -
Anyone with the link". Confirm the Access is set to "Anyone Can view</strong>", then
click Save.</p>



    
    

</figure>
Since serial numbers and MAC addresses could be considered somewhat sensitive
information, these settings will reduce the availablity of the data while still
allowing your clients to access the sheet.</p>
Finally, note your Google Sheet's document ID. It's the long string of
seemingly-random characters in the URL shown when editing the Sheet.</p>



    
    

</figure>Add a script to Jamf Pro</h2>
In your Jamf Pro server, visit Management Settings > Computer Management >
Scripts</em> and create a new script.</p>
Paste the contents of rename-computer.py</code> into the Script Contents area.</p>

Rule type</th>	Manages</th></tr></thead>
`TeamIdentifier</code></td>`	Any item signed by that team's certificate(s)</td></tr>
`BundleIdentifier</code></td>`	Single item exactly matching a bundle identifier, e.g. `org.macblog.exampleapp</code></td></tr>`
`Label</code></td>`	Single `launchd</code> job definition with exactly matching label, e.g. org.macblog.startup</code></td></tr>`
`BundleIdentifierPrefix</code></td>`	Any item with a bundle identifier starting with the provided value, e.g. `org.macblog</code> matches - org.macblog.example</code> - org.macblog.somethingelse</code></td></tr>`
`LabelPrefix</code></td>`	Any launchd</code> job definition with a label starting with the provided value, e.g. org.macblog</code> matches - org.macblog.example</code> - org.macblog.somethingelse</code></td></tr> </tbody></table> In general, you should use the most explicit rule type applicable to a particular login item. It may be tempting to use broad TeamIdentifier</code> rules for convenience, but if we're getting new controls, I want to use them correctly. I may not want to manage and "lock on" any</em> process a vendor might install, making a TeamIdentifier</code> rule inappropriate.</p> Here's a complete example Configuration Profile to manage two specific LaunchDaemons by label:</p> <?</span>xml</span> version</span>=</span>"</span>1.0"</span></span> encoding</span>=</span>"</span>UTF-8"</span></span>?></span></span> <!</span>DOCTYPE</span> plist</span> PUBLIC</span> "</span>-//Apple//DTD PLIST 1.0//EN"</span></span> "</span>http://www.apple.com/DTDs/PropertyList-1.0.dtd"</span></span>></span></span> <</span>plist</span> version</span>=</span>"</span>1.0"</span></span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>PayloadDisplayName</</span>key</span>></span></span> <</span>string</span>></span></span>Example Login and Background Item Management</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadIdentifier</</span>key</span>></span></span> <</span>string</span>></span></span>com.apple.servicemanagement.CA085574-9E75-4049-AACF-B7546F8B1378.privacy</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadUUID</</span>key</span>></span></span> <</span>string</span>></span></span>E572AD76-1AA0-48CA-872F-3A59784148F4</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadType</</span>key</span>></span></span> <</span>string</span>></span></span>Configuration</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadScope</</span>key</span>></span></span> <</span>string</span>></span></span>System</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadContent</</span>key</span>></span></span> <</span>array</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>PayloadDescription</</span>key</span>></span></span> <</span>string</span>></span></span>Configures managed Login and Background items.</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadDisplayName</</span>key</span>></span></span> <</span>string</span>></span></span>Example Login and Background Item Management</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadIdentifier</</span>key</span>></span></span> <</span>string</span>></span></span>A2EF9B5B-C13F-432C-8645-8FFE1C2024B7</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadUUID</</span>key</span>></span></span> <</span>string</span>></span></span>023BAA5C-29D4-4CAB-8042-64832AD3E6BB</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadType</</span>key</span>></span></span> <</span>string</span>></span></span>com.apple.servicemanagement</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadOrganization</</span>key</span>></span></span> <</span>string</span>></span></span>Pretendco</</span>string</span>></span></span> <</span>key</span>></span></span>Rules</</span>key</span>></span></span> <</span>array</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>RuleType</</span>key</span>></span></span> <</span>string</span>></span></span>Label</</span>string</span>></span></span> <</span>key</span>></span></span>RuleValue</</span>key</span>></span></span> <</span>string</span>></span></span>com.pretendco.example-startup-script</</span>string</span>></span></span> <</span>key</span>></span></span>Comment</</span>key</span>></span></span> <</span>string</span>></span></span>LaunchDaemon that runs a shell script at startup.</</span>string</span>></span></span> </</span>dict</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>RuleType</</span>key</span>></span></span> <</span>string</span>></span></span>Label</</span>string</span>></span></span> <</span>key</span>></span></span>RuleValue</</span>key</span>></span></span> <</span>string</span>></span></span>com.pretendco.second-example</</span>string</span>></span></span> <</span>key</span>></span></span>Comment</</span>key</span>></span></span> <</span>string</span>></span></span>Another, different, example LaunchDaemon.</</span>string</span>></span></span> </</span>dict</span>></span></span> </</span>array</span>></span></span> </</span>dict</span>></span></span> </</span>array</span>></span></span> </</span>dict</span>></span></span> </</span>plist</span>></span></span> </span></code></pre> Apple has provided a new command line tool in Ventura to help discover the values you might need to include in a com.apple.servicemanagement</code> profile. You can run sudo sfltool dumpbtm</code> to view a verbose listing of all loaded Login and Background items.</p> Here, however, I'm focused here on demonstrating how to manage custom background items you create. Next, I'll walk through preparing a script for deployment.</p> Packaging a startup script from scratch</h2> Let's step through a complete example of creating a script and LaunchDaemon designed to run at startup. We'll use munkipkg</a> to package these components for deployment. If you're not familiar with munkipkg, Elliot Jordan's You Might Like MunkiPkg guide</a> is an excellent resource.</p> Setup</h3> Create a new project and scaffold out the structure with the following commands.</p> munkipkg --create macblog-example mkdir -p macblog-example/payload/Library/LaunchDaemons mkdir -p macblog-example/payload/opt/macblog </span></code></pre> The project folder will look like this:</p> macblog-example ├── build ├── build-info.plist ├── payload │ ├── Library │ │ └── LaunchDaemons │ └── opt │ └── macblog └── scripts </span></code></pre> The script</h3> For this example, we'll create a simple script that will write a log file when run.</p> Save the following to payload/opt/macblog/example-startup-script.zsh</code>:</p> #!/bin/zsh echo "$( /bin/date ): example script execution" >> /Library/Logs/example.log exit 0 </span></code></pre> The LaunchDaemon</h3> Next, create a LaunchDaemon to run the script every time the computer starts up. There are many options for launchd job definitions</a> but we'll keep it very minimal.</p> Save the following to payload/Library/LaunchDaemons/org.macblog.example.plist</code>:</p> <?</span>xml</span> version</span>=</span>"</span>1.0"</span></span> encoding</span>=</span>"</span>UTF-8"</span></span>?></span></span> <!</span>DOCTYPE</span> plist</span> PUBLIC</span> "</span>-//Apple//DTD PLIST 1.0//EN"</span></span> "</span>http://www.apple.com/DTDs/PropertyList-1.0.dtd"</span></span>></span></span> <</span>plist</span> version</span>=</span>"</span>1.0"</span></span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>Label</</span>key</span>></span></span> <</span>string</span>></span></span>org.macblog.example</</span>string</span>></span></span> <</span>key</span>></span></span>ProgramArguments</</span>key</span>></span></span> <</span>array</span>></span></span> <</span>string</span>></span></span>/opt/macblog/example-startup-script.zsh</</span>string</span>></span></span> </</span>array</span>></span></span> </</span>dict</span>></span></span> </</span>plist</span>></span></span> </span></code></pre> The postinstall</code> script</h3> In order to set the proper file ownership and permissions, create a postinstall</code> script. This script will run during installation of the package, after the files are in place.</p> Save the following to scripts/postinstall</code> - note the lack of a file extension on this file; you must follow this convention:</p> #!/bin/zsh /bin/chmod 0744 /opt/macblog/example-startup-script.zsh /usr/sbin/chown root:wheel /opt/macblog/example-startup-script.zsh /bin/chmod 0644 /Library/LaunchDaemons/org.macblog.example.plist /usr/sbin/chown root:wheel /Library/LaunchDaemons/org.macblog.example.plist /bin/launchctl bootstrap system /Library/LaunchDaemons/org.macblog.example.plist </span></code></pre> This script also loads the LaunchDaemon after installation, so you won't need to reboot the system for the startup script to run for the first time.</p> Sign the startup script</h3> I recently wrote a full guide to signing custom scripts</a>, so I won't detail the entire process again here. Go read that guide first.</p> Use a Developer ID Application</strong> certificate issued by Apple to code sign the startup script:</p> /usr/bin/codesign --sign "Developer ID Application: MacBlog.org (SHJS42SFS32S)" \ --identifier "org.macblog.example" \ payload/opt/macblog/example-startup-script.zsh </span></code></pre> By signing the script, we provide identity information to macOS about the authorship of the code. These details are used to display the attribution of the item in System Settings > General > Login Items</em>.</p> This is the key to properly managing the login item. Signing the script provides the idenity information macOS needs to attribute the login item correctly.</mark></p> Edit build-info.plist</code></h3> build-info.plist</code> controls various options for how the package is built. The MunkiPkg readme details all available build-info keys</a> and offers guidance on their use.</p> I suggest you sign the package</a> by including signing_info</code>. If we're code signing the deployed startup script, we might as well code sign the deployment package too, right? You'll need a Developer ID Installer</strong> certificate from Apple to sign the package.</p> Package it all up and test</h3> The full project layout now looks like this:</p> macblog-example ├── build ├── build-info.plist ├── payload │ ├── Library │ │ └── LaunchDaemons │ │ └── org.macblog.example.plist │ └── opt │ └── macblog │ └── example-startup-script.zsh └── scripts └── postinstall </span></code></pre> Make sure you're in the directory containing the macblog-example</code> project, then run:</p> munkipkg macblog-example </span></code></pre> This outputs your completed package to the macblog-example/build</code> directory.</p> If you install the finalized package, you'll notice sudo launchctl list</code> will now report the the org.macblog.example</code> job running, and /Library/Logs/example.log</code> will show an entry.</p> More importantly, System Settings > General > Login Items</em> will list a new item attributed to the signing identity you used to sign the script!</p> A signed script attributed to the signing identity.</figcaption></figure> The UI displays the attribution of what's ultimately being executed</em> – in this case, the example-startup-script.zsh</code> file. Since that file is signed, the identity information tied to that certificate is shown in System Settings</em>.</p> The LaunchDaemon does not determine the attribution shown in the interface.</strong> Think about it this way: the interface displays identity information about what's running, not what "causes" it to run.</mark></p> Manage the script using MDM</h3> Create a Configuration Profile using the example above. The specific rule to manage the custom script should look like this:</p> <</span>array</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>RuleType</</span>key</span>></span></span> <</span>string</span>></span></span>Label</</span>string</span>></span></span> <</span>key</span>></span></span>RuleValue</</span>key</span>></span></span> <</span>string</span>></span></span>org.macblog.example</</span>string</span>></span></span> <</span>key</span>></span></span>Comment</</span>key</span>></span></span> <</span>string</span>></span></span>Example rule</</span>string</span>></span></span> </</span>dict</span>></span></span> </</span>array</span>></span></span> </span></code></pre> Note that the RuleValue</code> must match the Label</code> of the LaunchDaemon we created earlier.</p> For the sake of completeness, a full example Configuration Profile will look like this:</p> <?</span>xml</span> version</span>=</span>"</span>1.0"</span></span> encoding</span>=</span>"</span>UTF-8"</span></span>?></span></span> <!</span>DOCTYPE</span> plist</span> PUBLIC</span> "</span>-//Apple//DTD PLIST 1.0//EN"</span></span> "</span>http://www.apple.com/DTDs/PropertyList-1.0.dtd"</span></span>></span></span> <</span>plist</span> version</span>=</span>"</span>1.0"</span></span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>PayloadDisplayName</</span>key</span>></span></span> <</span>string</span>></span></span>Example Login and Background Item Management</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadIdentifier</</span>key</span>></span></span> <</span>string</span>></span></span>com.apple.servicemanagement.CA085574-9E75-4049-AACF-B7546F8B1378.privacy</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadUUID</</span>key</span>></span></span> <</span>string</span>></span></span>E572AD76-1AA0-48CA-872F-3A59784148F4</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadType</</span>key</span>></span></span> <</span>string</span>></span></span>Configuration</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadScope</</span>key</span>></span></span> <</span>string</span>></span></span>System</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadContent</</span>key</span>></span></span> <</span>array</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>PayloadDescription</</span>key</span>></span></span> <</span>string</span>></span></span>Configures managed Login and Background items.</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadDisplayName</</span>key</span>></span></span> <</span>string</span>></span></span>Example Login and Background Item Management</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadIdentifier</</span>key</span>></span></span> <</span>string</span>></span></span>A2EF9B5B-C13F-432C-8645-8FFE1C2024B7</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadUUID</</span>key</span>></span></span> <</span>string</span>></span></span>023BAA5C-29D4-4CAB-8042-64832AD3E6BB</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadType</</span>key</span>></span></span> <</span>string</span>></span></span>com.apple.servicemanagement</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadOrganization</</span>key</span>></span></span> <</span>string</span>></span></span>Pretendco</</span>string</span>></span></span> <</span>key</span>></span></span>Rules</</span>key</span>></span></span> <</span>array</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>RuleType</</span>key</span>></span></span> <</span>string</span>></span></span>Label</</span>string</span>></span></span> <</span>key</span>></span></span>RuleValue</</span>key</span>></span></span> <</span>string</span>></span></span>org.macblog.example</</span>string</span>></span></span> <</span>key</span>></span></span>Comment</</span>key</span>></span></span> <</span>string</span>></span></span>Example rule</</span>string</span>></span></span> </</span>dict</span>></span></span> </</span>array</span>></span></span> </</span>dict</span>></span></span> </</span>array</span>></span></span> </</span>dict</span>></span></span> </</span>plist</span>></span></span> </span></code></pre> When deployed to your endpoints via MDM, the Configuration Profile applies the rules provided. Since we signed the script being executed, its identity information is shown in Login Items. The script is flagged as "managed by your organization" and is "locked on."</p> Managed login item locked on, with proper identity information.</figcaption></figure> All done!</p> Avoid pitfalls</h3> I've seen some launchd configurations that use the ProgramArguments</code> array to first specify the path to an interpreter, then the path to a script, like so:</p> <</span>key</span>></span></span>ProgramArguments</</span>key</span>></span></span> <</span>array</span>></span></span> <</span>string</span>></span></span>/bin/zsh</</span>string</span>></span></span> <</span>string</span>></span></span>/opt/example.zsh</</span>string</span>></span></span> </</span>array</span>></span></span> </span></code></pre> This tells macOS that /bin/zsh</code> (or bash, or Python, etc) is the process your LaunchDaemon is launching, which your script as an argument. That's wrong, and it causes macOS to attribute the interpretter as the launched process.</p> Listing a script's interpretter in the launchd plist will lead to an incorrect attribution in System Settings.</figcaption></figure> Don't do this.</strong> You should set the path to the script's interpreter in its shebang, then make the script itself executable.</p> Future</h2> Managing legacy launchd plists works fine for now in Ventura, but there's a reason they're marked legacy</strong></a>.</p> The concept of "login items" and the new SMAppService</a> API signals a transition in Apple's recommended application design process.</mark> All helper resources should live inside an app bundle, and macOS will increasingly expect items to be deployed this way.</p> In a future version of macOS, it will likely be the only</strong> method to automatically launch a process. Deleting an app bundle would delete all associated resources and automated processes. That's a win for the end user.</p> With this clear signal toward a future without LaunchDaemons and LaunchAgents, I'm personally going to invest more time in learning Swift.</p> How to sign scripts and other custom code Tue, 04 Oct 2022 00:00:00 +0000 Code signing is a method of certifying that a program or script was created by a specific party, and has not been altered since it was signed.</p> While code signing is typically discussed in the context of apps (.app bundles), the same concept applies to almost any file stored on disk. You can easily code sign custom scripts and other files you deploy on your managed Macs.</p> This article provides an overview of why and how you might want to do that.</p> Why sign your code as a Mac administrator?</h2> Signing your code provides a few benefits.</p> First, it certifies authenticity</strong>. Signed code provides macOS (and your users) a mechanism to verify that a program was created by a specific trusted entity, and deployed to the Mac without modification.</p> Second, it verifies code integrity</strong>. If a user or malicious process modifies the code, a code signature check will fail. As an administrator, you can leverage code signature verification to detect when custom programs have been altered or tampered with.</p> Third, macOS continues to surface security- and privacy-related information within the macOS interface. Things that used to be "behind the scenes," like programs an administrator might run an organizationally managed Mac, are becoming more visible.</p> This increased visibility is good for end users, and means we need to take an extra step as administrators to supply identity information about the programs we deploy.</p> Signed scripts are not necessarily secure scripts</h2> It's important to note that the presence of a code signature does not mean a script is "safe." Code signing does not evaluate a script for security vulnerabilities, malicious behavior, or code correctness.</mark> The signature only assures that the script was provided by some entity and has not been changed since it was provided.</p> For app bundles, Gatekeeper assesses the code signature when a user opens that app for the first time. Changes to the bundle's contents after the time of signing will invalidate that signature. If the signature is invalid, Gatekeeper prevents the app from running.</p> Gatekeeper does no such assessment for code signed scripts you might run by automation (like via launchd</code>) on a managed Mac. It offers no protection against scripts with invalid signatures.</p> A malicious actor could modify external files referenced by a script, alter its interpreter, or try a number of other attacks – all without invalidating that script's signature. macOS makes no attempt to validate a script's contents or referenced resources.</p> Signed scripts are certainly no less</em> secure to run or deploy than unsigned scripts, but please do not mistake code signing as a security practice</strong>.</p> What can I sign?</h2> You can sign just about any "flat" file. Text files; shell scripts; Python modules; photo files; PDFs; XML property list files like LaunchDaemons and LaunchAgents.</p> Shell scripts are the most relevant file type for most administrators, but the steps below are the same for any file type you might sign.</p> Get a signing certificate</h2> A foundational element of all public key infrastructure is trust. A code signing certificate needs to be issued by a certificate authority that macOS trusts in order to be considered valid.</p> The best place to get a trusted code signing certificate is from Apple. Members of the Apple Developer Program</a> can generate one of several different certificate types suitable for code signing.</p> I recommend the Developer ID Application</strong> certificate. This certificate type includes the Code Signing extended key usage object identifier 1.3.6.1.5.5.7.3.3</code> required to sign code.</p> Sign in to the Apple Developer Program account portal.</li> Click "Certificates, IDs & Profiles".</li> Click the dropdown menu near the upper left labeled "iOS, tvOS, watchOS" then select "macOS".</li> Click "All" under the "Certificates" heading, then click the plus button near the upper right.</li> When prompted "What type of certificate do you need?", select "Developer ID", click Continue, then select "Developer ID Application</strong>."</li> Follow Apple's on-screen instructions to generate a Certificate Signing Request (CSR) and install the resultant certificate in your login keychain.</li> </ol> Other certificates available from Apple may also work, but the Developer ID Application</strong> certificate is the best choice for this task.</p> If you do not participate in the Apple Developer Program, other vendors may provide code signing certificates. You can also easily generate a self-signed code signing certificate</a> on your Mac. However, self-signed or third-party certificates are unlikely to be trusted by default on your client Macs.</p> Make your life easier and use an Apple-provided code signing certificate.</p> How to sign a file</h2> You'll need to know the common name of the certificate you wish to use for code signing. You can list the certificates installed in your keychain that are suitable for code signing with the following command:</p> /usr/bin/security find-identity -p codesigning -v </span></code></pre> A list of code signing certificates will be displayed on screen.</p> 1) {hash} "Developer ID Application: MacBlog.org (TEAMID)" 1 valid identities found </span></code></pre> The SHA-1 fingerprint and common name is displayed for each valid code signing certificate in your login keychain. Note the common name (in quotes) of the certificate you'd like to use. You'll need to provide that exact common name as an argument to the codesign</code> binary.</p> /usr/bin/codesign --sign "{signing identity}" \ --identifier "{reverse-DNS string}" \ /path/to/file.zsh </span></code></pre> In practice, this would look something like:</p> /usr/bin/codesign --sign "Developer ID Application: MacBlog.org (SHJS42SFS32S)" \ --identifier "org.macblog.example" \ ~/Code/example.zsh </span></code></pre> The first option, --sign</code>, tells codesign</code> we wish to sign a file. We follow that option with the full name of the signing identity we wish to use. This is one of the valid signing identities we listed earlier using the security</code> command. Typically, this will be the common name of the Developer ID certificate you generated in the Apple Developer portal.</p> The second option, --identifier</code>, is optional but recommended. By convention, the identifier should be a reverse-DNS formatted</a> string that uniquely identifies your program.</p> If you omit the --identifier</code> option, the file's name (minus extension) is used as a default identifier value. Again, the option is not required, but it helps reduce confusion.</p> Finally, pass the path to the file you want to sign. After executing the command you will be prompted to provide your keychain password (assuming your signing identity is stored in the login keychain). This authorizes the codesign</code> utility to access the private key for that certificate stored in your keychain.</p> The file is now signed!</p> Where is the signature stored?</h2> When developing and signing a full app bundle, the resultant .app</code> will contain a MyApp.app/Contents/_CodeSignature</code> folder containing information about the code signature.</p> Single files like scripts, however, don't have a directory structure.</p> Instead, the signature is stored in the file's extended attributes. To quote Apple's macOS Code Signing in depth article</a>:</p> ...code signing uses extended attributes to store signatures in non-Mach-O executables such as script files. If the extended attributes are lost then the program's signature will be broken. Many file transfer techniques do not preserve extended attributes...</p> </blockquote> You can list a file's extended attributes using xattr</code>:</p> xattr -l /path/to/file.pdf </span></code></pre> Note the com.apple.cs.CodeDirectory</code> and com.apple.cs.CodeRequirements</code> attributes listed in the output. These store the components of the single file's code signature.</p> Verify a code signature</h2> The codesign</code> binary can also verify the integrity of a file's code signature with the -v</code> or --verify</code> flag. This tool frustratingly interprets the short -v</code> flag as either "verify" or "verbose" depending on the context of other passed flags. I stick with the longer form --verify</code> to avoid confusion.</p> /usr/bin/codesign --verify /path/to/script.zsh </span></code></pre> No output (and a 0</code> return code) means the signature is valid and the file is unaltered since being signed. If you're interested in output, adding a second v</code> flag will provide more detail.</p> $ /usr/bin/codesign --verify -v /path/to/script.zsh script.zsh: valid on disk script.zsh: satisfies its Designated Requirement </span></code></pre> Otherwise, specifics of the problem with a signature will be displayed, and the command returns an error code.</p> Because codesign</code>'s verify</code> function returns proper success or failure status codes, it's easy to validate a code signature within the context of another shell script. Here is a small example:</p> if /usr/bin/codesign -v "/path/to/file.zsh"; then echo "Code signature is valid." else echo "Code signature is invalid!" fi </span></code></pre> Your configuration management system can run checks like the above to validate the integrity of custom scripts deployed on your endpoints. If the signature check fails, you know you need to redeploy the script.</p> Delivery</h2> Source control systems like Git will drop extended attributes from files when committed. If you sign a script, then commit it to a Git repository, it will no longer be signed.</p> Additionally, your configuration management tool may or may not be able to distribute files with extended attributes – and thus code signing – intact.</p> Because of these limitations, I recommend you package any signed code as a final step before distribution. Signed scripts will</strong> retain extended attributes and remain signed when delivered to managed Macs if you package them. </p> Common signing problems</h2> I mentioned you can code sign pretty much any file type. This includes images, PDFs, text files – almost anything (though in some cases, I'm not sure why you would want to).</p> If you try to sign an incompatible file – like a directory – you'll get an error message stating bundle format unrecognized, invalid, or unsuitable</code>.</p> If you receive the error resource fork, Finder information, or similar detritus not allowed</code>, this indicates the file has extended attributes that are incompatible with computing a code signature hash. You may be able to discard these attributes if they are not essential to the file type. For example, the most common incompatible extended attribute is the legacy "Finder Info" stored in the com.apple.FinderInfo</code> attribute. This attribute contains metadata like Finder tags and other information that is unlikely relavent for files mass deployed by an administrator.</p> Again, list the file's extended attributes using xattr</code>:</p> xattr -l /path/to/file.pdf </span></code></pre> Note the com.apple.FinderInfo</code> attribute in the ouput.</p> Removing the "Finder Info" attribute is as simple as xattr -d com.apple.FinderInfo /path/to/file.pdf</code>. Or, remove all</em> extended attributes via xattr -c /path/to/file.pdf</code>. You should then be able to code sign the file.</p> But remember – do not strip all extended attributes after</em> signing the file. That would remove the signature!</p> Further reading</h2> I've covered the basics here, but will close with a few recommended resources for more information on code signing within macOS.</p> Apple - TN3127: Inside Code Signing: Requirements</a></li> Apple - About Code Signing</a></li> Apple - TN2206 macOS Code Signing In Depth</a></li> </ul> How to examine the network traffic of MDM enrollment during Setup Assistant Sat, 28 May 2022 00:00:00 +0000 Part of my job is to test (and re-test) first-time setup workflows for new and repurposed Macs.</p> I recently needed to analyze the flow of network traffic during initial MDM enrollment to confirm an on-premise network was permitting all required traffic.</p> The tcpdump</code> tool – included with macOS – is a powerful utility that allows you to record all network traffic passing through any interface on the Mac. It requires elevated privileges to run, however. This presents a problem, since we do not yet have an account capable of running elevated processes during Setup Assistant. We haven't even created a local account yet!</p> To work around this, we need to enable the root</code> account before</em> proceeding through Setup Assistant</strong>.</p> </span> I strongly recommend doing these sorts of analyses on a dedicated test Mac that you don't mind erasing.</mark> Gather the data you need, then erase it.</p> Reinstall macOS</h2> First, we need to return the Mac to a "fresh" state by reinstalling macOS.</p> Apple provides complete instructions on reinstalling the operating system</a>.</p> If you're using a Mac with an Apple Silicon chip, you can very</em> quickly restore the Mac using Apple Configurator</a>.</p> Enable root</code> from macOS Recovery</h2> Next, we need to temporarily</em> enable the root</code> account by setting a password for it. We'll disable it later, but this is required</strong> to be able to run privileged processes during Setup Assistant.</p> Start up the Mac in Recovery mode</a>.</p> </li> Once Recovery loads, select Utilities > Terminal</em> on the top menu to open a Terminal window.</p> </li> Initiate a password reset for the root</code> account using the following command, depending on whether the Mac has an Apple Silicon or Intel chip:</p> For a Mac with an Apple Silicon chip...</em></p> dscl -f /Volumes/Data/private/var/db/dslocal/nodes/Default localhost -passwd /Local/Default/Users/root </span></code></pre> For a Mac with an Intel chip...</em></p> dscl -f /Volumes/Macintosh\ HD\ -\ Data/private/var/db/dslocal/nodes/Default localhost -passwd /Local/Default/Users/root </span></code></pre> </li> When prompted to enter a New password:</code>, type in the password you wish to use with the root</code> account. The value will not be displayed on screen, and you will not</em> be prompted to confirm it, so use caution.</p> </li> Restart the Mac by typing reboot</code> then pressing Return</kbd>.</p> </li> </ol> Open a Terminal during Setup Assistant</h2> When you start up the Mac, you'll see the "hello" screen and Setup Assistant will begin. Select your language to continue.</p> Next, press ⌃ Control</kbd> + ⌥ Option</kbd> + ⌘ Command</kbd> + T</kbd> on the keyboard to open a Terminal window.</p> Terminal will open in the background, and you'll be able to switch back and forth between the Setup Assistant and Terminal windows.</p> Setup Assistant runs under the temporary _mbsetupuser</code> user account. This is a standard – rather than administrator – account. Elevate to root by typing su -</code>, then entering the password you previously set for the root account in macOS Recovery.</p> </figure> Great, now we have a root</code> shell!</p> Run tcpdump</code></h2> With a root shell, we can run elevated processes like tcpdump</code>.</p> Advance through Setup Assistant until you reach the Remote Management</strong> screen. Switch focus to the Terminal window, then run:</p> tcpdump -nn -i any \| tee -a /Users/Shared/enrollment.dump </span></code></pre> This will display all traffic for all network interfaces, and will skip reverse resolution of network addresses to DNS names. I find these options useful to see where traffic is flowing, and the unresolved IP addresses and port numbers are the relevant bits of information I'm after.</p> I also use the tee</code> program to simultaneously print the traffic to standard output and also save a log to a known location. Writing the output to a file within /Users/Shared</code> ensures the file persists through any reboots and is accessible once Setup Assistant completes. You could use tcpdump</code>'s -w</code> flag to save the output to a file, but this creates a binary file that isn't immediately readable. Using tee</code> is my personal preference.</p> There are tons of options for tcpdump</code>, which is not the point of this post. I recommend Apple's developer documentation on recording a packet trace</a>, and Daniel Miessler's tcpdump tutorial</a> for extensive help using the tool.</p> Clean up</h2> Once MDM enrollment completes, switch focus to the Terminal window and press ⌘ Command</kbd> + C</kbd> to quit the tcmpdump</code> process.</p> The packet trace is displayed in the Terminal window for you to analyze. If you've also tee</code>'d the output to a file, you'll be able to copy that file to another system for analysis after you've completed Setup Assistant.</p> The only thing left to do is disable root</code> login. Do this from your administrator-level account by running:</p> dscl . -create /Users/root UserShell /usr/bin/false </span></code></pre> Or – since you're doing this on a test device – erase the Mac and start over fresh!</p> Slides and video for the 'Solving problems with custom AutoPkg processors' session at the University of Utah Mac Admin Meeting Fri, 20 May 2022 00:00:00 +0000 I recently presented at the monthly University of Utah Mac Admin Meeting</a> about two of my custom AutoPkg processors: DatetimeOutputter</a> and AppIconExtractor</a>.</p> Here are links to a recording of the presentation and the associated slides:</p> Solving problems with custom AutoPkg processors</a></li> Slides (PDF)</a></li> </ul> Output the Date and Time in AutoPkg Recipes Tue, 01 Mar 2022 00:00:00 +0000 I recently needed to use the date and time of an AutoPkg run from within the context of recipe.</p> While AutoPkg itself is aware of the date and time of a run, that information is not accessible to other processors within the recipe.</p> To fill this need, I wrote a new AutoPkg processor: DatetimeOutputter</strong>.</p> DatetimeOutputter</strong> helps you reference the current date and time as a variable within your AutoPkg recipes. Additionally, it can calculate future and past dates to enhance advanced workflows.</p> </span>Current date and time</h2> At its core, DatetimeOutputter</strong> adds a datetime</code> variable to an AutoPkg recipe execution. The datetime is outputted in ISO 8601 format relevant to the local time of the computer running the recipe.</p> Calling the processor using Shared Processor</a> syntax, with no arguments, invokes this default behavior. Here are examples in both XML and YAML recipe format.</p> XML:</p> <</span>key</span>></span></span>Process</</span>key</span>></span></span> <</span>array</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>Processor</</span>key</span>></span></span> <</span>string</span>></span></span>com.github.haircut.processors/DatetimeOutputter</</span>string</span>></span></span> </</span>dict</span>></span></span> </</span>array</span>></span></span> </span></code></pre> YAML:</p> Process</span></span>:</span> -</span> Processor</span></span>:</span> com.github.haircut.processors/DatetimeOutputter</span> </span></code></pre> This will output a new datetime</code> variable you can use in subsequent processors. datetime</code> will look something like 2022-03-01T09:45:45.544391</code> by default.</p> You can control the output format by supplying a datetime_format</code> argument. The processor accepts any strftime</a>-compatible format.</p> Additionally, you can pass the use_utc</code> argument as True</code> to output the datetime relative to UTC rather than your computer's local time.</p> This example illustrates both concepts:</p> Process</span></span>:</span> -</span> Processor</span></span>:</span> com.github.haircut.processors/DatetimeOutputter</span> Arguments</span></span>:</span> datetime_format</span></span>:</span> "</span>%A, %B %e, %Y at %l:%M %p"</span></span> use_utc</span></span>:</span> True</span> </span></code></pre> This would output something like Tuesday, March 1, 2022 at 1:45 PM</code> based on UTC time.</p> Past and future dates</h2> It's handy to know when a recipe runs, but determining past and future dates – e.g. one week from now, or 3 days ago – can augment many workflows.</p> DatetimeOutputter</strong> can generate an arbitrary number of datetime "deltas." A datetime delta adds or subtracts time from the current datetime and outputs a variable in your preferred format.</p> Outputting a delta requires specifying a few arguments.</p> output_name</code>: the output variable name for the time delta. Whatever you set here is the variable name you can use in subsequent processors.</li> direction</code>: specify whether the generated datetime should be in the future</code> or past</code>.</li> format</code>: the strftime</a>-compatible format to output the datetime.</li> interval</code>: a dictionary of keys specifying one or more values to add or subtract from the current datetime. Valid keys are: weeks</code>, days</code>, hours</code>, minutes</code>, seconds</code>, microseconds</code>, and milliseconds</code>.</li> </ul> The interval</code> argument accepts any number of keyword arguments compatible with Python's timedelta object</a>, as listed above. This means you may need to convert far-future or past intervals to "weeks" or "days;" e.g. instead of specifying months: 2</code>, use weeks: 8</code>.</p> Here's an example of outputting two deltas:</p> -</span> Processor</span></span>:</span> com.github.haircut.processors/DatetimeOutputter</span> Arguments</span></span>:</span> deltas</span></span>:</span> -</span> output_name</span></span>:</span> one_week_in_future</span> direction</span></span>:</span> future</span> datetime_format</span></span>:</span> "</span>%Y-%m-%d 00:00:00"</span></span> interval</span></span>:</span> weeks</span></span>:</span> 1</span> -</span> output_name</span></span>:</span> two_days_six_hours_twelve_minutes_ago</span> direction</span></span>:</span> past</span> datetime_format</span></span>:</span> "</span>%A, %B %e, at %Y %H:%M:%S"</span></span> interval</span></span>:</span> days</span></span>:</span> 2</span> hours</span></span>:</span> 6</span> minutes</span></span>:</span> 12</span> </span></code></pre> This would output two new variables as follows:</p> one_week_in_future</code> with the value 2022-03-08 00:00:00</code></li> two_days_six_hours_twelve_minutes_ago</code> with the value Sunday, February 27, 2022 at 03:33:45</code></li> </ul> You can output as many deltas as you need by simply adding new dictionaries to the deltas</code> array of the processor. Each will be available for use by later processors via variable substitution.</p> Deltas always respect the use_utc</code> option of the processor, if set. In a single run of DatetimeOutputter</strong> you cannot output UTC- and non-UTC-based datetimes. If you have a need for this, run DatetimeOutputter</strong> multiple times in your recipe, setting use_utc</code> accordingly.</p> Example use cases</h2> Keep it simple with just the date and time</h3> In the simplest use case, you might wish to note the date a package was uploaded by JamfUploader</a> within the Jamf Pro package notes field. Call DatetimeOutputter</strong> first to generate the datetime</code> variable, then reference that variable as %datetime%</code> in the next processor like so:</p> Process</span></span>:</span> -</span> Processor</span></span>:</span> com.github.haircut.processors/DatetimeOutputter</span> -</span> Processor</span></span>:</span> com.github.grahampugh.jamf-upload.processors/JamfPackageUploader</span> Arguments</span></span>:</span> pkg_notes</span></span>:</span> "</span>Uploaded via AutoPkg %datetime%"</span></span> </span></code></pre> Output a future datetime for use with Munki's "force install after date" feature</h3> Munki includes a feature to force installation of a package after a specified date</a>. Setting the force_install_after_date</code> key in a package's pkginfo</code> dictionary will cause client Macs to forcefully logout or restart to install the software after that (local) date and time.</p> If you use this functionality, Munki recommends setting the force_install_after_date</code> to at least 2 weeks in the future.</p> DatetimeOutputter</strong> can help you generate this future date in the required format:</p> -</span> Processor</span></span>:</span> com.github.haircut.processors/DatetimeOutputter</span> Arguments</span></span>:</span> format</span></span>:</span> "</span>%Y-%m-%dT%H:%M:%SZ"</span></span> deltas</span></span>:</span> -</span> output_name</span></span>:</span> force_after</span> direction</span></span>:</span> future</span> interval</span></span>:</span> weeks</span></span>:</span> 2</span> -</span> Processor</span></span>:</span> MunkiImporter</span> Arguments</span></span>:</span> MUNKI_REPO</span></span>:</span> <path to Munki repo></span> pkg_path</span></span>:</span> "</span>%pkg%"</span></span> pkginfo</span></span>:</span> force_install_after_date</span></span>:</span> "</span>%force_after%"</span></span> </span></code></pre> This will automate the calculation of a two-week window after uploading the package during which users will be prompted – but not forced – to install the package. After force_date</code> passes, users will be forced to install the software.</p> Output a future date for use with a Jamf Pro policy activation date</h3> You might wish to delay the installation of an application update for some number of days after release. One way to do this is to configure a Jamf Pro policy to include the "Activation Date/Time" server-side limitation. This prevents the policy from running before the configured date and time.</p> DatetimeOutputter</strong> can generate a dynamic datetime stamp n</em> number of days in the future. This means the new version of an application will be uploaded to your Jamf Pro server, and the installation policy ready to go when the Activation Date/Time rolls around. Automatically!</p> First, we add an activation_date</code> key to the date_time_limitations</code> of a policy template. We populate the key with an %activation_date%</code> substitution variable we will later define within the associated AutoPkg recipe.</p> Install-after-1-week.xml</code></p> <?</span>xml</span> version</span>=</span>"</span>1.0"</span></span> encoding</span>=</span>"</span>UTF-8"</span></span>?></span></span> <</span>policy</span>></span></span> <</span>general</span>></span></span> <</span>name</span>></span></span>Install %NAME% 1 Week After Release</</span>name</span>></span></span> <</span>enabled</span>></span></span>true</</span>enabled</span>></span></span> <</span>trigger</span>></span></span>CHECKIN</</span>trigger</span>></span></span> <</span>trigger_checkin</span>></span></span>true</</span>trigger_checkin</span>></span></span> <</span>frequency</span>></span></span>Once per computer</</span>frequency</span>></span></span> <</span>date_time_limitations</span>></span></span> <</span>activation_date</span>></span></span>%activation_date%</</span>activation_date</span>></span></span> </</span>date_time_limitations</span>></span></span> </</span>general</span>></span></span> <</span>scope</span>></span></span> <</span>all_computers</span>></span></span>false</</span>all_computers</span>></span></span> <</span>computer_groups</span>></span></span> <</span>computer_group</span>></span></span> <</span>name</span>></span></span>%UPDATE_GROUP_NAME%</</span>name</span>></span></span> </</span>computer_group</span>></span></span> </</span>computer_groups</span>></span></span> </</span>scope</span>></span></span> <</span>self_service</span>></span></span> <</span>use_for_self_service</span>></span></span>false</</span>use_for_self_service</span>></span></span> </</span>self_service</span>></span></span> <</span>package_configuration</span>></span></span> <</span>packages</span>></span></span> <</span>size</span>></span></span>1</</span>size</span>></span></span> <</span>package</span>></span></span> <</span>name</span>></span></span>%pkg_name%</</span>name</span>></span></span> <</span>action</span>></span></span>install</</span>action</span>></span></span> </</span>package</span>></span></span> </</span>packages</span>></span></span> </</span>package_configuration</span>></span></span> </</span>policy</span>></span></span> </span></code></pre> Next, we'll use DatetimeOutputter</strong> to generate a datestamp 1 week in the future from the time of the AutoPkg run, in the format Jamf Pro expects for midnight on that date. We set the output_name</code> to activation_date</code> to match what the policy template expects.</p> -</span> Processor</span></span>:</span> StopProcessingIf</span> Arguments</span></span>:</span> predicate</span></span>:</span> "</span>pkg_uploaded == False"</span></span> -</span> Processor</span></span>:</span> com.github.haircut.processors/DatetimeOutputter</span> Arguments</span></span>:</span> deltas</span></span>:</span> -</span> output_name</span></span>:</span> activation_date</span> direction</span></span>:</span> future</span> datetime_format</span></span>:</span> "</span>%Y-%m-%d 00:00:00"</span></span> interval</span></span>:</span> weeks</span></span>:</span> 1</span> -</span> Processor</span></span>:</span> com.github.grahampugh.jamf-upload.processors/JamfPolicyUploader</span> Arguments</span></span>:</span> policy_name</span></span>:</span> "</span>Install %NAME% 1 Week After Release"</span></span> policy_template</span></span>:</span> "</span>Install-after-1-week.xml"</span></span> </span></code></pre> This will create a policy that installs the uploaded package, but remains inactive until 1 week in the future. At that future date, the policy will automatically activate and install on eligible Macs.</p> More info</h2> These are just a few of the potential use cases for this processor. Please check the full details in the README</a>. And as always – pull requests are open if you have an improvement or correction!</p> Dynamically Add Dock Items with the Jamf Binary Sun, 13 Feb 2022 00:00:00 +0000 Adding your organization's common tools or newly-installed items to a user's Dock can minimize confusion for your colleagues, and is a common task for Mac admins.</p> For those managing their fleet with Jamf Pro, the jamf</code> binary includes a modifyDock</code> command which allows you to apply certain Dock modifications. It isn't a fully-featured Dock management tool, but it does include enough functionality to add new items to a user's Dock.</p> I was recently working on a project where I needed to conditionally add a Dock item based on some scripted logic. I wanted to minimize external dependencies, so I developed a method to leverage the jamf</code> binary's built-in Dock management capability and its -file</code> flag to complete the task.</p> </span> First, here's the documentation for the modifyDock</code> command, which you can read by running sudo jamf help modifyDock</code>:</p> Usage: jamf modifyDock -file <file name> [-leaveRunning] [-beginning] [-remove] Usage: jamf modifyDock -id <dock_item_id> [-leaveRunning] [-beginning] [-remove] -file The file that contains the formatted dock items. -id The dock_item_id of the dock item on the JSS. -leaveRunning The Dock process will not be restarted. -beginning The item will be placed at the beginning (left side) of the Dock. -remove The item will be removed instead of added. </span></code></pre> Typical use of this command assumes use of the -id</code> flag, which requires passing the ID of a "Dock Item" as configured within your Jamf Pro instance.</p> Dock Items can be added to Jamf Pro</a> via the web console or by using Jamf Admin. Once you've added a Dock Item to Jamf Pro, you can add it to a Mac's dock by using the Dock Items payload within a Policy, or by calling sudo jamf modifyDock -id <Dock Item ID></code> on the Mac itself.</p> However, the jamf</code> binary's modifyDock</code> command also accepts a -file</code> flag. The built-in help states the flag expects The file that contains the formatted dock items.</code> – a little vague. Online searches didn't turn up much additional information, and the official Jamf Pro documentation doesn't cover the binary in great detail.</p> With some experimentation, I found that the -file</code> flag expects an on-disk path to a file that contains XML representing one or more Dock item entries.</p> Roughly, the required format of that XML to add an app to the Dock is as follows:</p> <</span>dict</span>></span></span> <</span>key</span>></span></span>GUID</</span>key</span>></span></span> <</span>integer</span>></span></span>-91117049</</span>integer</span>></span></span> <</span>key</span>></span></span>tile-data</</span>key</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>file-data</</span>key</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>_CFURLString</</span>key</span>></span></span> <</span>string</span>></span></span>file://[path to app]/</</span>string</span>></span></span> <</span>key</span>></span></span>_CFURLStringType</</span>key</span>></span></span> <</span>integer</span>></span></span>15</</span>integer</span>></span></span> </</span>dict</span>></span></span> <</span>key</span>></span></span>file-label</</span>key</span>></span></span> <</span>string</span>></span></span>[item name]</</span>string</span>></span></span> </</span>dict</span>></span></span> <</span>key</span>></span></span>tile-type</</span>key</span>></span></span> <</span>string</span>></span></span>file-tile</</span>string</span>></span></span> </</span>dict</span>></span></span> </span></code></pre> Note: The GUID key can be any value, but Jamf Pro uses a consistent value across all instances, to my knowledge.</em></p> That's easy enough to generate the required data on-the-fly within a shell script, so I wrote a function to do just that.</p> dockitem</span> (</span>)</span> {</span> if</span> [[</span> -</span>d</span> "</span>$</span>{</span></span>1</span></span>}</span></span>"</span></span> &&</span> "</span>$</span>{</span></span>1</span></span>:</span></span> -</span>4</span></span>}</span></span>"</span></span> !=</span> "</span>.app"</span></span> ]]</span></span>;</span> then</span> TYPE</span>=</span>"</span>directory"</span></span></span></span>;</span> else</span> TYPE</span>=</span>"</span>file"</span></span></span></span>;</span> fi</span> TMPFILE</span>=</span>$</span>(</span> /usr/bin/mktemp</span></span> </span>)</span></span></span> echo</span></span> "</span><dict><key>GUID</key><integer>-91117049</integer><key>tile-data</key><dict><key>file-data</key><dict><key>_CFURLString</key><string>file://$</span>{</span></span>1%%</span></span></span>/</span>}</span></span>/</string><key>_CFURLStringType</key><integer>15</integer></dict><key>file-label</key><string>$</span>(</span> /usr/bin/basename</span></span> "</span>$</span>{</span></span>1</span></span>}</span></span>"</span></span></span>)</span></span></string></dict><key>tile-type</key><string>$</span>{</span></span>TYPE</span></span>}</span></span>-tile</string></dict>"</span></span> ></span> "</span>$</span>{</span></span>TMPFILE</span></span>}</span></span>"</span></span></span> echo</span></span> "</span>$</span>{</span></span>TMPFILE</span></span>}</span></span>"</span></span></span> }</span></span> </span></code></pre> This function requires a single argument: the path to the item you want to add to the Dock.</p> Stepping through the function, we first determine if the passed path is a directory that exists on the Mac. If so – and that directory is not actually an app bundle – the Dock item will be created as a "directory tile," which appears with a folder icon on the Dock. Otherwise, we assume the path is an app or individual file.</p> Next, we generate a temporary file on disk to which we can write the XML representing the new Dock item. The temporary file's path is captured.</p> Then we populate a blob of XML with our custom values, and finally print out the path to the that temporary file.</p> Using the function is as simple as calling dockitem</code> within a script, then passing a path as an argument.</p> dockitem</span></span> "</span>/Applications/Safari.app"</span></span></span> </span></code></pre> Putting it all together, we can then feed that file to the jamf</code> binary's modifyDock</code> command using command substitution like so:</p> #</span></span>!/bin/zsh</span> </span> dockitem</span> (</span>)</span> {</span> if</span> [[</span> -</span>d</span> "</span>$</span>{</span></span>1</span></span>}</span></span>"</span></span> &&</span> "</span>$</span>{</span></span>1</span></span>:</span></span> -</span>4</span></span>}</span></span>"</span></span> !=</span> "</span>.app"</span></span> ]]</span></span>;</span> then</span> TYPE</span>=</span>"</span>directory"</span></span></span></span>;</span> else</span> TYPE</span>=</span>"</span>file"</span></span></span></span>;</span> fi</span> TMPFILE</span>=</span>$</span>(</span> /usr/bin/mktemp</span></span> </span>)</span></span></span> echo</span></span> "</span><dict><key>GUID</key><integer>-91117049</integer><key>tile-data</key><dict><key>file-data</key><dict><key>_CFURLString</key><string>file://$</span>{</span></span>1%%</span></span></span>/</span>}</span></span>/</string><key>_CFURLStringType</key><integer>15</integer></dict><key>file-label</key><string>$</span>(</span> /usr/bin/basename</span></span> "</span>$</span>{</span></span>1</span></span>}</span></span>"</span></span></span>)</span></span></string></dict><key>tile-type</key><string>$</span>{</span></span>TYPE</span></span>}</span></span>-tile</string></dict>"</span></span> ></span> "</span>$</span>{</span></span>TMPFILE</span></span>}</span></span>"</span></span></span> echo</span></span> "</span>$</span>{</span></span>TMPFILE</span></span>}</span></span>"</span></span></span> }</span></span> jamf</span></span> modifyDock -</span>leaveRunning</span> -</span>file</span> $</span>(</span> dockitem</span></span> "</span>/Applications/Safari.app"</span></span> </span>)</span></span></span> jamf</span></span> modifyDock -</span>leaveRunning</span> -</span>file</span> $</span>(</span> dockitem</span></span> "</span>/Applications/BBEdit.app"</span></span> </span>)</span></span></span> jamf</span></span> modifyDock -</span>file</span> $</span>(</span> dockitem</span></span> "</span>/Applications/Slack.app"</span></span> </span>)</span></span></span> </span></code></pre> For another example, let's determine the logged-in user's home directory and add that to the Dock as a directory tile.</p> #</span></span>!/bin/zsh</span> </span> dockitem</span> (</span>)</span> {</span> if</span> [[</span> -</span>d</span> "</span>$</span>{</span></span>1</span></span>}</span></span>"</span></span> &&</span> "</span>$</span>{</span></span>1</span></span>:</span></span> -</span>4</span></span>}</span></span>"</span></span> !=</span> "</span>.app"</span></span> ]]</span></span>;</span> then</span> TYPE</span>=</span>"</span>directory"</span></span></span></span>;</span> else</span> TYPE</span>=</span>"</span>file"</span></span></span></span>;</span> fi</span> TMPFILE</span>=</span>$</span>(</span> /usr/bin/mktemp</span></span> </span>)</span></span></span> echo</span></span> "</span><dict><key>GUID</key><integer>-91117049</integer><key>tile-data</key><dict><key>file-data</key><dict><key>_CFURLString</key><string>file://$</span>{</span></span>1%%</span></span></span>/</span>}</span></span>/</string><key>_CFURLStringType</key><integer>15</integer></dict><key>file-label</key><string>$</span>(</span> /usr/bin/basename</span></span> "</span>$</span>{</span></span>1</span></span>}</span></span>"</span></span></span>)</span></span></string></dict><key>tile-type</key><string>$</span>{</span></span>TYPE</span></span>}</span></span>-tile</string></dict>"</span></span> ></span> "</span>$</span>{</span></span>TMPFILE</span></span>}</span></span>"</span></span></span> echo</span></span> "</span>$</span>{</span></span>TMPFILE</span></span>}</span></span>"</span></span></span> }</span></span> CURRENTUSER</span>=</span>$</span>(</span> /usr/sbin/scutil</span></span> <<<</span> "</span>show State:/Users/ConsoleUser"</span></span></span> \|</span> /usr/bin/awk</span></span> '</span>/Name :/ && ! /loginwindow/ { print $3 }'</span></span> </span>)</span></span></span> HOMEDIR</span>=</span>$</span>(</span> /usr/bin/dscl</span></span> . read "</span>/Users/$</span>{</span></span>CURRENTUSER</span></span>}</span></span>"</span></span> NFSHomeDirectory </span>)</span></span></span> jamf</span></span> modifyDock -</span>file</span> $</span>(</span> dockitem</span></span> "</span>$</span>{</span></span>HOMEDIR</span></span>}</span></span>"</span></span> </span>)</span></span></span> </span></code></pre> This script will read the NFSHomeDirectory</code> attribute of the currently-logged-in user's account and add it to the Dock. Dynamically determining the user's home directory path is not otherwise possible with a Jamf Pro policy alone, so this method bridges that gap.</p> Ultimately, you can probably file this method under "things you should probably do a better way, but this is also kind of neat and you may find a use."</p> A purpose-built tool like docklib</a> or dockutil</a> will offer wildly more flexibility and control over the Dock.</p> But... this will work in a pinch for simple needs.</p> Automatically Export and Generate App Icons in AutoPkg Recipes Mon, 31 Jan 2022 00:00:00 +0000 I'm a stickler for including icons for all policies available in Jamf Pro's Self Service app. They help users find items in Self Service, and generally make the app easier to use.</p> However, I don't like manually extracting icons from apps. It's easy enough with a tool like SAP's Icons app</a>, but if I'm automating package and policy creation with AutoPkg, I should similarly be able to automate icon creation, right?</p> I created the AppIconExtractor</strong></a> AutoPkg processor to fully automate this task.</p> At it's core, AppIconExtractor</strong> examines an app and exports its icon as a PNG image file.</p> More technically, it reads the CFBundleIconFile</code> property from an app's Info.plist</code> and saves that image as a PNG file at the path of your choice.</p> Additionally, ApplIconExtractor</code> can create icon variations by compositing a secondary image on top of the app's icon. This makes it simple to automatically create a version of an icon with a destructive "red X" icon superimposed over the app icon for use in uninstallation policies, or a version with an "update" graphic for use in policies that update an app.</p> </figure></span>Add my recipes and install the Pillow library</h2> First, you'll need my recipe repository available to your local AutoPkg installation. Add it with autopkg repo-add haircut-recipes</code>.</p> AppIconExtractor</strong> requires installation of the Pillow</a> Python library.</p> Pillow is used to convert and composite icons, and can be easily installed on the Mac you use to run AutoPkg. Use this command:</p> /usr/local/autopkg/python -m pip install --upgrade Pillow </span></code></pre> Note that this installs the Pillow library within the path of AutoPkg's Python framework</em>. This is very important.</strong> If you just run pip</code> or pip3</code> without the explicit path to AutoPkg's Python installation, AutoPkg won't be able to find the library. Recipes will produce an error directing you to install Pillow using the specifc command above.</p> The MunkiImporter processor</a>, via munkilib, includes code to extract and convert icons from app bundles. We could use features of this existing processor to accomplish some of our needs. However, MunkiImporter does not provide any features to composite images. Since AppIconExtractor</strong> is primarily targeted towards folks managing Macs with tools other than Munki, it makes more sense to require only a single external dependency – Pillow – that fulfills all our needs.</p> </aside> With Pillow installed, you're ready to go.</p> Basic use</h2> Using AppIconExtractor</strong> is as simple as including the processor as a step in a recipe's Process dictionary. Use the shared processor</a> syntax to call com.github.haircut.processors/AppIconExtractor</code>.</p> It requires only one argument: source_app</code>, which is the path to the .app</code> from which to extract an icon. If the path to the app points inside a disk image, that .dmg will be mounted automatically.</p> By default, the app's icon will be output to the recipe's cache directory as %NAME%.png%</code>. You can optionally override this output path (and filename) by setting the icon_output_path</code> argument.</p> A simple example in XML format might look like:</p> <</span>key</span>></span></span>Process</</span>key</span>></span></span> <</span>array</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>Processor</</span>key</span>></span></span> <</span>string</span>></span></span>com.github.haircut.processors/AppIconExtractor</</span>string</span>></span></span> <</span>key</span>></span></span>Arguments</</span>key</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>source_app</</span>key</span>></span></span> <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/CoolApp/CoolApp.app</</span>string</span>></span></span> </</span>dict</span>></span></span> </</span>dict</span>></span></span> </</span>array</span>></span></span> </span></code></pre> This will extract the icon from "CoolApp.app" and save it as a 256px square PNG image to the recipe cache directory.</p> As mentioned, adding the icon_output_path</code> argument will give you additional control over the output path and filename. Here's an example in YAML format:</p> Process</span></span>:</span> -</span> Processor</span></span>:</span> com.github.haircut.processors/AppIconExtractor</span> Arguments</span></span>:</span> source_app</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/CoolApp/CoolApp.app"</span></span> icon_output_path</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/Icons/Icon-%NAME%.png"</span></span> </span></code></pre> Generating composited variations</h2> Beyond extracting the app's icon, AppIconExtractor</strong> can also create variation images by compositing a "template image" on top of the app icon.</p> The processor can output variations for an "uninstall," "update," and "install" version of the app icon.</p> </figure> To generate a variation, add a processor argument to set an output path for that variation. Use one or more of the following arguments:</p> composite_install_path</code></li> composite_update_path</code></li> composite_uninstall_path</code></li> </ul> Omit any variations you don't want to generate. The processor will only create the variations you request be specify an output path.</p> If you specify only output paths for variations, AppIconExtractor</strong> will use sensible defaults to composite suitable icons. The default templates are glyphs from SF Symbols</a> that will work well in most situations. Each template is 64px in size, and looks nice in the corner.</p> </figure> These templates are encoded within the processor; you don't need to do anything to use these defaults!</mark></p> Here's an example in YAML format:</p> Process</span></span>:</span> -</span> Processor</span></span>:</span> com.github.haircut.processors/AppIconExtractor</span> Arguments</span></span>:</span> source_app</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/CoolApp/CoolApp.app"</span></span> icon_output_path</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/Icons/Icon-%NAME%.png"</span></span> composite_update_path</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/Icons/Update-%NAME%.png"</span></span> composite_uninstall_path</span></span>:</span> "</span>"</span></span>%RECIPE_CACHE_DIR%/Icons/Uninstall-%NAME%.png"</span> </span></code></pre> Notice that we included arguments for the "update" and "uninstall" variations, but did not set the composite_install_path</code> argument. This would output the "bare" app icon as well as variations for "update" and "uninstall" – but no "install" variation, since we omitted that argument.</p> Custom templates</h3> If you don't like the default variation templates, you can use your own by setting composite_install_template</code>, composite_update_template</code> and/or composite_unsinstall_template</code>. Each argument should be the path to alternative template image to use for that variation.</p> AppIconExtractor</strong> will calculate the size of the template image at the path you specify and correctly anchor that template to the composite_position</code> (see "Padding and position" below).</p> </figure> Here's an example of using a custom template to generate an "uninstall" variation in XML format:</p> <</span>key</span>></span></span>Process</</span>key</span>></span></span> <</span>array</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>Processor</</span>key</span>></span></span> <</span>string</span>></span></span>com.github.haircut.processors/AppIconExtractor</</span>string</span>></span></span> <</span>key</span>></span></span>Arguments</</span>key</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>source_app</</span>key</span>></span></span> <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/CoolApp/CoolApp.app</</span>string</span>></span></span> <</span>key</span>></span></span>composite_uninstall_template</</span>key</span>></span></span> <</span>string</span>></span></span>%RECIPE_DIR%/radical-flame.png</</span>string</span>></span></span> <</span>key</span>></span></span>composite_uninstall_path</</span>key</span>></span></span> <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/delete_%NAME%.png</</span>string</span>></span></span> </</span>dict</span>></span></span> </</span>dict</span>></span></span> </</span>array</span>></span></span> </span></code></pre> Padding and position</h2> AppIconExtractor</strong> includes a few additional options to customize your composited icon variations.</p> composite_padding</code>: sets the number of pixels from the edge of the image the superimposed template image is offset. Defaults to 10</code> pixels.</li> composite_position</code>: sets the corner to which the superimposed template image for composited variations is anchored. Defaults to br</code> for the bottom-right corner. You can change this to bl</code> (bottom left), ur</code> (upper right), or ul (upper left) if you prefer.</li> </ul> Combinations of these options are shown below with the padding highlighted in pink:</p> </figure> Clockwise from the upper left, this example shows:</p> composite_padding</code> omitted (so it defaults to 10</code>) and composite_position</code> of ul</code>.</li> composite_padding</code> of 20</code> and composite_position</code> of ur</code>.</li> composite_padding</code> of 0</code> and composite_position</code> omitted (so it defaults to br</code>).</li> composite_padding</code> of 5</code> and composite_position</code> of bl</code>.</li> </ul> Setting these options applies the same settings to all</em> composited variations. This is an intentional design choice to keep the input arguments – and thus the required code – more manageable.</p> Output variables</h2> AppIconExtractor</strong> sets the path(s) to the extracted app icon, and any composited variations, as output variables during an AutoPkg run. This means you can extract and generate icons, then immediately use those icons in subsequent processors like JamfPolicyUploader</a>.</p> The following output variables are set if (and only if) the associated variations are requested:</p> app_icon_path</code>: path to the extracted, unmodified app icon. Always set.</li> install_icon_path</code> path to the composited "install" variation. Only set if this variations is requested.</li> update_icon_path</code> path to the composited "update" variation. Only set if this variations is requested.</li> uninstall_icon_path</code> path to the composited "uninstall" variation. Only set if this variations is requested.</li> </ul> Example uses in recipes</h2> Here are two examples of using AppIconExtractor</strong> in a child recipe or override.</p> Extract the icon from an available .app bundle</h3> Greg Neagle's recipe for Sublime Text 4</a> leaves the unarchived .app available in the recipe cache dir at %RECIPE_CACHE_DIR%/%NAME%/Sublime Text.app</code>. We'll use this to extract the Sublime Text icon using AppIconExtractor's</strong> default settings.</p> Process</span></span>:</span> -</span> Processor</span></span>:</span> com.github.haircut.processors/AppIconExtractor</span> Arguments</span></span>:</span> source_app</span></span>:</span> "</span>%RECIPE_CACHE_DIR%/%NAME%/Sublime Text.app"</span></span> -</span> Processor</span></span>:</span> com.github.grahampugh.jamf-upload.processors/JamfPolicyUploader</span> Arguments</span></span>:</span> policy_template</span></span>:</span> "</span>%POLICY_TEMPLATE%"</span></span> policy_name</span></span>:</span> "</span>%POLICY_NAME%"</span></span> icon</span></span>:</span> "</span>%app_icon_path%"</span></span> replace_icon</span></span>:</span> True</span> </span></code></pre> This extracts Sublime Text's icon without generating any composite variations, then feeds that extracted icon to the JamfPolicyUploader</code> processor. We set replace_icon</code> to True</code> to ensure any change to the icon by the vendor is automatically reflected within our Jamf policy.</p> Unpacking a .pkg to extract an icon</h3> The recipe for the Google Chrome Enterprise package</a> downloads a .pkg directly from the vendor, so no repackaging is needed. And while the AutoPkg recipe unpacks the package to performe code signature verification, it then runs the PathDeleter</code> processor to clean up that operation. This means a child recipe does not have access to a .app from which to extract an icon.</p> That means we'll need to do a little more work to unpack the package again so that we can get to the app bundle. We'll also generate a custom "uninstall" variations and override the default composition position and padding.</p> Here's the Process of this more complex example in XML format:</p> <</span>key</span>></span></span>Process</</span>key</span>></span></span> <</span>array</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>Processor</</span>key</span>></span></span> <</span>string</span>></span></span>FlatPkgUnpacker</</span>string</span>></span></span> <</span>key</span>></span></span>Arguments</</span>key</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>destination_path</</span>key</span>></span></span> <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/unpack</</span>string</span>></span></span> <</span>key</span>></span></span>flat_pkg_path</</span>key</span>></span></span> <</span>string</span>></span></span>%pkg_path%</</span>string</span>></span></span> </</span>dict</span>></span></span> </</span>dict</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>Processor</</span>key</span>></span></span> <</span>string</span>></span></span>PkgPayloadUnpacker</</span>string</span>></span></span> <</span>key</span>></span></span>Arguments</</span>key</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>destination_path</</span>key</span>></span></span> <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/unpack/pkgpayload</</span>string</span>></span></span> <</span>key</span>></span></span>pkg_payload_path</</span>key</span>></span></span> <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/unpack/GoogleChrome.pkg/Payload</</span>string</span>></span></span> </</span>dict</span>></span></span> </</span>dict</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>Processor</</span>key</span>></span></span> <</span>string</span>></span></span>com.github.haircut.processors/AppIconExtractor</</span>string</span>></span></span> <</span>key</span>></span></span>Arguments</</span>key</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>composite_padding</</span>key</span>></span></span> <</span>integer</span>></span></span>20</</span>integer</span>></span></span> <</span>key</span>></span></span>composite_position</</span>key</span>></span></span> <</span>string</span>></span></span>ul</</span>string</span>></span></span> <</span>key</span>></span></span>composite_uninstall_path</</span>key</span>></span></span> <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/Icon-Uninstall-%NAME%.png</</span>string</span>></span></span> <</span>key</span>></span></span>composite_uninstall_template</</span>key</span>></span></span> <</span>string</span>></span></span>/Users/haircut/Documents/delete.png</</span>string</span>></span></span> <</span>key</span>></span></span>icon_output_path</</span>key</span>></span></span> <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/Icon-%NAME%.png</</span>string</span>></span></span> <</span>key</span>></span></span>source_app</</span>key</span>></span></span> <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/unpack/pkgpayload/Google Chrome.app</</span>string</span>></span></span> </</span>dict</span>></span></span> </</span>dict</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>Processor</</span>key</span>></span></span> <</span>string</span>></span></span>PathDeleter</</span>string</span>></span></span> <</span>key</span>></span></span>Arguments</</span>key</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>path_list</</span>key</span>></span></span> <</span>array</span>></span></span> <</span>string</span>></span></span>%RECIPE_CACHE_DIR%/unpack</</span>string</span>></span></span> </</span>array</span>></span></span> </</span>dict</span>></span></span> </</span>dict</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>Processor</</span>key</span>></span></span> <</span>string</span>></span></span>com.github.grahampugh.jamf-upload.processors/JamfPolicyUploader</</span>string</span>></span></span> <</span>key</span>></span></span>Arguments</</span>key</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>icon</</span>key</span>></span></span> <</span>string</span>></span></span>%app_icon_path%</</span>string</span>></span></span> <</span>key</span>></span></span>policy_name</</span>key</span>></span></span> <</span>string</span>></span></span>Install %NAME%</</span>string</span>></span></span> <</span>key</span>></span></span>policy_template</</span>key</span>></span></span> <</span>string</span>></span></span>Self-Service-Policy.xml</</span>string</span>></span></span> <</span>key</span>></span></span>replace_icon</</span>key</span>></span></span> <</span>true</span>/></span></span> </</span>dict</span>></span></span> </</span>dict</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>Processor</</span>key</span>></span></span> <</span>string</span>></span></span>com.github.grahampugh.jamf-upload.processors/JamfPolicyUploader</</span>string</span>></span></span> <</span>key</span>></span></span>Arguments</</span>key</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>icon</</span>key</span>></span></span> <</span>string</span>></span></span>%uninstall_icon_path%</</span>string</span>></span></span> <</span>key</span>></span></span>policy_name</</span>key</span>></span></span> <</span>string</span>></span></span>Uninstall %NAME%</</span>string</span>></span></span> <</span>key</span>></span></span>policy_template</</span>key</span>></span></span> <</span>string</span>></span></span>Uninstall-Policy.xml</</span>string</span>></span></span> <</span>key</span>></span></span>replace_icon</</span>key</span>></span></span> <</span>true</span>/></span></span> </</span>dict</span>></span></span> </</span>dict</span>></span></span> </</span>array</span>></span></span> </span></code></pre> This unpacks the Google Chrome enterprise package, extracts the unmodified app icon, and generates an "uninstall" composite version with a custom graphic in the upper left corner with 20px of padding.</p> </figure> The outputs of AppIconExtractor</strong> are then used as inputs to JamfPolicyUploader process runs to set the icons for two different policies. Setting the replace_icon</code> argument to True</code> ensures that any changes to the icons are reflected on the Jamf Pro policies.</p> Hopefully this processor will help you extract icons without the manual work, and spiff up those Self Service policies.</p> Pull requests accepted</a> if you fix a bug or make an improvement!</p> Stopping an AutoPkg Recipe if VirusTotal Detects Malware Tue, 14 Dec 2021 00:00:00 +0000 Hannes Juutilainen's VirusTotalAnalyzer</a> is a fantastic AutoPkg postprocessor. It automatically queries VirusTotal</a> to analyze items downloaded by AutoPkg and detect potential malware.</p> VirusTotalAnalyzer was designed to run as a postprocessor</a>. AutoPkg postprocessors allow you to add extra "steps" to an AutoPkg recipe at runtime without modifying the recipe itself. By this convention, VirusTotalAnalyzer scans files after all other recipe steps have completed. This means a recipe cannot conditionally act on the VirusTotal scan results; the query happens after</em> the recipe has otherwise finished.</p> In practice, code signature verification</a>, recipe trust verification</a>, and after-the-fact VirusTotal scanning offer strong protections against malicious software. Most Mac admins also report "never" seeing VirusTotal flag a vendor package; or if they have seen it, investigation revealed a false positive.</p> However, many AutoPkg workflows directly upload or import software packages to a Munki repository or Jamf Pro distribution point as part of a recipe run. If VirusTotal engines flag an item, VirusTotalAnalyzer reports on the detection after the item is already uploaded to your systems</em>. Further, most highly-automated AutoPkg workflows begin deploying the newly-uploaded software to a test group (or all endpoints) as soon as the recipe completes.</p> You may require additional assurance that downloaded software is not flagged by VirusTotal, and want to prevent any flagged files from being uploaded to your software distribution points.</p> You can do this by using a custom recipe that runs VirusTotalAnalyzer as a regular processor – instead of as a postprocessor – combined with the StopProcessingIf processor. This allows you to terminate a recipe if VirusTotal reports any hits before</strong> subsequent recipe steps upload an item to your systems.</p> Here's how to do that.</p> </span> Create a Custom Recipe</h3> While it's possible to append</em> additional processors to a recipe within a recipe override</a>, or call multiple postprocessors on the command line, I recommend creating a custom recipe for each application. This allows you to very specifically define exactly</em> what you wish to happen during a recipe run.</p> Yes, this is additional overhead. However, it's not uncommon for an organization to maintain custom recipes for all software to meet automation needs. And hey, if you want this extra security layer, you'll have to work a little for it.</p> I recommend creating an organization-specific child recipe for each app in your catalog, and adding the required processors to that child recipe.</p> Let's use Rectangle</a> as an example. Here's the shell of a new custom recipe:</p> Identifier</span></span>:</span> org.macblog.pkg.Rectangle</span> ParentRecipe</span></span>:</span> com.github.dataJAR-recipes.pkg.Rectangle</span> MinimumVersion</span></span>:</span> "</span>2.3"</span></span> Input</span></span>:</span> NAME</span></span>:</span> Rectangle</span> Process</span></span>:</span> </span></code></pre> Here, I've set a new Identifier</code> for the recipe specific to my organization. In this example, I ultimately want a .pkg, so I set the ParentRecipe</code> as the identifier of the pkg</code> version of the Rectangle recipe. Finally, since I'm using YAML here, I set the MinimumVersion</code> to 2.3</code> to require the version of AutoPkg that supports YAML-formatted recipes.</p> I'm setting the NAME</code> key in the Input</code> dictionary to ensure AutoPkg recognizes the file as a valid recipe. No additional Input keys are required for this minimal example. You can, however, customize them to fit your needs.</p> Since this is a child recipe it inherits all the output of the parent recipe. That means we don't need to do anything to get the pkg output from the parent, and the child recipe only needs to contain the additional processors we want to run.</p> Each child recipe receives and can act on the output of its parent recipe.</figcaption></figure>Add VirusTotalAnalyzer as a Regular Processor</h3> Instead of running VirusTotalAnalyzer as a postprocessor, you can call it as a "regular" processor inside the Process</code> dictionary of our custom recipe. Add it like so:</p> Identifier: org.macblog.pkg.Rectangle ParentRecipe: com.github.dataJAR-recipes.pkg.Rectangle MinimumVersion: "2.3" Input: NAME: Rectangle Process: - Processor: io.github.hjuutilainen.VirusTotalAnalyzer/VirusTotalAnalyzer</mark> </code> </pre> Since processors within a recipe run sequentially, you can run VirusTotalAnalyzer immediately after downloading an item, but before subsequent processors upload that item to your systems. It requires only that a pathname</code> variable exists.</p> In this example, the parent recipes have already handled downloading and packaging the app. Our child recipe receives all the output of those previous actions, and we're ready to use VirusTotalAnalyzer to scan the downloaded item for threats.</p> Add a StopProcessingIf Processor</h3> Next, add the StopProcessingIf</a> processor. The StopProcessingIf processor terminates a recipe execution if a condition is met. This is most commonly used to stop processing a recipe if a vendor download has not changed, by setting the predicate</code> to download_changed == FALSE</code>.</p> Because StopProcessingIf accepts NSPredicate-style</a> conditions, we can also test more complex conditions.</p> VirusTotalAnalyzer outputs its findings to the virus_total_analyzer_summary_result</code> output variable. Within that output is a ratio</code> key that denotes the number of VirusTotal engines that flagged a file as suspicious out of the total number of engines that scanned the file, e.g. 0/55</code>.</p> We can use the NSPredicate test BEGINSWITH</code> to target the beginning of the ratio</code> variable string. That variable is nested a couple levels deep, and we use dot notation to access nested values. Combined with a NOT</code> negation, our full predicate is:</p> NOT virus_total_analyzer_summary_result.data.ratio BEGINSWITH '0/' </span></code></pre> This means: If the reported ratio from VirusTotal begins with anything other than 0/</code>, e.g. 1/54</code> or 23/68</code>, stop processing the recipe.</em></p> Add these items to the Input</code> and Process</code> dictionaries like so:</p> Identifier: org.macblog.pkg.Rectangle ParentRecipe: com.github.dataJAR-recipes.pkg.Rectangle MinimumVersion: "2.3" Input: NAME: Rectangle STOP_PREDICATE: "NOT virus_total_analyzer_summary_result.data.ratio BEGINSWITH '0'"</mark> Process: - Processor: io.github.hjuutilainen.VirusTotalAnalyzer/VirusTotalAnalyzer - Processor: StopProcessingIf Arguments: predicate: "%STOP_PREDICATE%"</mark> </code> </pre> Setting the predicate as an Input key allows you to override the predicate at recipe runtime if you need to temporarily skip the StopProcessingIf functionality. Manually passing --key STOP_PREDICATE=FALSEPREDICATE</code> will bypass the StopProcessingIf processor and allow the recipe to complete, even if VirusTotal reports a detection.</p> Update:</span> Thanks to Graham Pugh</a> for the suggestion to specify the predicate in the Input dictionary. </p> Add Your Other Processors</h3> Add any additional processors after</em> the StopProcessingIf processor to suit your needs.</p> You might add JamfUploader</a> or MunkiImporter</a> processors to copy a package to your distribution servers. Whatever you add after the StopProcessingIf processor will be executed only if VirusTotal reports no malware detections.</p> This custom recipe can be used just like any other. You can (and should!) make local overrides, run it in recipe lists, add chat-notifying postprocessors, and commit it to your organization's private recipe repository. Run it manually, or within AutoPkgr, or in your CI pipeline.</p> Final Thoughts</h3> There are a few caveats worth mentioning:</p> You need to create a custom recipe for every app in your catalog. You may be doing this already – if so, good for you! (Or, try this alternative</a>)</li> You might get false positives, where a single VirusTotal engine erroneously reports a detection. You'll need to follow up manually, and perhaps temporarily disable the VirusTotalAnalyzer (or StopProcessingIf) processor in a recipe until VirusTotal or the vendor fixes the issue. As mentioned, passing --key STOP_PREDICATE=FALSEPREDICATE</code> will disable the StopProcessingIf behavior.</li> You cannot set a "threshold" of a permissible number of potential detections. The predicate used in the StopProcessingIf processor allows only zero</strong> detections.</li> </ol> If you don't mind this overhead, and your organization requires this increased assurance, you fit within the narrow band of utility this process provides. You might even view the above caveats as good things. If so, enjoy!</p> Alternative to a Custom Recipe</h3> AutoPkg is flexible, and you can run multiple postprocessors sequentially. Instead of creating a custom recipe, it's possible to "append" the required postprocessors to an existing recipe on the command line as follows:</p> autopkg</span></span> run com.github.dataJAR-recipes.pkg.Rectangle \ </span>--</span>post</span> io.github.hjuutilainen.VirusTotalAnalyzer/VirusTotalAnalyzer \ </span>--</span>post</span> StopProcessingIf \ </span>--</span>key</span> predicate="</span>NOT virus_total_analyzer_summary_result.data.ratio BEGINSWITH '0'"</span></span> \ </span>--</span>post</span> com.github.grahampugh.jamf-upload.processors/JamfPackageUploader</span> </span></code></pre> I personally prefer maintaining a custom recipe. I most frequently run multiple recipes using the -l</code> or --recipe-list</code> flag, and adding postprocessors to a recipe list run will call all those postprocessors for every recipe. For me, that decreases the flexibility afforded by creating a very explicit custom recipe, which is why I recommend that route.</p> But the multiple-postprocessor option works fine if you prefer it.</p> Complete Examples</h3> Here is a complete recipe example in both YAML and XML formats. It demonstrates uploading the example Rectangle package to Jamf Pro if VirusTotal engines find no malware.</p> YAML</h4> Identifier</span></span>:</span> org.macblog.pkg.Rectangle</span> ParentRecipe</span></span>:</span> com.github.dataJAR-recipes.pkg.Rectangle</span> MinimumVersion</span></span>:</span> "</span>2.3"</span></span> Input</span></span>:</span> NAME</span></span>:</span> Rectangle</span> STOP_PREDICATE</span></span>:</span> "</span>NOT virus_total_analyzer_summary_result.data.ratio BEGINSWITH '0'"</span></span> Process</span></span>:</span> -</span> Processor</span></span>:</span> io.github.hjuutilainen.VirusTotalAnalyzer/VirusTotalAnalyzer</span> -</span> Processor</span></span>:</span> StopProcessingIf</span> Arguments</span></span>:</span> predicate</span></span>:</span> "</span>%STOP_PREDICATE%"</span></span> -</span> Processor</span></span>:</span> com.github.grahampugh.jamf-upload.processors/JamfPackageUploader</span> </span></code></pre> XML</h4> <?</span>xml</span> version</span>=</span>"</span>1.0"</span></span> encoding</span>=</span>"</span>UTF-8"</span></span>?></span></span> <!</span>DOCTYPE</span> plist</span> PUBLIC</span> "</span>-//Apple//DTD PLIST 1.0//EN"</span></span> "</span>http://www.apple.com/DTDs/PropertyList-1.0.dtd"</span></span>></span></span> <</span>plist</span> version</span>=</span>"</span>1.0"</span></span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>Identifier</</span>key</span>></span></span> <</span>string</span>></span></span>org.macblog.pkg.Rectangle</</span>string</span>></span></span> <</span>key</span>></span></span>Input</</span>key</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>NAME</</span>key</span>></span></span> <</span>string</span>></span></span>Rectangle</</span>string</span>></span></span> <</span>key</span>></span></span>STOP_PREDICATE</</span>key</span>></span></span> <</span>string</span>></span></span>NOT virus_total_analyzer_summary_result.data.ratio BEGINSWITH '0'</</span>string</span>></span></span> </</span>dict</span>></span></span> <</span>key</span>></span></span>MinimumVersion</</span>key</span>></span></span> <</span>string</span>></span></span>2.3</</span>string</span>></span></span> <</span>key</span>></span></span>ParentRecipe</</span>key</span>></span></span> <</span>string</span>></span></span>com.github.dataJAR-recipes.pkg.Rectangle</</span>string</span>></span></span> <</span>key</span>></span></span>Process</</span>key</span>></span></span> <</span>array</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>Processor</</span>key</span>></span></span> <</span>string</span>></span></span>io.github.hjuutilainen.VirusTotalAnalyzer/VirusTotalAnalyzer</</span>string</span>></span></span> </</span>dict</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>Arguments</</span>key</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>predicate</</span>key</span>></span></span> <</span>string</span>></span></span>%STOP_PREDICATE%</</span>string</span>></span></span> </</span>dict</span>></span></span> <</span>key</span>></span></span>Processor</</span>key</span>></span></span> <</span>string</span>></span></span>StopProcessingIf</</span>string</span>></span></span> </</span>dict</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>Processor</</span>key</span>></span></span> <</span>string</span>></span></span>com.github.grahampugh.jamf-upload.processors/JamfPackageUploader</</span>string</span>></span></span> </</span>dict</span>></span></span> </</span>array</span>></span></span> </</span>dict</span>></span></span> </</span>plist</span>></span></span> </span></code></pre> Using JXA in Jamf Pro Scripts and Extension Attributes Thu, 18 Nov 2021 00:00:00 +0000 Quick follow-up to my earlier guide on using JavaScript for Automation</a>.</p> There must be something in the air that put the topic of JXA on the minds of the Apple community. Armin Briegel shared a great roundup of recent JXA work</a>, and the #scripting channel on the MacAdmins Slack team</a> is full of folks discussing new and old discoveries.</p> Here are a handful of additional tips.</p> Excutable JXA scripts</h3> You can run JXA directly by including the JavaScript language flag in a script's shebang, like this:</p> #!</span>/usr/bin/osascript -l JavaScript</span> function</span> run</span></span>(</span>)</span></span> {</span> var</span> app</span></span> </span>=</span> Application</span>.</span>currentApplication</span></span>(</span>)</span></span>;</span> app</span>.</span>includeStandardAdditions</span> =</span> true</span>;</span> return</span> app</span>.</span>systemInfo</span></span>(</span>)</span>.</span>cpuType</span>;</span> }</span></span></span> </span></code></pre> Save the file with a name and extension you like. I've been using .scpt</code>, which is the convention suggested by Apple's own Script Editor application. Something like cputype.scpt</code> will work just fine.</p> Mark the file as executable by running chmod +x cputype.scpt</code>. Then, you can run it on your system by simply calling ./cputype.scpt</code></p> This will output the CPU architecture of the computer, for example ARM64E</code> or Intel x86-64...</code></p> JXA in Jamf Pro Scripts</h3> You can drop a JXA script directly in Jamf Pro without any modification. As long as you include the JavaScript shebang outlined above, you're good to go.</p> You do not necessarily need to wrap JXA in a shell script.</strong> It might make sense to "shell out" to a JXA function from a shell script for some use cases, but it is not a requirement.</p> Jamf supports non-compiled AppleScript files</a> natively, and you can use them in your Policies like any other script.</p> JXA in Jamf Pro Extension Attributes</h3> Same deal; specify the Script type for the Extension Attribute, and include the JavaScript language flag shebang. Ensure your function returns the required <result></result></code> wrapper surrounding the output. You can do that with simple string concatenation using the plus operator</a>, like this:</p> #!</span>/usr/bin/osascript -l JavaScript</span> function</span> run</span></span>(</span>)</span></span> {</span> var</span> app</span></span> </span>=</span> Application</span>.</span>currentApplication</span></span>(</span>)</span></span>;</span> app</span>.</span>includeStandardAdditions</span> =</span> true</span>;</span> return</span> "</span><result>"</span></span> +</span> app</span>.</span>systemInfo</span></span>(</span>)</span>.</span>cpuType</span> +</span> "</span></result>"</span></span>;</span> }</span></span></span> </span></code></pre> This will output <result>ARM64E</result></code>, for example, which will show up on your computer's inventory record during the next device inventory.</p> --</p> That's it. Hopefully this helps you store and run JavaScript for Automation scripts.</p> How to Parse JSON on the macOS Command Line Without External Tools Using JavaScript for Automation Sun, 14 Nov 2021 00:00:00 +0000 JSON – JavaScript Object Notation</a> – is the lingua franca for shipping data between systems. Everything from software APIs to web services commonly support, and typically default to, outputting data in JSON format.</p> Because of its ubiquity, you're bound to run into a need to manipulate a chunk of JSON in the course of managing your fleet.</p> For example, you might run a shell script on your Macs that instructs them to read data from an external system via its API using curl</code>. That external system returns a big ol' heap of JSON, but you need to extract only a single data point from that payload, then act on that value.</p> This is somewhat of a challenge in the shell because macOS does not include any native or pre-installed tools to help you hack down that JSON. Administrators often resort to workarounds like shelling out to Python or using sed</code> and awk</code> to approximate parsing.</p> However, another, native</strong> solution is right there in the name: use JavaScript.</p> </span> JavaScript, JXA and Open Scripting Architecture</h3> It seems appropriate to use JavaScript to parse JavaScript</em> Object Notation, right? But how? Can you do that without relying on external tools?</p> Since Mac OS X Yosemite, Apple has supported JavaScript as a language to interact with the Open Scripting Architecture (OSA)</a>. OSA enables interapplication communication for automation, and using JavaScript for this purpose is known as JavaScript for Automation</em> (JXA).</p> JXA is built right into macOS and lets you use JavaScript without any additional tooling.</p> You may be familiar with using the osascript</code> binary to execute AppleScript snippets. While AppleScript is a more common choice for accessing OSA functionality, you can trivially use JavaScript instead.</p> On the command line, use the -l</code> (that's a lowercase L) flag with osascript</code> to specify JavaScript</code> as the scripting language. Without the flag, osascript</code> defaults to expecting AppleScript. </p> Here's a simple example derived from Apple's sample code</a>:</p> osascript</span> -</span>l</span> '</span>JavaScript'</span></span> -</span>e</span> '</span>var app = Application.currentApplication(); app.includeStandardAdditions = true; app.displayDialog("Hello from JavaScript!");'</span></span> </span></code></pre> This will display a dialog window using JavaScript. Easy!</p> Using JXA to read JSON in a shell script</h3> Let's look at an example where we use the ip-api.com</a> service to query the current geographic location of the system based on its IP address.</p> #!</span>/bin/bash</span> GEODATA</span>=</span>$</span></span>(</span> curl</span> -</span>s</span> http</span>://</span></span>ip-api.com/json/ )</span> read</span> -</span>r</span> -</span>d</span> '</span>'</span></span> JXA</span> <<</span>EOF</span> function</span> run</span></span>(</span>)</span></span> {</span> var</span> ipinfo</span></span> </span>=</span> JSON</span>.</span>parse</span></span>(</span>\`</span>$GEODATA\`</span>); return ipinfo.city; } EOF CITY=$( osascript -l 'JavaScript' <<< "${</span></span>JXA</span></span>}</span></span>" ) echo "This computer is in ${</span></span>CITY</span></span>}</span></span>" </span></span></span></span></span></code></pre> First, we call the ip-api service by using curl</code> to send a GET</code> request to the service's JSON endpoint. The results are stored in a variable called GEODATA</code> via command substitution</a>.</p> Next, we use the read -r -d '' VARIABLE_NAME <<LIMIT_STRING</code> "bashism" to store a multi-line JavaScript program as a variable using here-document</a> notation. This makes it easier to write and maintain the JavaScript code, rather than trying to smoosh it into a single line.</p> This (extremely basic) JavaScript program takes advantage of JXA's special run()</code> function. run()</code> is automatically executed when the program is called, and will print any output returned.</p> Within the JavaScript code, notice the assignment of ipinfo</code> references the GEODATA</code> variable defined in the outer shell script via variable expansion. The JSON returned by ip-api.com is a native JavaScript data structure that could be used directly, but for safety we treat it as a string and parse it using the JSON.parse()</code></a> method. Since most JSON payloads are multi-line strings, we wrap the variable expansion in ``</code> backticks to take advantage of JavaScript's template literal</a> feature. And finally, those backticks need to be escaped using \</code> backslashes since they're embedded within a shall script. Whew!</p> When I first published this article, I advised that you could reference and use a JSON object received from a remote source directly, without running it through JSON.parse()</code>.</p> This is true, but it's not secure. I was assuming the safety of the external data.</p> Paul Galow wisely pointed out</a> that a malicious source could potentially send JavaScript instead of JSON, which our script would dutifully execute. RCEs are bad. Be like Paul and run payloads through JSON.parse()</code>. This ensures things that aren't JSON cause the script to error.</p> </aside> A quick aside on quoting and here-documents: Quoting the limit string (EOF</code> in this case) will prevent</strong> variable expansion within the here-document. <<'EOF'</code> would cause $GEODATA</code> to be interpretted literally rather than replaced by the results of the curl</code> command. The unquoted <<EOF</code> allows the variable to expand as expected.</p> Next, we simply return the city</code> attribute of the ipinfo</code> object.</p> Finally, we use the osascript</code> binary to run the JavaScript program. osascript</code> can read input from stdin</code>, so we use <<<</code> to read the program stored in the JXA</code> variable. Storing its output in the CITY</code> variable lets us use it elsewhere in the shell script. In this case we're outputting a nice message. Running the script will print This computer is in Atlanta</code> (or your approximate location) to your terminal.</p> That was an extremely verbose explanation of a very basic program! But, hopefully it helps explain the patterns being used here. Now let's try something more complex.</p> Complex JSON manipulation</h3> Our next example will demonstrate the power of JavaScript's native JSON capabilities. It's a neat trick to pull a single attribute out of a simple JSON payload – but it's actually useful</strong> to manipulate the data using conditional logic.</p> Here we'll pull the recent commit history of the AutoPkg GitHub repository, then retrieve the commits whose commit message length is longer than the soft 50-character recommended maximum length.</p> Here's the code:</p> #!</span>/bin/bash</span> GITHUB</span>=</span>$</span></span>(</span> curl</span> -</span>s</span> https</span>://</span></span>api.github.com/repos/autopkg/autopkg/commits )</span> read</span> -</span>r</span> -</span>d</span> '</span>'</span></span> GITCOMMITS</span> <<</span>EOF</span> function</span> run</span></span>(</span>)</span></span> {</span> const</span> commits</span></span> </span>=</span> JSON</span>.</span>parse</span></span>(</span>\`</span>$GITHUB\`</span>); const long_messages = []; for (const commit of commits) { if (commit.commit.message.length > 50) { var msg = "'" + commit.commit.message + "' - Commit " + commit.sha; long_messages.push(msg); } } return long_messages.join("\n</span>"); } EOF osascript -l "JavaScript" <<< "${</span></span>GITCOMMITS</span></span>}</span></span>" </span></span></span></span></span></code></pre> The basic structure is largely the same as in the previous example: use curl</code> to gather data, then feed that into a JavaScript program.</p> The cool part is being able to manipulate the JSON data in place. Here, we're iterating through each commit and checking the string length of each commit message. If that length is longer than 50 characters, we append that message to an array, along with the commit's SHA hash. Finally, we return a newline-joined string of those commits.</p> The end result prints only those commit messages longer than 50 characters.</p> This example would have been extremely</em> cumbersome to implement in pure shell. With JXA, it's just some relatively simple JavaScript.</p> Reading JSON files from disk</h3> You can also read JSON files that exist on disk with just a tiny bit of extra effort.</p> #!</span>/bin/bash</span> read</span> -</span>r</span> -</span>d</span> '</span>'</span></span> PARSE</span> <<</span>EOF</span> var</span> app</span></span> </span>=</span> Application</span>.</span>currentApplication</span></span>(</span>)</span></span>;</span> app</span>.</span>includeStandardAdditions</span> =</span> true</span>;</span> function</span> parseJSON</span></span>(</span>path</span>)</span></span> {</span> const</span> data</span></span> </span>=</span> app</span>.</span>read</span></span>(</span>path</span>)</span></span>;</span> return</span> JSON</span>.</span>parse</span></span>(</span>data</span>)</span>;</span> }</span></span></span> function</span> run</span></span>(</span>)</span></span> {</span> const</span> parsed</span></span> </span>=</span> parseJSON</span></span>(</span>"</span>/path/to/some/file.json"</span></span>)</span></span>;</span> return</span> parsed</span>.</span>some</span>.</span>key</span>;</span> }</span></span></span> EOF</span> </span></code></pre> This time, we're using using JXA to get an instance of the "current application." This lets us do useful things like access the file system. We define a reusable function to parse a JSON file at a path supplied as a parameter. Within the run()</code> function, we call that parseJSON()</code> function and supply the full path to a JSON file. We can then access the parsed JSON properties using standard dot notation</a>.</p> Other tools and alternatives</h3> Why go through the trouble of using JXA for these use cases?</p> First, it's really not much "trouble." I'd be implementing similar logic in another external language or tool. This is more or less adding a thin wrapper. As long as you are comfortable writing JavaScript (or searching StackOverflow), it's very little extra effort.</p> But why not use another tool or method?</p> When running code on client systems within a fleet, it's best to use the tools those clients have available by default.</p> Since Apple will soon stop shipping scripting runtimes</a> such as Python, Perl, and Ruby, you should not</strong> rely on "shelling out" to those languages. Sure, it might be easy enough to add a parse=$( python -c 'import json;...' )</code> call to your script; but at this point you'd just be creating new technical debt. Don't do that.</p> If you ship your own Python 3 runtime – such as with "macadmin python</a>" – you could, of course, use that. Installing your own Python 3 framework on your clients is a great idea if you routinely use Python code to manage them. Otherwise, it is</em> another external dependency.</p> Alternatively, you could</em> pull down jq</a> on your client systems. jq is built specifically to handle JSON on the command line and in shell scripts. But again – it's an external dependency.</p> Using JXA requires no new installations or configuration changes. It will simply run on your systems as they currently exist.</p> For that reason, I think JXA a great tool to reach for when you need to work with JSON.</p> Plus, constraints are fun, right?!</p> Further reading</h3> Interacting with JSON is a common need, but these examples barely scratch the surface of what you can achieve with JavaScript for Automation.</p> JXA even includes an Objective-C bridge</a>, which allows you to use macOS frameworks like AppKit and Foundation.</p> The JXA Cookbook</a> on GitHub contains a wealth of information and is an essential read on this topic. It's a great supplement to Apple's somewhat sparse documentation</a>.</p> How to Disable iCloud Private Relay in macOS Monterey Wed, 27 Oct 2021 00:00:00 +0000 Apple recently introduced iCloud Private Relay</a> as an additional benefit for iCloud+ subscribers. The feature routes Safari web browsing (and some other insecure Internet traffic) through a semi-anonymizing service to reduce third parties' ability to profile and track individual users.</p> However, it may be necessary in some environments to disable iCloud Private Relay. The feature may interfere with management controls, prevent required traffic auditing, or complicate troubleshooting procedures.</p> Apple provides a guide to prepare your network or service for iCloud Private Relay</a>, but it's also possible to disable the feature using a Restrictions</a> Configuration Profile.</p> </span> To disable iCloud Private Relay, set the allowCloudPrivateRelay</code> key to false</code> in the com.apple.applicationaccess</code> domain. An example full Configuration Profile is below:</p> <?</span>xml</span> version</span>=</span>"</span>1.0"</span></span> encoding</span>=</span>"</span>UTF-8"</span></span>?></span></span> <!</span>DOCTYPE</span> plist</span> PUBLIC</span> "</span>-//Apple//DTD PLIST 1.0//EN"</span></span> "</span>http://www.apple.com/DTDs/PropertyList-1.0.dtd"</span></span>></span></span> <</span>plist</span> version</span>=</span>"</span>1.0"</span></span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>PayloadContent</</span>key</span>></span></span> <</span>array</span>></span></span> <</span>dict</span>></span></span> <</span>key</span>></span></span>PayloadDisplayName</</span>key</span>></span></span> <</span>string</span>></span></span>Restrictions</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadIdentifier</</span>key</span>></span></span> <</span>string</span>></span></span>com.apple.applicationaccess.E8C72ECD-7122-4C66-853F-3F3467D1AEF5</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadType</</span>key</span>></span></span> <</span>string</span>></span></span>com.apple.applicationaccess</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadUUID</</span>key</span>></span></span> <</span>string</span>></span></span>1953B7E6-DB5C-4FDA-A579-2EE05978F4B6</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadVersion</</span>key</span>></span></span> <</span>integer</span>></span></span>1</</span>integer</span>></span></span> <</span>key</span>></span></span>allowCloudPrivateRelay</</span>key</span>></span></span> <</span>false</span> /></span></span> </</span>dict</span>></span></span> </</span>array</span>></span></span> <</span>key</span>></span></span>PayloadDescription</</span>key</span>></span></span> <</span>string</span>></span></span>Disables the iCloud Private Relay feature.</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadDisplayName</</span>key</span>></span></span> <</span>string</span>></span></span>Disable iCloud Private Relay</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadIdentifier</</span>key</span>></span></span> <</span>string</span>></span></span>E31B0811-3164-49CE-BAA9-67075398DE85</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadOrganization</</span>key</span>></span></span> <</span>string</span>></span></span>Company Name</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadScope</</span>key</span>></span></span> <</span>string</span>></span></span>System</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadType</</span>key</span>></span></span> <</span>string</span>></span></span>Configuration</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadUUID</</span>key</span>></span></span> <</span>string</span>></span></span>ECEB2ECA-B16F-41F8-9909-7DD36FA1609C</</span>string</span>></span></span> <</span>key</span>></span></span>PayloadVersion</</span>key</span>></span></span> <</span>integer</span>></span></span>1</</span>integer</span>></span></span> </</span>dict</span>></span></span> </</span>plist</span>></span></span> </span></code></pre> This profile is also available on GitHub</a>.</p> Once installed, this profile:</p> Stops traffic from routing to mask.icloud.com</code> and mask-h2.icloud.com</code> at the network level.</li> Removes "Private Relay" from the list of services available to enable in System Preferences > Apple ID</em>.</li> Removes the "Use iCloud Private Relay" checkbox from the "Network" pane in System Preferences.</li> </ol> Requirements</h3> Unlike many Configuration Profiles payloads, the com.apple.applicationaccess</code> payload is re-evaluated after initial installation.</p> That means this profile can be pre-installed on systems running macOS versions prior to Monterey. Go ahead and deploy this restriction to your fleet before they upgrade to macOS Monterey so the configuration takes immediate effect. It won't have any effect on macOS Big Sur (or previous systems), but will begin working once the system is upgraded to Monterey.</p> This restriction does not</em> require Supervision.</p> Caveat</h3> I've noted a small bug in macOS Monterey 12.0.1. If the Configuration Profile restricting iCloud Private Relay is installed while the relay is active</em>, the checkbox in System Preferences > Network</em> remains visible.</p> </figure> Private Relay is in fact disabled</mark>, and no traffic is routed through the service. The "Private Relay" feature is</em> removed from the listing in System Preferences > Apple ID</em>. This visual bug persists through reboots, but only occurs when the profile is installed while iCloud Private Relay is already running.</p> Getting the currently logged-in user's ID (UID) for launchctl Mon, 15 Mar 2021 00:00:00 +0000 Many scripted macOS workflows require determining the username of the currently logged-in user. Whether you wish to execute a command as that user via su</code> or you just want to log the username during your script's execution, you may need to query macOS for this information.</p> This is a solved problem, and Armin Briegel's excellent article on Getting the current user in macOS</a> outlines the best method.</p> In addition to determining the logged-in user's username, you may also need their user ID number, or UID. For example, loading a LaunchAgent as a specific user requires providing that user's UID. </p> Previous solutions involved grabbing the logged-in user's username, then feeding that to id -u $loggedInUser</code> – but you can get the currently logged-in user's UID in one step.</p> </span> The code</h2> A slight modification of Armin's recommendation for grabbing the username will give us the UID.</p> For bash and zsh</h3> loggedInUserID=$( scutil <<< "show State:/Users/ConsoleUser" \| awk '/kCGSSessionUserIDKey :/ { print $3 }' ) </span></code></pre> For shell</h3> Vanilla shell does not support the <<<</code> here-string</a> used in the previous example, so instead we must pipe the show</code> statement to scutil</code>.</p> loggedInUserID=$( echo "show State:/Users/ConsoleUser" \| scutil \| awk '/kCGSSessionUserIDKey :/ { print $3 }' ) </span></code></pre> Both variants will return the UID of the currently logged-in user, or an empty string if the Mac is sitting at the login window.</p> An example and a note on launchctl</code> syntax</h2> With a UID in hand, you can now load a LaunchAgent as</em> that user:</p> launchctl asuser <uid> launchctl load /Library/LaunchAgents/com.org.example.plist </span></code></pre> However! In macOS Big Sur, I'm finding launchctl</code> is more reliable using the launchctl 2.0 syntax (as documented by Balmes Pavlov</a>). This makes sense, as subcommands like asuser</code> have been marked as "legacy" for some time now.</p> Switching from the "legacy" subcommand asuser</code> to bootstrap gui/"${loggedInUserID}"</code> consistently loads launchd tasks, and is my current recommendation.</p> A complete example of loading a LaunchAgent as the currently logged-in user:</p> loggedInUserID=$( scutil <<< "show State:/Users/ConsoleUser" \| awk '/kCGSSessionUserIDKey :/ && ! /loginwindow/ { print $3 }' ) /bin/launchctl bootstrap gui/"${loggedInUserID}" /Library/LaunchAgents/com.org.example.plist </span></code></pre> Renaming Computers via Snipe-IT using Jamf Pro Wed, 13 Jan 2021 00:00:00 +0000 A couple of years ago, I shared a method to set a Mac's hostname via a Google Sheet</a>. It's worked well at my organization (as well as many others!) and helped us keep our computer names consistent.</p> We've since moved to using Snipe-IT</a> for asset management. Snipe is a fantastic open-source tool that simplifies inventory tracking for our whole IT shop. It also includes a robust API that allows us to integrate with external systems and processes.</p> I'm now using the Snipe API to script our computer naming process. We treat Snipe as the system of record for all inventory, and any change made to a computer's hostname in Snipe can be reflected on both</em> the client system and in Jamf Pro. Here's how.</p> </span> Why Python?</h2> For many years, Apple included Python 2.7 with the default installation of macOS. With the 2019 release macOS Catalina, of Apple began warning</a> that "future versions of macOS will not include" runtimes for popular languages including Python.</p> As of macOS Big Sur 11.1, the Python 2.7 runtime is still present. However, Python 2 is no longer maintained</a> and is not a good choice for forward compatibility. Many administrators are moving their system administration processes to shell scripts, which mostly "run anywhere" and don't rely on any runtime dependencies.</p> Despite the convenience and portablity of shell scripts, I maintain a number of complex Python workflows that are arduous or ill-suited to port to shell.</p> This script interfaces with the Snipe API, which accepts and returns data in JSON format. While tools and workarounds exist to work with JSON in shell scripts, it's frankly painful.</p> In my organization, I've taken to installing Python 3 to a known location using Greg Neagle's Relocatable Python</a> tool. This allows me to use Python's native JSON tooling and interact with the Snipe API without hassle.</p> As such, this script is written in Python 3, and the shebang on line 1</code> requires you to specify the path to the Python 3 runtime you've installed on the client system.</p> The script</h2> I've published this script is as a project on Github at haircut/jamf-snipe-rename</a>.</p> The set_computer_name.py</code> script is what you're looking for.</p> What it does</h3> The script gathers the serial number of the computer upon which it's running, then queries your Snipe instance via the API to discover its current Asset Name as set within that system. Then, it sets the hostname of the computer using the Jamf binary's setComputerName</code> command.</p> As a fallback, if your Snipe instance does not have a record of the serial number, the computer name will be set to that serial number. Setting the hostname to the computer's serial number is a reasonable alternative, as it lets us easily identify machines that could not be renamed by the script, then fix the source data within Snipe. And, the serial number is much better than a bunch of Macs named "Sarah's MacBook Pro!"</p> Setting up Snipe</h2> I recommend setting up a dedicated local user with restricted access in Snipe to handle all requests associated with this workflow. </p> The Snipe documentation explains creating users</a> and setting permissions</a>. I name my user something relevant like "Jamf Computer Naming User" or similar.</p> Following the principle of least privilege, grant this local user only</em> the View</strong> permission under Assets</strong> and Create API Keys</strong> under Self</strong>.</p> Log in to Snipe as the new local user, and generate an API key</a>. This will generate a (very long) bearer token</a> we'll use to authenticate our script's requests.</p> Using the script</h2> Save a local copy of set_computer_name.py</code> and configure the SNIPE_SERVER</code> value (near the top of the script) to point toward your Snipe installation. It's important to only provide the base URL here, as the script will add the full path to the API endpoint we need.</p> Encrypting script parameters</h3> Since we're using the sensitive API key in our script to authenticate requests to Snipe, it's best not to hardcode that API key into the script. Nor is it wise to pass the API key as a script parameter</a> in cleartext.</p> While the restricted permissions of the Snipe user limit the potential damage from a leaked key, it's still best to avoid the hazard by encrypting the user's API key and passing it as a script paramter.</p> I'm using Jamf's Encrypted Script Parameters</a> utility to securely pass the API token from Jamf Pro to the client system. A full explanation of the utility is beyond this article's scope, but briefly:</p> Follow Jamf's README to encrypt your API key.</li> Note the ecrypted value, salt, and passphrase. Save them all in your organization's shared password manager :)</li> Paste the salt and passphrase in the TOKEN_SALT</code> and TOKEN_PASSPHRASE</code> constants near the top of your copy of the script.</li> </ol> Adding the script to Jamf Pro</h3> Within your Jamf Pro instance, visit _Management Settings > Computer Management</p> Scripts_, then add a new script. Name it something helpful, like "Set Computer Name from Snipe" and then set the label for Parameter 4 to "Encrypted API Key." Paste in your (configured) copy of the script, then save.</p> </blockquote> Running the script via policy</h3> Create a new policy, then configure the "Script" payload. Add the "Set Computer Name from Snipe" script, then fill in the "Encrypted API Key" script parameter with the encrypted API key you created earlier.</p> I recommend updating the computer's inventory after renaming it, so that your Jamf instance is updated with the new hostname as soon as possible. If your deployment is large, consider omitting the inventory update to save on the processing burden inherent in updating inventory.</p> How and when to run the script is largely dependent on your needs. I run the renaming process early in our provisioning workflow using Jamf's "Enrollment Complete" trigger.</p> You could also create a secondary policy that runs on a routine basis – say, weekly – to ensure Jamf data stays consistent with your inventory data in Snipe.</p> Running the script outside of Jamf Pro</h3> If your organization does not use Jamf Pro to manage Macs, you can still use this script after a few modifications.</p> As written, the script uses the Jamf binary's setComputerName</code> command. This is a convenient shorthand for running the following three commands:</p> sudo</span></span> scutil --</span>set</span> ComputerName "</span>name"</span></span></span> sudo</span></span> scutil --</span>set</span> LocalHostName "</span>name"</span></span></span> sudo</span></span> scutil --</span>set</span> HostName "</span>name"</span></span></span> </span></code></pre> Within this project's repository</a>, I've also shared set_computer_name_non_jamf.py</code> which substitues the Jamf binary call for the three commands above. This non-Jamf script expects an encrypted</em> Snipe API token as its first positional parameter. If you're using this workflow with a management platform other than Jamf, I've left it as an exercise to the reader on passing the parameter. Even if you're not using Jamf, their encrypted script parameters</a> project is platform agnostic.</p> Conclusion</h2> This transition from my previous Google Sheets-based workflow</a> has been a big help in my organization. It allows us to treat our inventory system as our source of truth for computer names, as it should be. Changes made in the inventory system are reflected on the client system with no manual intervention.</p> Don't disable accessibility options during Setup Assistant Fri, 27 Nov 2020 00:00:00 +0000 macOS Big Sur includes a new screen during Setup Assistant: Accessbility. It prompts users to explore the accessibility features of macOS to adapt their computer to their vision, motor, hearing, and cognitive needs.</p> You might want to disable or skip this setup screen. Don't.</p> </span> </figure> The first time you boot a Mac, it runs through a process known as Setup Assistant. This lets your users configure some basic options before they begin using the computer. With each new macOS release, Apple adds additional screens to Setup Assistant. Some are of dubious utility. </p> Most popular MDMs allow you, as an administrator, to instruct Macs to skip certain screens during Setup Assistant. In a corporate environment, your users may not need to set up Apple Pay, or agree to the Terms and Conditions – so it makes sense to simply skip these screens and streamline their first boot.</p> If you support more humans than only yourself, how those humans interact with their computer is not your decision.</strong></mark></p> Even those who would not traditionally consider themselves in need of accessibility features can still benefit. Putting these options front and center allows everyone the opportunity to explore settings that might just make their Mac a bit easier to use.</p> Kudos to Apple for making accessibility a default</em> aspect of the macOS setup process.</p> Sending Autopkg and JSSImporter Notifications to Google Hangouts Chat Mon, 29 Apr 2019 00:00:00 +0000 Although Slack</a> has seemingly taken over the world of workplace chat, my organization is a G Suite</strong> shop and we use Hangouts Chat</a> for a majority of our internal communication. It's included as a "core" G Suite app, so why not use the product we already have, right?</p> I wanted a way to post notifications to Hangsouts Chat rooms when autopkg</a> downloads new software, or makes changes to our Jamf Pro server via JSSImporter</a>. No solution existed. Building on the excellent Slack-centric work of both Graham R Pugh</a> and Rich Trouton</a>, I've made two different autopkg postprocessors</a> to send autopkg notifications to Google Hangouts Chat.</p> </span> HangoutsChatNotifier</code> - simple notifications</h3> If you'd just like to know when your automated autopkg run downloads new software, HangoutsChatNotifier</code> will send a simple note to a Hangouts Chat room.</p> </figure>HangoutsChatJSSNotifier</code> - going deeper with JSSImporter</code></h3> If you're using JSSImporter</a> to automate the process of adding the software autopkg downloads to your JSS, HangoutsChatJSSNotifier</code> will send more detailed messages to a Hangouts Chat room.</p> </figure> Both postprocessors leverage the existing data provided during an autopkg run to send data to a Hangouts Chat incoming webhook</a>.</p> To set these up on your own G Suite domain, you'll need:</p> Hangouts Chat</a> enabled for your users</li> Bots enabled</a> for all OUs in your domain. If Bots are not enabled across the domain, your notifications will fail</a></li> My haircut-recipes</a> autopkg recipes present in your autopkg repository, which includes these Hangouts Chat postprocessors</li> An incoming webhook</a> configured for the Hangouts Chat room you wish to notify</li> ...and of course, a working autopkg setup</li> </ul> Setting up a webhook</h2> In Hangouts Chat, open the room you'd like to notify, then click the room's name near to top of the screen.</p> </figure> Click Configure webhooks</em>. Enter a name for the incoming webhook – I just use "autopkg" – then click Save</em>. </p> </figure> You'll see a long URL displayed representing the API endpoint we can use to send messages to this room. Copy that URL and save it for later.</p> </figure>Which postprocessor should I use?</h2> Whichever you like! </p> HangoutsChatNotifier</code> sends simple messages to inform you when your autopkg workflow has downloaded new software. The quick notifications might be useful to send to your desktop support team Hangouts Chat room, or your QA group.</p> If you're using JSSImporter</code> as part of your autopkg workflow, you may find the expanded detail provided by HangoutsChatJSSNotifier</code> useful. Setting up JSSImporter</code> is beyond the scope of this article – but if you're already there, HangoutsChatJSSNotifier</code> will help you send notifications to Hangouts Chat.</p> Running the postprocessor</h2> You have two options to include the Hangouts Chat postprocessors in your autopkg runs.</p> Using a postprocessor at the command line</h3> The simplest method is to include the --post</code> flag when running autopkg at the command line. </p> ...for HangoutsChatNotifier</code></h4> Specify the postprocessor name com.github.haircut.HangoutsChatNotifier/HangoutsChatNotifier</code> and provide a --key</code> in the form --key hangoutschat_webhook_url="<incoming webhook url>"</code>. Replace <incoming webhook url></code> with the URL you noted earlier after creating an incoming webhook in your Hangouts Chat room.</p> A complete command might look like:</p> autopkg run MyRecipe.recipe \ --post "com.github.haircut.HangoutsChatNotifier/HangoutsChatNotifier" \ --key hangoutschat_webhook_url="https://chat.googleapis.com/v1/spaces/XXX/messages?key=XXX-XXX&token=XXX-XXX" </span></code></pre> ...for HangoutsChatJSSNotifier</code></h4> Just like the simple notifier, add a --post</code> flag to your autopkg run and specify com.github.haircut.HangoutsChatNotifier/HangoutsChatNotifier</code>, and a --key hangoutschatjss_webhook_url="<incoming webhook url>"</code>.</p> This example might look like:</p> autopkg run MyRecipe.recipe \ --post "com.github.haircut.HangoutsChatJSSNotifier/HangoutsChatJSSNotifier" \ --key hangoutschatjss_webhook_url="https://chat.googleapis.com/v1/spaces/XXX/messages?key=XXX-XXX&token=XXX-XXX" </span></code></pre> ...with a recipes text list</h4> If you use a text file list of multiple recipes</a> the postprocessors are compatible and will send a Hangouts Chat message after each recipe runs.</p> For example:</p> autopkg run --recipe-list /path/to/recipe_list.txt \ --post "com.github.haircut.HangoutsChatJSSNotifier/HangoutsChatJSSNotifier" \ --key hangoutschatjss_webhook_url="https://chat.googleapis.com/v1/spaces/XXX/messages?key=XXX-XXX&token=XXX-XXX" </span></code></pre> Using a postprocessor with a recipe property list</h3> My preferred method of running multiple autopkg recipes is using a property list (plist)</a>. A plist recipe list lets you set up declarative and robust autopkg configurations that would otherwise require a messy string of command line arguments.</p> To include the Hangouts Chat postprocessor, add it as an array item under the postprocessors</code> key. Then, add your incoming webhook url as a string under a hangoutschat_webhook_url</code> key.</p> <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"> <plist version="1.0"> <dict> <key>recipes</key> <array> <string>MyRecipe.recipe</string> <string>AnotherRecipe.recipe</string> <string>RadicalRecipe.recipe</string> </array> <key>hangoutschat_webhook_url</key> <string>https://chat.googleapis.com/v1/spaces/XXX/messages?key=XXX-XXX&token=XXX-XXX</string> <key>postprocessors</key> <array> <string>com.github.haircut.HangoutsChatNotifier/HangoutsChatNotifier</string> </array> </dict> </plist> </span></code></pre> Important!</strong> Hangouts Chat incoming webhook URLs include an ampersand (&</code>) in the query parameters, which is an illegal character within an XML <string></code> element. You must</strong> replace the ampersand with its character entity &</code> when including the incoming webhook URL in a property list file – otherwise the postprocessor will fail to send a notification. </p> e.g. .../XXX/messages?key=XXX-XXX&token=XXX-XXX</code> </aside> Now you can run your recipe list and send Hangouts Chat notifications using a much less cumbersome command:</p> autopkg run --recipe-list /path/to/recipe_list.plist </span></code></pre> Using both HangoutsChatNotifier</code> and HangoutsChatJSSNotifier</code> together</h2> The namespace for each postprocessor is distinct, so you can</em> use both simultaneously during a single autopkg run. For example, you might like to send your helpdesk a brief notification that new software is available using HangoutsChatNotifier</code>, and your engineering team managing Jamf Pro a more detailed note showing the changes made to your JSS.</p> For this example, you'd create one incoming webhook in your "helpdesk" Hangouts Chat room and set its URL as the hangoutschat_webhook_url</code> key. Create a second incoming webhook in your "Jamf Pro" Hangouts Chat room and set that URL as the hangoutschatjss_webhook_url</code>. Add both postprocessors to your autpkg run – done!</p> Wrapping up</h2> If you have need to customize the formatting or content of the Hangouts Chat notifications, you can fork my postprocessors found at autopkg/haircut-recipes/PostProcessor</a>. Google has great documentation</a> around their message formats.</p> Now go forth and notify your teams!</p> Helping Your Users Reset TCC Privacy Policy Decisions Mon, 10 Sep 2018 00:00:00 +0000 Taking a cue from iOS, Mac OS X 10.8 "Mountain Lion" introduced new systems to help users manage access requests to potentially sensitive and private personal information. When an app required access to a user's Contacts, for instance, a consent prompt appeared on screen asking the user to allow or disallow this access.</p> Broadly, this system is known as TCC</code> or transparency, consent and control</em>.</p> With each version of macOS, Apple broadens the scope of privacy controls. The upcoming release of macOS Mojave expands these controls such that many previously-permitted interactions will require user consent. Prompts for consent appear only once</em> when an action first requires approval.</p> With more to manage and only a single prompt to allow or disallow access, it can be opaque for users to understand the state of their system. Actions may fail with no clear indication as to why; a decision to disallow access is easily forgotten after many weeks or months.</p> Let's create an easy method to reset these decisions to allow for a fresh start.</p> <!- -more --></p> Background</h2> Some brief background.</p> The origins of TCC</code> are explained during the "How iOS Security Really Works</a></em>" session from WWDC 2016.</p> During WWDC 2018 Apple hosted two sessions explaining the direction of their privacy and security posture:</p> Your Apps and the Future of macOS Security</a></li> Better Apps through Better Privacy</a></li> </ul> Both sessions are insightful – check them out!</p> For a deeper dive into changes around Privacy controls in macOS Mojave, I highly recommend Rich Mogull's excellent article Mojave’s New Security and Privacy Protections Face Usability Challenges</a>.</p> The Issue</h2> When a user decides to allow or disallow an interaction via a user consent prompt, that decision should appear in _System Preferences > Security & Privacy</p> Privacy_. In my testing of macOS Mojave, I noticed that some allowed or disallowed interactions – namely certain "automation" decisions – did not appear in a user-configurable capacity in System Preferences</em>. This effectively makes affected decisions "permanent" unless a user is comfortable using a command line utility.</p> </blockquote> Moreover, there is no GUI-based method to reset all privacy consent decisions and "start from scratch." Apple does, helpfully, provide a command line utility to programmatically un-configure consent decisions so that interactions may prompt for approval again.</p> Resetting Privacy Consent Decisions</h2> macOS includes a utility called tccutil</code>. This tool allows you to manage the privacy database and reset decisions you've made regarding TCC-protected services.</p> tccutil</code> is a simple utility, supporting one command: reset</code></p> Resetting decisions made for a particular service is straightforward:</p> tccutil reset <service name> </span></code></pre> And here's a list of known services:</p> Accessibility AddressBook All AppleEvents Calendar Camera Facebook LinkedIn Liverpool Location MediaLibrary Microphone Photos PhotosAdd PostEvent Reminders ShareKit SinaWeibo Siri SystemPolicyAllFiles SystemPolicyDeveloperFiles SystemPolicySysAdminFiles TencentWeibo Twitter Ubiquity Willow </span></code></pre> (Thanks to @opragel</a> for extracting the list of services.)</p> By way of example, the following command would reset all decisions you've made regarding access to your calendar events. All apps that access your calendar would then prompt you again for consent to access the data the next time you launch them.</p> tccutil reset Calendar </span></code></pre> In testing this utility I developed a quick script to automate the process of resetting all</strong> the above-listed services. You can find tcc-reset.py on GitHub</a>.</p> I wanted to provide the same tool to my users as an easy-to-use troubleshooting utility, so I've expanded it to make it available in Jamf Self Service. This allows users to reset privacy consent decisions without needing to contact IT.</p> Self Service Privacy Consent Reset</h2> The goal here is to provide a mechanism for users to reset all their decisions to allow or disallow apps to access protected services or files. We'll accomplish this with a script and a policy.</p> The Script</h3> Self-Service-Reset-Privacy-Consent.py</a> is an expansion of my original tcc-reset.py</a> script. Running the script with no parameters will reset all privacy consent decisions for the currently-logged-in user. Optionally, you may pass the word all</code> as Jamf Parameter 4 to reset privacy consent decisions for all users on a system.</p> Add a new Script to your JSS. Give the script a suitable name, then paste in the contents of Self-Service-Reset-Privacy-Consent.py</a> in the "Script" tab.</p> Jump to the "Options" tab. Leave the Priority set to "After", then add a label for Parameter 4: "Reset all users? (Type 'all')"</p> </figure> Save the Script. Next, we'll set up a policy.</p> The Policy</h3> Create a new Policy. Give it an appropriate name; I've chosen "Reset Privacy Consent Decisions" to be consistent with the language Apple uses to describe TCC features. Leave all Triggers un-checked; this policy will only be available via Self Service. I set the Execution Frequency to "Ongoing" to ensure users have access to the utility whenever they need.</p> Add your Self-Service-Reset-Privacy-Consent.py</code> script to the Scripts payload of your policy. As mentioned, you can optionally set Parameter 4 to all</code> so that privacy consent is reset for all users on a system. With single-user systems this shouldn't be necessary. By default the script resets consent decisions for the currently-logged-in user. However, I've included the option for those managing labs or other multi-user systems.</p> </figure> Set an appropriate policy scope in the "Scope" tab. I use the "All Managed Clients" computer group so the utility is available to all users.</p> Next, open the "Self Service" tab and check the box to "Make policy available in Self Service." I set the "Button Name Before Initiation" and "Button Name After Initiation" to "Reset" so the button always displays the same text.</p> I check "Ensure that users view the description" and set the following text as the description:</p> Resets your Privacy Consent decisions.</p> If you experience application behavior where certain features like Camera, Microphone, or Disk Access do not work as expected, resetting your Privacy Consent decisions will allow applications to prompt you for consent to access these features.</p> </blockquote> Finally, I upload an icon to spruce up the presentation of the policy when viewed in Self Service. You're welcome to download the icon</a> for use in your organization.</p> </figure> And there we go! Our users can now reset or "undo" all the decisions they've made regarding privacy consent. Apps will once again prompt for consent when initiating a sensitive interaction.</p> Wrapping Up</h2> As the release date of macOS Mojave approaches, I'm hopeful Apple will provide more detailed documentation around these features. While I applaud their apparent goal of increased visibility into access of potentially-sensitive user data, I'm concerned this current implementation will only confuse users who may not understand the effects of allowing or disallowing certain interactions.</p> We shouldn't have to engineer scripts to help users manage Privacy features. If Apple wants users to embrace these features, they must understand them and their implications on how their Mac functions. Explicit and concise controls provided in the GUI should display all</em> user decisions and allow for seamless administration. Resetting these decisions shouldn't be relegated to a command line tool. Users need clarity. I mean... "transparency" is right there in the name "Transparency, Consent and Control", right?</p> For more information, please join the #tcc</code> channel on the MacAdmins Slack Team</a>.</p> Signing Configuration Profiles Fri, 03 Aug 2018 00:00:00 +0000 Apple has made it clear; MDM is the future.</p> As the preferred method of device management moves more and more to Configuration Profiles, administrators must turn their focus toward digital security.</p> Signing configuration profiles provides assurance of their origin, and an assertion their contents have not been modified in transit.</p> </span> A profile signed with a trusted signing certificate appears in System Preferences > Profiles with a green "Verified" label.</p> </figure> If the profile is signed by a certificate that was not issued by a certificate authority trusted by the operating system – as is the case with a self-signed certificate – the profile appears with a red "Unverified" label.</p> </figure> If the profile is not signed at all, it appears with a red "Unsigned" label.</p> </figure> Note:</strong> While this guide focuses on signing Configuration Profiles for use with Jamf Pro, the concepts apply generally.</p> </aside> Jamf Pro includes a built-in certificate authority. It's a key piece of functionality that allows Jamf Pro to generate digital certificates to facilitate secure, trusted communication between your clients and your Jamf Pro server.</p> During setup, the Jamf Pro built-in certificate authority generates a signing certificate for both macOS and iOS. This signing certificate is used to digitally sign configuration profiles deployed by your Jamf Pro server. Each enrolled client will have the "JSS Built-in Signing Certificate" installed to its System keychain. This certificate is issued by your Jamf Pro server's built-in certificate authority. Since your clients trust your Jamf Pro server's root certificate, the signing certificate is also trusted; the chain is complete.</p> Profiles created using the Jamf Pro configuration profile interface are automatically signed using the "JSS Built-in Signing Certificate" created during installation of your Jamf Pro server.</p> </figure>Why Sign Your Profiles?</h2> If you only use Jamf Pro's configuration profile creation interface, Jamf Pro handles all the signing for you.</p> However, if you create custom profiles "from scratch," then upload them to Jamf Pro for deployment, you should sign them.</p> When you upload an unsigned configuration profile, the Jamf Pro server converts it into a format you can edit using their interface. Unfortunately, this conversion process often results in a finished profile that incorrectly manages the settings you specified, or even manages settings that were not included in the original source profile at all.</p> Here's one example. Uploading a profile that manages the domain com.apple.security.firewall</code> and sets the key EnableFirewall</code> to true</code> results in a Jamf-converted profile that sets that key to false</code> – the exact opposite of what you intended! This particular defect is filed as Product Issue PI-004130, but no resolution is currently in place.</p> Signing your custom configuration profiles before uploading them prevents the Jamf Pro server from manipulating their contents.</mark> This ensures your profile is delivered unaltered to your clients.</p> When you upload a signed configuration profile, Jamf Pro warns you that the profile is read-only and offers you the opportunity to remove the digital signature.</p> </figure> Don't click the "Remove Signature" button. You won't be able to edit the profile within the Jamf Pro web interface – but neither can Jamf! The profile is delivered to client systems unmodified.</p> If you do need to make edits to the profile, you'll need to do so in a text editor, re-sign the profile, then upload it again to your Jamf Pro server. It's a minor inconvenience, but ensures you don't accidentally manage unintended preferences.</p> Signing Profiles for Trust by Any Client</h2> With an Apple Developer certificate you can easily sign profiles (and other objects) to provide assurance of origin. So long as you abide by the terms of the Apple Developer Program, your profiles will be trusted on any macOS or iOS device.</p> If you manage more than a handful of devices, you should really</strong> sign up for the Apple Developer Program</a>. The Developer Program will provide you with a number of certificates issued by Apple that are trusted on all macOS and iOS devices. This is useful for signing your Jamf Pro QuickAdd package, signing other installer packages, and signing configuration profiles. When these objects are signed you avoid the hurdles of your packages being quarantined by Gatekeeper, or your profiles appearing as "unverified."</p> Sign in to the Apple Developer Program account portal</a>. </li> Click "Certificates, IDs & Profiles".</li> Click the dropdown menu near the upper left labeled "iOS, tvOS, watchOS" then select "macOS".</li> Click "All" under the "Certificates" heading, then click the plus button near the upper right.</li> When prompted "What type of certificate do you need?", select "Developer ID", click Continue, then select "Developer ID Installer." While this type of certificate may be the best choice, other certificates will also work. See the note below for details.</li> Follow Apple's on-screen instructions to generate a Certificate Signing Request (CSR) and install the resultant certificate in your login keychain.</li> </ol> With your certificate installed in your keychain, use the security</code> tool to sign a profile.</p> /usr/bin/security cms -S -N "<common name of certificate>" -i <input path to unsigned profile> -o <output path for signed profile> </span></code></pre> A complete example might look like:</p> /usr/bin/security cms -S -N "Mac Developer: Matthew Warren (XXXXXXXXXX)" -i ~/Documents/Unsigned.mobileconfig -o ~/Documents/Signed.mobileconfig </span></code></pre> When signing a Profile, you'll be asked to unlock your login keychain. Enter your login keychain password and click "Allow".</p> </figure> You could also click "Always Allow" to avoid future prompts when signing Profiles, but I tend to err on the side of security and just enter my password each time.</p> Note: What type of certificate should you choose?</em></h4> Apple provides a number of different certificate types. While I recommend the "Developer ID Installer," most (if not all) of the options Apple provides will produce a certificate with the correct Key Usage attributes required to sign a Configuration Profile.</p> The choice is largely aesthetic, since the Common Name of the certificate will be visible to end users when viewing a Configuration Profile in the Profiles</em> pane within System Preferences.</p> The visible name listed beside the "Signed" heading generally follows the pattern <Certificate Type>: <Company or Individual Name> (<Team ID>)</code>. For example:</p> </figure> Another consideration is the Apple ID used to create the certificate. If you're signed in using the "parent" Apple ID of your organization's Apple Developer Account you'll have the most options available, including the recommended "Developer ID Installer" option. Generated certificates will include your company or organization's</strong> name in their Common Name. If you're using an Apple ID that has been granted delegated access to your organization's Developer Program, generated certificates will instead have your name</strong> included in the Common Name.</p> Again, most if not all of the Apple's options are suitable for signing Configuration Profiles – just keep in mind the differences in presentation.</p> Next, let's take a look at an alternative way to generate a signing certificate we can use to sign Configuration Profiles without</em> having access to Apple's certificate portal.</p> Signing Profiles for Trust Only by Jamf-enrolled Clients</h2> If you do not (and/or cannot</em>) participate in the Apple Developer Program, you can use Jamf Pro to generate a certificate to sign your custom configuration profiles. Profiles signed with a Jamf Pro-generated certificate will be trusted only</strong> by clients enrolled to your Jamf Pro instance; however, this is likely sufficient for most use cases.</p> Jamf Pro's Built-in CA allows you to generate arbitrary certificates of the following types:</p> Client Certificate</li> Web Server Certificate</li> SSO Certificate</li> </ul> During setup, the Jamf Pro built-in certificate authority generates a signing certificate for both macOS and iOS. This signing certificate is used to digitally sign configuration profiles deployed by your Jamf Pro server. Each enrolled client will have the "JSS Built-in Signing Certificate" installed to its System keychain. This certificate is issued by your Jamf Pro server's built-in certificate authority. Since your clients trust your Jamf Pro server's root certificate, the signing certificate is also trusted; the chain is complete.</p> While it might seem tempting to re-use these certificates to sign your custom-crafted profiles, Jamf Pro does not present a GUI option to download them. This is a good thing!</p> If you could</em> download and use the private key of your "JSS Built-in Signing Certificate" to sign arbitrary profiles it would present a larger security risk. If that key was ever compromised, it would affect every item signed by that certificate. This includes devices' MDM enrollment profiles. You'd have to regenerate your Jamf Pro built-in certificate authority and re-enroll every client. Let's avoid that!</p> Instead, we'll generate our own certificate for signing configuration profiles. First we'll need to generate a Certificate Signing Request (CSR) on your Mac.</p> Create A CSR on Your Mac</h3> Perform these steps on a client enrolled to your Jamf Pro server so that the certificate trust chain is complete.</p> Open the Keychain Access app.</li> Click the Keychain Access</strong> menu in the menu bar, hover over Certificate Assistant</em>, then select Request a Certificate From a Certificate Authority...</em>.</li> In the Certificate Assistant</strong> window that appears enter an email address for your organization (I use a generic one) and a suitable Common Name, such as " Profile Signing Certificate" or similar. For the "Request is:" option, select "Saved to disk" then click Continue</em>. </figure></li> When prompted, choose a location to save the CSR.</li> </ol> Upload the CSR to your Jamf Pro Server</h3> Open the CSR you saved to disk during the previous steps in a plain text editor and copy the entire contents to your clipboard. </figure></li> Sign in to your Jamf Pro server and navigate to _Settings > Global Management PKI Certificates_.</p> </blockquote> </li> Click the "Management Certificate Template" tab near the top of the screen.</li> Click the "Create Certificate from CSR" button.</li> In the modal window, paste the contents of your CSR, then select a Certificate Type</em> of "Web Server Certificate" and click the "Create" button. </figure></li> After clicking "Create", a file with a name in the format of C=US,CN=<common name you chose>,E=<email you specified>.pem</code> will automatically download. In my experience, the Jamf Pro GUI freezes at this point; simply click any link on the page to navigate away – we've already got what we came for!</li> Open the downloaded .pem</code> file. When prompted, choose to install the certificate in your login keychain. </figure></li> </ol> The certificate is now installed to your login keychain and ready to reference by name when signing Configuration Profiles.</p> /usr/bin/security cms -S -N "<common name of certificate you just installed>" -i <input path to unsigned profile> -o <output path for signed profile> </span></code></pre> When prompted, enter unlock your login keychain to finish signing the profile.</p> Finally, let's look at a third way to generate a certificate suitable for signing Profiles.</p> Signing a Profile – The Quick-and-Dirty, But Not Best Way</h2> If for some reason you neither participate in the Apple Developer Program, nor create a certificate within your Jamf Pro server, you do still have an option. We can create a Self Signed Certificate suitable for signing profiles. The resulting signed profile will not be trusted once deployed to a client system, but its signature will</em> prevent Jamf Pro from modifying its contents. Once installed, if the profile is viewed in the Profiles pane of System Preferences, it will display the red "Unverified" notice.</p> Create a Self Signed Code Signing Certificate</h3> Open the Keychain Access app.</li> Click the Keychain Access</strong> menu in the menu bar, hover over Certificate Assistant</em>, then select Create a Certificate...</em>.</li> In the Certificate Assistant</strong> window that appears, enter a sensible name. Select the Identity Type</em> of "Self Signed Root" and Certificate Type</em> of "Code Signing". Check the box beside "Let me override defaults". </figure></li> Leave the Serial Number</em> set to "1", and increase the Validity Period</em> to something like "1096" days (3 years) for convenience. </figure></li> On the next screen, enter relevant values for your organization. Make sure to specify a descriptive Common Name</em> for the certificate, as this will be viewable when inspecting Configuration Profiles signed by this certificate. </figure></li> Leave the default values of "2048 bits" for Key Size</em> and "RSA" for Algorithm</em>. </figure></li> Ensure "Signature" is selected for the Key Usage Extension</em>. </figure></li> Ensure "Code Signing" is selected for the Extended Key Usage Extension</em>.</li> </figure></li> On the following screens, leave "Include Basic Contraints Extension" and "Include Subject Alternate Name Extension" unchecked.</li> When prompted, ensure the certificate is set to be stored in your "login" keychain. </figure></li> </ol> After clicking "Done" you should see the new certificate listed in your login keychain.</p> </figure> You can now sign Configuration Profiles using the security</code> binary by referencing the common name of your new self-signed certificate.</p> /usr/bin/security cms -S -N "<common name of self-signed certificate>" -i <input path to unsigned profile> -o <output path for signed profile> </span></code></pre> Again, keep in mind that Configuration Profiles signed with a self-signed certificate will be listed as "Unverified" in System Preferences. While this won't affect the ability to install the profile, it could be a security concern depending on your environment. "Unverified" profiles assure that their contents have not been modified in transit, but provided no assurance of origin.</p> GUI Tool</h2> If you'd prefer a graphical tool to manage signing Configuration Profiles (or packages), check out Hancock</a>. You'll still need to correctly generate a signing certificate using a method outlined above, but Hancock can save you some keystrokes if you prefer an app!</p> Wrapping Up</h2> We've covered three different methods – in order of preference – to generate a signing certificate we can use to sign Configuration Profiles.</p> Signing a Configuration Profile prevents an MDM system, like Jamf Pro, from tampering with its contents; your hand-crafted profile is delivered to clients unaltered. If your signing certificate is trusted by the client system, it also provides verification that the Configuration Profile was created and delivered by a trusted party.</p> Regardless of how you generate your signing certificate, remember the command:</p> /usr/bin/security cms -S -N "<common name of signing certificate>" -i <input path to unsigned profile> -o <output path for signed profile> </span></code></pre> That's it! Don't hesitate to reach out if you have any questions, feedback, or corrections.</p> Express Setup, Location Services, Time Zone, and High Sierra Sun, 04 Feb 2018 00:00:00 +0000 I recently ran into a snag with our Device Enrollment Program (DEP) workflow. Users were not being prompted to enable Location Services to automatically set the time zone, nor was the explicit Time Zone selection screen displayed during Setup Assistant.</p> The result was that devices wound up configured with the default Cupertino, CA location, and a Pacific time zone. We're on the East coast – so we'd have to script a change of settings, or worse, have the user manually modify them.</p> As it turns out, this is an effect of the new "Express Setup" option in macOS High Sierra.</p> </span>Skipping Setup Assistant screens</h2> Update for macOS Monterey</strong></p> As of macOS Monterey, Express Setup</em> will only display if the user is logged in to an Apple ID and has previously configured Siri, Location Services, and App Analytics settings while signed in to that Apple ID.</p> </aside> When first booted, if a Mac has network connectivity it contacts Apple to see if it should receive an enrollment configuration from an MDM solution.</p> In most MDMs you can configure devices to skip any of a handful of Setup Assistant screens. In Jamf Pro, the configuration looks like this:</p> </figure> If a screen is skipped, the default options for settings on the screen are configured. In the case of Location Services, the default option is to disable</strong> Location Services.</p> In macOS 10.13.3 and below, running sudo /usr/libexec/mdmclient dep nag</code> will output the device's "activation record."</p> Activation record: { AllowPairing = 0; AnchorCertificates = ( ); AwaitDeviceConfigured = 1; ConfigurationURL = "<enrollment url>"; IsMDMUnremovable = 0; IsMandatory = 1; IsSupervised = 1; OrganizationAddress = "<organization address>"; OrganizationAddressLine1 = "<organization address>"; OrganizationCity = <organization city>; OrganizationCountry = <organization country>; OrganizationDepartment = "<organization department>"; OrganizationEmail = "<organization email>"; OrganizationMagic = <organization magic>; OrganizationName = "<organization name>"; OrganizationPhone = "<organization phone>"; OrganizationSupportPhone = "<organization phone>"; OrganizationZipCode = <organization zipcode>; SkipSetup = ( Diagnostics, Biometric, Restore, Registration, TOS, Payment, AppleID, iCloudDiagnostics ); } </span></code></pre> Note:</strong> The mdmclient</code> command and some terminology are specific to macOS 10.13.3 and below. Future versions of macOS may change the command and/or terminology.</p> </aside> You'll notice the SkipSetup</code> dictionary contains the list of Setup Assistant screens to be skipped.</p> In troubleshooting our issue with Location Services I was perplexed! The activation record clearly showed that Location Services was not</em> configured to be skipped. We should be seeing it during Setup Assistant.</p> A couple of colleagues on the MacAdmins Slack team</a> provided me with the necessary clue to resolve the issue. Specifically, Nate Van Dam noted the new behavior</a>.</p> Express Setup</h2> macOS High Sierra introduces a new "Express Setup" workflow during Setup Assistant. This screen consolidates the activation of Siri</strong>, Location Services</strong>, and App Analytics</strong> into one screen.</p> </figure> All three of these screens must not</strong> be skipped in order for Express Setup to appear. When you click "Continue" on the Express Setup screen, all three settings will be activated for you.</p> If you do configure any of these screens to be skipped, Express Setup will not appear and the Mac may be configured in an undesired way.</p> The dependency between these three settings is not currently documented in Apple's Device Enrollment Program Profile details</a>.</p> Fixing it</h2> Simple – just make sure Siri</strong>, Location Services</strong>, and App Analytics</strong> are not skipped in your DEP configurations.</p> </figure> Now, when a you run through Setup Assistant the Express Setup screen will appear. Accepting the default settings will turn Siri, Location Services, and App Analytics on, and devices will be configured to use the correct time zone of their current location.</mark></p> Disabling undesired settings</h2> Since the new Express Setup screen "bundles" these privacy-related options, it has the side effect of obfuscating your ability to disable them individually.</p> You can, however, click "Customize Settings" on the Express Setup screen to invidually disable Siri, Location Services, or App Analytics. It's common to disable the App Analytics telemetry options, and unfortunately this new workflow adds several extra clicks accomplish that result.</p> Hopefully Apple will document this change, and MDM solutions will update their interfaces to better clarify these Setup Assistant dependencies.</p> Automatically Renaming Computers from a Google Sheet with Jamf Pro Tue, 30 Jan 2018 00:00:00 +0000 In a post-imaging, DEP-only world, maintaining your organization's computer naming convention can be a challenge.</p> We can ease the pain with a little bit of Python, some clever interaction with the jamf</code> binary, and a remotely-hosted Google Sheet.</p> </span> The problem</h2> With DEP enrollments, your Macs are assigned a default computer hostname in the format <user's first name>'s <Mac model></code>. DEP provides no facility to set computer names, and Jamf Pro's PreStage Enrollments are similarly limited.</p> You wind up with your devices having very consumer-centric names like "Susie's MacBook Pro" and "Dave's iMac". Hostnames like that can cause compatibility issues in some environments, and often don't fit an organization's device naming convention.</p> Helpfully, the jamf</code> binary includes a setComputerName</code> verb to aid in – as it says on the tin – setting the computer's name. </p> The -name</code> flag will set the computer name to whatever you provide.</p> $ sudo jamf setComputerName -name ITDEPT-MAC14 Set Computer Name to ITDEPT-MAC14 </span></code></pre> The -useSerialNumber</code> and -useMACAddress</code> flags will set the computer name to either of those values.</p> $ sudo jamf setComputerName -useMACAddress Set Computer Name to 724f43aa12f </span></code></pre> You can also create more complex computer names with the optional -prefix</code> and -suffix</code> flags.</p> $ sudo jamf setComputerName -useMACAddress -prefix "Mac-" -suffix "-ITDEPT" Set Computer Name to Mac-784f435ee12d-ITDEPT </span></code></pre> These options may be sufficient for you – so feel free to tune out now!</p> However, your organization's naming scheme might include information that's not easily discernable from the device. In my case, our hostnames include the name of the department who owns the device and the asset tag.</p> One workaround is to script a GUI prompt for an end user or IT staff to manually enter the correct computer name. You can then feed this input to jamf setComputerName -name <input></code> – but that's error-prone and cumbersome to the user.</p> I want this automated!</mark></p> The -fromFile</code> flag</h2> The jamf</code> binary's setComputerName</code> command also includes the -fromFile</code> flag. From the jamf</code> help:</p> -fromFile The path to a CSV file containing the computer's MAC Address or Serial Number followed by the desired name </span></code></pre> This little gem allows you to provide the path to a CSV file containing device serial numbers or MAC addresses and those devices' associated desired hostnames.</p> Some experimentation showed the required format of the CSV file is:</p> <serial number or MAC address>,<desired hostname> </span></code></pre> A complete CSV using serial numbers might look like:</p> C02S1234GTFZ,ACCOUNTING-123 C02S1232GTFZ,PURCHASING-432 C02S1252GTFZ,MARKETING-823 C02S1211GTFZ,PUBLICSAFETY-242 </span></code></pre> After saving that CSV file to /var/tmp/serials.csv</code> for example, you can then run:</p> sudo jamf setComputerName -fromFile /var/tmp/serials.csv </span></code></pre> If the device running this command has a serial number listed in the specified CSV file, the jamf</code> binary will find it and set the computer name to the provided value. If the serial number (or MAC address) of the device is not</em> found in the specific CSV file, the jamf</code> binary will print an error and the computer name remains unchanged.</p> Using the CSV file allows you to assign more complex hostnames to your devices, but that CSV file must exist on the client in order to be used. You could create a policy to install the file on your fleet, but this is very</strong> messy and would quickly lead to stale data.</p> Instead, we'll host the CSV on a web server in a central location. This way, you can easily update the data without having to re-install any files on your clients.</p> For ease, we'll use a Google Sheet.</p> Create a Google Sheet</h2> You'll need a Google account with the Drive service available. If your organization uses G Suite, you're good to go, though any Google account will work.</p> Create a new Google Sheet document. Populate column A with your computer serial numbers or MAC address, and column B with their associated desired hostnames.</p> </figure> Click "Share" in the upper right corner, then click "Advanced" in the lower right of the modal Share window. Under the "Who has access" heading, you'll likey see "Private - Only you can access". </p> </figure> Click the "Change..." link here, then select the Link Sharing option "On - Anyone with the link". Confirm the Access is set to "Anyone Can view</strong>", then click Save.</p> </figure> Since serial numbers and MAC addresses could be considered somewhat sensitive information, these settings will reduce the availablity of the data while still allowing your clients to access the sheet.</p> Finally, note your Google Sheet's document ID. It's the long string of seemingly-random characters in the URL shown when editing the Sheet.</p> </figure>Add a script to Jamf Pro</h2> In your Jamf Pro server, visit Management Settings > Computer Management > Scripts</em> and create a new script.</p> Paste the contents of rename-computer.py</code> into the Script Contents area.</p>

How to sign scripts and other custom code

How to examine the network traffic of MDM enrollment during Setup Assistant

Slides and video for the 'Solving problems with custom AutoPkg processors' session at the University of Utah Mac Admin Meeting

Output the Date and Time in AutoPkg Recipes

More info</h2>
These are just a few of the potential use cases for this processor. Please check the full details in the README</a>. And as always – pull requests are open if you have an improvement or correction!</p>

Dynamically Add Dock Items with the Jamf Binary

Automatically Export and Generate App Icons in AutoPkg Recipes

Example uses in recipes</h2>
Here are two examples of using AppIconExtractor</strong> in a child recipe or override.</p>

Stopping an AutoPkg Recipe if VirusTotal Detects Malware

Using JXA in Jamf Pro Scripts and Extension Attributes

How to Parse JSON on the macOS Command Line Without External Tools Using JavaScript for Automation

How to Disable iCloud Private Relay in macOS Monterey

Getting the currently logged-in user's ID (UID) for launchctl

Renaming Computers via Snipe-IT using Jamf Pro

Don't disable accessibility options during Setup Assistant

Sending Autopkg and JSSImporter Notifications to Google Hangouts Chat

Using a postprocessor at the command line</h3>
The simplest method is to include the `--post</code> flag when running autopkg at the command line. </p>`

Helping Your Users Reset TCC Privacy Policy Decisions

Signing Configuration Profiles

GUI Tool</h2>
If you'd prefer a graphical tool to manage signing Configuration Profiles (or packages), check out Hancock</a>. You'll still need to correctly generate a signing certificate using a method outlined above, but Hancock can save you some keystrokes if you prefer an app!</p>

Express Setup, Location Services, Time Zone, and High Sierra

Automatically Renaming Computers from a Google Sheet with Jamf Pro

Add a script to Jamf Pro</h2>
In your Jamf Pro server, visit Management Settings > Computer Management > Scripts</em> and create a new script.</p>
Paste the contents of `rename-computer.py</code> into the Script Contents area.</p>`

MacBlog

Use AutoPkg to package GitHub repositories with no binary assets

Manage and enforce custom Login and Background items in macOS Ventura

MacBlog

Use AutoPkg to package GitHub repositories with no binary assets

Manage and enforce custom Login and Background items in macOS Ventura

How to sign scripts and other custom code

Get a signing certificate</h2> A foundational element of all public key infrastructure is trust. A code signing certificate needs to be issued by a certificate authority that macOS trusts in order to be considered valid.</p>

How to examine the network traffic of MDM enrollment during Setup Assistant

Slides and video for the 'Solving problems with custom AutoPkg processors' session at the University of Utah Mac Admin Meeting

Output the Date and Time in AutoPkg Recipes

Dynamically Add Dock Items with the Jamf Binary

Automatically Export and Generate App Icons in AutoPkg Recipes

Add my recipes and install the Pillow library</h2> First, you'll need my recipe repository available to your local AutoPkg installation. Add it with autopkg repo-add haircut-recipes</code>.</p>

Padding and position</h2> AppIconExtractor</strong> includes a few additional options to customize your composited icon variations.</p>

Example uses in recipes</h2> Here are two examples of using AppIconExtractor</strong> in a child recipe or override.</p>

Stopping an AutoPkg Recipe if VirusTotal Detects Malware

Add VirusTotalAnalyzer as a Regular Processor</h3> Instead of running VirusTotalAnalyzer as a postprocessor, you can call it as a "regular" processor inside the Process</code> dictionary of our custom recipe. Add it like so:</p>

Using JXA in Jamf Pro Scripts and Extension Attributes

How to Parse JSON on the macOS Command Line Without External Tools Using JavaScript for Automation

How to Disable iCloud Private Relay in macOS Monterey

Getting the currently logged-in user's ID (UID) for launchctl

Renaming Computers via Snipe-IT using Jamf Pro

Adding the script to Jamf Pro</h3> Within your Jamf Pro instance, visit _Management Settings > Computer Management</p>

Don't disable accessibility options during Setup Assistant

Sending Autopkg and JSSImporter Notifications to Google Hangouts Chat

Setting up a webhook</h2> In Hangouts Chat, open the room you'd like to notify, then click the room's name near to top of the screen.</p>

Using a postprocessor at the command line</h3> The simplest method is to include the --post</code> flag when running autopkg at the command line. </p>

Helping Your Users Reset TCC Privacy Policy Decisions

Signing Configuration Profiles

GUI Tool</h2> If you'd prefer a graphical tool to manage signing Configuration Profiles (or packages), check out Hancock</a>. You'll still need to correctly generate a signing certificate using a method outlined above, but Hancock can save you some keystrokes if you prefer an app!</p>

Express Setup, Location Services, Time Zone, and High Sierra

Automatically Renaming Computers from a Google Sheet with Jamf Pro

Example uses in recipes</h2>
Here are two examples of using AppIconExtractor</strong> in a child recipe or override.</p>

Using a postprocessor at the command line</h3>
The simplest method is to include the `--post</code> flag when running autopkg at the command line. </p>`

GUI Tool</h2>
If you'd prefer a graphical tool to manage signing Configuration Profiles (or packages), check out Hancock</a>. You'll still need to correctly generate a signing certificate using a method outlined above, but Hancock can save you some keystrokes if you prefer an app!</p>