Getting Started - macadmins/nudge GitHub Wiki

What is Nudge?

Nudge is a lightweight, open-source application that encourages users to update the operating system on their company-issued Mac (in accordance with their organization's IT policies). By design, Nudge cannot forcibly install any macOS updates. Instead the user is periodically presented with a pop-up, asking them to update their system. When a user ignores the deadline for required updates, Nudge will take over the user's screen and require them to click the “Update” button to continue.

What’s New in Nudge 2.0

Since the beginning, Nudge was designed to train users to respond to software updates in a timely manner, with increasing reminders and escalating levels of reinforcement over time.

Nudge 2.0 takes this compliance a step further and solves one of the main challenges for busy sysadmins: staying on top of the updates themselves. The next version of Nudge integrates a new public feed URL called “SOFA,” which is short for Simple Organized Feed for Apple Software Updates. This is an open-source project that contains information about available macOS versions, their release dates, supported hardware models, and relevant CVE vulnerability severity.

With SOFA, Nudge compliance rules can be completely automated to follow the release cadence of Apple’s major and minor OS updates. This new integration includes several additional options for administrators who want fine-grained operational control.

Nudge depends on three principal components to function:

the Nudge app itself;
a LaunchAgent to run Nudge periodically;
a set of configuration and compliance rules.

Barring any customizations, the Nudge LaunchAgent runs the Nudge app at 0:00 and 0:30 after each hour. The Nudge compliance rules can be provided as managed preferences in a Configuration Profile (delivered via MDM) - while this can also be achieved with a JSON manifest deployed locally, or as a remote URL, this is less recommended than the Configuration Profile approach..

Install Nudge

The first step is to install Nudge.app itself. Nudge is extremely safe to install without configuration as it doesn't do anything unless it is configured and has a LaunchAgent configured to open it on a cadence. Install the latest version from the releases page. You will want the package that has a name similar to Nudge-2.x.x.x.x.x.pkg.

Alternatively, use the following .sh script to install the latest version published.

Configuration

Before we are ready to create a LaunchAgent, we must define Nudge's configuration. This is done using a Configuration Profile, however it is important to note that because Nudge is configured with a number of sane defaults, not every configuration option needs to be specified.

With the new SOFA feed integration in Nudge 2.0, the only attribute you must configure in Nudge is requiredMinimumOSVersion.

The requiredMinimumOSVersion key tells Nudge which OS release devices must be running in order to be considered “in compliance”.
The options for this key include:

latest: always force latest release and if the machine can't this version, show the new "unsupported device" user interface
- latest-supported: always get the latest version SOFA shows that is supported by this device
- latest-minor: stay in the current major release and get the latest minor updates available

As mentioned above, Nudge bases its values for these attributes on the SOFA feed, which is polled once every 24 hours.

Now that Nudge knows which versions to push users to, we need to take a look at the SLAs (i.e. the timeframe) that users have for complying, before Nudge becomes increasingly insistent.

By default Nudge applies the following SLAs:

Standard updates (minor or major versions), which do not include any patches for known vulnerabilities, have an SLA of 28 days
Minor or Major versions which include patches for known vulnerabilities (CVEs) have an SLA of 21 days
Minor or Major versions which include patches for vulnerabilities which are known to be actively exploited have an SLA of 14 days

If you wish to adjust any of these SLAs, use the following keys under the osVersionRequirement key:

activelyExploitedCVEsMajorUpgradeSLA
activelyExploitedCVEsMinorUpdateSLA
nonActivelyExploitedCVEsMajorUpgradeSLA
nonActivelyExploitedCVEsMinorUpdateSLA
standardMajorUpgradeSLA
standardMinorUpdateSLA

Admins also commonly choose to configure certain options which will prevent Nudge from activating, for example if an application is in use for activities such as videoconferencing or screen sharing. These options include:

acceptableCameraUsage
acceptableScreenSharingUsage
acceptableAssertionUsage
acceptableAssertionApplicationNames

See examples of these in the configuration below.

You can easily customise the look of your Nudge application, by configuring the icon paths (iconLightPath and iconDarkPath) to point to either a remote URL where you host your icons, or a path to the icon files on the local system.

Basic Configuration Profile

<?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>PayloadContent</key>
    <array>
      <dict>
        <key>PayloadDescription</key>
        <string>Configures Nudge preferences</string>
        <key>PayloadDisplayName</key>
        <string>Nudge Preferences</string>
        <key>PayloadIdentifier</key>
       <string>com.github.macadmins.Nudge.preferences.example</string>
        <key>PayloadOrganization</key>
        <string>Company Name</string>
        <key>PayloadType</key>
        <string>com.github.macadmins.Nudge</string>
        <key>PayloadUUID</key>
        <string>CA02957C-7472-446B-9F77-3E0414405556</string>
        <key>PayloadVersion</key>
        <integer>1</integer>
   <key>optionalFeatures</key>
        <dict>
            <key>acceptableAssertionApplicationNames</key>
            <array>
                <string>Brave Browser</string>
                <string>Google Chrome</string>
                <string>firefox</string>
                <string>zoom.us</string>
            </array>
            <key>acceptableAssertionUsage</key>
            <true/>
            <key>acceptableCameraUsage</key>
            <true/>
            <key>acceptableScreenSharingUsage</key>
            <true/>
        </dict>
        <key>osVersionRequirements</key>
        <array>
          <dict>
            <key>requiredMinimumOSVersion</key>
            <string>latest-minor</string>
          </dict>
        </array>
	   <key>userInterface</key>
        <dict>
            <key>iconDarkPath</key>
            <string>https://somewhere/NudgeAssets/dark.png</string>
            <key>iconLightPath</key>
            <string>https://somewhere/NudgeAssets/light.png</string>
        </dict>
   <key>userExperience</key>
        <dict>
            <key>allowGracePeriods</key>
            <true/>
            <key>gracePeriodInstallDelay</key>
            <integer>12</integer>
            <key>gracePeriodLaunchDelay</key>
            <integer>1</integer>
        </dict>

      </dict>
    </array>
    <key>PayloadDescription</key>
    <string>Configures Nudge application</string>
    <key>PayloadDisplayName</key>
    <string>Nudge (v2.0) Example</string>
    <key>PayloadIdentifier</key>
    <string>com.github.macadmins.Nudge.example</string>
    <key>PayloadOrganization</key>
    <string>Company Name</string>
    <key>PayloadScope</key>
    <string>System</string>
    <key>PayloadType</key>
    <string>Configuration</string>
    <key>PayloadUUID</key>
    <string>2F54F734-132D-4539-B583-F1DCF23DB5EB</string>
    <key>PayloadVersion</key>
    <integer>1</integer>
  </dict>
</plist>

Testing Nudge

Once you're happy with your desired Nudge configuration, it's time to test it.

Save the profile changes, double click the profile file in the Finder, then go to System Preferences => Profiles and click install at the top. Once the profile is installed, we will launch Nudge while simulating an outdated OS version by running the following command in the Terminal (and disable the default random delay):

/Applications/Utilities/Nudge.app/Contents/MacOS/Nudge -simulate-os-version "14.2" -disable-random-delay

If everything went well, Nudge should launch and it should ask you to update macOS to the required version. If this did not happen, now is a good time to look at the documentation for Logging. For general logging around nudge, the go-to is the following log command:

log stream --predicate 'subsystem == "com.github.macadmins.Nudge"' --style syslog --color none

In order to do more detailed testing, you have to simulate specific releases in the SOFA feed by pointing Nudge to a custom SOFA feed with the help of the customSOFAFeedURL configuration key, or by making edits to the local cached SOFA feed:

~/Library/Application\ Support/com.github.macadmins.Nudge/sofa-macos_data_feed.json

LaunchAgent

The Nudge LaunchAgent controls how frequently the Nudge application is run.

In a default configuration, the LaunchAgent runs at the top (:00) and the bottom (:30) of the hour. The LaunchAgent timer is independent of the Nudge refresh intervals, which only fire while the application is open.

The LaunchAgent delivers the optimal Nudge experience, and should always be deployed with the app unless your shop has a very specific reason not to use it.

Packages

Nudge is compiled as three sets of packages:

Application
Logger
LaunchAgent

These three are also combined into the Nudge Suite. All three are rebuilt by a Github Action every time a new build is released.

To upgrade any of Nudge’s components, simply install the latest version of the individual package on top of an existing installation. Most of the time, the Nudge app is the only component being upgraded. Alternatively, you may deploy the entire suite as a convenience.

Congratulations, you now have a working Nudge config!