Frequently Asked Questions
Installing Suspicious Package
What versions of macOS does Suspicious Package support?
Suspicious Package supports:
- macOS 10.13 (High Sierra)
- macOS 10.12 (Sierra) and
- OS X 10.11 (El Capitan)
If you're using an older version of macOS, you can download an old version of Suspicious Package as follows:
- 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).
Although we make these old versions available for those who need them, keep in mind that we have not tested them since they were current.
Does Suspicious Package work on the macOS 10.14 (Mojave) beta?
It's early days for macOS 10.14 (Mojave), and we have only just begun to work on it. However, we are already aware of the following issues on the current beta version of Mojave:
- The new Dark Mode feature is obviously not supported.
- In the scripts browser, the main text pane shows a conventional (but nonsensical in this context) ruler, instead of the expected line numbers. Also, the text of the script is partially hidden underneath this ruler, unless you scroll horizontally to expose it.
We will continue to update this FAQ as we work on Mojave compatibility. In the meantime, if you find other issues not yet listed here, please contact us with details.
Why don't I get the Suspicious Package preview in Quick Look?
Although you can install Suspicious Package app anywhere you like, Quick Look can be stubborn about recognizing the plug-in that is bundled inside of it. Specifically, you must open the Suspicious Package app at least once before Quick Look will even consider using its plug-in (this is, presumably, a security measure, so that only apps which pass the Gatekeeper checks can generate Quick Look previews). After you do that, Quick Look should find and use the plug-in.
If you open the app before dragging it to your Applications folder (or wherever you've decided to keep it), make sure to open it again after you've copied it. If you open the app directly from the disk image, it will not be marked as safe-to-use for Quick Look.
When the Suspicious Package app is opened for the first time, it will request that Quick Look update its plug-in registry, and that will usually suffice to get previews working immediately. Starting in version 3.3, the app repeats this request to Quick Look after the app has been moved or updated, or after macOS itself has been updated — these are all scenarios that can prevent or delay Quick Look in finding Suspicious Package.
If, after opening the app, you still do not get a proper Suspicious Package preview from Quick Look, you can open the Terminal and run the following command to force the issue:
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 on the right side of the app's title bar: and at the bottom of the Quick Look preview:
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: Note that the automatic check preference you set here applies to both the app and the Quick Look plug-in.
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.
How do I remove the old standalone Quick Look plug-in?
Although Quick Look should find the new plug-in inside the Suspicious Package app (eventually), you may still want to remove the old standalone plug-in, just to save disk space and avoid unnecessary cruft.
After launching the app, you can use Suspicious Package > Move Old Plug-in to Trash to get rid of the standalone plug-in, whether it was installed for the current user or for all users. (If you don't see this item in the app menu, no standalone plug-in was found in either of the standard locations.)
Can I download Suspicious Package as a disk image (and what happened to XIP)?
Suspicious Package was previously distributed as a XIP archive, but in macOS 10.12 (Sierra), Apple has removed support for XIP archives, except for those signed by Apple.
From the Suspicious Package download page, you will now get a disk image instead. This disk image is “signed” for the benefit of macOS 10.12 (Sierra), but is still compatible with earlier versions of macOS. As with any app distributed via a disk image, you will need to open the disk image, copy the app to your Applications folder (or wherever), and then eject and trash the disk image.
For the sake of existing scripts and distribution tools, we will continue to make Suspicious Package available as a XIP archive for the near future. But you should switch to using the disk image download when feasible.
I don't want an app. Can I install only the Quick Look plug-in?
No. But you don't have to use the app at all, if you don't want to. As a bonus, bundling the Quick Look plug-in inside the app simplifies installation: drag the app into your Applications folder (or wherever) and the Quick Look plug-in is automatically available (see here for troubleshooting). No more ironic Suspicious Package package!
Don't try to drag the Quick Look plug-in out of the app bundle. It won't work, because the plug-in relies on other resources within the app bundle.
Understanding Suspicious Package
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”?
Unfortunately not; 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 some restrictions that would severely reduce the usability of the app. Most significantly, a top-level package can reference “sub-packages” that are in sibling folders. (This is not uncommon for packages delivered on disk images, where only a single top-level package is visible in the Finder, but it references sub-packages in some hidden folder on the same disk image.) If Suspicious Package were sandboxed, it wouldn't be able to read those external sub-packages.
That isn't to say that Suspicious Package won't ever be sandboxed, just that it isn't today.
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. Allowing other people to muck with our code requires giving up control. Sure, we appreciate that when you work with other people in a real company, that teamwork 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.
Using Suspicious Package
How can I tell which files a
Custom Install will install?
Some installer packages contain sub-packages, and allow you to deselect one or more of these through the Customize dialog. And some installer packages contain sub-packages that are selected or deselected automatically, based on the macOS version, the other software installed, or even the hardware of your Mac.
Suspicious Package doesn't have the smarts to figure out which sub-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.
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, or 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).
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.
Why don't I get a Quick Look preview in Finder windows set to use Column view?
Finder's Column view (i.e. View > as Columns) shows Quick Look previews in the rightmost pane for some types of files. But it doesn't support interactive previews such as Suspicious Package (excepting some of the built-in types, like PDF files or movie files).
You might notice that, for a large package, Column view will work a bit before simply showing the generic package icon. This, unfortunately, is Suspicious Package producing a Quick Look preview, which the Finder will then decline to show. We tried to find a way to avoid this, but there seems to be no way to tell the Finder ahead of time that it shouldn't bother.
Why doesn't Suspicious Package show the indirect scripts for certain packages?
Suspicious Package shows all scripts for modern (so-called “flat”) installer packages. It is otherwise extremely difficult to see the scripts in a flat package.
An older package format (known as “bundle-style”) 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.
What is a “distribution” script and should I inspect it?
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 sub-packages will be installed. It can even automatically change which sub-packages will be installed, based on which macOS version — or other software — is already installed.
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:
This also causes the macOS Installer to present a warning dialog when it opens the package:
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 script.
Which brings us to the other bad news: the distribution script 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 script 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 script in all its glory, you can go to Suspicious Package > Preferences > General and check Distribution script.
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 script'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 script 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 Continue 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 script.
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 this warning dialog:
Unfortunately, unlike the distribution script 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.
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 did Suspicious Package change the icon 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.
Unfortunately, prior to version 3.3.1, a side effect of doing this was that the Finder (and everything else on the system) would start to use the generic document icon for every package. This is because macOS doesn't define the installer package icon globally, but associates it specifically with the macOS Installer application. And since Suspicious Package didn't try to redefine the icon for installer packages, it fell into generic document territory.
So, starting in version 3.3.1, Suspicious Package defines an icon to avoid this ugliness. 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 (and also, frankly, to avoid bloating the size of the app by delivering another copy of the rather large package icon that already exists on every macOS system!).
All of this is relevant only if you change Suspicious Package to be the default application for installer packages. If you leave the macOS Installer as the default application, you should not see any change in the icons.
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 identifiers of the sub-package(s) that install the item. This can be useful if you're trying to determine what sub-package is installing what, especially in a package that is bundling sub-packages from other places. Note that there can be multiple sub-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 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
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
man page, and the
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.
Starting in version 3.3, 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.
If you're using OS X 10.11 (El Capitan), Suspicious Package can't show additional information in the standard certificate trust sheet, because a bug in OS X prevents the text from being displayed correctly. Instead, you'll need to click the More Info button to see the verified signing time, and then click Done to return to the trust sheet. If there is no More Info button, Suspicious Package did not find a verified signing time.
What happened to certificate validity information in the Quick Look preview?
macOS provides a standard “certificate trust” sheet for examining a chain of certificates. This UI includes detail on each certificate, including its validity (or lack thereof). The Suspicious Package app uses this standard UI, much like other macOS applications, such as Safari or the macOS Installer.
Because of the way that Quick Look previews work, Suspicious Package can't use the standard UI there. Instead, it re-creates this UI, using lower-level macOS APIs to get the relevant certificate information. But in macOS 10.12 (Sierra), those lower-level APIs stopping providing details of individual certificate validity. For this reason, on Sierra and newer versions of macOS, the Quick Look preview omits the validity information for individual certificates, rather than presenting information that might be wrong.
If you need this detail, you can open the package in the Suspicious Package app, and use Window > Signature Details (Cmd-5) to access the standard certificate trust sheet.
Apple fixed the lower-level APIs in macOS 10.13 (High Sierra), but since they work a bit differently, we haven't (yet) brought back the certificate validity information. Given that you can get this information by opening the app, we're honestly not convinced that it is worth the effort to support three different modes of operation (for 10.11, 10.12 and 10.13). But if you have a strong reason for wanting to see this detail return to the Quick Look preview, contact us and let us know.