Once upon a time

.gitignore

@@ -0,0 +1,3 @@
+py_env/
+*.pdf
+*.html

1.Writing.md

@@ -0,0 +1,57 @@
+# 1. Writing
+
+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.
+
+## 1.1. Story structure
+
+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](https://en.wikipedia.org/wiki/Three-act_structure) 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.
+
+## 1.2. Logical order
+
+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 complete paragraph should communicate a single idea. Other paragraphs build upon the ideas from previous ones to create a coherent whole.
+
+## 1.3. Archetypes
+
+[Archetypes](https://en.wikipedia.org/wiki/Archetype) 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.
+
+## 1.4. Sound and rhythm
+
+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](https://en.wikipedia.org/wiki/Bouba/kiki_effect) 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.
+
+## 1.5. Lazy wording
+
+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. It also won’t do in your essays.”_
+
+## 1.6. Playful proof
+
+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.
+
+## 1.7. Finding inspiration
+
+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.

2.Content.md

@@ -0,0 +1,112 @@
+# 2. Content
+
+The elements of a pentest report seem concrete, but every part has subtleties that make it work. Let's take a tour of them with examples and pointers.
+
+A pentest report needs at least:
+
+* A title page.
+* Assessment details.
+* Findings, if any.
+* A conclusion or management summary.
+
+## 2.1. Title page
+
+The title page helps readers quickly figure out what the document is about. It should still make sense when someone finds your report on a share three years from now. We can achieve this by stating:
+* That it is a pentest report.
+* The subject of the pentest.
+* The date or version.
+* The pentest company with a logo and/or the author.
+
+## 2.2. Assessment details
+
+The assessment details describe the context of the pentest. A reader without knowledge of the pentest should be able to understand the setup. I generally find it helpful to provide:
+* The start and stop dates of the assessment.
+* The scope, meaning the components of the subject that the pentest focused on.
+* Type of assessment and provided materials. This helps the reader know if you looked at the code, used certain accounts, etc.
+* The goal or objective of the client, if specified. Examples are research questions or testing a certain type of attack.
+* Limitations of the pentest, like when certain tests couldn't be performed. Limited functionality in a test environment is quite common. It is good to make a note of it to inform the client on testing blind spots.
+
+## 2.3. Conclusion
+
+Start with a paragraph that introduces the conclusion. This paragraph can include a general summary of the results. For example: "_[Pentest Company] performed a pentest on [Application] between [date] and [date]. The application currently has a weak security posture. Two high-risk vulnerabilities allow attackers to exfiltrate customer data without requiring authentication._"
+
+The next few paragraphs describe the results from the story. Don't just make a list of findings. but write about overlapping themes. High-risk vulnerabilities can get their own paragraph if they are not related. Leave out low-risk vulnerabilities if they don't add to the most important themes.
+
+End the conclusion with a paragraph that reads like a closing statement. Common formulas are: recommending to fix and retest the vulnerabilities; recommending sharing the security knowledge in the development team; recommending a structural solution to the security challenges.
+
+## 2.4. The order of findings
+
+List findings from high-risk to low-risk. It might seem to counteract Act II of the three-act structure, where tension is built from low to high, but remember that additional findings will still build up tension, and that the climax exists in the conclusion.
+
+Complementary findings with the same risk rating should be put next to each other. For example, a finding that reads an impact description like "_to exploit this vulnerability, an attacker would need to know x_" can be followed up by a finding that reads "_Stack traces leak x_", to show that this leak is possible while its impact is still fresh in memory. You can later use this as a theme in the conclusion to bring the point home.
+
+## 2.5. A Finding
+
+The story line of a finding is generally as follows: We must introduce an application’s happy flow, followed by the vulnerability to show some kind of conflict. The story peaks in the exploit and the impact description, and tension is resolved in the recommendation.
+
+Before we start with the finding's details we'll create a heading with a proper name and risk rating.
+
+### 2.5.1. Naming a finding
+
+The ideal finding name describes risk and context. Don't just write "_SQL-Injection_". Better are "_SQL-Injection in [customer page]_", "_Public API vulnerable to SQL-Injection_" or "_SQL-Injection allows Code Execution_". The art here is to make the title speak to the imagination without making it too long.
+
+### 2.5.2. Estimating risk
+
+The formula `Risk = chance * impact` seems trivial but risk ratings differ per pentester. Calculations depend on security philosophy and view of the scope. Whatever your security philosophy, be consistent per report, and communicate your approach on risk analysis. In the end the client decides which business risks the findings pose; you are just providing estimates. 
+
+It might not be your job to tell clients their business risk, but the integrity of your report remains yours to protect. It is not uncommon for companies to try and downplay risks. These risks are calculated from your professional view point. They should only be changed when the client provides valid arguments. Examples of valid arguments are: that it is a false positive; that mitigating measures exist that you were unaware of; that you misinterpreted the function of data.
+
+### 2.4.1. Finding details
+
+Introduce the finding with a summary of the finding and the impact. This can be easily done in three sentences. Start with the happy flow, like "_Users from the Foo application can perform Bar to keep track of their stats_". We then jump to the twist: "_The database queries use input from Bar, but they do not apply the proper encoding to protect against SQL-Injection_". A quick summary of impact can be used to close the introductory paragraph: "_An attacker can inject arbitrary queries to obtain or modify all customer data_".
+
+Now we can start discussing technical details. This part is meant for developers and pentesters. Guide the reader into understanding the vulnerability with code snippets, HTTP responses, etc, in logical order. A developer should be able to understand it, and a pentester should be able to reproduce it. Ideally both are able to reproduce it, but you can’t always make this work. Always provide a proof of some kind. A screenshot is the most common form of proof and it works great.
+
+### 2.4.2 Code snippets
+
+Make code snippets readable and understandable. Include a code path if it is available, and cut out the parts that are unimportant. I like to explain the code in the paragraph that comes before it. For example: "_The code snippet below shows that the account controller will grant the user all roles if the ID parameter has the value 1234._"
+
+_src/controllers/accountHandler.java_
+```
+public Foo(UserContext user, int ID) {
+  [..]
+  if (ID == 1234) { grantAllRoles(user); }
+```
+
+### 2.4.3. Screenshots
+
+Make sure that your screenshots are properly readable and not too big. Like with code snippets, the reader should have just read a sentence or paragraph that explains what the screenshot is about, like "_The following screenshot shows that the tool successfully decrypted the ciphertext_". Ideally you add a caption – like "_Tool successfully decrypting the ciphertext_" – but this ability depends on the reporting tool you’re using.
+
+Put a border around screenshots with a white background, if the background of your report is white. Also consider making screenshots a bit transparent if the contrast with the rest of the page is too harsh.  
+
+### 2.4.4. Impact description
+
+Start with a sentence that summarizes the finding details, and build from that. We’ll take the example "_An authenticated attacker can use the Bar field of the Foo application to execute arbitrary SQL queries in the database_". Now summarize the abilities of the attacker, e.g. "_Arbitrary SQL queries allow the attacker to insert, modify and delete all data_". Note that this sentence is required for the less technical, since they don’t always know what SQL queries are. Elaborate by explaining the type of data: "_the data includes customer PII and financial records_". A great way to finish the climax of the story is a business risk like "_Extraction of such data is considered a data breach according to the GDPR and can result in large fines_".
+
+Remember that every paragraph communicates a unique idea. If you’d like to highlight an additional risk, make a new paragraph. In the case of SQL injection, you could create a paragraph on the risk of code execution that can results from such a vulnerability.
+
+If there are any mitigating measures in place that limit the risk of the vulnerability, it is best to put it at the end of the impact description. Note that this is in-line with the story structure. The story just reached its peak, and we’re now working towards the release of tension.
+
+### 2.4.5. Recommendation
+
+Don’t start a recommendation with "_We recommend_" or "_It is recommended to_". The heading Recommendation makes these texts redundant. Make an action statement like "_Prevent brute-force attacks on 2FA codes by such and such_".
+
+Provide short and long term advise if required. For example, let’s say we have a vulnerable file upload function, where the ideal solution requires refactoring and design adjustments. Provide a short term solution for a quick patch, and a recommendation to change the file upload design in the long term.
+
+Make sure your further reading links are easy to process. NIST provides awesome standards for information security, but their documents are lengthy. Sources like OWASP copy NIST in a summarized format, which is why I prefer to link to OWASP, especially to their [Cheat Sheet series](https://cheatsheetseries.owasp.org/).
+
+## 2.5. Dos and don'ts
+
+### 2.5.1. Dos
+
+* Be consistent with the way you write terms, like _SQL-Injection_ or _JavaScript_. I like to use OWASP as a reference.
+* Try to stay objective and steer away from personal opinion. It is impossible to be purely objective when describing something like the security posture of an application. One trick is to change a statement to a recommendation, like "_We recommend not taking it into production until .._" as opposed to "_It is not production-ready_".
+* Do your homework and check if your recommendations are feasible. If you encounter hardcoded secrets, and you say "_Encrypt these secrets_", do check the documentation if this is even possible, or you'll leave the developer hanging.
+* Use a spell checker.
+* Make sure your report is done before sending it to peers for review. A review is like a pentest; its purpose is to check for things you missed, not to do the work for you.
+* Review it yourself at least two times before sending it in for review. This means reading the entire thing from the title page to the conclusion.
+
+### 2.5.2. Don'ts
+
+* Try to avoid one-sentence finding details, impact descriptions or recommendations for anything higher than low-risk.
+* Don't use slang like _info_ or _admin_, but use _information_ and _administrator_.