Suspicious Package

Frequently Asked Questions

Installing Suspicious Package

What versions of OS X does Suspicious Package support?

Suspicious Package requires OS X 10.11 (El Capitan), OS X 10.10 (Yosemite) or OS X 10.9 (Mavericks).

If you're using an older version of OS X, you can still download an old version of the standalone Quick Look plugin:

Quick Look itself was introduced with Leopard, so Suspicious Package does not exist for earlier versions.

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

Although you can install Suspicious Package app anywhere you like, Quick Look is sometimes slow to recognize the plug-in that is bundled inside of it. For this reason, you might not get a proper preview right away, or if you previously installed the standalone plug-in, that might get used instead. (You can see the version of Suspicious Package in use at the bottom of the Quick Look preview, if one gets generated at all.)

If you've recently installed the Suspicious Package app, try to open it at least once. The first time the app is opened, it will request Quick Look to update its plug-in registry, and then it ought to find the right version.

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: available update indication and at the bottom of the Quick Look preview: available update indication

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: update pref pane 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 plugin?

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 in some other format than a XIP archive?

Yes. XIP is secure but obscure. If you prefer, you can download Suspicious Package in a disk image. Open the disk image, drag the app to wherever you want, and then you can eject and trash the dmg file.

Using Suspicious Package

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

No, not necessarily. 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. So, finding no issues for review simply means that none of the things that Suspicious Package knows to look for are there — 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 OS X do it directly, and none of this would be necessary!)

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 OS X 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's the difference between Suspicious Package and “Show Package Contents” in the Finder?

Show Package Contents in the Finder's context menu actually refers to a completely different sort of package. OS X 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, 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 is just saying to open the folder in the Finder, instead of opening the application associated with the package.

A modern (“flat”) installer package is not even a folder, so you won't see this Finder command. On an older (“bundle-style”) installer package, the Finder will offer to Show Package Contents, but that will show you only the internal structure of the installer package, which isn't the same as seeing what the package will install. (However, it is occasionally useful for finding scripts and executables referenced by install scripts: see more details.)

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?

Most modern installer packages generally have a “distribution” script. This is an XML-format file, with (typically) a smattering of embedded JavaScript code. The OS X 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 contains rules that determine what OS X version and/or what Macintosh hardware is required to install the package. 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 what sub-packages will be installed. And it can also change the sub-packages that get installed automatically, based on what OS X 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 OS X Installer exposes to it — 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, though 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: Run-on-Open issue This also causes the OS X Installer to present a warning dialog when it opens the package: Run-on-Open issue

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 OS X Installer opens?

As noted above, a script that runs when the OS X 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 OS X Installer opens are:

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

The OS X 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 OS X Installer, upon opening of the package. As with run-on-open scripts, this also will cause the OS X Installer to present this warning dialog: Run-on-Open issue

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: OS X Installer plugins 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 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 OS X 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: