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:
- In Archaeology, choose File > Open, locate the file and click Open.
- In the Finder, locate the file and drag it onto the Archaeology icon, either in your Dock or in your Applications folder.
- From the Terminal, use the “trowel” command-line tool to tell Archaeology to open a given path.
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:
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
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
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
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:
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
From this data value inspector, you'll find the following information:
- Source File shows the actual file that the data value was found in,
which might be different than the item you opened (especially for File TOC
types that are really bundles). Click the adjacent Show in Finder
button to reveal the actual file.
- Size of Value shows how large the data chunk is.
- Offset in File shows where the data chunk resides within the Source File,
if Archaeology can figure this out. (This will depend on the file format, and on the format of any
recursive decodes that were performed to get to this point.) If the offset is known, you can
click the adjacent Copy button
to copy a Terminal command that will extract this precise chunk of data from the Source File (which you can then pipe into some other command).
- Hex Encoded shows the actual data in hexadecimal encoding — or up to one line's worth.
If you click on this hex representation, Archaeology will insert a space between every byte; click again to
change the number of bytes per group. If the value appears to be a UUID, Archaeology will also show a
UUID-formatted version as you click through the representations. This may make the value more recognizable,
in some cases. You can click the adjacent Copy button
to copy the hex-encoded data value to the clipboard, as discussed further below. If you want to copy the shown representation (i.e. space-separated groups or UUID formatting), hold down Option when clicking the Copy button.
- SHA-1 Digest and SHA-256 Digest show the result of calculating the named digest algorithm against the data value shown. Whether or not these digests have any meaning is unknown to Archaeology — it just provides them as a convenient alternative to copying out the value and using an external app to hash it. (The example above is one where the SHA-256 does have meaning: this digest of the “Code Directory” is the code signing digest or cdhash value.)
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:
- To export the selected data value to a new file, click the Export toolbar button
or use File > Export Value As (Cmd-Shift-E).
- To copy the selected data value to the clipboard, click the Copy toolbar button
or use Edit > Copy Data (Cmd-Shift-C).
Archaeology places the data value on the clipboard as a hexadecimal-encoded string. We've found this to be the most useful form for getting into other apps. (There isn't really a widely-understood clipboard type for arbitrary binary data, as far as we've found.)
- To open the selected data value in another app — presumably, one that can view or edit arbitrary
binary data — use File > Export Value in Hex Editor (Cmd-Option-E).
Archaeology writes the data value to a temporary location, and asks the other app to open it. Use Archaeology > Preferences > General > Open values in hex editor to change the app that Archaeology uses for this purpose.
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:
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
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:
- Size of data only. This option is the most compact, showing only the number of bytes of data.
- String if printable, else hex-encoded data. This option tries to interpret the data as some sort of string, using various enodings, and shows that string if it appears to be entirely printable; otherwise, it falls back to showing the hex-encoded data.
- SHA-256 digest of data. This option shows only a digest of the data, which keeps the output compact regardless of the size of the data, while still allowing you to detect when the value has changed (from, say, a different version of the file).
- SHA-256 digest, unless hex encoding is shorter. This option shows a digest of the data, unless the data itself is shorter, in which case it shows the hex-encoded version.
- Complete hex-encoded data. This option always shows the complete hex-encoded version of the data, no matter how large it is.
- Complete Base64-encoded data. This option always shows the complete Base64-encoded version of the data, no matter how large it is.
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.