Note Taking and Write-ups
Estimated Reading Time: 8 minutes
Introduction:
This is just going to be a quick post detailing my personal preferences for documentation in the hope that it may help a few people get started with write-ups, and perhaps introduce you to some great software!
We’ll start by looking at a couple of pieces of software (Cherrytree and Flameshot) which, frankly, I couldn’t recommend more; then briefly discuss a few tips for writeups and documentation as a whole.
Let’s start with the software.
Software:
Cherrytree
Cherrytree is a wonderful piece of note-taking software from Giuspen. It’s an extremely flexible program, allowing you to take structured notes in a hierarchical format. To my understanding, Cherrytree is one of (if not the) most common pieces note-taking software in the industry — which is a testament to its applicability — however, I would still like to cover some of its features and drawbacks.
In terms of features, Cherrytree has many:
- It’s cross-compatible with Linux and Windows. It is possible to get it running on MacOS, but it requires a bit more work. On Debian based Linux it’s as easy as running
sudo apt update && sudo apt-get install cherrytree. Kali comes with it pre-installed. - It saves its notes in a single file, giving you the option of two primary formats: SQLite database and XML document. These are self-contained in a single file, and both can be encrypted. When encryption is chosen, Cherrytree stores the file in a password protected 7zip archive.
- As an
exeit can be installed as a portable app on a USB without difficulty - It’s still being maintained, unlike many otherwise equal competitors (Keepnote, for example)
- On the note of competitors, it can import from a huge variety of different formats, and export to everything from PDF to HTML. I have genuinely exported a notebook to HTML, uploaded it directly to my website, and had it run perfectly before.
- It allows you to embed images and files directly into the document. Embedding images and files does come with an upper limit of 10Mb per file (and obviously, the more you attach, the bigger the file, so saving can get a little slow if you start adding in lots of documents).
- You can also create codeboxes with syntax highlighting for a vast range of languages
- It gives you an option to autosave on a user-specified schedule, and keeps a version history if you ask it to.
- It’s got a great search feature, allowing you to limit your search to the current node, the current node and subnodes, or the entire tree.
- It’s got an up-to-date manual
- Perhaps most importantly, it’s FOSS!
The one big drawback that I find can be an absolute pain is that it doesn’t currently support syncing notes between devices — a feature that I hope will soon be added. Currently I have solved this problem by automating a backup of my notebooks to a remote server, then just downloading the up-to-date version frequently across my computers.
As far as notebooks go, I cannot recommend Cherrytree enough. Its sheer versatility makes it a go-to tool in my opinion.
In terms of how I would use it for a CTF write-up, my hierarchy would usually look something like this:
Inside the top node (containing the name of the box), I would place three main sections (along with any other generic things):
These sections would show generic system information, any gathered credentials, and any important submissions (flags, for example).
Next would be an Initial Enumeration section. This would be where I store the nmap output from initial port scans. In the targets sub-section there would be a node for each service — in these nodes I would save service information provided by nmap, specific to each service.
After the Initial Enumeration would be an Active Enumeration section. This essentially contains any hands-on enumeration. For example, in a webserver I would contain any output from tools, along with each page where something interesting was discovered. Once I notice something exploitable, I would make a node for that in the Exploitation section and use that to detail anything I tried — including what succeeded, and what failed.
With a service successfully exploited to gain a shell, I would show any further enumeration in the “Foothold” section. Having found a vector for privesc, I would then move into the Privesc node, and again, show everything that succeeded and failed.
This is a flexible structure — nodes can be added, removed and changed as required — however, it provides a starting point; a basis which can be used in many different applications.
Of course, Cherrytree is useful for a lot more than just CTF Notes. I also use it for my uni notes, and keep a Notebook detailing interesting things that I come across in the infosec sector, be it tools, techniques or resources. I know that it’s also used by professionals in Pentesting roles, but not being there myself yet, I can’t fully attest to this.
Either way, it’s a superb piece of software that I would fully recommend checking out! There are tonnes of tutorials and in depth reviews for Cherrytree floating around the internet, so I reckon it’s time to move on to the next piece of software.
Flameshot
Flameshot is, in my opinion, the best screenshot software around. It’s designed solely for Linux, which is fine for me because the bulk of my setup is based off one distro or another, but may be more problematic if your primary OS is Windows or MacOS. Once again, Flameshot can be downloaded from apt: sudo apt update && sudo apt install flameshot. You will also need to specify your own shortcut to open Flameshot within your window manager. I chose Ctrl + Shift + F, but you could go with something simpler like the Print Screen key. The full instructions for installation are in the github repo linked to above.
As with Cherrytree, the reason I like Flameshot so much is for its sheer versatility. I’ve yet to find an aspect of it that I don’t actually like. It’s fully configurable, down to the colour scheme and the buttons available in the editor.
That leads me into what I consider to be the best feature of Flameshot. By default, when you grab a screenshot, it loads straight into an inline editor. From here you can modify it in many different ways — nothing too fancy, but pretty much everything you could want for documentation. One of the most beautiful aspects of this (that I’ve not seen from any other software to date) is that you can even resize the screen grab after the original selection has been made. Once you’re done with any modifications, you can export the image in a variety of different ways: to the clipboard, to file, to another app on the system, or straight up to imgur.
I tend to use Flameshot in two distinct ways when it comes to documentation.
- For my initial notes I take a really quick screengrab of whatever I’m wanting to save. This gets copied straight to the clipboard with no edits, and goes into the Cherrytree document at the appropriate place. Takes about a second, and allows me to get on with actually tackling the challenge with barely an interruption to my train of thought.
- When it comes to formal documentation, I go back and take “beautified” screengrabs. These are the ones where I ensure that the boundaries of the screenshot are right, appropriate information is blurred and anything that needs highlighted has been highlighted. This is where Flameshot really shines, as the powerful editor makes the whole process really streamlined.
Perhaps in a real-world setting I would take the pretty screenshots first time around, who knows? That’s something I’ll find out when I get there, but for the time being, this is the method I tend to use.
In terms of why I initially chose to try out Flameshot: I’d heard good things about Greenshot for Windows, and that Flameshot was designed as an imitation for Linux. I tend to work a lot more in Linux than I do in Windows, so I was really looking for a screengrabber that worked in Linux.
When working in Windows (say, with a Linux VM), I can fully recommend Greenshot, as an equivalent screenshot tool. In many ways this setup actually works better, as you can keep your notes isolated from your hacking VM.
All in all, I find that these two pieces of software work spectacularly hand-in-hand. I’m aware that they’re not exactly uncommon; however, I felt it worth talking about them — not least in the hope that it might be beneficial to people who may not have run into them before!
Tips and Tricks:
There are one or two tips that I wish someone had told me in my first few weeks. As it stands, it’s taken me close to five months in the industry to get to where I am now with regards to my documentation setup.
- My first tip is to document everything. I mean that literally. Even if something doesn’t work — get a screenshot and just put down in your notes that it didn’t return anything. Failures aren’t necessarily a bad thing: they allow you to avoid making the same mistake twice, and help you to learn what works in different situations. Anything that you do, make a note of it. This is the benefit of my “Working Theory” node in Cherrytree: it allows me to write down what works, leaving me free and clear to put everything down elsewhere. Document every single thing that you try — you’ll thank me later.
- Take a special note of anything of particular interest. In a CTF this might mean flags and creds, for example. Anything that you might need later, keep it close at hand.
- Find a documentation style that works for you. I’ve shown you the hierarchy I use in my Cherrytree documents for CTF writeups. That works for me, but you might find that something else works better for you. Mess around with it and experiment until you find something that sits comfortably with you.
- On a similar vein, different people can stand different levels of disarray. My natural instinct is to have everything ordered neatly so that things are easy to find in a logical fashion; other people might find that different setups work better for them. The one thing that I would recommend keeping in mind though, is that you never know when someone else might need to read through your notes for one reason or another. Try to keep them (relatively) neat and tidy, even if your ordering system is completely different to the one I’ve suggested.
That’s it for documentation. Here are a few quick tips for CTF write-ups:
- Everyone has their own style: don’t try to imitate anyone else, even if you particularly admire their writing. For example, I tend to be very florid with my write-ups; however, I know that others do them in a bare-bones style detailing exactly what they did and nothing more. It’s a sliding scale, and neither side of it is right or wrong. Do what feels natural to you — that’s what’s important.
- Remember that you’re writing up what worked for you — not a tutorial for other people. In many ways I blur this line with my own write-ups, I’ll freely admit that; however, when it comes to exploits that are potentially unstable, I cannot guarantee that what worked for me will work for everyone. When push comes to shove, all you can do is write down what worked when you did it. If that same thing helps someone else: superb. Otherwise they’re just going to have to go with the fundamental theory of hacking: read, learn, understand and adapt.
- I know a lot of people disagree with blurring things like flags and passwords in a write-up, but I would honestly highly recommend doing it. A good write-up should be able to guide people precisely; however, even if they’re stuck, there is no benefit to them if they can just pick the flags (or anything else that they would otherwise need to work for) directly out of your work. To do so would be to cheat themselves as much as anything else. In order to learn you must do things for yourself, thus it’s worth not just handing people the answers on a silver platter.
Final Thoughts:
That’s it for my introduction to documentation and write-ups. I have no idea if this will be useful to anyone, but I would like to think that by detailing my own preferences and passing along some tips that I find helpful, this will be beneficial to one or two people. I may also update this post as my preferences evolve.
Please feel free to drop a comment down below if you want to discuss anything I’ve written here — I’m fully open to constructive criticism, or even just to discuss in further detail any of the sections in this post.