Understanding basic writing theory is an essential part of anyone's professional toolbox. These tools will help you develop a feeling for text and they'll aid us in future chapters of the guide. Subjects will return in the Examples and Exercises sections, so you don't need to remember everything at once. Just sit back and enjoy the show.
Humans are story-telling creatures; it is how we perceive the world. Reports are stories, and findings are stories as well. A well known tool for conveying stories is the three-act story structure. This structure helps us convey the meaning of our words, even if the content is objective and technical. Humans like most messages to have a similar structure. It doesn't matter if it is an email, a paragraph, a report or a conference call. We like to have some kind of introduction, followed by a main part, and an end that is not too abrupt.
The three-act story start with a Setup, where context is created. Main characters are introduced as well as a conflict that gets the story going. The tension is developed in act two, known as the Confrontation, which ends just before the climax. In the Resolution, the climax determines the outcome of the story, and the tension is resolved.
Let’s analyze the story of a pentest report. The Setup starts with the title page, followed by the assessment details, like the scope. Act II are the findings, where tension accumulates. As findings unfold, the result of the story starts to take shape. This result is summarized in the conclusion, which is the climax, ideally followed by a recommendation to bring the story down gently.
Humans also like things to be orderly. Put the most important thing first to find the proper place for words, sentences and paragraphs. You don't need to organize everything the same way; it is just a way of finding order when you need to.
A sentence is more readable when it starts with its subject, because the subject is what the sentence is about. Let's look at two examples:
- "Firewalls are essential for protecting a network from unauthorized access."
- "To protect a network from unauthorized access, using firewalls is essential."
The first sentence is easier to read, because it logically progresses from the subject (firewalls). The second example requires the reader to keep track of the words up until the end, where the sentence has to be mentally reconstructed. This is why the second example causes more mental fatigue.
A paragraph should also start with an introductory sentence from which successive sentences logically flow. The sentences form a complete paragraph which should communicate a single idea. Other paragraphs build upon the ideas from previous ones to create a coherent whole.
Archetypes are abstract characters that we unconsciously understand. If you want your reader to become aware of danger, then starting a sentence with "An attacker can" packs additional punch over the use of "We were able to". In the first example, the attacker acts as the enemy, the adversary, or evil itself. Clients will fill in the blanks with what they perceive their enemy to be. If you refer to yourself using "We", they'll think of a positive professional, which distracts from the message you're trying to get across.
Sometimes I like to play around with switching up the enemy and myself. I'll say that a screenshot shows "an attacker taking control of the server", while it's obviously me. It is a play that starts with correctly conveying the potential danger, and ends with the message that we're in control.
Sound and rhythm play parts in the symbolic meaning of text. Poets use these gadgets to create art. We don't have to become poets, but having a basic feeling for these arts can help you understand why your sentence reads like shit.
The Bouba/Kiki effect demonstrates how humans associate sounds with shapes. Westerners associate the word Bouba with round shapes, and Kiki with sharp angles. Check it out and you'll see why. We can use this knowledge to fine-tune the perception of our text.
Shakespeare demonstrates the aesthetic power of the written word like no other. His most used rhythm is the iambic pentameter, which means repeating a soft-HARD pattern five times over. For example: "Shall I compare thee to a summer's day?" reads in the pattern "shall-I com-PARE thee-TO a-SUMmer’s-DAY?". The sounds of his words also beautifully convey the thoughts of his poems.
It is hard to put this better than in the slightly sexist yet comical quote from the amazing movie Dead Poets Society:
“So avoid using the word ‘very’ because it’s lazy. A man is not very tired, he is exhausted. Don’t use very sad, use morose. Language was invented for one reason, boys - to woo women - and, in that endeavor, laziness will not do.”
The objective and technical nature of pentest reports can make them a bit bland. Proofs and screenshots provide an opportunity to add a bit of seasoning.
Images are a great catalysts for creativity because they can set the tone of a report. Stimulating test images - like a cute animal or a culture reference - can give the report a personal touch in a positive way. Clients like to see that you’re enjoying your work, but images must not be unprofessional, disturbing or distracting. With distracting I mean that it is loaded with additional meaning or a personal opinion, like a political statement.
Text from our workflow can be made more interesting by giving it a whiff of Hollywood hacking. Maybe your Cross-Site Scripting payload says “Got some hijacked cookies: [cookie]” instead of a boring “Stored XSS Test #3 – Double Encoding: [cookie]”. Giving it a bit of the gray area vibe helps clients visualize the attack path of a real adversary. Don't overdo this and keep it professional.
Having a writer's block? Simply imagine talking to your target audience. Imagine the manager - the personification of your audience - sitting next to you in the cafeteria, asking “What are the results of the pentest?,” or “I heard you found a vulnerability, what is the business impact?”. Literally write it like you would say it. Then restructure the writing to fit the report.
Another trick for conjuring up content is to dump a bunch of decoupled sentences next to each other and work from there. We'll use this technique in the Examples chapter.