A User Guide
Opening an Installer Package
Open a package in Suspicious Package using File > Open, or by dragging the package onto the Suspicious Package icon.
Or Control-click on the package in the Finder, and choose Open With:
Or, if you've already used Quick Look to see a preview of the package, you can open it in the Suspicious Package app directly:
Either way, Suspicious Package will open the package and show an overview in the Package Info tab:
Browsing Installed Files
To see the files that will be installed by the package, select the All Files tab: Or use Window > All Files (Command-2).
Find Like the Finder
The All Files tab is designed to work much like the Finder's list view, so:
- Click the disclosure triangle next to a folder to show (or hide) the contents of that folder.
- Double-click a folder to open it.
Unlike in the Finder, double-clicking a “special” folder — such as an application bundle — will simply open that folder. Suspicious Package will never launch an app as a result of navigating through the All Files view.
- Use Go > Enclosing Folder (Command-Up Arrow) to move up a folder.
- Use the Path button on the toolbar to go directly to any folder above the current one.
Suspicious Package also provides quick access to some standard locations via the Go menu. For example, you can go right to the Applications folder using Go > Applications (Command-Shift-A). If a location is disabled in the Go menu, the package doesn't install anything there.
To see an item in context, select it and use File > Show Destination Folder in Finder (Command-R). This reveals the folder where the selected item would be installed, showing any existing version of the item.
Get Additional Metadata
When you select a file or folder in the All Files tab, the Info pane will show any additional metadata that Suspicious Package has about the item.
If the Info pane isn't visible, click the Get Info toolbar button to show it.
The metadata shown in the Info pane will vary with what is selected, and what data is in the package. If you select a bundle (such as an application or a framework), you will generally see the bundle identifier, and probably version information.
The permissions are shown in the same way as the Finder's Get Info window. If you'd prefer to see these in traditional Unix symbolic form, click on the permissions table to toggle the view. You can also click on the Kind, Owner, Group or Version to cycle through other views of the available metadata.
If you want to see additional installer-specific metadata about component packages and bundle overwrite rules, turn on Component Package and Bundle Info in Suspicious Package > Preferences > General.
Go Back in History
Suspicious Package keeps track as you navigate through the All Files view. To retrace your steps, click the Back toolbar button or use Go > Back (Command-[).
If you hold down the Back button momentarily, you can jump back to a specific point in the history.
Of course, once you've gone back, you can use the Forward button to go in the other direction again.
Open Additional Tabs
If you find files or folders that you want to come back to, you might find it useful to open additional tabs:
To open another tab identical to the current All Files view, use File > Open in New Tab (Command-T).
To open a new tab with the contents of a specific folder, hold down Command while double-clicking the folder.
To open a new tab for a specific folder without immediately selecting that new tab (a.k.a. Open in New Tab in Background), hold down both Shift and Command while double-clicking the folder. For example, if you see several folders that you want to examine, you can Shift-Command-double-click all of them, and then move between the new tabs.
To quickly cycle between open tabs, use Window > Next Tab in Package (Shift-Command-]) or Window > Previous Tab in Package (Shift-Command-[).
To rearrange tabs, simply drag them around in the tab bar.
To close a tab, click the close button or use File > Close Tab (Shift-Command-W).
In macOS 10.12 (Sierra), Apple introduced window tabs, which are supported automatically in most applications — including Suspicious Package. By default, window tabs are used only in full screen mode, but you can change this in System Preferences > Dock > Prefer tabs when opening documents. Or, you can manage window tabs manually from the Window menu of the app.
Note that Sierra's window tabs do not replace Suspicious Package's own tabs. Window tabs represent different packages, which would otherwise be shown in separate windows. Suspicious Package tabs represent different parts of a single package, such as Scripts or All Files. When you enable window tabs, you'll see two tab bars, e.g.: The window tabs are on top, while the Suspicious Package tabs are underneath.
We considered switching to a different term for Suspicious Package tabs, but it only seemed more confusing. Nevertheless, we've tried to make the various tab-related menu commands more specific about which tab is involved.
Opening Installed Files in Another Application
Suspicious Package chooses a small subset of the installed files, and makes them available for you to view in another application. For example, if you want to see the contents of some “Info.plist” file, you can select that file and use File > Open Item With > Xcode (or with some other installed application that can show a property list).
Suspicious Package picks a default application (based on the file kind), which can be opened with Command-Shift-O. If you want to change the default application for all files of the current kind, hold down Option and use File > Always Open Kind With. This is all meant to work like the Finder's Open With feature.
You can also tell Suspicious Package to open a file with the Finder, which means that the file will be revealed in a Finder window. This can be helpful if you want to manipulate it in the Terminal, or in some application that can't directly “open” the file (but can import it or analyze it in some other way).
If File > Open Item With is disabled, the selected file is not one that Suspicious Package has made available for viewing. Suspicious Package picks files that it suspects will be useful and that are likely to be viewable, such as property lists and plain text files. It skips files that are especially large, to avoid using tons of disk space for files that you're unlikely to open. If you find a file that you want to see but that Suspicious Package doesn't make available, you can always export it from the package.
When you use the Open With command, Suspicious Package writes the file to a temporary location, and hands that temporary copy off to the chosen application. All of these temporary files are removed when you close the Suspicious Package window for that package. If you want to keep the file around longer, you will need to copy it somewhere else, or export a copy elsewhere.
Searching and Filtering the Installed Files
In addition to browsing through the folder hierarchy on the All Files tab, you can also search for files by name or other attributes.
Searching by Name
To search for files (or folders) whose name contains specific text, use Edit > Search Package (Command-F). Enter the text in the search field and press Return to do the search:
Suspicious Package will show the matching files and folders. It also lists the nearest enclosing bundle or top-level folder, to give some context to each match.
To see details for a matching item, select it and examine the Info pane.
The path bar at the bottom of the window shows the complete folder path for the selected item: you can double-click on any folder in the path bar to open that folder, and show the matching item in context. Then, if you want to go back to the search results, use the Back button.
Searching Within a Folder
If you open a folder, and then start a search, you'll have the option to limit the search to the contents of that folder.
Use the buttons on the left side of the search bar to switch between the original folder and the entire contents of the package: Note that searching within a folder considers the entire contents of that folder, no matter how many subfolders it contains.
Filtering on Other Attributes
In addition to the name of a file, you can search on other attributes. For example, you can show all files of a particular kind.
First enter search mode using Edit > Search Package (Command-F). Then click the add button on the right side of the search bar:
From here, you can add and edit rules, very much as in the Finder. For example, if you choose the “kind” attribute, you'll get a pop-up menu containing all of the file kinds that are installed by the current package — this is also a quick way to look for “interesting” kinds of files (such as kernel extensions, or privileged tools):
You can also incorporate file name-based rules here, with more control over the matching of the entered text (such as a file name that starts or ends with the text, or which matches the case of letters exactly).
Note that, if you hold down the Option key, the add button becomes an ellipsis button — this adds a new group of sub-rules, allowing you to construct arbitrarily complex Boolean requirements, if you should be so inclined.
Once you've set up a search — especially a complex one involving multiple rules — you might want to save it for later.
A saved search can be reused in any package. If you have a standard set of things you look for in a package, saved searches are a good way to go.
To save the current search, click the Save As button on the right side of the search bar: and give the search a name:
Later, you can redo the search by choosing it from the Go menu:
If you modify the search rules, you can click Save As again to either update the search (using the same name as before) or save it under a different name.
To rename or delete saved searches, use Suspicious Package > Preferences > Searches.
Exporting Installed Files
If you want to examine the contents of a file that would be installed, you can tell Suspicious Package to export it. Select any file or folder, and use File > Export Item (Command-Shift-E). Choose a name and location, and Suspicious Package will extract the item from the package.
Alternatively, you can export the selected item directly to your Downloads folder with File > Export Item to Default Folder (Command-Option-E). Suspicious Package will use the same name as the item being exported, unless there's already an item by that name there. To change the default folder to use for exports, use Suspicious Package > Preferences > General > Default export location.
You can also drag a file or folder out of Suspicious Package, into the Finder or onto your desktop, and it will be exported to that location.
The OS X installer package format is not optimized for partial expansion, so exporting one small item can take almost as much time as exporting everything. If you export multiple items in quick succession, Suspicious Package does its best to export them in parallel. But if you plan to export a number of items underneath a single folder, you may find it faster to just export the folder itself.
Using the Exports List
Depending on the size of the package, exporting a file or folder might take awhile. Click the Exports toolbar button to see information about running and finished exports.
If you decide you want to cancel a long-running export, click its cancel button .
To show an exported item in the Finder, click its show button .
To select an exported item in Suspicious Package, click its info button . This can be useful if you forgot where the item would be installed, or want to see what metadata it would have when installed.
Exporting Is Not Installing
The intention of Suspicious Package's export feature is to allow you to inspect the contents of installed files, and not to behave as a “partial installer.” An item exported by Suspicious Package may differ from the version installed by the OS X Installer in a number of ways:
- The exported item will be written where you specify — or in the default export location — and not where the package indicates (which is almost always some system location). Suspicious Package doesn't have any special privileges to write outside of your home folder.
- The exported item will have the owner and group of the user running Suspicious Package, and not the owner and group specified by the package (which will typically be root or some other system account).
- The exported item will have permissions that allow it to be examined, changed and deleted by the user running Suspicious Package, even if the package permissions might prevent such changes. This is done primarily so that exported items can be easily removed when you're done examining them.
- The exported item will maintain any extended attributes specified in the package — these might carry code signatures or other important information — but it will omit any access control lists, since those might prevent the item from being easily removed again.
- An application (or other bundle) might be delivered as a “delta update” to an old version. If this is the case, exporting that application won't result in a complete bundle. You can see the files that the package will actually install, but the end result will not be the same as what the OS X Installer would produce.
- Likewise, a package might deliver a file as a “binary patch” to an existing version (in bsdiff format). In this case, the item exported by Suspicious Package will be the patch rather than the result of applying the patch to the original file, as the OS X Installer would do.
If you are suspicious of a package, the last thing you want is for an exported file to be inadvertently opened, especially if it is an application. To minimize this risk, Suspicious Package will mark all exported items as if they were “downloaded from the Internet,” much as Safari does (OS X calls this a quarantine). If the exported item is opened, Gatekeeper may block it, or at least present a warning before opening, such as: Gatekeeper says that Suspicious Package “created” the file, simply because it wrote the file after exporting. If you click the Show Source button, OS X will open the source package using Suspicious Package.
Examining Install Scripts
In addition to installing files, a package can contain “install scripts,” which are run by the OS X Installer. These scripts typically run as the root user, and can do anything (with some limitations imposed by the System Integrity Protection feature of OS X 10.11).
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.
To see the install scripts that the package contains, select the All Scripts tab: Or use Window > All Scripts (Command-3).
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, 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).
The Scripts Browser
On the left side of the All Scripts tab, a browser pane shows all of the install scripts in the package.
If the package uses folders to organize its scripts — most do — these will be shown as well.
A package typically contains one or more sub-packages, each of which can contain its own set of scripts. For this reason, the scripts in the browser pane are usually grouped by sub-package.
If the top-level package also contains scripts, these are grouped under an “Installer Package” heading at the top of the browser.
The Many Flavors of Install Scripts
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.
In fact, a preinstall or postinstall script can, in turn, run other scripts, or even standalone applications. 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).
The scripts browser shows all the scripts, including any “indirect” ones. (The indirect scripts are sometimes put into subfolders within the package, but that is at the whim of the package creator.) Generally, to understand how the indirect scripts are run, you have to start at the top — preinstall and postinstall — and work your way down. Suspicious Package can help a bit by searching for where an indirect script is invoked.
Packages that come from Apple use a convention where a generic preinstall script runs all of the scripts in the sibling preinstall_actions folder — and likewise with postinstall and postinstall_actions. When you're looking at an Apple package and see this pattern, you can usually focus on the actions folder instead. But be careful not to make this assumption in non-Apple packages, because the “generic” top-level script might not actually do what you expect!
Viewing An Install Script
Most install scripts are in a plain text format — usually a scripting language like Perl, Python or Ruby, or the Bourne or Bash shell. If you select a plain text script in the browser, the text of the script will be shown in the center pane: The Info pane on the right will show metadata about the script, including some clues about how the script will be run. (If the Info pane isn't visible, click the Get Info toolbar button to show it.) The “When” field indicates which OS X Installer hook applies — preinstall (“Before moving files into place”), postinstall (“After moving files into place”) and so on. The “Arguments” table describes the command-line arguments that the OS X Installer will pass to the script, in terms of the current scripting language.
For an indirect script, the “When” will be shown as unknown. If you click the Search For References button, Suspicious Package will search for all scripts that contain the indirect script's name, and will show those matching scripts. This may help you figure out how the indirect script is used, presumably by some preinstall or postinstall script. However, keep in mind that Suspicious Package doesn't actually understand what any of the scripts do; this is just doing a simple text search.
You can also search for text within the current script. Use Edit > Find in Script (Command-Option-F), and enter the text to find in the search bar at the bottom of the center pane: Alternatively, if you select some text and want to find other instances of the same text, you can simply use Edit > Use Selection for Find (Command-E).
Unfortunately, some install scripts are not in a plain text format at all. For example, a script might be a binary (“Mach-O”) executable, which is especially opaque. (There are sometimes good reasons for having binary executables as install scripts, such as needing access to an API that can't be used from a scripting language, so this isn't necessarily a sign of subterfuge.) In such cases, you might try opening the script in another application, or if it's an indirect script, searching for references. Or, you might simply need to focus more on other evidence of trustworthiness, such as the identity of the distributor.
Opening Scripts in Another Application
If you prefer to view a script in another application — or if the script is not plain text and can't be shown — you can tell Suspicious Package to open that script differently using File > Open Item With.
Suspicious Package picks a default application (based on the script kind), which can be opened with Command-Shift-O. If you want to change the default application for all scripts of the current kind, hold down Option and use File > Always Open Kind With. This is all meant to work like the Finder's Open With feature.
You can also tell Suspicious Package to open a script with the Finder, which means that the script will be revealed in a Finder window. This can be helpful if you want to manipulate it in the Terminal, or in some application that can't directly “open” the script (but can import it or analyze it in some other way).
When you use the Open With command, Suspicious Package writes the script to a temporary location, and hands that temporary copy off to the chosen application. All of these temporary files are removed when you close the Suspicious Package window for that package. If you want to keep the script around longer, you will need to copy it somewhere else, e.g. by telling Suspicious Package to open it with the Finder, and Option-dragging it elsewhere.
Going Backward & Opening Additional Tabs
The All Scripts tab works like the All Files tab, in that it keeps a history of the scripts that you've selected. To retrace your steps, click the Back toolbar button or use Go > Back (Command-[). Or hold the Back button down momentarily to jump back to a specific point in the history.
You can also open additional Scripts tab as needed. For example, you might want to leave a script open in a separate tab to remind yourself to come back and examine it more closely. To open the currently selected script in a new tab, use File > Open in New Tab (Command-T).
Searching and Filtering in Install Scripts
In addition to finding text within a single script, you can also search across all install scripts for specific text (among other attributes). This works much the same way as searching in the All Files tab.
Searching Plain Text Content
To search for plain text scripts that contain specific text — perhaps an interesting command name — use Edit > Search Package (Command-F). Enter the text in the search field and press Return to do the search:
Suspicious Package will enable the matching scripts in the scripts browser (and disable everything else). You can then select any matching script, and the matching text within the script will be highlighted. Use the navigation buttons in the search bar to move between the matches within each script:
Filtering on Other Attributes
The plain text content of scripts is usually the most useful thing to search, but if you need more control, you can add other rules, as in the All Files tab.
First, enter search mode using Edit > Search Package (Command-F). Click the add button on the right side of the search bar. Then you can add and edit rules as needed.
Script searches can be saved for later use, exactly as for All Files searches.
Note that the Go menu will list whatever saved searches are appropriate for the currently selected tab. So you must select an All Scripts tab in order to see the saved Script searches.
Checking the Package Signature
An installer package can be signed with a digital certificate, both to identify the distributor, and to enable detection of any subsequent tampering with the package contents. Suspicious Package evaluates the digital signature and assigns a general category of “trust” to the signing certificate. It also allows you to examine the details of the entire “certificate chain.”
The Gatekeeper feature of OS X also evaluates the signature of any package that was downloaded from the Internet. With the default Security preferences — “Allow apps downloaded from Mac App Store and identified developers” — OS X will refuse to open a downloaded package that was not signed with an Apple-issued “Developer ID” certificate: more on this below.
Trustworthiness of the Signing Certificate
To see how the package was signed (if at all), select the Package Info tab: Or use Window > Package Info (Command-1).
Suspicious Package shows the name of the certificate that signed the package, along with a trust type, such as Developer ID If the package is simply not signed, Suspicious Package will say so:
The trust type is assigned by Suspicious Package, based on the validity and trust of the signing certificate. It will be one of the following:
|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. You can read more about Developer ID certificates below.|
|valid||Package was signed with a certificate that was issued by a certificate authority which is generally trusted by OS X (but which is not an Apple or Developer ID certificate). See more below.|
|not trusted||Package was signed with a certificate that is not trusted by OS X, nor issued by a trusted certificate authority.|
Package was signed with a certificate that has expired or been revoked by the certificate authority. All certificates expire after some amount of time. Or a certificate might be revoked because it has been lost or stolen.
In certain cases, OS X can verify that a package was signed before the certificate became invalid (where the signature contains verifiable time-of-signing information). Thus, a package signed by an expired or revoked certificate might still be classified with one of the above valid trust types.
|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.|
Gatekeeper and Developer ID
A “Developer ID” certificate is issued by Apple under the Gatekeeper program. Developers registered with the Apple Developer Program can get Developer ID certificates, and use them to sign their packages (and applications). Suspicious Package assigns the Developer ID trust type to packages signed with a valid Developer ID certificate.
Since Developer ID certificates are tied to the Apple Developer Program, and since that program usually requires real names (or other proof of legal status, e.g. for a corporation), the name of a Developer ID certificate is a bit more likely to be meaningful. (But note that Apple doesn't make any explicit promises about vetting of Developer ID identities; see the Developer ID Certification Practice Statement on the Apple PKI page).
Like any certificate, a Developer ID certificate proves only identity (at best) and not benign intent. Apple doesn't know that someone enrolled in the Apple Developer Program won't try to distribute malware. But if Apple discovers that a Developer ID certificate is being used for that purpose, they have the ability to revoke the certificate (and in all likelihood, terminate the developer's account). Apple can also revoke a certificate at the developer's request, if the certificate has been lost or stolen.
Suspicious Package assigns the revoked trust type to packages signed by a revoked certificate (unless it can be verified that the package was signed before the certificate was revoked). Gatekeeper will also prevent such packages from being opened in the OS X Installer.
Interpreting Other Valid Certificates
Although Developer ID certificates have special status for Gatekeeper, a package can instead be signed with a certificate issued by another certificate authority. As long as the certificate authority is trusted by OS X (and the signing certificate otherwise checks out), Suspicious Package assigns the Valid trust type.
That said, a certificate issued by a third-party certificate authority may actually tell you very little. There are different standards of validation for certificates; for example, domain validation requires only that the requestor demonstrate control over a domain name — and the certificate identifies nothing more than that domain name. How much this is worth depends on much you trust the organization that owns that domain name — and how confident you are that you know who owns that domain name!
Also keep in mind that no certificate proves benign intent, only some level of identity. Arguably, a third-party certificate authority has less interest in tracking how certificates are used, simply because they have no vested interest in the security of the OS X platform. So there's that.
Fortunately, with the advent of Gatekeeper and Developer ID, there is not much reason to use third-party certificate authorities for signing OS X installer packages (or applications), so you are unlikely to see them very often.
Packages signed with third-party certificates, even if trusted by OS X, will not be allowed to open by Gatekeeper. Indeed, you may find that you can't even open them in Suspicious Package. If you want to override Gatekeeper — at least to open them in Suspicious Package — you can Control-click on the package, and choose Open With > Suspicious Package, and Gatekeeper will give you the option of opening the package despite the signature issues.
Inspecting the Complete Certificate Chain
Occasionally, you may want to see more information about the signing certificate, or the certificate authority that issued it.
On the Package Info tab, click on the package signature line: Or use Window > Signature Details (Command-5).
Suspicious Package will then display the standard OS X certificate trust sheet: If you click Show Certificate, you can see the complete information about the signing certificate, and the entire chain leading to the certificate authority.
Detecting a Modified Package
Once you've determined that you trust the signing certificate, there's still one more piece to the puzzle: ensuring that the package wasn't modified after being signed by the certificate.
Upon opening a package, Suspicious Package begins checking for various potential issues in the background. Using the signature to detect possible tampering is one of these checks. (It is done in the background because it can take a significant amount of time, especially for large packages.) If a problem is found, Suspicious Package will flag it as a critical issue: see Reviewing Potential Issues.
The OS X Installer will do the same verification of the signature. If this fails, the OS X Installer will stop with an error before any file has been installed, and before any install script has been run. So, waiting for Suspicious Package to do the verification is not strictly necessary, but if you're particularly suspicious of a particular package, you might want to let it do so anyway.
Reviewing Potential Issues
When you open a package in Suspicious Package, it loads information about the installed files and the install scripts, and then it begins to check the package for a number of potential issues. You can go ahead and examine the installed files and scripts while these checks run. The Review toolbar button will show the progress of these checks , and will change to show the result when the checks are complete .
If Suspicious Package finds any potential issues, you'll want to review them before deciding that the package is safe to install. Click on the Review toolbar button and then click Review Details. Or use Window > Review Details (Command-4).
Either way, Suspicious Package will open a new tab named Review: Here you can see descriptions of each of the potential issues. For some issues, there will be a button to get additional information.
Suspicious Package attempts to classify issues by severity. Critical issues are generally clear-cut problems that should raise a red flag. Warnings are suspicious, but after understanding what is going on, you may wish to proceed. Informational issues are typically of minor interest. Of course, these classifications are all somewhat arbitrary, so you should read and understand all issues before deciding to install the package.
Especially for large packages, the review may still be in progress when you are ready to proceed. If you close the window — or tell Suspicious Package to open the OS X Installer — before the review is complete, it will warn you that you may wish to wait for the review to finish. Obviously, this is only relevant if you have made the decision to install the package.
On to the OS X Installer?
Presumably, the reason you've spent all this time examining a package is to install it. Once you've made the decision to do that, you can quickly open the package in the OS X Installer by clicking the Installer toolbar button or using File > Open in Installer (Command-Shift-I). If you hold down Option while doing either, the package will be automatically closed in Suspicious Package after the OS X Installer opens.
Using From Quick Look
Suspicious Package also includes a plug-in for the Quick Look feature of OS X, so you can get a quick preview of a package right from the Finder. Select a package and use File > Quick Look (Command-Y), or just press the spacebar: Suspicious Package will generate a preview, from which you can see the installed files, the install scripts, and some other general information, such as the signature trust type:
The Quick Look preview doesn't show everything that the app does, and doesn't offer all of the same features (mostly because of the fundamental limitations of Quick Look). For example, you can't do any sort of searching or filtering of files or scripts; copying of script text or opening scripts in other applications is impossible; and no checking is done for potential issues.
Back to the App
If you're examining a package with the Quick Look preview and want additional information, click the Open in Suspicious Package button (in the top-right corner of the preview) to open the same package in the app.
To jump directly to a specific installed file or folder in the app, hold down the Command key, and click the Show in Suspicious Package button that appears: To jump directly to a specific install script in the app, select the script in the browser, and click the Show in Suspicious Package button next to the script name: