What are the best practice methods for documenting research into the reverse engineering of a file format?

Question

I a conduct research requiring the reverse engineering file formats, and I am currently looking at ways of documenting that work.

On the web you will find resources that use box diagrams and free text. For example, this attempt to look at Microsoft Access: https://github.com/brianb/mdbtools/blob/master/HACKING

This is fairly consistent with the approach taken in ISO specs for formats.

This type of work is part of what I do professionally but I haven't come across anything to help me store my information in a consistent and useful manner for anyone else - months down the line it might not even be useful to me.

Is there a 'community' best practice (methods, tools, authoring tools etc.) to help document research into a file format?

Answer 1

Concur with V and only throwing out some thoughts.

In general would say that one, (of course), has to clearly denote holes as black or gray. As in "no idea" or "several possibilities".

Beside file format specifications openly distributed I find the style used by RFC's to be one I adapt frequently. All depending on context using such things as Augmented Backus–Naur Form as shown here.

Use truth tables and logical expressions to assert unambiguity.

Else there is e.g. 3GPP and the like which one also can learn from.

If you want to go for the good ASCII style use tools like asciiflow for flow diagrams etc. Have found myself that using ASCII often helps me writing more clear documents and split diagrams into layers of more understandable form. Perhaps one can learn something from phrack as well.

If not plain text then LaTeX as it is very nice for organizing documents. Separate out each section into own files that one include. Shuffling around sections become easy as do indexing etc. And the product looks great on paper. – This can of course also be done in some way with plain text.

As with any approach (I) always use Git and commit very frequently with short concise comments.

Answer 2

In the past my reverse engineering efforts of file formats were documented in source, i.e. 010 Editor binary templates. If you know C, this is pretty descriptive, but it has its limitations and at times it can get a bit convoluted when trying to express certain more exotic concepts. Another issue with the tool as such is the slowness with larger scripts on larger files and the lack of an extension mechanism beyond the scripts and binary templates (such as plugins).

A widely used alternative, to mentioned Augmented BNF, is ASN.1 (permalink). I prefer the BER encoding (see previous link to Wikipedia article), but your mileage may vary.

For graphical representations I have used LaTeX (with bytefield, PDF) and Visio.

Answer 3

Like @0xC0000022L, I tend to document first in source, or in something that can immediately be re-used in a tool (unlike a pure text documentation).

A generic approach is to use a hex editor that has some abilities to annotate or describe structures

with coloring abilities

• wxHexEditor nice, simple, good
• BinID2 lightweight, straightforward

with templates

• 010 editor many templates available, lacks easy manual coloring, but recommended
• hex workshop nice competitor, limited scripting and availability
• Hex editor Neo interesting features (multiple selections) but heavy

with structures

• IDA: this can sound weird to use IDA as a hex editor, but you can create structures (or import them from a .H file), then apply them, create a script to chain them - and in the end you have a ready-made IDAPython script and the structures ready to use for the next time you encounter that format: you build the future tools progressively and skip the documentation text part ;)
  • even better, it enables you to re-create the file from scratch with these defined structures, which is good for experimenting/fuzzing afterwards.

Answer 4

I can't think of anything more "standard" than block diagrams, a pseudo-code implementation, and possibly a reference implementation.

Take for example the FIPS standard here or the LUKS standard document. They provide a basic narrative of functionality, pseudo-code, and in the case of OGG/OGV even a full reference implementation. A standard you took apart, in my opinion, should be documented the same way a standard you designed is documented. Some fields may be "unknown" or "seems to be magic, just leave it".

I don't think you'll find anything more standard than that is. If you don't mind posting a document and a parser, github/bitbucket/etc are great. Some of the other file format questions point to Wotsit.org (I look there), so submitting a link there could be a good thing as well.