Archaeology

A User Guide

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.

Opening a File in Archaeology

There are several ways to open file using Archaeology:

Whichever method you choose, Archaeology examines the file to identify the binary format and — assuming it is a format that Archaeology recognizes — opens a new window with the best representation possible: Archaeology main window

In this example, the binary data is in BER-encoded ASN.1 format, as shown on the right side of the window, under the toolbar.

The representation underneath will vary with the actual format: see Formats for how to navigate each supported format. Or click the Help toolbar button Help toolbar button to directly open the format-specific documentation for the current representation.

Archaeology tells macOS that it can open any kind of file, because binary formats are often used without file extensions, and might have any Kind, or a generic Document one. Archaeology does its best to decode whatever you open, but if it doesn't find a format it recognizes, it will say that the file “contains data in a format that can't be decoded.”

Decoding an Embedded Data Value

Depending on the file and its binary format, you will often find an embedded “chunk” of data that is further encoded in some way. In Archaeology, this will appear as an item whose contents is described as “X bytes of data” or in the ASN.1 format, as an item with a tag like OCTET STRING.

In this case, you can ask Archaeology to further decode this chunk of data. Select the item and click the Decode toolbar button Decode toolbar button or use Go > Decode Item (Cmd-Down Arrow). Assuming that Archaeology recognizes the format of the data, it will decode it and show a new view, replacing the file that it came from.

Each time you find another embedded chunk of data, you can continue recursively decoding in this manner.

Of course, not every chunk of data will be decodable. Some have formats that aren't known or supported by Archaeology. Some are unique identifiers or cryptographic hashes of some sort — it's not uncommon to come across SHA-256 digests or the like. (If you come across data that is exactly 16, 20 or 32 bytes, it's very likely a digest of some sort, for example.) However, you can always ask Archaeology to try. If Archaeology can't decode a specific chunk of data, you might learn more by inspecting the value info.

If, at any point, you want to go back to the previous (containing) view, click the Back toolbar button Back toolbar button or use Go > Back (Cmd-[). To go back multiple steps at once — or just to see where you've come from — hold down the toolbar button briefly: Hold down the Back button

Most of the time, Archaeology will figure out the best way to decode a chunk of data (if it can decode it at all). But there are a few cases where data can be decoded in different ways — such as Cocoa Keyed Archives, which are also macOS Property Lists. To override Archaeology's default choice, hold down the Decode toolbar button briefly, and choose a specific format: Hold down the Decode button

Getting More Info About a Data Value

In addition to asking Archaeology to decode an item containing a chunk of data, you can see some general information about that chunk. This can be especially helpful where Archaeology doesn't know how to decode the chunk in question.

To show this additional information, select the item and click the Info toolbar button Show Info toolbar button or use File > Show Value Info (Cmd-I): Show Value Info inspector

From this data value inspector, you'll find the following information:

The Open in Hex Editor and Export Data Value buttons are simply shortcuts to the integration features described below.

Moving a Data Value to Another App

Archaeology provides a few ways to get a specific data value into another app or Terminal command:

Searching the Decoded View

For some binary formats, Archaeology allows you to search in the decoded data. For example, you can search a Cocoa Keyed Archive for specific keys, class names or string values; you can search a macOS Property List for keys or values.

If searching is possible for the current view, the toolbar search field will be enabled. Click in the search field (or use Cmd-F) and enter text: Search Field in toolbar

Press Return to perform the search. How the search results are shown varies with the binary format: see Formats for details.

To change which aspect of the decoded data is being searched — keys or values, say — click the search button Search button in toolbar search field inside the search field.

Exporting the Decoded View as Text

Archaeology allows you to export the decoded data in a text format, optionally performing a recursive decode of every embedded data value that's in a supported format. This can be helpful if you don't know where the data you're seeking is actually buried, since you can then search the entirety of the exported text for clues. It can also be helpful if you're trying to compare two versions of a binary file.

To export a text version of the decoded data — as currently shown in the active Archaeology window — use File > Export Item As Text (Cmd-Shift-D), and then choose where you want to export the text file. By default, Archaeology will attempt to recursively decode every embedded data value it finds, but if you want to disable that, uncheck Show as decoded text if possible before clicking Export.

The export starts from the currently-shown data, so you can drill down into a file first, and then export only that portion (recursively, if you wish). If you know you want the entire file, however, you can avoid having to navigate back to the top-level first by holding down Option and choosing File > Export Entire File As Text.

The exported text generally uses the same format as the Archaeology app. Each time that Archaeology starts a recursive decode, it inserts delimiters like so:

[BER-encoded ASN.1]
SEQUENCE
   OBJECT ID Signed Data ( 1.2.840.113549.1.7.2 )
   context-specific tag 0
      SEQUENCE
         ...
         SEQUENCE
            OBJECT ID Data ( 1.2.840.113549.1.7.1 )
            context-specific tag 0
               OCTET STRING <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<{ [macOS Property List]
                  AppIDName = “Apparency macOS”
                  ApplicationIdentifierPrefix = [array of one item]
                     item 0 = “936EB786NH”
                  CreationDate = 12-7-2025, 10:18 AM
                  ...
                  UUID = “178438d1-4c55-44b2-8699-69fd2edf3294”
                  Version = 1 [0x1]
                  }>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

We chose this format to make it easy to find each recursive decode, by searching for <{, and to make typical source code editor navigation techniques work on the { and } characters.

You can also control how Archaeology outputs embedded data values that are not decoded — either because you disabled recursion, or because the data is an format not supported by Archaeology. From the Show undecoded data as pop-up, choose one of the following:

For any option other than size-only, Archaeology inserts the same delimiters as for recursive decodes, e.g.:

  SEQUENCE
     OBJECT ID Message Digest ( 1.2.840.113549.1.9.4 )
     SET
        OCTET STRING <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<{ [20 bytes of data]
              -----BEGIN HEX DATA-----
              8c63316ce16ed451ee0e14d73a394407227dcb94
              -----END HEX DATA-----
           >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>

Especially if you're trying to compare two versions of a decoded file, you may find it more convenient to export using the trowel CLI tool, as described below.

The “trowel” Command-Line Tool

Archaeology provides a command-line tool — called trowel — that can be useful when you're working in the Terminal. You can use it to open a file in Archaeology by path, without needing to go through the File > Open dialog. You can also specify the expected format and other options.

The trowel tool is delivered inside the Archaeology application bundle, but consistent with our philosophy that you should decide when and how to install software on your Mac, the app does not try to install the command line tool for you.

The easiest way to use trowel is to make a symbolic link to it, inside some directory that is already in your shell's search path. You can get the path to the tool (regardless of where Archaeology itself is installed) by using Help > About the Command-Line Tool, and clicking Copy Path to “trowel” Tool. Then paste that into a Terminal command something like this:

ln -s ⌘V /usr/local/bin

Run trowel with no arguments to see usage information.

The trowel tool relies upon other resources inside the Archaeology application bundle, so don't try to copy or hard-link the tool somewhere else, or it will simply abort when you try to run it. A symbolic link works because the executable can still find the rest of Archaeology relative to itself. If you don't want to use a symbolic link, though, you can use any other mechanism that expands to the actual tool path retrieved through Copy Path to “trowel” Tool, such as a shell alias.

Exporting as Text to Compare Binary Files

As described above, Archaeology can export the decoded data in a text format. You can also do this directly from the command line, using the trowel tool's ‑‑text option, which causes the decoded data to be output to the standard output (instead of opening the Archaeology app). You can enable recursive decoding with the ‑‑recurse option, and select the handling of undecoded data using the ‑‑data‑style option, as described in the usage.

Exporting via trowel can be useful if you're trying to determine what changed between two different versions of the “same” binary file.

For example, let's say you're trying to determine why all of your apps are suddenly flagged by VirusTotal as delivering MS-DOS malware. You've managed to narrow it down to one compiled nib file (don't even ask how), but what specifically triggers the false positive? No, problem! You have source control, and can diff the xib source files, right?

$ git diff MRSAppKit-1309 MRSAppKit-1415 -- Base.lproj/DataSelectionInfoView.xib
# dozens and dozens of meaningless diffs omitted

Oops, you had the temerity to open the xib file in a different version of Xcode, which helpfully rearranged all the XML attributes and tweaked frames that have no effect whatsoever on the end result. So much for easily isolating what actually changed in the compiled nib file!

But what if you could diff the compiled versions directly?

$ diff <(trowel --text 1309/DataSelectionInfoView.nib) <(trowel --text 1415/DataSelectionInfoView.nib)
2251,2252c2251,2252
<    NS.bytes = [15 bytes of data]
<    NS.bytes ➔ UTF-8 string = “Copy data value”
---
>    NS.bytes = [50 bytes of data]
>    NS.bytes ➔ UTF-8 string = “Copy data value; ⌥-click to copy in format shown”
2259,2260c2259,2260
<    NS.bytes = [15 bytes of data]
<    NS.bytes ➔ UTF-8 string = “Copy data value”
---
>    NS.bytes = [50 bytes of data]
>    NS.bytes ➔ UTF-8 string = “Copy data value; ⌥-click to copy in format shown”

Oh, right, you changed a tooltip. (Yes, the Unicode character U+2325 is a virus.)

This is all, of course, wholly theoretical, and has nothing to do with why we thought that someone else might get value from this whole export as text nonsense.