Archaeology

Frequently Asked Questions

Looking for something specific? The User Guide, Formats, Reversing Topics and FAQ are indexed within the app — open Archaeology, click on the Help menu (Command-?), and type in the Search field. Results listed under Help Topics link directly to the appropriate section here.

Installing Archaeology

What versions of macOS does Archaeology support?

Archaeology supports:

About Archaeology on the macOS 26 (Tahoe) Beta. We've done limited testing of Archaeology on the macOS 26 betas, and are not aware of any Tahoe-specific problems. However, if you run into any, we would appreciate your telling us about them.

Does Archaeology automatically check for updates?

Yes, once every 2 weeks — or less, if you use it less often — Archaeology 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

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

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

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

Understanding Archaeology

Is Archaeology “sandboxed”? What entitlements does it have?

Yes, Archaeology is sandboxed. You can examine the entitlements using Apparency or Archaeology itself.

To quickly open Archaeology using Archaeology, use Cmd-Option-O. Select and decode Code Signature for one of the architectures, and then decode Entitlements (or DER-encoded Entitlements).

However you view them, you'll see that Archaeology has the following entitlements:

Entitlements for the Archaeology application
Entitlement KeyValueReason
com.apple.security.files.user-selected.read-write YES This allows Archaeology to see the file or directory that you tell it to open — even if it's in a place that is not otherwise accessible to sandboxed apps, such as inside your home folder.

Archaeology requests the read-write rather than the read-only entitlement, not because it ever writes to the file you open (it doesn't) but in order to make the File > Export Value As feature work (i.e. by giving Archaeology the ability to write to the file that you designate).

com.apple.security.application-groups 936EB786NH.com.mothersruin.MRSFoundation.ASN1AnnotationStore This declares an app group container that Archaeology shares with our other apps. This group container is used to store the comments that you annotate to ASN.1 data. This is sideband data, by definition. We store it in this group container on the theory that it could be used and loaded by another app that shows ASN.1-format data — although at the moment, we don't do this elsewhere.
com.apple.security.temporary-exception.mach-lookup.global-name com.apple.security.syspolicy This allows Archaeology to talk to the /usr/libexec/syspolicyd daemon, which is required to check notarization status. Archaeology uses this to evaluate a Code Signing Requirement, if it includes a notarized term.

Within Archaeology, there is one other component that is also sandboxed, and thus has explicit entitlements. 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:

Entitlements for the com.mothersruin.MRSFoundation.UpdateCheckingService.xpc component
Entitlement KeyValueReason
com.apple.security.network.client YES This allows the XPC service to make an outgoing network connection, in order to fetch this file, which contains the information about the current version of Archaeology available for download.

Why did Archaeology add a “quarantine” to the file I opened?

When you download a file in your web browser, macOS records how and where it was downloaded. If the file is an app (or another “potentially dangerous” kind), this tells macOS to activate Gatekeeper when the app is first opened. (If the file contains an app, as in the case of a disk image or zip file, the download information gets copied along with the app. So even after you've dragged the app to your Applications folder, macOS still knows that the app was downloaded.)

Usually, the result of Gatekeeper is an alert, saying that the app was “downloaded from the Internet,” and asking you if you still want to open it. However, depending on the kind of downloaded item — and whether it is signed and notarized — Gatekeeper alerts can get more alarming. In modern macOS, you sometimes have to go to System Settings to override Gatekeeper and open the app.

macOS uses the term quarantine to refer to this download information. That is, in between when you download a file, and when you click OK in that Gatekeeper alert, the file is considered to be “in quarantine.” This information is stored in an extended attribute on the file, named com.apple.quarantine. Once you've allowed Gatekeeper to open the app, it is no longer considered quarantined (but the attribute usually remains, slightly modified to indicate that the file was approved to open).

For files that you've actually downloaded, this is all straightforward enough. However, after the advent of the App Sandbox, macOS started applying quarantine to more than just download scenarios. In modern versions of macOS, any file that is “touched” by a sandboxed app is generally marked as quarantined by that app. Whether or not that triggers a Gatekeeper alert depends on the kind of file. If the file's a Mach-O executable, for example, it most certainly will trigger Gatekeeper. But there are other, less obvious kinds of files that Gatekeeper might consider potentially dangerous — including some document types, and even unknown file types (which is probably because macOS isn't great about recognizing some executables, such as those with period characters in the name).

What constitutes a sandboxed app actually “touching” a file, and thus triggering quarantine? Basically, any time that the app opens a file that it could write to, even if it never does so.

Archaeology acts solely as a viewer of the files you open. If you examine its Info.plist, you'll see it declares its CFBundleTypeRole as Viewer. But to make the File > Export Value As command work, Archaeology must be entitled for com.apple.security.files.user-selected.read-write; otherwise, the Save dialog won't appear.

As a result of this entitlement, when you choose a file using File > Open, macOS gives Archaeology a security-scoped URL that grants read-write access (even though we want and need only read access). Later, AppKit persists the URL on our behalf — both for managing Recent Items, and for the window-reopening Resume feature — by making a security-scoped bookmark. AppKit creates this bookmark as read-write (that is, it doesn't use NSURLBookmarkCreationSecurityScopeAllowOnlyReadAccess), simply because the calling process could write the file. Creation of the read-write bookmark begins by calling open(2) with O_RDWR, and that triggers macOS to quarantine the file.

The above applies to regular files, but not to directories. This prevents a sandbox-based quarantine from being added to apps and other bundles. Also, if you select a file that you don't have write access to — such as something installed with root ownership — Archaeology gets a proper read-only URL, and no quarantine is triggered.

Starting in version 1.4, Archaeology jumps through some extra hoops to minimize this annoying quarantining effect. Basically, any time that Archaeology receives a read-write URL from macOS, it attempts to coerce that URL to be read-only, such that its write access is revoked and only read access is persisted via bookmarks. In addition to the File > Open scenario described above, this applies to other scenarios where macOS might hand us a read-write URL — including dragging a file from the Finder, and using the open(1) command. This Archaeology change should greatly reduce the application of unnecessary and confusing quarantines.

How does Archaeology go about coercing the URL to be read-only? It ain't pretty:
  1. Upon being given a URL to open via -[NSDocumentController openDocumentWithContentsOfURL:display:completionHandler:], Archaeology checks to see if the file is writable. This should only be the case if the URL is security-scoped with read-write access. If not — or if it's not a regular file — we leave it alone.
  2. If the URL appears to grant us write access, we first save the read part of this access by creating a non-security-scoped bookmark, which includes a sandbox extension (sometimes called an implicit security scope for extra confusion). Normally, this saved sandbox extension would reflect the access of the calling process, which is still read-write at this point. However, we add the private NSURLBookmarkCreationOptions value at bit 30 (0x40000000), which limits the sandbox extension to com.apple.app-sandbox.read regardless (see more on the private bookmark creation options here).
  3. Having saved our read access, we need to revoke our write access, by sending -[NSURL stopAccessingSecurityScopedResource] one or more times. This has two purposes:
    • It removes the read-write sandbox extension (associated with the original URL) from the SandboxExtensionCache maintained by the CoreServicesInternal framework. This cache is keyed by the underlying file path (not by individual URL objects). If the original extension remains in the cache, it prevents our new read-only extension from getting attached in step 4 below.
    • It ensures that, when AppKit builds security-scoped bookmarks on our behalf, it will make them read-only, because we actually lack write access. It isn't enough that the security-scoped URL being bookmarked specifies read-only access; if the calling process has write access, the bookmark will be made that way. (Remember, it is the creation of a read-write bookmark that triggers the quarantine.)

    Yes, we did say that we send -stopAccessingSecurityScopedResource one or more times, which is ... dubious. Unfortunately, at this point, the read-write URL has had its sandbox extension consumed multiple times, once by the open panel machinery and once by the document controller. If we only stop accessing once, we might clear the cache without actually relinquishing write access.

  4. Finally, we resolve the bookmark that we created in step 2. Because that bookmark contains only a com.apple.app-sandbox.read extension, and because there is nothing else cached for this file path by CoreServicesInternal, we'll get back a security-scoped URL that is read-only. This URL also automatically gets sent -startAccessingSecurityScopedResource by the resolution code (i.e. we don't specify NSURLBookmarkResolutionWithoutImplicitStartAccessing). We now have a proper read-only URL and have only read access to the referenced file. We continue the document opening process with this new URL.

See how easy that was?

If you're using macOS 12 (Monterey), you may find that Archaeology continues to quarantine the files that it opens. On Monterey, the Recent Items mechanism (the SharedFileList framework) doesn't seem to use security-scoped bookmarks, but simply creates read-write security-scoped URLs out-of-process (in the sharedfilelistd agent). As a result, although we start out properly treating the file as read-only, it gets converted to read-write (and quarantined) as soon as the Recent Items are updated.