Red Teaming
How to write better security reports (for techies & execs)
Writing reports in cybersecurity might not be as thrilling as catching intrusions in real-time or cracking into systems during a test, but it’s a crucial skill.
Table of Contents
Writing is a technology. One that’s been invented independently at least four or five times in humanity’s history.
The ability to record data, store it, and retrieve it later without the author’s help represented a significant leap forward in our relationship to information.
That said, a lot of us aren’t getting into cybersecurity with the goal of writing reports. It can feel tedious and time-consuming, and a little out of some folks’ realms of expertise.
But, writing is a skill.
And, as with all skills, some practice and good advice makes “getting gud” feel more manageable.
Want specific templates for pentesting or security incident reports? Try these:
If you have a format, follow that first
Depending on the type of report you’re writing, the company or teams you’re working with, or even the cybersecurity framework you’re working within, some of the basic details are likely already documented pretty well. So if you have an existing reporting format, start with that.
You’re then ready for more advanced writing techniques that can up your reporting game—and they don’t require knowing the proper use of semicolons or what a dangling participle even is.
This blog post contains a few of these writing “hacks” aimed at writing better cybersecurity reports. You’ll learn how to laser focus on the audience, pick good screenshots, speak consistently on a topic, and edit well before any quality assurance (QA) processes.
Free course on documenting and reporting
The content and examples in this post are based on our HTB Academy on Documentation & Reporting module. Enroll in the module to master everything related to writing penetration testing reports and documentation.
Are you reporting to an executive or technical audience?
Reports usually have a target audience. Depending on who is in that audience, there are certain key things they may want to know, things they may need explained, or things they’re less interested in hearing about.
This is why knowing who the audience is important for different types of documents—or even sections within a document—can help. Tailoring your writing to that audience makes you a more effective communicator because it helps them get the information they need much faster.
While editing pentest reports, for example, I’ve run into two main audiences:
The executive team
The C-suite (CEO, CFO, etc), or other executive-level team members. They may have technical experience, but generally they tend to focus more on business decisions. They’re also people writing the checks, so they want to know that they spent their money well.
-
What do they need? The bottom line: What’s broken, what can be fixed, what’s working well.
-
What do they not want? Verbosity, lots of text to read, and in-depth details.
The technical team
The “boots on the ground” in the security operations center (SOC), blue team, or other IT-related functions. Usually, they hold a higher level of technical expertise, although they may have a different background than you.
They’re the people fixing vulnerabilities, so they need to know what you saw.
-
What do they need? Details, but only relevant ones. What parameters or settings are broken? What’s the root cause of an issue? How can we fix it?
-
What do they not want? Extraneous information, wandering focus, unclear or hard-to-follow steps.
These two audiences seem to be looking for wildly different things from a report. Fortunately, it’s not too difficult to meet both sets of needs.
One key tool for addressing this is sectioning the report.
Many templates you work with may already have certain sections designated for the exec team, usually called something like the “executive summary”. They’re usually also at the top, so the senior leadership can get their bottom line within a few pages, and then move on to something else.
 |
 |
Everything else is likely aimed at the more technical teams. If it’s about the nitty-gritty details of a vulnerability or requires a cybersecurity certification to understand, it’s probably intended for someone working within an IT function.
A picture is worth 1,000 words: why you should sweat over (good) screenshots
Getting good screenshots is one of the best things you can do to level up a report. A good screenshot:
-
Gives context within the app or asset you’re testing.
-
Shares a clear indication of the steps you took to get there.
-
Shows the whether the objective was achieved.
It should tell a story of: your input, the application’s response, key variables highlighted or called out, and a clear path from one step to the next.
But a bad screenshot? You can’t see what’s going on, or there’s a lot of empty space or extraneous pieces of information cluttering.
If the text is too small to read, or there are hundreds of lines of code, I have to read through to find the relevant one. In that case, the screenshot may as well not be there.
Here are the key tips for snapping the best screenshot:
-
Zoom in. Unless you need to capture the entire screen, just take a picture of (or crop down to) the line or lines you need to show. If you have a lot of extra blank space, you probably have too many screens in your shot. Sometimes, one screenshot won’t get the detail you need, so two screenshots with different parts of the same thing are probably fine.
-
Use callouts. When you’re trying to show the reader specific pieces of information, a red box, circle, or arrow pointing to that info makes a huge difference. It saves the reader from needing to sift through 45 lines of code to find the one you changed, and can help for situations where zooming in is harder.
-
Minimize clutter. Keep the screenshot simple. If you have multiple windows open, keep the edges of the others out of the way. Keep your desktop background out of frame (you may need to change transparency settings for this). Try to keep a clean desk policy, as much as possible.
-
Ask what to do about personal info or credentials. In some cases, you may be working with a user’s real name or other personally identifiable information (PII), or you may capture a username and password pair. Make sure you know what to do with those, and redact the screenshot as necessary. When in doubt, err on the side of caution.
As with the other pieces of advice here, if you’re working with an organization and they have defined standards already, follow those standards!
Ask for the style guide
A style guide is a document that contains the organization’s preferred way to use certain terms or grammatical features. One of the most common examples is acronyms.
You could look at a dozen or so different style guides, and get variations on the following rules:
-
Capitalize the first letter only at the start of a sentence. As in, Cross-site scripting (XSS)...
-
Capitalize the acronym’s letters. As in, … Cross-Site Scripting (XSS) …
-
Don’t use acronyms, don’t capitalize, as in, … cross-site scripting…
For numbers, you may run into:
-
Spell out numbers under 10 only, as in one, two, three, 10, 11, 13, 100, etc.
-
Always use digits, as in 1, 2, 3, 10, 11, 13, 100, etc.
-
Always spell them out, as in one, ten, fifteen, one hundred, etc.
(And that’s before we talk about date formats, or American versus British English.)
The reasons for these differences are somewhat immaterial; preferences vary across teams and organizations, becoming codified over time.
What you need to know, however, is which rules apply to the document you’re working on. And when you know the rules, stick with them. If the style guide wants you to define an acronym the first time it shows up in a report, then it’s Role-based access controls (RBAC) the first time, and RBAC everywhere else.
For names of software or companies, the general rule is to stick with how they stylize it.
A lot of rules about title case generally don’t recommend capitalizing articles and other words like “the”, “and” or “a”. However, Hack The Box (HTB) spells its name with a capital T, so it’s a mark of respect to use HTB’s preference wherever you talk about them.
The style guide is rarely going to be a perfect document. There will be stuff missing. So, if something is not in the guide (and nobody has a preference), pick a style and stick with it. You can always check in on that when you edit later.
Self-edit to figure out what your report actually says
You’ve written the words already, isn’t that good enough?
Self-editing might be the hardest technique to get in the habit of. The flip side of that is:
Some of the best writing advice I’ve ever gotten is to write the first draft badly, and come back to fix it later. Whoever your favorite author is, I can nearly guarantee that any really neat sentence they wrote was not perfect on the first take.
Editing is a little more than just re-reading what you wrote. Although that’s a very good first step. There also isn’t a one-size-fits-all approach that’ll make you a perfect writer tomorrow. So you may need to experiment with a few techniques.
When I’m editing anyone’s writing, including my own, here’s how I usually approach it:
Step zero: If I’ve written it, I’m taking a minimum of 15 minutes (ideally a day or two) between writing and editing.
-
First pass: Read everything as though I’m seeing it for the first time. I’ll let myself grab the very obvious edits—a missing comma here, a typo there—but for the most part, I’m trying to figure out what the document actually says, not what I expect it to say.
-
Editing pass: Go through sentence by sentence, and paragraph by paragraph. Ask a lot of questions, like “Have we already said this thing?” or “Does it make sense to introduce this idea before or after this other term?” This is the main editing pass, where I try to approach it as a series of questions and answers.
-
Read it aloud: Yes, this is going to feel very silly. Do it anyway. (You can wait until you’re alone first). There’s no way around feeling goofy doing it, but it is honestly one of the best things you can do to make sure the findings are clear. If I catch myself stumbling on a line, that’s usually a sign I need to move some words around.
Other great tips for editing include:
-
Change the background color or the font of the whole document. (Just don’t forget to change it back afterward.)
-
Read from the bottom up. One line at a time. (Usually, after you’ve read it forwards at least once).
-
Make yourself a checklist. Ensure it includes the inconsistencies or typos you know you’re prone to.
-
Ask someone else to read it (assuming this doesn’t violate an NDA or anything).
HTB resources to practice report writing
HTB offers some excellent training work on how to document security issues and write reports, which are excellent foundations to start with, as well as good places to practice using these tips.
Even if you already feel comfortable writing reports, it’s never a bad idea to practice the fundamentals with HTB Academy modules on:
