Suspicious Package

Frequently Asked Questions

Installing Suspicious Package

What versions of OS X does Suspicious Package support?

Suspicious Package requires OS X 10.9 (Mavericks) or OS X 10.8 (Mountain Lion).

If you're using an older version of OS X, you can download an older version of Suspicious Package: 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. (Quick Look itself was introduced with Leopard, so Suspicious Package does not exist for earlier versions.)

Suspicious Package version 2.0 basically works with DP7 of OS X 10.10 (Yosemite), although we haven't tested it completely. If you find problems on Yosemite, please let us know.

Shouldn't I be suspicious of the Suspicious Package package?

Yes, we're aware of the ... irony of distributing Suspicious Package as a package, but it's very awkward to distribute it any other way. If you want an alternative, though, there are instructions here.

The Suspicious Package package is signed with an Apple-issued “Developer ID” certificate, and so will be recognized as valid by the Gatekeeper feature of OS X. The signer, as displayed by Suspicious Package itself, will be “Randy Saldinger,” which is the real name of the person who writes in the first person plural for Mothers Ruin Software.

See below for a discussion of Developer ID, and what it does — and doesn't — promise.

Does Suspicious Package automatically check for updates (and how can I stop it)?

Yes. Once a month — or less, if you use it less often — Suspicious Package will download a small file from our web site to get the current version. If a newer version is available, you'll see this 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 don't like the automatic checking and want to turn it off, use the following command in the Terminal:

defaults write com.mothersruin.SuspiciousPackage UpdateCheckDisabled -bool YES

There ought to be a more friendly way to disable update checking, but the architecture of Quick Look plug-ins makes it near impossible to connect the UI in the Quick Look preview back to the plug-in that generates the preview (and does the update check).

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 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.

Why does Suspicious Package not work on installer X?

If Suspicious Package doesn't recognize the structure of an installer package, the Quick Look preview will not show the file view, and will indicate that the package is “broken or archaic.” Even for normal-appearing package files, this can happen for a number of reasons; the OS X Installer supports a bewildering array of package formats, going back to NeXT days, and Suspicious Package simply does not understand them all.

If you find an installer package that Suspicious Package doesn't work on, feel free to contact us with the details, although we can't promise we can get it working.

Why does Suspicious Package say it is not showing some files that the package installs?

When a package installs more than about 10,000 files, the Suspicious Package file view can get unwieldy and slow. Since we haven't figured out a way to improve this — within the limits of the Quick Look plug-in architecture — Suspicious Package omits the deeper levels of folder hierarchy when the number of files gets too high. When this happens, you'll see a message like this above the file view: omitted files indication

If you open folders below the indicated level, the “private folder” icon will show you where information has been omitted by Suspicious Package.

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 don't I get a 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.

Understanding Install Scripts

What is an install script and why should I care?

In addition to installing files, a package can contain “install scripts,” which are run by the OS X Installer. These scripts can do anything, and typically run as the root user. There are countless legitimate reasons for a package to have install scripts — starting and stopping background processes, cleaning up and rebuilding caches, and so on. But a malicious package could take advantage of this mechanism to wreak havoc, and even well-intentioned but buggy packages might do damage.

If a package contains install scripts, Suspicious Package will show how many, like so: summary of install scripts Clicking on this will open the scripts browser, where you can see the content of every script in the package, e.g.: scripts browser

Unfortunately, the hard part is actually auditing the install scripts for safety, which requires knowledge of the scripting language being used. Suspicious Package tries to give a few clues — including the arguments that the script will get from the OS X Installer — but it can still be a challenge.

As a general rule, the less you understand what the install scripts do, the more you should trust the distributor of the package before installing it — and the more carefully you'll want to vet the package signature (to ensure that the distributor is really who you think it is).

What are all these files and folders in the scripts browser? And why are some “not directly used by the Installer?”

The OS X Installer has specific “hooks” for running install scripts — a preinstall script is run before the package files are installed, and a postinstall script is run after. That sounds very simple, but you will often see more than just these two files in the scripts browser. There are two reasons for this:

  1. An installer package can (and often does) contain sub-packages, and each one of those sub-packages might contain its own preinstall and postinstall scripts. In such cases, you'll see the sub-packages as folders at the top level of the scripts browser.
  2. A preinstall or postinstall script can, in turn, run other scripts, or even standalone applications, which are also contained within the package. So even though the OS X Installer does not directly run anything but preinstall and postinstall, the other scripts in the package are likely still used (or they wouldn't be there). For this reason, Suspicious Package shows all the scripts in the package, with the indirect ones in gray. But to understand how the indirect scripts are used, you generally have to start at the top — preinstall and postinstall — and work your way down.

A couple of other notes about interpreting install scripts:

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

The Suspicious Package policy of showing all scripts holds only 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.

Understanding Package Signatures

What does the package signature prove?

At a minimum, a package signature that is marked as valid by Suspicious Package indicates that someone has obtained a certificate from a certificate authority which is trusted by OS X, and has used that certificate to sign the package. (This is a bit oversimplified: see more below.)

Since a certificate — at best — proves identity, rather than benign intent, there is only so much reassurance you should take from it. Furthermore, some certificates prove nothing more than that the certificate holder owns the Internet domain that the certificate names, which, unless you trust the domain, means little.

However, in the Apple ecosystem, there are a couple forms of signatures that promise a bit more. One is a signature from Apple itself — such as on packages downloaded from the Apple web site, through OS X Software Update, or through the Mac App Store. These are certificates that Apple issues to itself, but since Apple owns the platform, this is sufficient to warrant that the package came from Apple. Suspicious Package marks such signatures as Apple Inc.

Another signature uses a “Developer ID” certificate, issued by Apple under the Gatekeeper program. These are certificates that Apple issues to developers registered with the Apple Developer program, and which developers use to sign their packages. Suspicious Package marks such signatures as Developer ID

Although Developer ID certificates don't prove benign intent either, Apple has the ability to revoke such certificates if they are being used to distribute malware — or if they are lost or stolen. Signatures from revoked certificates will be marked as revoked in Suspicious Package, and will not be allowed to open in the OS X Installer.

What do the package signature types — “revoked,” “expired,” etc. — indicate?

The meaning of each package signature type is described below:

Signature TypeDescription
Apple Inc. Package was signed with a valid Apple certificate, such as for distribution of software through www.apple.com, OS X Software Update or the Mac App Store.
Developer ID Package was signed with a valid Developer ID certificate, which was issued by Apple to a third-party developer, for distribution of software outside of the Mac App Store.
valid Package was signed with a certificate that was issued by a certificate authority which is trusted by OS X (but which is not an Apple or Developer ID certificate).
not trusted Package was signed with a certificate that is not trusted by OS X, nor issued by a trusted certificate authority.
expired

Package was signed with a certificate that has expired or been revoked by the issuer. All certificates expire after some amount of time. Or a certificate might be revoked because it has been lost or stolen.

In certain cases, the OS X Installer can verify that a package was signed before the certificate became invalid, and so will consider the signature valid — even where Suspicious Package does not, because it not have access to this verified time-of-signing information.

revoked
marked as trusted Package was signed with a certificate that would not normally be trusted by OS X, but which is marked as trusted on your computer. You should see this only if you opened Keychain Access and changed the “Trust Settings” for the certificate, or if you have an IT department that did so globally.

Will Suspicious Package tell me if a package was modified since being signed?

Not directly. There are actually two pieces to verifying a package signature:

  1. First, the trust of the signing certificate is evaluated. This is what Suspicious Package shows as valid or Developer ID or the like.
  2. Then, the signature is verified against the certificate and against the actual contents of the package. This ensures that the package really was signed by the (trusted) certificate, and that it has not been modified since being signed.

Suspicious Package does not do the second step, because (a) it can take a long time, especially for large packages, and (b) the OS X Installer is going to do it anyway. In fact, if there is a failure in signature verification, the OS X Installer will stop with an error before any file has been installed, and before any install script has been run. So rather than turning Quick Look into Not-So-Quick Look, Suspicious Package defers this verification to the OS X Installer.

However, if you want to completely verify the signature without even attempting installation, you can use the OS X pkgutil(1) tool from the Terminal, e.g.:

pkgutil --check-signature ~/Desktop/SomePackageToCheck.pkg

This will do a complete verification of both certificate trust and signature validity.