security research repository of nathan andrew fain / cyphunk

Workflow for hardware security analysis

My workflow for threat weighted hardware analsysis or research has changed with time. Slight uniformaty has found its way into my routine which is helpful for cross referencing knowledge between projects. With the curse of multitasking projects a constant this also reduces the time required to switch between projects or pickup on an old project. I’d like to share this with those that might have interest or comments for improvement. The organizational steps tend to reflect the actual structure I use for filing resources and data i gather. Note: this is for target/threat weighted research or analysis. This structure will probably not apply when the goal is weighted differently.

First, the directory structure:

  • Attacks (segmented by attack class with logs on attempts and all information needed to replicate)
  • Logs (all non-attack specific notes and logs)
  • Photos
  • References (datasheets, application notes, documentation)
  • Reports (information used to document or report findings)
  • Tools (software, schematics, non-attack specific custom built tools)


  1. Objectives
    This isn’t represented as a directory but instead typically the first note sheet I start to write and store in the Logs directory. An objective comes from either a client or research goals. With clients this might come in the form of their general concern or attack vectors. For research this is often in the form of low hanging fruit (objective milestones).
  2. References
    Build an overview of the device by determining the function and relation between components. Meaning, find all the datasheets or application notes you can, store them here and read them. I typically have a separate note sheet with very short summarization of this information which I store in the Logs directory.
  3. Targets
    Again, not a directory. When I find a pin cluster I will test all the electrical characteristics (resistance to GND, voltage levels at different states, etc). I make note of these either on note sheets or visual notations and I store both in the Logs directory. electrical_10pinheader.txt, electrical_4pinpad.txt, electrical_3statebusctrl.txt, network_TCPIPstates.txt, firmware_interestingSymbols.txt, etc. This becomes extremely useful information not just for the current project but for cross referencing in future projects.
  4. Attacks
    Make a sub directory for every class of attack (jtag, serial, i2c, spi, firmware, network, etc). If and when we have to build specific tools or record results, all of it will be here. In this case, for notes I store them with each attack, not in the Logs directory.
  5. Reports
    When an attack is note worthy, be it a success or not, I will copy the relevent photos, notations, to this directory so that writing reports or documenting the work at the end is easier.

Additional repositories that are useful:

  • Photos
    Take photos of everything. This is essential for documentation.
  • Tools
    If I have to download software libraries, tools or schematics for building software or hardware tools I will store the originals here. If I write wind up writing custom code for e a specific attack ill store it in its attack directory (with dependencies here). Otherwise if it is a custom made tool used across many attacks I will store it here as well. Some of the tools I find useful eventually find their way into the sectk github.
  • Logs
    All Notes or logs that do not relate to a specific attack go here. Such as general network captures, logic analysis logs, electrical testing notations, etc. At times I will go off on a general hunch that has no clear attack, target or objective and I will store the logs in a subdirectory. Also, any time I am working with software or a terminal (console) I keep a screen log (man screen) of the work and store and label these here as “screen_weekN_dayN.log”. I have one or two logs for every day while I am working on the project which gives me a very low level point to return to if I need to find something later that I might have forgotten to document. To retain absolute continuity of these logs I always append to the log for each day and when the log needs to be included in a directory for a specific attack I will copy it to that directory, retaining the original here.

Idealy all information should be digestable by one person. Verbose notes and documentation are essential for tracking down methods and pecularities later but ultimately you want to be able to quickly document the essentials either to pass on others, share with the community or include in a report to your client. I haven’t found a good medium between detail and summary in an active way so what I tend to do with my notes is repeat prior knowledge required to replicate findings, even if the information was already noted earlier in the same note sheet. The result is that when going back over notes one would start at the very end of the note sheet and work their way back up. Often times I will make note of this at the top of the sheet when I feel I have reached a closure point for the thread.

These are simple basic suggestions that are absolutely unexciting but often helpful. My experiance has been mostly with embedded analysis but this field can quickly forge into software level reverse engineering so this structure can be applied to some degree there as well. I would be elated if anyone has constructive suggestions or would like to contribute link or comment on their own workflow.


Published by

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s