What versions of macOS does Suspicious Package support?

Suspicious Package supports:

• macOS 14 (Sonoma)
• macOS 13 (Ventura)
• macOS 12 (Monterey)

If you're using an older version of macOS, you can download an old version of Suspicious Package as follows:

• For macOS 11 (Big Sur), use Version 4.3.3.
• For macOS 10.15 (Catalina), use Version 4.2.1.
• For macOS 10.14 (Mojave), use Version 4.0.
• For macOS 10.13 (High Sierra), use Version 3.5.3.
• For macOS 10.12 (Sierra) or OS X 10.11 (El Capitan), use Version 3.4.1.
• For OS X 10.10 (Yosemite) or OS X 10.9 (Mavericks), use Version 3.2.
• For OS X 10.8 (Mountain Lion), use Version 2.0.2.
• For OS X 10.7 (Lion) or OS X 10.6 (Snow Leopard), use Version 1.3.
• For OS X 10.5 (Leopard), use Version 1.2.

Note that prior to version 3, Suspicious Package was only a standalone Quick Look plug-in (there was no app).

We make these older versions available for those who need them, but we have not tested them since they were current, and can't make any claims about how well they might work.

Ensuring that Suspicious Package works properly on even a single version of macOS takes a great deal of work, especially for our one-person company. Since we are not willing to claim support for a macOS version that we have not tested, and since Apple releases a new macOS version every year, we must periodically drop support for older versions.

Why don't I get the Suspicious Package preview in Quick Look?

Generally, macOS automatically enables the Quick Look extension provided by Suspicious Package. However, if you're getting only the standard macOS Quick Look for an installer package, you may need to explicitly enable the extension.

Open System Settings and go to Privacy & Security > Others > Extensions > Quick Look. (On macOS 12 or earlier, open System Preferences and go to Extensions > Quick Look.) You should see a checkbox here for Suspicious Package; make sure that it is checked. (If you don't see the checkbox at all, make sure that you have already dragged Suspicious Package to your Applications folder and have opened it from there at least once: this gives macOS a chance to run Gatekeeper on the app before allowing the extensions that it provides.)

What happened to the file and script details in the Quick Look preview?

Until version 3.6, Suspicious Package provided a Quick Look generator plug-in, which is the API that macOS has used since Mac OS X 10.5 (Leopard). But in macOS 10.15 (Catalina), Apple introduced a new API for third-party Quick Look previews, known as Quick Look preview extensions, and have “deprecated” the old generator API.

We held out on adopting the new Quick Look API for a while, but even in Catalina, the old generator API was becoming less capable — for example, we lost the ability to link from the preview back to the app. So we finally decided to take the plunge, even though this meant essentially re-writing our Quick Look support. But we also decided to re-think what works well from Quick Look and what doesn't. (Our original Quick Look plug-in pre-dated the app by several years, but our Quick Look support today doesn't need to stand on its own.) In particular, any non-trivial interaction within the Quick Look UI has always been iffy, and has only gotten more so over the years.

Hence, we decided to simplify the Quick Look preview to be a variation on the app's Package Info tab, with links back into the app. This was still more work than we would've liked to re-invest in Quick Look support, but we hope that it provides some sort of utility.

Does Suspicious Package automatically check for updates?

Yes, once every 2 weeks — or less, if you use it less often — Suspicious Package will download a small file from our website to get the current version number. If a newer version is available, you'll see an Update Available button under the app's toolbar (on macOS 10.15 or earlier, it'll be on the right side of the title bar):

Click on Update Available to open the Suspicious Package download page, where you can get the latest version.

If you want to change the frequency with which Suspicious Package checks for updates, or turn off automatic checking entirely, use Suspicious Package > Preferences > Update:

Suspicious Package never automatically downloads or installs the actual updated app. You make the decision about when or if to download it, and where and how to install it.

Does Suspicious Package support languages other than English?

We speak only English, unfortunately, and our zero-revenue model makes it difficult to justify paying for a company to localize the app. Especially since Suspicious Package has a lot of complex strings to explain different parts of the package and identify potential issues in the review.

However, as of version 3.6, Suspicious Package is localized for French — thanks to the hard work of Olivier Prompt, who generously volunteered to translate the hundreds of strings required to make this a reality!

If you have any feedback on the localization — or if you are interested in discussing localization for another language — please contact us.

Why does Little Snitch tell me that com.mothersruin.XPCService.UpdateChecker.xpc wants to make a connection?

If you use Objective Development's Little Snitch, you may encounter a connection alert that tells you that “com.mothersruin.XPCService.UpdateChecker.xpc wants to connect to www.mothersruin.com.” This is triggered by Suspicious Package's automatic check for updates.

If you deny the connection, Suspicious Package won't be able to check for updates, and won't notify you when one is available. If you don't want it to attempt this connection in the first place, you can also turn off automatic checking using Suspicious Package > Preferences > Update.

Suspicious Package includes an Internet Access Policy, so that the purpose of this connection will be correctly explained in Little Snitch's Research Assistant view.

Will Suspicious Package protect my computer from malware?

No. The purpose of Suspicious Package is to provide visibility into macOS Installer packages, such that you can see what files they will install and what scripts they will run. You can certainly use those capabilities to evaluate the safety of a given package, but Suspicious Package can't make that determination for you.

Automatically defending your computer against malware is a huge problem that even Apple — with control of the OS, plus the resources of the most valuable company on the planet — struggles to solve. No independent developer is going to be able to solve that problem — especially not one that gives away their product for nothing!

But if Suspicious Package “didn't find any issues for review,” is the package safe to install?

No. Although the Suspicious Package app examines the package for a number of potential issues, it doesn't know how to determine if the package is truly safe to install. The review is intended only to highlight things that might be of interest in your determination of safety. Finding “no issues for review” only means that none of the things that Suspicious Package looks for are present — that doesn't mean that there aren't other issues.

There is, unfortunately, no substitute for the hard work of evaluating the contents and scripts in the package, and vetting the package signature. (If that could all be done algorithmically, Apple would presumably have macOS do it directly, and none of this would be necessary!)

Why can't I just use “Show Package Contents” from the Finder?

You can, but you'll get little to no information about what will be installed.

That's because Show Package Contents in the Finder's context menu actually refers to a different sort of package. macOS also uses the term “package” to refer to a folder that appears to be a file in the Finder. (A developer might call this a bundle, but a package is actually a more generic thing than a bundle, since a bundle implies a specific internal structure, such as an Info.plist file and a Resources directory.) The Finder's Show Package Contents command simply opens the folder in the Finder, instead of opening the application associated with the package.

A modern (“flat”) installer package is not a folder, so you won't even see this Finder command.

On an older (“bundle-style”) installer package, the Finder will offer to Show Package Contents, but that will only show the internal structure of the installer package, which isn't the same as seeing what the package will install. For example, you'll see an Archive.pax.gz file, but that would need to be further unpacked to get at the actual files that would be installed.

For bundle-style packages, Show Package Contents is occasionally useful for finding scripts and executables referenced by install scripts: see more details.

Why can't I just use “Show Files” from the macOS Installer?

Yes, you can open the package in the macOS Installer, and choose File > Show Files, which will show you the path of each file to be installed.

That's fine as far as it goes, but there is more involved in many installer packages — most significantly, installer scripts that might do anything — and Suspicious Package gives you visibility into all of it. Suspicious Package also provides more ways to examine the installed files, with Finder-like navigation, detailed metadata, sophisticated searching and filtering, tabbed browsing, and the ability to open or export individual files.

That said, if you opt to rely on the macOS Installer's “Show Files” feature, be aware that a package might run code as soon as it is opened by the Installer, via the system.run() capability or from an installer plug-in. The good news is that the macOS Installer prompts you before allowing this code to run; the bad news is that File > Show Files is not available until you've clicked through that prompt!

Is Suspicious Package “sandboxed”? Does it have entitlements?

No, the current version of the Suspicious Package app does not opt into the macOS App Sandbox mechanism.

We've attempted to sandbox Suspicious Package in the past, but there are restrictions that would reduce the usability of the app — including features in the Welcome to Suspicious Package window, and support for packages that reference external component packages. We might someday overcome these sandboxing obstacles, but it isn't at the top of our priority list, and we aren't eager to remove capabilities from the app to make it possible.

That said, the app does have some explicit entitlements (as required by the macOS hardened runtime mechanism), and there are a couple of components inside Suspicious Package that are sandboxed. The entitlements for all of these can be seen using an app like our own Apparency, and are described further below.

The top-level Suspicious Package app has the following entitlements:

The SuspiciousPackagePreviewExtension.appex component provides the Quick Look Preview to the Finder and has the following entitlements:

Also, under the MRSFoundation.framework component, you'll find a com.mothersruin.MRSFoundation.UpdateCheckingService.xpc XPC service. This is the component that performs the periodic check for updates, and is entitled as follows:

Why isn't Suspicious Package distributed through the Mac App Store?

The primary reason is that it isn't sandboxed, which is a requirement for the App Store.

A secondary reason is that we highly suspect that Apple's App Review would — sooner or later — declare that our tongue-in-cheek app name was a problem, and we're not interested in changing that now.

Unfortunately, the value added by the App Store, especially for a free app, is too small to be worth the cost to us.

Why isn't Suspicious Package open-source?

Frankly, because we are obsessive software engineers who like our code to be as polished as our products, and we are not eager to give up that level of control.

We appreciate that, when you work with other people in a real company, working as a team is what you get paid for. But when you develop and publish software for free, you require some other reward, and for us, that's a measure of control.

How does Suspicious Package decide what packages to show in the welcome window?

The “Welcome to Suspicious Package” window attempts to show the macOS installer packages that you are likely to be interested in inspecting. It does this by asking Spotlight to find the installer packages under your home folder, preferring those inside Downloads and Desktop, as well as the ones that were more recently downloaded.

In addition, since installer packages are commonly delivered inside disk image (.dmg) files, Suspicious Package also looks for packages inside any opened disk images. It examines only the top level of any mounted disk image, and prefers disk images that were more recently opened. Note that it won't show packages inside of disk images that aren't open: you need to open them from the Finder (as described below).

Note that the welcome window is not a “recents” list. If you want to choose from the packages that were recently opened in Suspicious Package, use any of the standard macOS mechanisms, such as File > Open Recent, or the menu from the Dock icon.

If you find the welcome window annoying, uncheck “Show this window when Suspicious Package opens” and it won't be shown automatically in the future. You can always use Help > Welcome to Suspicious Package... to summon it manually.

Why doesn't the package I just downloaded show up in the welcome window?

Since macOS 10.15 (Catalina), an app can't access your Downloads, Desktop or Documents folder until you give it explicit permission to do so.

However, when Suspicious Package asks Spotlight to find the packages it should show in the “ Welcome to Suspicious Package” window, macOS doesn't even ask for permission. Instead, it simply doesn't tell Suspicious Package about packages that might exist in those protected folders. The welcome window warns that “some installer packages may be missing, due to macOS Folder Privacy Settings.” If you click Fix, Suspicious Package will let you choose which of these folders you would like to search, and will nudge macOS to ask for permission. If you don't want Suspicious Package to have access to any of these folders, you can click Ignore to get rid of the warning.

You can always get back to this dialog by choosing Suspicious Package > Review macOS Folder Privacy.... However, once you've explicitly denied access to Suspicious Package, the app can't resolve the problem, even by asking again. You must open System Settings, go to Privacy & Security > Privacy > Files and Folders, and change the per-folder switches for Suspicious Package. (On macOS 12 or earlier, open System Preferences and go to Security & Privacy > Privacy > Files and Folders.)

After allowing access to Suspicious Package, you might need to quit and re-open the app to see the welcome window change. Or, you might not. Apple has documented about 10% of these access control mechanisms; we don't even know how they intended this to work. So we've given up: if it does something sensible for you, that's great. If not, there's nothing that we can suggest, and we quite frankly no longer care. ¯\_(ツ)_/¯

Why won't Suspicious Package open this disk image (dmg) file?

Suspicious Package is specifically designed to open installer packages. An installer package usually has an “open box” icon that looks like the one at right, and will normally open in the standard macOS Installer application. (If you look at the extension of an installer package, it will be either be .pkg or .mpkg.)

Although a disk image (.dmg) file might contain an installer package inside it, you still must open the disk image first, i.e. by double-clicking it in the Finder. Then, you can ask Suspicious Package to open the installer package inside — if the welcome window is showing, any package inside the just-opened disk image will appear there automatically.

In any case, Suspicious Package does not know anything about disk images, and so can't open them directly.

Note that there are many ways to distribute macOS software. Disk images are common downloads, but they do not always contain installer packages. If you open a disk image and don't see a package, or if Suspicious Package won't open whatever is inside, it is almost certainly not an installer package. It might be the actual app of interest, or it might be some custom app that performs an install. Either way, Suspicious Package can't provide any information on what the contained software might do.

Why does Suspicious Package ask to access my Downloads, Desktop or Documents folders?

Since macOS 10.15 (Catalina), an app can't access your Downloads, Desktop or Documents folder until you give it explicit permission to do so.

Generally, Suspicious Package reads only those macOS Installer packages (or installer receipts) that you directly ask it to open. But there are a couple of reasons that it might also ask for general access to these protected folders. One is for the “Welcome to Suspicious Package” window, as described above.

Additionally, for the File > Export Item to Default Folder (Cmd-Option-E) command, Suspicious Package has a default export location. The first time that you use this command, macOS may ask for permission to access that folder. (Or, it might not: if you used Suspicious Package > Preferences to choose a different default export folder, the macOS standard open dialog interprets selection of a folder there as indicating “user intent” to grant the app access to that item.)

Suspicious Package should behave properly if you tell macOS to Allow this access. If you choose Don't Allow instead, the export may not work properly, but the other functionality of Suspicious Package should be unaffected.

Note that macOS will only ask once for a given folder and app. If you want to change these permissions at a later time, you must open System Settings, and go to Privacy & Security > Privacy > Files and Folders (or on macOS 12 or earlier, open System Preferences, and go to Security & Privacy > Privacy > Files and Folders). There should be a group of switches for every app, where you can enable or disable access for the folders that macOS considers to be privacy-sensitive. (If a folder isn't listed here, it is either not one that is specially protected by macOS, or not one that the app has previously requested to access.)

Why does macOS tell me that Suspicious Package “was prevented from modifying apps on your Mac”?

On macOS 14 (Sonoma) or macOS 13 (Ventura), you might be presented with this surprising notification:

Suspicious Package does not modify apps on your Mac. But the Suspicious Package Export Item command, combined with a somewhat dubious interpretation of modifying an app, can trigger this notification.

Whenever you export an item from a package, Suspicious Package registers itself with macOS as a “presenter” of the exported item. This is done to keep the exports list up-to-date, showing the correct information even if you move or rename an item, and ensuring that the Show in Finder button can still find the item in order to reveal it. When you close the window for that installer package, Suspicious Package stops monitoring all of the items that were exported from the package.

On macOS 13 (Ventura) or later, before notifying Suspicious Package that an item has been moved, macOS tries to extend permissions to the item in its new location — which might be somewhere that the app would not otherwise be able to access, such as your Desktop. When extending these new permissions, macOS requests read/write access, only because Suspicious Package had the ability to modify the item in its old location (we have no control over this choice of permissions).

This usually works fine, but if the item being moved is a notarized app, the TCC mechanism requires that the process being granted the new permissions — Suspicious Package, in this example — be enabled for App Management (which is managed in System Settings at Privacy & Security > App Management). Since Suspicious Package has no reason to have App Management, it likely does not, and thus TCC denies the request and posts the above notification.

Despite the wording of the notification, Suspicious Package wasn't actually prevented from doing anything, because it never wanted to modify the app. You can simply dismiss the notification, which should not appear again. There is no reason to give Suspicious Package the App Management ability; it doesn't need it.

Note that “moving” an app includes moving it to the trash. So you might see this notification as a result of disposing of the item exported by Suspicious Package.

Since we debugged it, here is the more detailed version of what is happening here:

Suspicious Package registers with Foundation as an NSFilePresenter. Before sending us -presentedItemDidMoveToURL:, Foundation tries to make a new security-scoped URL for the item in its new location. This eventually asks the Sandbox subsystem to issue an extension for the new path, with the right com.apple.app-sandbox.read-write — chosen simply because access( old_path, O_RDWR ) returned zero. Before issuing the extension, Sandbox consults the TCC subsystem. Since the path is a signed-and-notarized app, TCC checks to see if the recipient of the sandbox extension (Suspicious Package) is allowed for either kTCCServiceSystemPolicyAllFiles (Full Disk Access) or kTCCServiceSystemPolicyAppBundles (App Management). Since Suspicious Package has neither, TCC denies the request, and the notification is displayed.

Why does macOS tell me that Suspicious Package wants to “access data from other apps”?

On macOS 14 (Sonoma), you might be presented with this surprising dialog, especially when using Quick Look to preview a macOS Full Installer package:

Suspicious Package does not access data from other apps. But this can be triggered by a strange interaction between the app's Welcome to Suspicious Package window, the sandbox environment that the Quick Look Preview extension runs inside, and the way that macOS Full Installer packages are analyzed.

As explained above, Suspicious Package looks for packages inside open disk images to show in its Welcome window, since these are likely candidates for inspection. To do this, Suspicious Package monitors for the mounting (and unmounting) of disk images. When a new disk image is mounted, Suspicious Package looks at the top level of the new volume for any installer packages.

Meanwhile, the way that a macOS Full Installer package is constructed, getting the version info requires that Suspicious Package temporarily attach the embedded disk image to read the files inside. To do this cleanly, Suspicious Package uses the macOS-provided temporary folder for the mount point (and avoids showing the volume in the Finder).

This same process is used to generate a Quick Look preview for a macOS Full Installer package, except that this is done from the Suspicious Package Quick Look Preview extension, which is sandboxed per macOS rules.

Starting in macOS 14 (Sonoma), Apple has changed the location of the standard temporary folder for sandboxed components. Instead of being underneath the per-user DARWIN_USER_TEMP_DIR directory, it is placed inside the component's sandbox container, at Library/Containers/bundle-identifier/Data/tmp. The sandbox container is the very definition of “app-specific data.”

So, if the Suspicious Package app is open and showing its Welcome window, and you go to the Finder, and preview a macOS Full Installer package, our Quick Look Preview extension mounts the embedded disk image under its sandbox container. The app sees this disk image mount, and tries to find any installer packages in that newly mounted volume. To macOS, this constitutes the Suspicious Package app trying to access data from another app, and it presents the above dialog.

Even if the app was stopped from reading the mounted disk image, it wouldn't've found any installer packages there, so it doesn't really matter if you click Allow or Don't Allow here.

We will attempt to inhibit this annoying behavior in a future version of Suspicious Package. We haven't (yet) investigated why macOS even flags this case, since the app and the Quick Look Preview extension ought to be seen as coming from the same development team and thus be allowed to share this level of data.

What happened to Open With > Suspicious Package in the Finder?

If you're working in the Finder, you should be able to control-click on a macOS Installer package and choose Open With > Suspicious Package. Unfortunately, after the macOS 13.3 update, Finder no longer offers any choice other than the macOS Installer itself. Also, if you use File > Get Info, the Open with pop-up is completely disabled.

It turns out that this was an intentional security change. Apple's About the security content of macOS Ventura 13.3 document described this rather obliquely as:

“LaunchServices

Available for: macOS Ventura

Impact: An app may be able to gain root privileges

Description: This issue was addressed with improved checks.

CVE-2023-23525: Mickey Jin (@patch1t)”

However, the reporter of CVE-2023-23525, Mickey Jin, has since published a writeup of the exploit, which led Apple to lock down the Open With menu. Why Apple chose to address the default application vulnerability by also restricting the Open With menu choices is not clear. (Allowing the user to explicitly choose to open a specific package in something other than the macOS Installer seems safe to us. Perhaps this has to do with the Option-key triggered “Always Open with” shortcut for changing the default application: of course, that would still be a user action, but they seem to have chosen the hammer of disallowing changes to the default binding via any mechanism.)

In any case, to compensate for this, starting in version 4.3.2, Suspicious Package adds an Open With Suspicious Package service. When a package is selected, this service will be available from the Finder > Services menu.

Likewise, when you control-click a package, this service will appear near the bottom of the Finder's context menu. Here, it might be grouped under a Services item, depending on how many other services are applicable at the time.

If you have a package selected, but don't see the Open With Suspicious Package item in the Finder > Services menu or in the Finder's context menu, the service might need to be enabled. Choose Finder > Services > Services Settings, go to the Development group, and make sure that Open With Suspicious Package is checked.

At some point after this Ventura update, the same change was apparently rolled into both Monterey and Big Sur security updates. We're guessing this change was part of macOS 12.6.6 and macOS 11.7.7, since LaunchServices was changed in those updates — but the above CVE isn't mentioned in the release notes, and we didn't notice this when it happened.

In any case, the Open With Suspicious Package service can also be used on Monterey or Big Sur, as described above.

Since we took the time to reverse-engineer the change before the CVE details were known, we'll keep them here for posterity.

macOS 13.3 introduces a new LaunchServices key in the CFBundleDocumentTypes dictionary, named LSIsAppleDefaultNoOverrideForType. This new key is applied in only one place that we could find: /System/Library/CoreServices/CoreTypes.bundle/Contents/Resources/Exceptions.plist adds it to all three package document types declared by Installer.app. (This can also be seen in an lsregister dump of the LaunchServices database, as an apple-default-no-override flag on the “claim” that the Installer makes on its document types.) This new key changes how LaunchServices constructs the Open With menu for the Finder, as well as disabling the Open With controls in the Finder's Get Info window.

How do I open macOS Installer packages with Suspicious Package by default?

With the changes in macOS 13.3, macOS 12.6.6 and macOS 11.7.7, it is no longer possible to choose a different default app for macOS Installer packages.

If you use Suspicious Package on every package before opening it in the macOS Installer, you might find it convenient to make Suspicious Package the default application for packages. This can be done in the Finder, by choosing File > Get Info on any installer package, choosing Suspicious Package from the Open With popup, and then choosing Change All.

Once you do this, double-clicking any installer package will open that package in Suspicious Package. Once you decide you want to install it, you can use Suspicious Package's Open In Installer toolbar button (or Command-Shift-I) to proceed to the installer.

If you've downloaded a package, macOS will run Gatekeeper on that package when you first open it, no matter which app you are using to open it. So, if you switch the default app to be Suspicious Package, you'll get any Gatekeeper dialogs before it opens there. Of course, Suspicious Package isn't going to install the package — or run any of its install scripts — no matter what. But Gatekeeper doesn't know that.

Why did Suspicious Package change the icon for macOS Installer packages?

If you change the default app for opening macOS Installer packages, as described above, you'll notice that macOS (eventually) shows a different icon for these packages. The behavior of macOS here has changed repeatedly in just the last few years, so what you see will depend on the macOS version.

In macOS 12 (Monterey), you should see the alternate “document” icon we provide for installer packages. We chose an icon that is somewhat different from the standard one (at larger sizes), so that you can see at a glance that the default application has been changed.

In macOS 11 (Big Sur), you'll probably see a generic (blank) document icon. We attempted to make this better, either showing some version of a standard package icon or at least a document icon tied to Suspicious Package, without any luck. (Big Sur introduced a couple of new methods for defining document icons, but we couldn't get either of them to work here. We suspect this has to do with the way that macOS defines the types for installer packages — partly in the system-wide CoreTypes bundle, and partly in the macOS Installer.app bundle — but we couldn't find a way to override this to produce a better experience.)

If this icon mess makes you crazy and you just want to go back to the default state, start by re-assigning the default app for installer packages to be the macOS Installer application, using the same process described above. On macOS 11 (Big Sur) or later, that ought to be enough — although you may need to restart your Mac, and then start clicking on some package items, in order to convince the Finder to start showing the right icons again.

What is a “receipt” and what will I find if I open it?

Each time that the macOS Installer installs a package, it creates a “receipt” that contains some information about what was installed. Most significantly, the receipt includes the file listing from the package, which is the primary source of information for Suspicious Package's All Files tab. (The receipt does not contain the scripts from the package, nor the actual installed files, of course.)

Suspicious Package can open and inspect a receipt, in much the same way as a package. Because a receipt contains less information than the package it came from, you're always better off examining the original package, but sometimes you might only have the receipt available. But the first challenge is to find the receipt.

The macOS Installer creates receipts in the (normally hidden) /var/db/receipts folder. To open this folder, you can use Go > Go to Folder (Shift-Command-G) from the Finder. Apps that you install (or update) from the App Store will also have receipts created in this folder. Note that receipt names are generally in “reverse DNS” form, so you might need to use the Finder's File > Find (Command-F) feature to find the receipt you want within this folder.

Updates to macOS itself (installed from the Updates page of the App Store) also create receipts, but in a different folder: these go into /System/Library/Receipts, which is at least not hidden.

Either way, a receipt has a .bom extension, and a Kind description of “Installer receipt.” You can open this file with Suspicious Package in the same way that you would open a package, such as by dragging it to the app icon, or control-clicking in the Finder and choosing Open With > Suspicious Package.

You will usually find a second file with the same name as the receipt, but with a .plist extension instead of .bom. This property list file carries some additional information about the installation (such as the date), and Suspicious Package will automatically read and show this information. However, Suspicious Package will recognize only the .bom file as the receipt, so don't try to open the .plist file in Suspicious Package (it won't work).

Can I change how Suspicious Package creates temporary files?

To analyze a package or perform other operations (like exporting installed files), Suspicious Package must create temporary files. We strive to minimize this, but the format of packages — and the general absence of APIs for dealing with them — makes a certain number of temporary files unavoidable.

Generally, Suspicious Package puts all of its temporary files under the macOS-provided per-user temporary folder. Underneath this folder, for each package that you open, Suspicious Package creates a sub-folder — named something like Files from SomeApp.pkg - g8fv — and puts all temporary files related to that package under that sub-folder. When you close a package, Suspicious Package deletes the corresponding sub-folder; when you quit Suspicious Package, it deletes the sub-folders for all open packages (which is why you might notice the app taking a bit of time to quit, especially if there are many or large packages open).

The macOS-provided per-user temporary folder is an ugly-looking path, starting with /var/folders. Suspicious Package retrieves this path using a Cocoa API, but you can determine the same path using this Terminal command:

/usr/bin/getconf DARWIN_USER_TEMP_DIR

One reason that we use the standard per-user temporary folder is that macOS periodically cleans up these locations in the background — when you restart your computer, as well as at other times. (This is controlled via the launchd job defined at /System/Library/LaunchDaemons/com.apple.bsd.dirhelper.plist.) Suspicious Package aims to clean up its temporary files more promptly, instead of waiting for macOS to do it, but this is a useful backstop in case something goes wrong.

You can't change Suspicious Package's requirement to create these temporary files, but if you want, you can change where it does so. For example, if you want temporary files to be written to another disk, quit Suspicious Package and use a Terminal command like this:

defaults write com.mothersruin.SuspiciousPackageApp MRSAlternateTemporaryDirectory /Volumes/Other/TemporaryItems

When you re-open Suspicious Package, it will use /Volumes/Other/TemporaryItems instead of the macOS per-user temporary folder. But there are several things to be aware of here:

• The specified directory path must already exist and be readable and writable to Suspicious Package as the current user, or no package will open successfully.
• The specified directory path need not be at the top-level of a disk; it can be anywhere you want, as long as it has the right ownership and permissions for the current user (or is on a volume for which owners are disabled). You can, if you like, use a dot-prefixed name — or add the hidden flag using chflags(1) — to hide the folder from the Finder.
• The specified directory path should probably be on a disk that is locally-attached and is formatted as case-insensitive APFS. Something else might work, but we haven't tested it.
• If the specified directory path is on a removable disk, macOS may display a prompt that “Suspicious Package” would like to access files on a removable volume. You must allow this access, in accordance with the standard macOS privacy rules.
• If the specified directory path is on a removable disk, that disk must remain mounted while Suspicious Package is open. If you eject the disk while packages are open in Suspicious Package, the app is unlikely to behave well.
• Suspicious Package will create a sub-folder for each package under the specified directory path, regardless of whether the opened package is itself on that disk or not. In other words, the choice of temporary folder is independent of where the package itself resides (or where an item exported from the package is to be saved).
• Suspicious Package will delete the per-package sub-folder when the package is closed, or when the app is quit. But since macOS won't do any automatic cleanup — as it does with the standard per-user temporary folder — you may get orphaned temporary files if Suspicious Package is Force Quit or otherwise improperly terminates.

All of this is why we don't provide a nicer UI than setting a preference via the Terminal. If you don't know why you'd want to change the temporary folder, you probably shouldn't!

To undo this and return to using the standard macOS per-user temporary folder, quit Suspicious Package and delete the preference, e.g.

defaults delete com.mothersruin.SuspiciousPackageApp MRSAlternateTemporaryDirectory

What do the different “package formats” indicate?

On the Package Info tab, directly under the package name, Suspicious Package summarizes the package, as something like Developer ID Software • Distribution Archive.

The first part describes where the package came from. This is derived from the package signature, and gives you a quick way to see if the package contains Apple software, came from the App Store, or from a third-party developer.

The second part is the “package format,” which describes how the package was built. Although every installer package looks the same — and usually even has the same .pkg extension — there are actually many different package formats supported by macOS. If you simply double-click the package to open it in the macOS Installer, the format is probably uninteresting. But if you are an administrator using any sort of automated deployment mechanism, you may need this detail, since different deployment schemes have different requirements.

We are not Mac admins ourselves, so are being purposely vague about the specifics of deployment. For a good introduction to the different package formats and the implications for deployment, check out Armin Briegel's talk The Encylopaedia of Packages from MacDevOpsYVR 2021.

Unfortunately, there isn't much standardization on what to call the different package formats — Apple presents them all as simply “installer packages” and doesn't offer any distinction. So we've tried to name them based on available clues, some community practice, and our own personal experience working on the things. So that you know what we mean by something like Distribution Archive, the table below gives more background on each of the possible formats:

What is a “component package”?

Installer packages are often constructed of multiple sub-packages: these are called component packages by the macOS Installer, and by Suspicious Package.

This separation of content into component packages is generally not very interesting — unless you are the person developing the package — so Suspicious Package mostly tries to hide it. For example, the All Files tab always shows everything that would be installed by all of the component packages. However, it is sometimes difficult to ignore the existence of component packages — such as with scripts and receipts.

Also note that when you install the top-level package, all of the component packages might not be installed. The package's Distribution file might allow specific component packages to be turned on or off through the macOS Installer's Customize dialog. Or the distribution might automatically turn component packages on or off, based on the version of macOS, the other software you have installed, or even the hardware capabilities of your Mac.

You can get more information about which files are installed by which component package by turning on additional component package info. You can also use the rule-based search feature on the All Files tab to filter files by their component package.

What is a macOS Full Installer?

Since Mac OS X 10.7 (Lion), an upgrade to a new major version of macOS has started with an app named “Install macOS” or the like. This app starts the upgrade process, and contains all of the resources needed to install the new version of macOS — which is why the app is so large.

Typically, the “Install macOS” app itself gets installed through the Software Update preference pane, or in olden times, through the App Store. As with other Software Updates, a package is used to deliver the “Install macOS” app, even if the user doesn't normally see this package. However, Apple has started to offer these macOS full installer packages in other ways — especially for older versions of macOS — including the ‑‑fetch‑full‑installer option on softwareupdate(8), as well as by direct download.

For a more thorough review of all of the many ways to get macOS full installers, see this Mr. Macintosh article.

If you need to keep these packages around, it can be difficult to determine which versions of macOS they contain (unless you are fanatical about renaming them after downloading). To make this easier, when you open a macOS full installer package in Suspicious Package, you'll see extra information on the Package Info tab, e.g.:

This indicates that the package would install an “Install macOS” app that would, in turn, install the indicated version and build of macOS itself. This also shows how much space in the package is occupied by the macOS resources — these aren't included in the size of the package payload, and won't appear on the All Files tab. You can click on this line in the Package Info to get more details.

Suspicious Package understands macOS full installers going all the way back to Lion. But note that macOS 10.13 (High Sierra), 10.14 (Mojave) and 10.15 (Catalina) did not use self-contained full installer packages (the “Install macOS” app was assembled by Software Update out of multiple packages and other downloads). Starting in macOS 11 (Big Sur), however, the full installer is once again delivered as a self-contained package.

Suspicious Package also shows the full installer information in its Quick Look preview, making it easy to see what's inside such packages, directly from the Finder.

What is an “embedded disk image”?

As you might gather from the discussion above, the macOS full installer package is a bit of a weird beast. You'll no doubt notice that a multi-gigabyte package is described as installing an app that occupies less than 50MB on disk. This is accurate, but not the whole story.

Inside the “Install macOS” app, the resources needed to install macOS are wrapped in a disk image. Since macOS 11 (Big Sur), this lives at Contents/SharedSupport/SharedSupport.dmg (previously, it was called InstallESD.dmg but served essentially the same purpose). This massive file is not part of the normal package payload, and you won't see it on the All Files tab of Suspicious Package. There is a special optimization that Apple uses here, to avoid the huge time and disk space costs of unarchiving a 12 GB disk image from the package payload.

Essentially, the SharedSupport.dmg file is embedded inside the macOS full installer package in a way that allows the disk image to be mounted directly, without having to unarchive it. In fact, if you changed the extension from .pkg to .dmg, you could double-click it and see the disk image contents. (Be careful, though, because macOS will want to verify the disk image, and this will take a long time.)

So what is this black magic? Strictly for the curious, we'll expound a bit. The embedded disk image is stored as an additional member of the package's xar archive. Then, some additional data is glued onto the end of the xar file to tell macOS how to find the enclosed disk image.

This is possible only because the macOS disk image format uses a trailer structure — i.e. a block of data always at the very end of the file — to record where in the file the disk image data is found. In contrast, the xar archive format uses a header structure — i.e. a block of data always at the very start of the file. This allows the two structures to coexist: xar sees a xar archive, and the DiskImages framework sees a disk image!

When you install one of these macOS full installer packages, a postinstall script saves the original package as Contents/SharedSupport/SharedSupport.dmg (using a hard-link, so no data is actually copied). This allows the “Install macOS” app to find the required macOS resources, even if the package used to install the app has since been moved.

In Suspicious Package, if you want to see what is inside that embedded disk image — without changing the extension or waiting for it to verify — you can click on the macOS full installer summary line on the Package Info tab, and then click the Mount Disk Image button. The disk image will open in the Finder.

Note that this duality goes both ways: if you use Show Package Contents on the “Install macOS” app from the Finder, you can find the SharedSupport.dmg file. If you changed the extension to .pkg, you could double-click it to open the macOS Installer, and it would install the “Install macOS” app.

Suspicious Package also lets you open this special disk image directly, without changing the extension to .pkg. The trick is to drag the file from the Finder and drop it onto the Suspicious Package icon (e.g. in the Dock), while holding down both the Command and Option keys. This key combination forces macOS to ask Suspicious Package to open this file, even though it doesn't generally support opening disk images. As long as it is one of these special disk images, it will open normally. (If you get a dialog saying that “Suspicious Package cannot open files in the ‘Disk Image’ format,” that means that Suspicious Package examined the actual file and found that it isn't really any sort of package.) You can also drop the disk image onto Suspicious Package's welcome window (no modifier keys required), or use the “spkg” command line tool to open it from the Terminal.

Note that this is the only exception to the Suspicious Package can't open disk images rule.

What is the difference between a “flat” and “bundle-style” package? What is a xar archive?

In the beginning, a macOS installer package was a bundle — a directory containing specific files for the various pieces of the package. For example, there would be an Info.plist with the package metadata, an Archive.bom with the file listing and an Archive.pax.gz with the actual payload. (This style of package dates back, in one form or another, all the way to NeXTSTEP days.) Because a bundle-style package is a directory, it must be put into some other container — like a disk image — to be easily downloadable. There is no provision for signing a bundle-style package, so the origin and integrity can't be verified.

In Mac OS X 10.5 (Leopard), Apple introduced a new style of macOS installer package, often referred to as “flat packages.” This style of package is a file, rather than a directory, and can be easily downloaded, even if not wrapped in a disk image. The pieces of the package — including the metadata, the file listing, the payload archive, and the scripts — are archived using the xar archive format.

The xar archive format was developed at Apple, and originally open-sourced as part of the OpenDarwin project. Xar was designed to be a generalized archive format, but for macOS installer packages, probably its most important feature is the ability to sign the archive. The xar signature is what allows macOS (and Suspicious Package) to evaluate the trustworthiness of a package, and to verify that the contents have not been tampered with since being signed.

The subsequent security features and requirements of macOS installer packages are built upon the signing and verification aspects of xar-format flat packages. These include Gatekeeper's Developer ID requirements [added in Mac OS X 10.7 (Lion)] and notarization requirements [added in macOS 10.14 (Mojave)].

The macOS Installer still supports installing bundle-style packages, but because they can't be vetted through Gatekeeper, you probably won't encounter them often. However, the relative simplicity of their construction apparently makes them irresistible to some vendors.

For many years, the canonical open-source repository for the xar archive project was at Google Code. With the demise of Google Code, the closest thing to a canonical replacement — at least as far as Apple platforms are concerned — is the Apple project on GitHub, but that gives you only source code, without any documentation or community. There are many forks on GitHub, but we don't know if Apple pushes their changes to any of them (we rather doubt it).

As of the macOS 12 (Monterey) SDK, Apple have declared that “xar is a deprecated file format and should not be used.” What this foretells is anyone's guess. Although we suspect Apple would like to deprecate macOS Installer packages altogether — especially now that macOS itself is not installed or updated using packages — this is probably a long and complicated road that starts elsewhere. Perhaps more likely is that Apple doesn't want anyone relying on the system-provided version of xar for new file formats, because they don't want to be asked to fix anything that isn't strictly required for installer packages? ¯\_(ツ)_/¯

What is the significance of the date and time that a package was signed?

All certificates — including Apple-issued Developer ID certificates — expire after some amount of time. (This is a security precaution, since the underlying technology and the attacks against it are always moving forward.) In the ideal case, developers replace certificates before they expire, and a package you download today will be signed with a still-valid certificate. But in the real world, developers don't always get ahead of expiring certificates; and on occasion, you might keep an older package and want to use it after the certificate has already expired.

However, an expired certificate does not necessarily make the package signature invalid. When a package is signed on macOS, the current date and time can be incorporated into the signature in a way that is independently verified by Apple. That is, instead of the package just claiming to have been signed at a specific date and time, the actual signing time is securely supplied by Apple, and bound to the package signature cryptographically. (This is known as a “trusted timestamp,” with an Apple server as the “Time Stamping Authority.”) This typically happens automatically when the developer signs the package, but it might have been disabled (see the productsign(1) man page, and the ‑‑timestamp option).

When you go to install the package — or merely examine it in Suspicious Package — macOS evaluates the validity of the signature. If it finds a verified signing time (and confirms that it is trustworthy), macOS will evaluate the signing certificate as of that date and time. If the certificate is expired now, but was not expired (and was otherwise valid) at the time the package was signed, macOS might declare that the signature is still valid. (There are exceptions; for example, a certificate might have been explicitly revoked, and might not be considered valid for any signature on any date.)

Suspicious Package uses the standard macOS mechanism for validating the package signature, so it will apply these same rules with respect to the verified signing time.

Unfortunately, the way that this is presented in the standard macOS certificate trust sheet is less than clear: if you examine the certificate details, you'll see that the certificate has expired, but macOS still says “this certificate is valid.” Of course, the certificate itself is no longer valid, but since it was valid at the verified signing time, the signature is nevertheless valid. However, macOS doesn't show the verified signing time anywhere, nor even note its existence. (As of macOS 10.15.4, the standard pkgutil(1) command will provide this information, but the standard certificate trust sheet is as confusing as ever.)

Suspicious Package attempts to improve matters by explicitly noting when a verified signing time is found in the package signature. If you choose Window > Signature Details (Command-5), and if the package signature includes a verified signing time, it will be shown in the sheet:

If you click Show Certificate, you may still see the certificate-is-expired-but-valid confusion described above — since Suspicious Package uses the standard macOS certificate trust sheet, and can't change this bit — but at least this gives some context to the confusion.

What are “merged entitlements” and what do they have to do with PPPC Profiles?

Suspicious Package allows you to select an app or other executable item on the All Files tab, and show the entitlements that it requests. However, since the package might install any number of executable items, Suspicious Package also provides a way to see a high-level view of all entitlements requested by all executables. For example, this can be useful when you are creating a Privacy Preferences Policy Control (PPPC) Profile, because it tells you (indirectly) what capabilities the software will request, and how you want macOS to prompt (or not) the end users.

If this sounds a bit hand-wavy, that's because we are not Mac admins, and have never built a PPPC Profile ourselves. We hope that this feature is useful, but if you have any feedback or suggestions in this area, please do contact us.

To get this merged view of entitlements, click on the summary from the Package Info tab: or choose File > Show Entitlements for All Executables (Cmd-Control-A).

In this view, Suspicious Package shows every entitlement key that is requested by at least one executable. In some cases, the keys might be all that you need, in order to see what the software wants to do. But if you need more information, Suspicious Package also merges together all of the distinct values for a given key. If all executables use the same value (such as a Boolean YES), that will also be the merged value. But if different executables use different values (such as string identifiers), Suspicious Package will combine these into an array (or if it's already an array, it will combine the distinct values).

The icon in the rightmost column tells you how Suspicious Package created the merged value: either the same value was found for all executables, or multiple values were merged together. If you move the pointer over the icon, a tooltip will show how many executables requested this particular entitlement.

If you're creating a PPPC Profile, you may want to allow a specific “service” for all of the executables that request a related entitlement. For example, perhaps you want to allow the AddressBook service for executables that request com.apple.security.personal-information.addressbook. If you select that entitlement, and choose Copy App Identities for PPPC Profile, Suspicious Package will construct the array-of-dictionaries structure that a PPPC Profile uses to establish app identities and put this on the clipboard. Then you can go to your property list editor and paste directly under the Services dictionary.

Suspicious Package doesn't understand the mapping between entitlements and PPPC services, so you will still need to infer that part. The intent here is only to reduce the tedium of gathering identifiers and code signing identities (requirements) from multiple apps and executables.

How can I tell which files a “Custom Install” will install?

As noted above, the macOS Installer's Customize dialog may allow specific component packages to be turned on or off. Unfortunately, Suspicious Package doesn't have the smarts to figure out which component packages will actually be installed, and merely assumes that they all would be. For the purpose of evaluating what a package might do to your system, this is usually enough.

If you want more information about what files are installed by which component package, you can turn on Component package and bundle info (as described here). You can also use the rule-based search feature on the All Files tab to filter files by their component package.

If you need to examine component packages in more detail than that, Suspicious Package is probably not the best tool to use.

Why does Suspicious Package show the wrong icon for this file or application?

Suspicious Package actually has no idea what icon an item will have after being installed. (It would have to essentially do the install in order to determine this reliably.) Instead, Suspicious Package shows a generic icon, determined from metadata about the item, such as its name, extension, location and permissions. This is why you'll see only generic application icons, for example. These icons are intended only to give you helpful visual clues as you scan the file view.

How can I find installed files with dubious permissions?

Among the things you might want to examine in a package are the permissions — ownership and modes — of the installed files and folders. For example, you might want to look for the creation of files or folders that are outside the user's home folder but are writable to all. Or you might want to find executables which use the “Set User ID” or “Set Group ID” features to escalate privileges. (These things can be used for legitimate, non-malicious reasons, but they can also have security implications.)

Suspicious Package automatically flags some of these things in its Review, but often, interpretation is required. Another approach is to use the rule-based search feature on the All Files tab.

To enter the rule-based search mode, use Edit > Search Package (Command-F), and click the add button on the right side of the search bar. Then, you can change the name pop-up to owner, group or file mode. For ownership rules, you can choose from the users or groups found in the package payload. For a file mode rule, you specify the bit(s) of the mode that you want to match, e.g.:

Note that you need to use numeric notation for the bits — these are the “absolute modes” you'd specify with the standard chmod(1) tool, whose man page has a good summary of these values. Some examples you might use here include the following:

• file mode sets any bit in mask 022 shows all files or folders which are writable to the group or to everybody.
• file mode sets all bits in mask 003 shows all files or folders which are executable and writable to everybody.
• file mode sets any bit in mask 06000 shows files that use the “Set User ID” (04000) or “Set Group ID” (02000) feature to escalate privileges.

Depending on the pattern of interest, you may be able to combine everything into one sets any bit in mask rule. Or you may need to add multiple sets all bits in mask rules, underneath an any grouping. To combine file mode checks with other rules, Option-click an add button — it will turn into an ellipsis button — to add a new grouping.

Tip: If you have a common set of scenarios you want to look for in every package, configure your rules here once, and create a saved search. You can then apply these rules to any package, by going to the All Files tab, and choosing your saved search from the Go menu.

Why did Suspicious Package change the name of this item in its Quick Look preview?

When you ask Suspicious Package to Quick Look the selected item, it exports that item (to a temporary location) and then activates the standard macOS Quick Look mechanism. That usually results in a meaningful preview — or at least, as meaningful a preview as you're going to get for that file.

However, there are some cases in which macOS does a poor job of choosing a preview. This is typically because macOS hasn't deduced the correct kind for the item, based on its file extension. For example, the package might install a Python script that doesn't have any extension at all. The script doesn't need an extension, because it has a #! directive. Suspicious Package knows that it's a Python script, because it looks inside and finds the #! line. But macOS doesn't look inside, so it simply assigns the generic “Unix executable” kind, based only on the executable bit being set. A Quick Look preview for a generic executable won't show the text of the script, and isn't terribly useful.

Or maybe the package installs an actual executable that has a reverse-DNS type of name, like “com.example.some-helper-tool” (as macOS requires for certain types of components, such as XPC services or bundled privileged helper tools). Suspicious Package knows that it's a Mach-O binary, but macOS misinterprets the last part of the name as the file extension, and not knowing what a “.some-helper-tool” extension is, assigns the generic “Document” kind. A Quick Look preview for a generic document is basically useless — whereas an executable preview could be useful, especially if you have Apparency installed.

In such situations, Suspicious Package attempts to improve the Quick Look result by making a copy of the item with a less ambiguous name. For example, that Python script will get a “.py” extension, and macOS will then show the text of the script. Likewise, that reverse-DNS executable will have its dot characters replaced with hyphens, so that macOS sees it as a proper executable, and will choose a preview extension such as Apparency.

This all happens automatically, and you might not even notice. But some Quick Look preview extensions do show the actual file name of the item — like Apparency does — so it might not be totally hidden.

Why does Suspicious Package always export “All Openable Items”?

Suspicious Package allows a subset of installed files (such as property lists) to be opened in another application. To make this work, it exports these “openable files” into a temporary location, shortly after you open the package. Depending on the size of the package, this automatic export might take awhile, so Suspicious Package shows the progress in the Exports list like so:

For more on how to open these automatically exported files, see Opening Installed Files in Another Application.

Suspicious Package automatically deletes these files again when you close the window for the package.

Why does the path put on the clipboard by “Copy Path to Item” not paste properly in app X?

From the All Files tab, you can copy the path to the selected file or folder by using Copy Path for Item from the toolbar's Action menu , or from the context menu (displayed by Control-clicking). Suspicious Package puts the path on the clipboard in a way that optimizes paste behavior in an app like Terminal — especially if any component of the path contains spaces or other characters that would require escaping in shell commands.

That is, when the clipboard contains a path that is simply plain text, Terminal won't automatically escape any characters when you paste it, because Terminal doesn't know that the text is supposed to be a file path. For example, if the path is something like /Library/Application Support/Script Editor, you won't get the proper result unless you remember to add quotes before and after pasting. However, if the path is placed on the clipboard as a file URL, Terminal recognizes that the pasted text is supposed to be a path, and automatically inserts backslash characters before the spaces. This avoids the need to insert any explicit quote characters.

For this reason, Suspicious Package has always put paths on the clipboard as file URLs — with plain text paths as a fallback, for apps that don't try to do anything with file URLs.

However, there are some apps that do interpret the file URLs, but do so differently. This is especially true of apps that work with files directly, such as attachments to a message or document. Such apps might try to find and read the file from the given URL, and the result will probably not be what you wanted — and will depend on whether or not the path already exists (unlikely prior to installing the package), the kind of file referenced, and whether the app is sandboxed (which might prevent it from reading the file even if it does exist). If pasting produces nothing, or maybe just the name of the file (without the path), this is likely the problem.

Unfortunately, we haven't found any single way of putting the path on the clipboard that avoids these issues. But starting in version 4.3.1, we've added a way to explicitly copy the path as plain text: hold down the Option key, and the menu item will become Copy Path for Item as Text. Of course, you have to know to do this, based on the app you'll be pasting it into, but this is the best solution we could devise for now.

This scheme is all (intentionally) similiar to the way that Finder handles copying a selected file or folder to the clipboard. A standard Edit > Copy Item puts a file URL on the clipboard. Of course, if you then paste within Finder, that will actually copy the file; but if you paste within Terminal, you'll get a properly escaped path to the original file. In contrast, if you hold down Option, this command becomes Edit > Copy Item as Pathname, which puts only the plain text path on the clipboard.

What purpose do package identifiers and bundle overwrite rules serve?

The metadata presented by Suspicious Package in the Info pane of the All Files tab all pertains to the end result of installing the package. There is additional data in the package (usually) that has more to do with the way that the macOS Installer performs the install; Suspicious Package does not show these by default. They are generally only of interest if you're developing or debugging a package yourself.

That said, if you want to see this additional data in the Info pane, you can enable it by going to Suspicious Package > Preferences > General, and checking Component package and bundle info. This adds two fields to the info pane:

• Package shows the identifier of the component package that installs the item. This can be useful if you're trying to determine what component package is installing what, especially in a package that is bundling components from other places. Note that there can be multiple component package identifiers for folders, since their installed folder structure can overlap.
• When a bundle is selected, the Bundle field cycles through various information about the way that the macOS Installer handles that bundle. For example, the Installer might (or might not) look for an existing copy of that bundle that has been moved elsewhere and update it there (this is generally only pertinent for application bundles). Or the Installer may need to follow specific rules about how to update an existing version of the bundle. Hopefully, if you need this information, the descriptions given in the Bundle field will make sense to you!

What is a “writable startup volume folder”?

macOS 10.15 (Catalina) introduced a new scheme whereby the traditional startup disk is split into two volumes: a read-only volume containing the OS itself, and a read-write volume containing user data, software that isn't built into macOS (whether from the Mac App Store or direct from third-party developers), and supporting system files (like caches and data files that are updated outside of Software Update). This split is pretty much hidden in the UI, but you can see evidence of it in Terminal.

The reason this is relevant to Suspicious Package is that certain — probably rare — packages need to install into an alternate folder on the read-write volume, while still installing into the normal read-write system folder on versions of macOS prior to Catalina. Rather than have two different packages for the different macOS versions, developers can declare both folder paths and let the macOS Installer pick the right one. For example, there are packages from Apple — such as the mobile development support packages that Xcode installs on first run — which are installed under the /System/Library folder on Mojave, but under the /Library/Apple/System/Library folder on Catalina.

When constructing the All Files tab for such a package, Suspicious Package assumes that it will be installed on the current startup disk. So, if Suspicious Package is running on Catalina or later, it will apply the alternate folder path to the All Files tab. That alternate folder will be identified with a special Kind description of writable startup volume folder. In the Review tab, you will see an informational “issue,” showing which paths were declared and which one was applied.

This is all well and good — as long as you are examining the package on the system where you'll install it. But if you are, say, working on Big Sur and will install on Mojave, you might want the All Files tab to represent the other scenario. You can do this by closing and reopening the package, while telling Suspicious Package exactly which macOS version it should assume. There are several ways to do this:

• Choose File > Open and select the package as usual, but before clicking Open, click the Options button at the bottom of the dialog, and use the popup menu to choose a macOS version.
• Choose File > Open Recent to reopen the package, while holding down the Option key. Suspicious Package will show a dialog where you can choose a macOS version.
• Likewise, from the Welcome to Suspicious Package window, you can hold down the Option key while double-clicking on the package, and then choose a macOS version from the same dialog.
• Using the “spkg” command line tool, you can specify a macOS version using the --target-os-version option.

Note that none of this is relevant unless a package declares one of these alternate folder paths. If you don't get an informational issue to that effect in the Review tab, you can ignore these complications.

What is a “Distribution” file and should I inspect it?

Most modern installer packages have a “Distribution” file. This is an XML-format file, with (typically) a smattering of embedded JavaScript code. The macOS Installer reads the distribution when it opens the package, and uses the information in this file to decide how and if the package should be installed.

For example, the distribution might declare which macOS version and/or Macintosh hardware is required for the installed software. It defines any special UI that the Installer displays, such as a software license agreement. It determines what choices the user can make on the Customize dialog, and how those customizations change which component packages will be installed. It can even automatically change which component packages will be installed, based on which macOS version — or other software — is already installed.

The good news is that even the JavaScript code within the distribution is limited in what it can do: although it can read files in your home folder and elsewhere, it can't write any files, and it can't make any Internet connections. (In this way, it is much more limited than the typical JavaScript you'd find on the web. The distribution uses the JavaScript language only, and that JavaScript can use only what the macOS Installer exposes to it — namely, functionality designed to determine the capabilities of the hardware and the presence of previously-installed software.)

The bad news is that there's an exception: a way for the distribution to run arbitrary commands, through a JavaScript method called system.run() [or its relative, system.runOnce()]. If a distribution declares its intention to use this exception, Suspicious Package will flag this as a potential issue:

The same scenario will cause the macOS Installer to present a warning dialog when it opens the package, saying that “This package will run a program to determine if the software can be installed.”

If you click the Show Scripts That Run on Open button, Suspicious Package will show you the scripts within the package that might be run by system.run(). However, the distribution may also run system commands with this mechanism, so in order to completely understand what it does, you really need to read the Distribution file.

Which brings us to the other bad news: the Distribution file is an arcane, Apple-defined format that is not easy to interpret. The Distribution XML Reference provides some reference information, but if you've never looked at a distribution file before, it probably won't help much. Even those of us that have been staring at these things for years are no experts!

All of this is why Suspicious Package does not show you the Distribution file by default. Given the challenges of making heads or tails of it, you're probably better off focusing on other evidence of trustworthiness, such as the identity of the distributor. But if you want to see the Distribution file in all its glory, you can go to Suspicious Package > Preferences > General and check Show Distribution file on All Scripts tab.

What is a “PackageInfo” file and why would I want to see it?

Within a modern installer package, each component package has a “PackageInfo” file that contains most of the metadata for that component. This XML-format file includes information such as the top-level scripts that should be run, what bundles are installed and how, and other attributes — including the component package identifier and version, and any special install path information.

Suspicious Package always reads the PackageInfo files, and attempts to present that information in a more useful way, e.g. incorporating install paths into the All Files view, and showing bundle version strings in the info pane. Optionally, the info pane will also show the special installer rules that apply to a bundle, and the component package identifier to which a specific file or folder belongs.

For this reason, Suspicious Package does not show you the PackageInfo file by default. Apple doesn't provide any documentation of the PackageInfo format, and some of it is quite arcane. So if you can avoid looking at it, all the better.

However, if you want to see the PackageInfo file anyway — perhaps because you are authoring a package, or dealing with a package that is behaving badly — you can go to Suspicious Package > Preferences > General and check Show PackageInfo files on All Scripts tab.

Why doesn't Suspicious Package show the indirect scripts for certain packages?

Suspicious Package shows all scripts for a modern xar-format flat installer package. Presumably, indirect scripts are there for a reason, and if Suspicious Package didn't show them, you'd have to unarchive the package yourself to see them.

Older bundle-style packages can also have indirect scripts. But in this case, the scripts are visible within the bundle, if you open the package using the Finder's Show Package Contents command (see above). Suspicious Package shows only the top-level (preinstall and postinstall) scripts in this case, rather than trying to show the entire contents of the package, and doing so less effectively than the Finder.

Can I increase the size of the font used for showing script text?

When showing the script text on the All Scripts tab, Suspicious Package asks macOS for the default user fixed-pitch font, which is typically Menlo 11.

Although the Cocoa API defines this as a user preference, macOS doesn't actually provide any standard UI for setting it. But starting in version 4.3.2, Suspicious Package allows you to select a different fixed-pitch font. Go to Suspicious Package > Preferences > General > Plain text font and click Select. The font you choose here will be used on the All Scripts tab, and will also change the font used for certain Quick Look previews initiated from All Files or All Scripts.

In version 4.3.1, we suggested using a Terminal command to set the NSFixedPitchFontSize default key. If you did this previously, that choice should be reflected in the Preferences window described above, as the new UI is controlling the same default key.

As an aside, the Preferences UI described above selects the fixed-pitch font for Suspicious Package only. But because Cocoa defines standard keys for this, you can set a preferred fixed-width font that gets used for any application, using Terminal commands like this:

defaults write -globalDomain NSFixedPitchFont Menlo-Bold
defaults write -globalDomain NSFixedPitchFontSize -int 18

Here, NSFixedPitchFont specifies the “PostScript name” of the font to use and NSFixedPitchFontSize specifies the point size. (The PostScript name can be found in the Font Book app: select the font and choose View > Show Font Info.)

Setting these in the global preferences will also affect other apps that use the standard macOS user fixed-pitch font mechanism. However, if an app provides its own UI for setting these prefs — such as Suspicious Package's Plain text font or Mail's Fonts & Colors > Fixed-width font — this might override the global preferences.

Why does Suspicious Package say that Apple has “deprecated” Bash?

We have no inside information or secret sources: we were just trying to read the same tea leaves as everyone else!

In Suspicious Package 4.2, we added the “deprecated runtimes” review warning upon request — a request which lumped Bash in with the other built-in runtimes like Python, Perl and Ruby. Although the status of Bash seemed less clear-cut to us, it did seem obvious that Apple is trying to discourage its use, and has long since stopped updating it (presumably due to licensing changes). Our clearly-not-good-enough research led us to believe that people regarded the built-in Bash as being at least “soft deprecated,” and we implemented the review warning accordingly.

But subsequently, we learned that there is far from agreement on this matter. We have no basis to argue one way or the other — and even less inclination to do so. Accordingly, we have removed the Bash part of this review warning in Suspicious Package 4.2.1. If you update to the latest version of the app, any such Bash warnings should go away.

Why does Suspicious Package say that Apple has “deprecated” Python, Perl and Ruby?

There's less debate about this one: Apple began calling these scripting language runtimes “deprecated” back in the macOS Catalina 10.15 Release Notes:

“Scripting language runtimes such as Python, Ruby, and Perl are included in macOS for compatibility with legacy software. Future versions of macOS won’t include scripting language runtimes by default, and might require you to install additional packages. If your software depends on scripting languages, it’s recommended that you bundle the runtime within the app.”

Although that “such as” qualifier is a bit ambiguous — what exactly constitutes a “scripting language runtime”? — we can at least assume that Python, Perl and Ruby are on the chopping block. Indeed, Apple removed the Python runtime in macOS 12.3 — a minor update to Monterey!

With an installer package, the primary concern is the install scripts: if these rely on a deprecated runtime, the package might stop working correctly in a future version of macOS. That's not an idle concern, since the use of Python and Perl in install scripts is quite common. Suspicious Package warns about this situation to increase awareness, especially among the creators of such packages. You can also go directly to the All Scripts tab and choose Go > Deprecated Scripts, which will show all of the install scripts that use one of the deprecated runtimes.

Suspicious Package does its best to determine which install scripts use the built-in runtime for a scripting language. That's based on the path given in the #! directive: anything under /usr/bin or /System/Library is assumed to be Apple-provided. Also, a #! directive prefixed with /usr/bin/env is assumed to implicitly reference a built-in runtime, since the PATH variable in effect for an install script normally includes only system locations. (As of macOS 12.3.1, that PATH is /bin:/sbin:/usr/bin:/usr/sbin:/usr/libexec.) However, in a managed environment, install scripts might depend on other runtimes (like this one); Suspicious Package tries to avoid warning about these.

So what is a “safe” choice for writing install scripts? We can't say. Clearly, some people think Bash is still safe, as discussed above. We've also seen people posit that the only safe choice is the strict POSIX-conformant subset implied by /bin/sh. ¯\_(ツ)_/¯

How should I evaluate scripts that run when the macOS Installer opens?

As noted above, a script that runs when the macOS Installer opens is an artifact of the Distribution file's system.run() capability. Suspicious Package will always show such scripts that are bundled with the package itself: these appear under the Installer Package heading in the scripts browser. But as described above, the distribution can also run system commands, and the only way to determine that is by inspecting the Distribution file itself.

With that proviso, the important things to know about scripts that run when the macOS Installer opens are:

• These scripts may run as soon as you click Allow in the macOS Installer dialog that says “this package will run a program to determine if the software can be installed.”
• These scripts run as the current user, so they can't change system files, but they can do anything with the files in your home folder.
• The command-line arguments passed to these scripts are up to the Distribution file.

How should I evaluate a package that contains plug-in code for the macOS Installer?

The macOS Installer provides a plug-in mechanism by which a package can add UI to the installer: this normally takes the form of additional steps, such as entering registration or licensing information, or performing some sort of post-install cleanup or update checking.

However, this mechanism results in code provided by the package being run by the macOS Installer, upon opening of the package. As with run-on-open scripts, this also will cause the macOS Installer to present a warning dialog, as shown here.

Unfortunately, unlike the Distribution file mechanisms, where there's something that you can see (no matter how arcane), there is basically nothing you can check here: macOS Installer plug-ins are binary executables, and there's not much you can do to analyze them beforehand. Again, you're probably better off focusing on other evidence of trustworthiness, such as the identity of the distributor.

What is an “Unverified CRC-32 checksum”?

When you create a diffable manifest for a package, files are described with their kind, ownership and permissions, size and so on. One other piece of metadata, which is not normally shown by Suspicious Package, is called an Unverified CRC-32.

When a package is created with the standard Apple tools [e.g. pkgbuild(1)], this 32-bit checksum value is calculated for all regular files and stored in the package metadata (specifically, the Bom file). The checksum algorithm used here is called CRC-32 and is used in various other places; it is the same algorithm used by cksum(1) by default.

Therefore, if a file is changed, the CRC-32 value will probably also change; and if the CRC-32 stays the same, the file is probably unchanged. However, there are a few important caveats to be aware of here:

• A CRC-32 checksum is not a cryptographic hash: it is designed to detect data corruption that occurs in transmission, and not to detect tampering. (In other words, it's quite feasible to modify a file in such a way that the CRC-32 value doesn't change, thus evading detection. Compare this to cryptographic hash algorithm like SHA-256, where designing two files that produce the same hash value is believed to be infeasible.)
• The macOS Installer does not (to our knowledge) verify the actual file against the CRC-32 checksum at installation time, nor even require that the CRC-32 checksums be present in the package metadata. (So why are they there? Um, history?)
• Likewise, Suspicious Package does not verify the CRC-32 checksums against the actual files in the package payload. (It could do so, in theory, but it would take a lot of time and CPU and is of dubious benefit.) That's why we specifically label it Unverified.

Nevertheless, the CRC-32 can provide a clue as whether or not a file has changed, which is why Suspicious Package includes it in the diffable manifest by default. (You can, if you like, turn this off by going to Suspicious Package > Preferences > Compare > Diffable Manifests Include and unchecking Unverified CRC-32 checksums in metadata.)

Note that Suspicious Package omits the CRC-32 (by default) for executable files that have been code-signed, in favor of code signing digests.

What is a Code Signing Digest (cdhash) and when does it change?

When a macOS executable is code-signed, a cryptographic digest is computed for each supported architecture (e.g. Intel — 64-bit or Apple Silicon — 64-bit). This cdhash (short for code directory hash) is a SHA-256 digest of other hashes, covering the executable code, the Info.plist file, the bundled resource files (via the _CodeSignature/CodeResources file), the entitlements, and the code signing identities (a.k.a. requirements). The cdhash is the object that gets signed with the developer's certificate (such as a “Developer ID Application” certificate) to produce the code signature. And of course, when macOS verifies the code signature, the calculated cdhash must match what was signed.

Various parts of macOS treat the cdhash — or code signing digest — as uniquely and securely representing that bit of code — whether it's an app bundle, a framework, a plug-in or a standalone executable. For example, when macOS checks for notarization of an app, it queries Apple servers for a notarization ticket matching the code signing digest of the app. If you tell macOS to open an unnotarized app (using the Finder's context menu), the app's code signing digest is recorded as being allowed to open. And so on.

All of this means that the code signing digest should reliably change when the executable (or some related resource) changes. Suspicious Package extracts the code signing digests from the executable in the package payload, and includes them in the diffable manifest metadata file. (For a Universal executable, there will be multiple code signing digests.) If you are comparing two versions of a package, and the digests are unchanged, you can be pretty certain that the executable didn't change. If the digests did change, this means that the executable and/or its related resources have changed.

Although Suspicious Package extracts the code signing digests from the package payload, it does not verify them against the code signature or against the executable and resources. Of course, any tampering with the executable or resources will break the code signature, which would be detected by Gatekeeper. But at least prior to macOS 13 (Ventura), Gatekeeper won't evaluate items installed by the macOS Installer (because they aren't individually quarantined). Remember that the origin and trustworthiness of everything installed by a package should be evaluated using the package signature.

Note that code signing digests have the advantage of not changing when the same code is rebuilt (using the same version of Xcode with the same SDK and the same dependencies, at least). The unverified CRC-32 checksum will change on every build, because the signature includes timestamps that will never be identical. But the code signing digest excludes the actual signature (since the digest is, by definition, the object being signed). For this reason, Suspicious Package doesn't bother with CRC-32 checksums where code signing digests are available; this might result in fewer differences to dig through, when code is rebuilt but otherwise unchanged.