Category Archives: Preaching

A short wishlist for tool writers

Posted on by

2019-01-20: Updated to add Brian‘s suggestion.

Prologue

We have got so many tools now. It’s like almost every week there is a new tool, plug-in, or their update announced.

Happy days!

Yet, many of them still surprise us with deficiencies that should be very well understood by now. Ones that we should not really see in 2019 anymore.

Exhibit #1.

No binaries.

Rant:

Yes, we know that everyone loves compiling binaries from sources, but seriously… who does, really?

Especially that it compiles in your build environment, but it doesn’t in others. And obviously everyone who wants to test your program is an experienced developer.

Re-creating your build environment means installing same compilers, make tools, dependencies, often libraries or packages that are no longer obtainable in versions you have installed. At this stage the build environment is already different from yours.

And once the environment is ready, everyone loves spending time fixing various code issues, suppressing or ignoring warnings, adding missing header files, and often even modifying building commands.

It often takes a few hours. (In fairness, I must bow here to Mimikatz and SQLITE3 authors – their code compiles like a charm!)

Wishlist item:

If you build a tool for yourself, keep it to yourself. If you write for everyone then please ship binaries that give everyone a chance to try your software w/o wasting time on building. Not everyone who will, is a developer. Not everyone who is a developer, will.

Exhibit #2.

Missing dependencies.

Rant:

@#$%^&*

Wishlist item:

Static linking, or adding prerequisite to install Microsoft Visual C++ Redistributable Package may help in this case.

But actually…

This is not a library problem. It is a testing problem.

Yes, all works perfectly in your build environment, but have you tried running it outside of it? The dependency issue would be immediately visible if you tried to run it on a plain vanilla OS, ideally a few of them, and lo-and-behold – if you tried on non-English OS versions too.

Exhibit #3.

Portability and backward compatibility is dead.

Your program only runs on Windows version XYZ.

Rant:

So, you write the tool with the latest, shiniest compiler. It just happens to include requirements, or dependencies that make it work only on a specific Windows version, or up. Nothing in this program actually uses any of the specific features of Window version XYZ or up, as it relies on Windows API available since Windows 95, but… the program won’t work on older versions of Windows.

Wishlist item:

Of course, test it on old versions. if it doesn’t work, find out why:

  • Is it the compiler? See if you can change flags, or settings. Can you use an older version of the compiler?
  • Is it a static linking to a DLL or an API introduced in recent years? Load the DLL / resolve the API dynamically. Note that many sysinternals tools are still backward compatible, because they do it exactly this way!
  • Is it a very demanding value of MajorOperatingSystemVersion / MajorOperatingSystemVersion (OS version required to run the program that is simply too high w/o any reason) ? Adjust them during the build process in an automatic fashion.
  • Is it a dependency on a library that doesn’t work on older versions of Windows? Fair enough, you can either find a different library, or make it clear that this is the reason the software doesn’t work on older versions.
  • Also, perhaps double-check if the troublesome library provides the service that is used all the time, or only in certain, rare instances; consider making certain features available dependent on the availability of such library that could be loaded dynamically; this way the program can still do most of its work on older OS versions.
  • Test the final product on older versions of Windows.

Exhibit #4.

Tools crashing. Often during the first run.

Rant:

@#$%^&(*

Wishlist:

  • detect & resolve dependencies (f.ex. on specific .NET versions)
  • handle these exceptions; this is so much easier now than 20 years ago – it’s a built-in feature for us to use
  • more code review?
  • more error checking?
  • more testing in general?

Exhibit #5.

Tools showing so much that they eventually show nothing.

Rant:

We know that many tools are POC so it’s hard to let go. Anytime you look at the problem e.g. file format parsing, you do need to include all the possible fields, and highlight all the nuances your tool can extract or understand, and of course send it to the output. Users will enjoy it.

You also need to make the output fancy: format it, colorize it, add ASCII Art logo, a copyright banner, use Unicode output characters that show up on your terminal configured to use a Unicode font, etc.

Wishlist item:

By all means, add verbose/debug logs to your tool, but think of the users. What is that they want from your tool? How do they use it? Who are really these tool users? Noobs, experienced practitioners, advanced pros, hardcore hackers? For example, for a PE parser, will they need to know all the gore characteristics of the file when they only want to know the very basic properties of the file (that can drive their next steps in analysis)? What are the real and most common use cases?

Less is often more.

  • Add debug/verbosity, but make it optional.
  • Consider saving such logs to a file, not to standard output.
  • Add options to disable copyright banners.
  • Avoid whistles and fireworks. UI metaphores went down the drain last few years, but we can still try to make the UI user-friendly.
  • Think of the audience. Ask the audience what works, and what doesn’t.
  • Learn from other tool makers.

Exhibit #6.

Help.

Rant:

How do I use your tool? Twitter animations are cool, youtube video with your presentation is great, screenshots are fantastic. But… can I have a basic written documentation please?

What are the problems it tries to solve? This should be the first line of any documentation. You can’t assume everyone who visits your page knows.

What file formats are supported? What is the desired output? What are known issues? What is the competition, or if you don’t want to write about them – how do I verify output of your tool? What are the references to documents, functional specifications, older work that you relied on?

Finally, what are the command line arguments? Give a loooong list of examples. Be generous. Treat users like they have never seen a computer before. It will save them a lot of time.

Seriously, this is such a pain that it bogs my mind how much time I sometimes spend looking for an example usage for some tools. One that actually works. Because these that don’t — it’s endless. And how many times I actually had to reverse engineer some binary to discover a proper usage for this particular version…

And if you want a good example on how to do it right — look at programs written by Nirsoft. They all share similar GUI interface. They also have very good documentation pages, all of which are quite uniform, so seeing it once makes it easy to read others. They include very detailed information about command line arguments programs support. You will also find a lot of information about known issues, request for feedback, licensing info, and lots of lots of useful hints on how to use the programs.

Exhibit #7.

Missing Feedback opportunities.

Brian provided a good suggestion to add to the list – a suggestion that is more towards users than tool developers, but this reminds me that the feedback is not always easy to provide, because developers simply forget to tell us how.  

Rant:

If your program doesn’t work on my system, or with my samples, how can you learn about it if there is no way to provide a feedback?

Wishlist item:

Email address, Twitter handle, or enabled bug logging/comments for your repo/blog will do wonders.

And if you are the user, please provide the feedback to the tool writers!

Exhibit #8.

Not everything is a tool.

Rant:

So, you used 20 libraries, and wrote a 50 lines of code that reads JSON, converts it to XML, transforms it with AI, and then outputs movie rendering a unicorn printed with a virtual 3d printer galloping over the rainbow.

It’s great you are proving yourself. It’s great you are trying. It’s great the program you wrote works for you. There is no sarcasm here. This is how we all learn.

You are in luck. There are so many libraries available now that writing code that does extremely complex tasks in just a few lines of code is trivial. We should respect that.

AND

If there are 50 other programs doing exactly the same thing, and often do it better. If the tool is half-cooked for the sake of a demo during the con, and/or it only works well for your test data. If the whole code is so simple that any average developer could implement it w/o much trouble. If the actual snippets can be found on the StackOverflow. Then please please do not call it a tool. Calling it a POC is enough.

This is not to discourage you from coding. This is to encourage you to assess your code quality & usefulness on a grand scheme of things. If you claim that your software allows to do a specific thing, or assess certain quality of some data, or extract certain properties, and someone can quickly prove that these are not done right, because of a limited scope of the original idea that drove the development, then as a POC it’s still a very valuable asset, but as a part of somebody’s toolbox – completely useless. Hence, not a tool.

Epilogue:

Okay, it’s easy to rant and play a blame games. I coded lots of bad programs myself, and some of them are still available on this web site. Making everyone happy is very hard. Programming itself is actually very hard. Testing is even harder. And writing documentation the most undesirable task coders have to face.

BUT.

I think there is a minimum responsibility to bear for anyone that releases programs publicly, and announces them to the world. It is a basic empathy for the users, and their needs.

And if you release code, a POC, a tool, a suite, and it actually can be quickly tested, won’t crash on its first run, and will deliver expected output — you will actually make a dent in the industry.

Blue Sheet Of Cyber v0.2

Posted on by

I have updated the sheet based on a feedback I got so far.

One of the ideas that drove the development of this sheet was this question: who is a better hire: a forensicator with 15 years of bit-by-bit/primarily encase experience on the LE job, or talented young engineer who loves breaking stuff apart and already made a dent on the industry by discovering new forensic artifacts, writing tools, and presenting novelty ideas at conferences?

This is the reality of cyber (not only blue teams) for last 20+ years, and in my view it is one of the reason why we see everyone talking about ‘talent shortage’. This is because they look at the numbers, and characteristics of people already employed in the space. Not these that could be.

As such, the ‘talent shortage’ may not be an accurate statement if we change the scene. I’d argue that unlike other industries where primarily experience and academically obtained skills matter, the ‘canonical knowledge’, ‘adaptability’ and obviously the actual experience & academic achievements all play important role in diagnosing that ‘shortage’ and for individuals – their ‘hireability’.

And to add insult to the injury, given the fact that most blue team junior analysts are assumed to be almost clueless at first, the ‘jack of all trades’ approach dictates that with a proper mentorship, they can quickly conquer shallow waters of the knowledge necessary to progress to the next higher technical level. The path will quickly become more demanding then, but by the time they get to the next level, it may as well happen they will be already very well prepared. A.K.A. hiring juniors w/o experience should be done with doors open by default, and only closed if candidate makes it happen. Part of me doesn’t believe what I wrote, because I had mixed experience interviewing people for very junior positions, but maybe at that time I was still too biased(?).

The second reason that drove the development of this sheet was this: it tries to support manager’s work; junior analysts often want to know what is that they should learn to ‘climb’. Even if some engineer doesn’t particularly see a need for the ‘advancement’ of their career, and may see such matrix as counter-productive, even anti-climatic and bringing bad blood to the team, they will hopefully appreciate that an ability to self-asses themselves is a nice thing to have. Again, not important today, but may become important tomorrow. Like any other industry before, things will most likely slow down, stagnate, salaries will get adjusted, market saturated with new talent, competition will be harder, etc. etc. – luck favors prepared mind as they say.

And in terms of how to interpret the sheet. I guess we should see the ‘right wing’ on the sheet as a cumulative effort of many years of experience, and a result of many technical ‘lives’ of an individual coming together. The ‘left wing’ is the Jack of Few Trades, the ‘right wing’ is the Jack of Many. I would argue that working for various companies over the years (whether as an FTE, or a consultant) puts people with such a wide experience in a more favorable position here. This is indirectly supported by the process of promotions happening typically when people change the jobs, not on the jobs.

Last, but not least – the stuff that is already in there shows that the era of introvert nerds that just want, and are allowed to do ‘technical’ stuff only is no longer…

The file can be downloaded from here.