Install (Kandji)

The macOS forwarder collects files from Intel and Apple Silicon Macs, but macOS will not simply let it run: the system extension needs permission to load, and reading the whole disk needs Full Disk Access. Both arrive as configuration profiles, and both have to be on the machine before the installer is.

Four profiles, then the app, in this order:

You will need a Stairwell environment ID and a forwarder authentication token before you start. Assign everything below to a test blueprint first, and only widen it once a pilot machine is reporting objects.

🚧

Do not start with your crown jewels

The forwarder's first act is a full-disk backscan, which is I/O-heavy for a few hours and then subsides. Treat your first several installs as sacrificial: they upload the most unique files, and every later install is cheaper because Stairwell already knows what the earlier ones sent. See Forwarder Performance Tuning.

Installing the Privacy Profile

The privacy profile ensures that the Forwarder can access all files on the entire disk, including in the User home directory. By default this access is denied by macOS, so it is critical that this profile is deployed ahead of installing the Forwarder.

• On the left hand menu, select Library
• Select Add new in the top right hand corner
• Search for Privacy, select the Privacy profile option then Add & Configure
• Name the item Stairwell Forwarder Privacy
• Under Assignment, add this to your test group blueprint.
• Use the following values in the App Access pane
  • 🔘 Bundle ID
  • Identifier: com.stairwell.Inception.ProcessMonitor
  • For Code Requirement, copy the following string into the box:

anchor apple generic and identifier "com.stairwell.Inception.ProcessMonitor" and (certificate leaf[field.1.2.840.113635.100.6.1.9] /* exists */ or certificate 1[field.1.2.840.113635.100.6.2.6] /* exists */ and certificate leaf[field.1.2.840.113635.100.6.1.13] /* exists */ and certificate leaf[subject.OU] = "677UQVFGY8")

• Under App or Service use the following settings:
  • App or Service: SystemPolicyAllFiles
  • Access: Allow
• Select Save in the bottom right.

Installing the System Extension Profile

The system extension policy allows the Stairwell Forwarder system extension to load without user interaction.

• On the left hand menu, select Library

• Select Add new in the top right hand corner

• Search for System Extension, select the System Extension profile option then Add & Configure

• Name the item Stairwell Forwarder System Extension

• Under Assignment, add this to your test group blueprint.

• Use the following values for this profile:

  • General - ☑️ Allow users to approve system extensions (Unless your security policy dictates otherwise)
  • Under Team ID
    • Team Identifier - 677UQVFGY8
    • Name - Stairwell Forwarder
    • System Extensions - Allow specific system extensions
    • Click Add more
      • Allowed System Extension - com.stairwell.Inception.ProcessMonitor
      • Name - Stairwell Forwarder
    • The completed settings should look like the following:

• Select Save in the bottom right

Installing the System Extension Policy

If this policy is not pushed, it is impossible to silently remove the Stairwell Forwarder. It is highly suggested to push this profile so that silent remediations are possible.

• On the left hand menu, select Library
• Select Add new in the top right hand corner
• Select Custom Profile followed by Add & Configure
• Name the item Stairwell Forwarder System Extension Policy
• Under Assignment, add this to your test group blueprint.
• Download the example System Extension Policy from the Download Center.
• Drag and drop the file under the Profile box, where it says Drag file here or click to upload .mobileconfig file
• Click save in the bottom right corner

Installing the Stairwell Forwarder Profile

This profile contains the Environment ID for your Stairwell Environment as well as a registration token. Without these settings, the Forwarder will not register correctly.

• On the left hand menu, select Library
• Select Add new in the top right hand corner
• Select Custom Profile followed by Add & Configure
• Name the item Stairwell Forwarder Settings
• Under Assignment, add this to your test group blueprint.
• Download the example profile from the Download Center.
• Edit the example profile with your favorite text editor
• Replace YOUR_ENVID_HERE with your actual Env ID.
• Replace YOUR_REGISTRATION_TOKEN_HERE with your registration token.

❗️

If either of these values are incorrect, the Forwarder will fail to register. Double check these values before continuing.

• Save your changes to the profile
• Drag and drop your customized settings profile under the Profile box, where it says Drag file here or click to upload .mobileconfig file
• Click save in the bottom right corner

📘

Fleets where MAC addresses are not stable

By default a Mac identifies itself to Stairwell by computer name plus primary MAC address. If your machines change MAC -- or are imaged from a template that already had the forwarder installed -- add a STAIRWELL_REGISTRATION_KEY entry to this profile, set per machine to something stable and unique such as the hardware serial. It is read only at first registration, so it has to be right before the rollout. See Asset Identifiers.

Installing the Stairwell Forwarder

Once all the above profiles are pushed to the blueprint you are targeting, the last step is to install the Stairwell Forwarder itself.

• On the left hand menu, select Library

• Select Add new in the top right hand corner

• Select Custom Apps followed by Add & Configure

• Name the item Stairwell Forwarder Install

• Under Assignment, add this to your test group blueprint.

• Use the following values for this Custom App:

• Installation - Audit and enforce

• Use the following audit script:

  #!/bin/zsh
  
  # App install check
  APP_CHECK_ENABLED=true
  APP_NAME="Inception Forwarder"
  APP_PATH="/Applications/${APP_NAME}.app"
  APP_VERSION_CHECK_ENABLED=true
  APP_VERSION=851
  APP_VERSION_KEY="CFBundleVersion"
  # Profile install check
  PROFILE_CHECK_ENABLED=true
  PROFILE_NAME="Stairwell Forwarder System Extension"
  
  # non-zero exit code to install the software
  
  appVersionCheck() {
  	## App Version check
  	INSTALLED_APP_VERSION=$(defaults read "${APP_PATH}/Contents/Info" "${APP_VERSION_KEY}")
  	if (($INSTALLED_APP_VERSION >= $APP_VERSION)); then
  		echo "${APP_NAME} is up to date, exiting..."
  		exit 0
  	else
  		echo "${APP_NAME} is out of date, proceeding..."
  		exit 1
  	fi
  }
  
  ## Profile check
  # If a profile is required for the software to work properly, check for it before
  # proceeding
  if [ "$PROFILE_CHECK_ENABLED" = true ] ; then
  	/usr/bin/profiles -C -v | awk -F: '/attribute: name/{print $NF}' | grep -q "${PROFILE_NAME}"
  	# 1 if missing, 0 if present
  	profile_installed=$?
  	if [ $profile_installed -ne 0 ]; then
  		echo "${PROFILE_NAME} profile is missing, exiting..."
  		exit 0
  	else
  		echo "${PROFILE_NAME} profile is installed, proceeding..."
  	fi
  fi
  
  ## App check
  if [ "$APP_CHECK_ENABLED" = true ] ; then
  	# If the app exists in the path specified in APP_PATH, skip install
  	if [ -d $APP_PATH ]; then
  		if [ "$APP_VERSION_CHECK_ENABLED" = true ]; then
  			appVersionCheck
  		fi
  		echo "${APP_NAME}.app is installed, exiting..."
  		exit 0
  	else
  		echo "${APP_NAME}.app is missing, proceeding..."
  		exit 1
  	fi
  fi

❗️

Change APP_VERSION before you use this script

APP_VERSION is the build number of the package you are deploying -- the last component of the filename. InceptionForwarder-1.7.4.1493.pkg is build 1493. The sample above says 851, which is a 2022 build: leave it and the script decides every machine is already up to date, installs nothing, and reports success.

PROFILE_NAME must match the system extension profile exactly. Following this guide, that is Stairwell Forwarder System Extension.

• Skip all Self Service settings
• Under Install Details, use the following settings:
  • 🔘 Installer Package
  • Drag and drop the latest install package found on the Download Center
• No Preinstall or Postinstall scripts are required
• Click Save in the bottom right corner.

Once all of the above has been completed, the Forwarder will be deployed and working on the blueprint selected in the above steps.

Confirm Installation

• Navigate to app.stairwell.com and log in
• Click Assets
• Open the newly created asset to confirm files are arriving
• Check the count under All Objects

Ingestion takes a few minutes to become visible. An asset that appears and then stays at zero objects is almost always the Privacy profile: the forwarder is running and reporting in, but macOS is showing it only what any unprivileged process can see. That looks like a healthy deployment until someone asks why coverage is thin. See macOS Troubleshooting.

What should I read next?

• macOS Forwarder downloads, for the current package and its build number.
• Anti-Tamper on macOS, which is why the System Extension Policy profile is worth pushing.
• Install (Generic MDM), if some of your Macs are managed elsewhere.