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
- 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
- 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. This may make the value more recognizable, in some cases.
You can click the adjacent 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
- To copy the selected data value to the clipboard, click the Copy toolbar button
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
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.