diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..5d40186 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +py_env/ +*.pdf +*.html \ No newline at end of file diff --git a/1.Writing.md b/1.Writing.md new file mode 100644 index 0000000..9d8acb1 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/2.Content.md b/2.Content.md new file mode 100644 index 0000000..af2485e --- /dev/null +++ b/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_. \ No newline at end of file diff --git a/3.Communication.md b/3.Communication.md new file mode 100644 index 0000000..e15edee --- /dev/null +++ b/3.Communication.md @@ -0,0 +1,43 @@ +# 3. Communication + +Writing is about communication. Before, during and after we write a report we need to be communicative to ourselves and to our customers. + +## 3.1. The intake call + +Use the intake call to learn about the values and needs that surround the scope. Ask about the worst case scenario, so you can use it as a theme in your story. If you can uncover why the pentest was requested you can adjust your writing to it. + +The intake can also be used to tune the scope if the wrong type of assignment was requested. For example, I had a client who planned a pentest on their company website and a scan of their external infrastructure. When asked about the worst case scenario, they answered that they planned the pentest because they were afraid of ransomware attacks. I explained that they'd be better off assessing things like their backup capabilities. They were thankful and decided to steer the project in that direction. + +Aim to agree on a list of the requirements that are needed to test all functionality in scope. Also reach consensus about the duration of the pentest. A concrete start date can later be discussed via email. + +## 3.2. Report while you pentest + +Start writing findings during the pentest. Ideally you'd do this while testing, but I found it to disrupt my flow. What works for me is noting the basics at the end of the day of confirming the vulnerability. With basics I mean loosely couples sentences for the details, the impact and the recommendation. We need at least the basic information so we can write out the finding if the testing environment goes down, so also dump in evidence like screenshots. + +## 3.3. Asking the devs + +Discussing findings with developers can help improve the quality of a pentest. You can learn about the root cause, how shocked they are to find it, if it is a structural issue, and what they think the proper solution is. Clients also tend to love this approach because you're doing part of the work for them. Managers with a working moral compass can't be happier if a vulnerability is halfway fixed when they read the report. It shows that you're really stepping up to better their company, and it lets developers know that you have no intention of bypassing them to brown-nose management. + +## 3.4. The findings meeting + +A findings meeting is an essential part of the pentest process. It is the presentation of the story that sets the tone of the results. Present the findings that make up the themes from the conclusion. Consider skipping low-risk findings if you run out of time, and give others a chance to speak and ask questions. + +## 3.6. Expectation management + +Expectation management is vital for smooth delivery of a product. Think of this like a trailer to the story of your report. Their imaginations will play this trailer on a loop before and during the assessment. If the story of the report turns out to be completely different, it can ruin the whole experience, regardless of results. + +Try to steer away from ambiguous or vague statements like "_We expect to deliver the report shortly_". What does shortly mean? Just pick a day, and just make sure you timely communicate if you aren't going to make it. You can get away with "_We expect to deliver it early next week_" if you're not sure you can deliver it by Monday or Tuesday. Just don't keep quiet if it is going to be Wednesday or later. + +Communicate high-risk vulnerabilities during the assessment. Also tell them if it is an easy fix or not. The client can decide if they'll start fixing parallel to the pentest. Don't forget to mention that you'd rather not have them deploy new things to your testing environment until the pentest is done. Sometimes when I find a high-risk on Friday afternoon, I wait until Monday, because I know nobody is going to pick it up and the poor ISO will just lose sleep on it. + +Expectation management is also about _meeting_ expectations. It doesn't always need to come from pro-active heads-ups. For example, a client expects to at least find something useful in a report. A pentest without findings can be made nice by adding what has been tested, which tests failed, or by describing security controls that are well established. You can also level their expectations by informing them that nothing of interest was found halfway into the pentest. Just don't let their imaginations race for a week only to be handed a bunch of blank papers. + +## 3.7. Being proactive + +Meet the client's expectations and exceed them when possible. This can be as simple as asking the right questions. I was once testing an application in a production environment that had some auto-login link to a bug tracker. In the room were the development team and the Risk Assessor (person managing the pentest), who said the bug tracker was out of scope because it "didn't contain production data". Clicking the auto-login link seemed to work, so I asked the developers how this was possible, who answered "oh yeah we sync those accounts from prod". Turns out you could hack the bugtracker (MantisBT) to obtain production accounts for escalating privileges. The Risk Assessor - who was surprised to learn about this - changes the risk rating for the tracker and we put it in scope. The insight for tuning business risk added a dimension of collaboration. This was a small interaction but it elevated the pentest-experience. + +## 3.8. Positivity + +Our job is to make people enthusiastic about security so we can guide them towards improvement. We build routes to better security with concise findings and eloquently tailored solutions. Part of doing this job properly is keeping up morale. If there are too many findings, we'll advise to focus on the high-risk ones. If the proper long-term solutions overwhelm them, we'll provide simpler short-term solutions so they can at least make a start. Motivation, morale and enthusiasm all stem from positivity. This is how we lead and motivate customers to make their companies more secure. + +It is essential to work towards positivity inside yourself. Remember that security can't exist without someone valuing something. This means that if you can't see value in the world, it'll become a challenge to imagine the security needs of your customer. This valuing of the world starts by valuing the self, even when you [miss vulnerabilities](https://www.securify.nl/blog/staying-positive-about-false-negatives/), mess up communication or curse your job and especially those fucking clients. These things happen, but they are all temporary. What's important is that you manage the self like you manage your client's; guide yourself towards improvements, because you can always get better, and that is something worth being positive about. \ No newline at end of file diff --git a/4.Examples.md b/4.Examples.md new file mode 100644 index 0000000..ddccd03 --- /dev/null +++ b/4.Examples.md @@ -0,0 +1,166 @@ +# 4. Examples + +## 4.1. Writing a finding + +1. We'll start with notes and a finding template. The notes are from a pentest on an application called Foo that's written in Java. + +**Notes** + +``` +High risk. SQL-Injection via POST to /bar. +Caused by string concat at Bar controller in /src/bar: [code sample]. +Example request: [screenshot]. +Impact is full db access. Use prepared statements. +``` + +**Template** + +``` +[Title] +[Risk] + +[Finding details] + [Introduction paragraph, summarize finding and impact] + + [Technical details, reproduction steps and proof] + +[Impact description] + [Summarize details in sentence or paragraph] + + [Explain business risk] + +[Recommendation] + [One or more action statements with references if possible] +``` + +2. Let us now re-order the information to fit the finding template. + +``` +Title: SQL-Injection via /bar +Risk: High + +Finding + Users from the Foo application can perform Bar to keep track of their stats. + Allows SQL-Injection. + + Caused by string concat at /src/bar: [code sample]. + Example request: [screenshot]. + +Impact + An authenticated attacker can use the Bar field of the Foo application to + execute arbitrary SQL queries in the database. + + Impact is full db access. + +Recommendation + Use prepared statements, Java PreparedStatement. +``` + +3. We professionalize all elements by writing complete sentences and explanatory paragraphs. Note that we also update the title to match the story. + +``` +# Title: Database compromise via SQL-Injection in Bar page +### Risk: High + +## Finding + +Users from the Foo application can perform Bar to keep track of their stats. +A database query uses input from Bar, but it does not apply the proper encoding +to protect against SQL-Injection. An attacker can inject arbitrary queries to +obtain or modify all customer data. + +The Bar controller at /src/bar use string concatenation to append the barType +variable to an SQL query. + +/src/bar/barController.java +-------------------------------------- +public RESTEndpoint getBar(Session session, string barType) { + [...] + sql.execute("SELECT * from bar_entries where user_id = " + + session.user_id + " and type = " + barType); +-------------------------------------- + +The barType variable is not properly encoded to prevent an attacker from adding +arbitrary SQL queries. Since the endpoint returns the complete output from the +query, it is trivial to retrieve data from any table using the UNION statement. +The screenshot below shows an attacker adding a UNION statement via the barType +variable to obtain financial records from other users. + +[screenshot] + +## Impact + +An authenticated attacker can use the Bar field of the Foo application to execute +arbitrary SQL queries in the database. Arbitrary SQL queries allow the attacker +to insert, modify and delete all data. The data includes customer PII and financial +records. Extraction of such data is considered a data breach according to the GDPR +and can result in large fines. + +## Recommendation + +Use prepared statements to separate user input from SQL queries. This can be done +in Java using the PreparedStatement object. See also: + +https://docs.oracle.com/javase/tutorial/jdbc/basics/prepared.html + +More information on SQL-Injection and other mitigating measures can be found on +the following page from the OWASP Cheat Sheet series: + +https://cheatsheetseries.owasp.org/cheatsheets/SQL_Injection_Prevention_Cheat_Sheet.html +``` + +## 4.2. Writing a conclusion + +1. At the end of writing a report we'll start with a dump of findings and ideas: + +``` +SQL-Injection in the REST API + +Administrative user had weak password + +Cross-Site Scripting in Derp page + +Some active users weren't working at Company anymore + +Application wasn't pentested before, emphasis on the structural security +``` + +2. We clump together findings with the same theme and expand on them a bit. Also add an introduction and part of a closing statement. Here I chose the following clusters: + +``` +Pentest Company performed a pentest on Application between 3 and 17 March 2023. +The application currently has a weak security posture. + +SQL-Injection and XSS are both related to secure development in terms of basic +web security. Share security knowledge in the team. Implement static analysis. + +Weak password use and the outdated account are both related to user management. +Password use is onboarding and account management is offboarding. Improve process. + +Structural security, future development. +``` + +3. Now just write full sentences, shuffle the lines around, and there we go: + +``` +Pentest Company performed a pentest on Application between 3 and 17 March 2023. +The application currently has a weak security posture. High-risk vulnerabilities +show missing controls on basic web security and on user management. + +Basic web security vulnerabilities allow attackers to compromise the database and +to hijack sessions from other users. The vulnerabilities can be prevented by using +security best practices from the Framework framework. It is recommended to share these +practices among the development teams and to incorporate them in the development +process. Static Code Analysis can also be implemented to aid in detecting these +vulnerable patterns. + +The user management process is missing security controls. A high-privileged user +was found to have a weak password. Consider adding or improving password strength +awareness in the onboarding process. Another finding showed that users weren't removed +from the database during offboarding. Fortunately, that issue can be mitigated +using automation. + +Structural improvements are required for securing future development of +Application. Pentest Company advises to mitigate all vulnerabilities and to perform a +retest to validate the new security controls. +``` \ No newline at end of file diff --git a/5.Exercises.md b/5.Exercises.md new file mode 100644 index 0000000..db264fe --- /dev/null +++ b/5.Exercises.md @@ -0,0 +1,121 @@ +## 5.1. Chapter 1 - Writing + +### 5.1.1 Think of three buzzwords for everyday life + +Here we are just having fun expressing an idea using creative word association. Examples: +* microwave-compatible dinner +* rollerblade-soothing pavement +* brain-shattering orgasm +* .. [insert your thoughts] .. + +### 5.1.2 Find words that are softer + +Imagine you're writing a report conclusion. The results are kind of harsh so you want to balance it by using words that are rounder, softer or less loaded. Find a match for the following words to attain that goal. + +* Example: terrifying, formidable +* attacker, ..? +* virus, ..? +* rectify, ..? + +### 5.1.3 Read Shakespeare + +Read Shakespeare his [18th Sonnet](https://www.poetryfoundation.org/poems/45087/sonnet-18-shall-i-compare-thee-to-a-summers-day). Enjoy the words and their rhythm. Try to identify the story structure, as in, the beginning, the middle and the end. Where do you feel the tension is at its peak? + +### 5.1.3 Choose your archetypes + +Link the following five personas to one of the common archetypes below: developer, pentester, attacker, the company, the phishing victim. Link them to the archetype that you think your client will most likely view them as. + +* Hero: The protagonist who embarks on a quest or journey, typically displaying bravery, courage, and a sense of duty. +* Mentor: A wise and experienced figure who guides and provides wisdom to the hero. +* Trickster: A mischievous character who uses wit, deception, or humor to disrupt the status quo. +* Explorer: A character driven by curiosity and a desire for adventure, often journeying into the unknown. +* Rebel: A character who challenges authority or the established order, often seeking change or liberation. +* Villain: The antagonist who opposes the hero and represents evil or conflict. +* Innocent: A character who represents purity, naivety, and a lack of experience. +* Creator/Innovator: A character who brings something new into the world, whether it's an invention, art, or ideas. +* Ruler/King: A character who holds power and authority, often responsible for maintaining order and justice. + +### 5.1.4 Archetype bonus questions + +* Does your client see their company or you as the hero who's embarking on a journey? Or in other words, if they're paying for a pentest, is that their journey or yours? Are you the main character or a side-character? +* Can an application or a server act a character in the story? + +### 5.1.4 Write a Shakespearean sonnet + +Check out Wikipedia at ["Form and structure of the sonnets"](https://en.wikipedia.org/wiki/Shakespeare%27s_sonnets#Form_and_structure_of_the_sonnets). The scheme is: ABAB CDCD EFEF GG. Construct sentences using the [iambic pentameter](https://en.wikipedia.org/wiki/Iambic_pentameter), or five "da-DUM"s if you will. + +## 5.2. Chapter 2 - Content + +### 5.2.1. Write an impact description + +Write an impact description using the method described in 2.4.4 (Impact description). + +### 5.2.2. Create a recommendation + +Suppose a website has an HTML editor that allows users to create blog posts with additional layout, but the users can use it to perform Cross-Site Scripting attacks against each other. What would be your recommendation? + +Hint: Applying output encoding is the wrong answer. + +### 5.2.3. Rewrite a paragraph + +Give the following paragraph a professional make-over. Make it at least less opinionated and better readable. Also consider splitting it in two. + +"_The Foo application has bad security. Developers should step up their game and learn real security. They are doing a bad job at securing their application. Don't take this application into production!_" + +### 5.2.4. Write a conclusion paragraph + +Write a single paragraph that describes the results from the following three findings: +* An administrative account in production has weak, guessable credentials. +* 2FA tokens aren't protected against brute-force attacks. +* The application doesn't produce an audit trail for login attempts. + +### 5.2.5. Estimate a risk + +Let's say I found an SQL-Injection vulnerability in a documentation tool. The SQL user only has read access to public data, and no additional rights like DB Admin. Would you rate it Low, Medium or High? Would you even consider it a finding? + +## 5.3. Chapter 3 - Communication + +### 5.3.1. Spot the core task + +Consider the following excerpt from an intake call: +"_In scope are three applications and a custom SSO API. Employees will eventually use this API to access all internal applications. We chose these three applications as a pilot group before we continue development. We haven't pentested the SSO API before._" + +Think of an argument for performing a white-box assessment on the SSO API. Can you think of an important theme for this story? + +### 5.3.2. Expectation management expectations + +Think of three cases where you should manage expectations. Two examples are given. + +* When there are so many high-risk issues that you have to stop testing and start reporting to deliver the report on time. +* When you're behind on schedule and it looks like you won't be able to deliver proper results in the agreed time frame. +* .. [insert cases] .. + +### 5.3.3. Proactive cases + +* A company has an internal SOC that is testing their monitoring capabilities. Which detail can you pro-actively add to the findings of a Red Team assignment? +* You're on-site, testing an application that is 'only accessible via the internal network'. In the waiting area where guests are picked up you spot a network socket. Think of a proactive test to perform, and how you should go about executing it. +* A colleague accidentally scanned an out-of-scope network range and found a vulnerability. How would you communicate this? And how will you incorporate this into the report? + +### 5.3.4. List positive things + +Make a list of five things that you experience as positive. Three examples are given. If you can't think of anything positive, write positive negatives, e.g. "_At least I'm not currently being eaten by sharks_". If you'd rather be eaten by sharks at the moment, you can always go with the passive aggressive "_It is positive that this meeting is two hours instead of four_". + +Examples: +* Walking in nature +* Walking on grass with bare feet +* Writing two sentences underneath each other that happen to be exactly the same length +* .. [insert positive things you like] .. + +## 5.4. Misc - Self-study + +### 5.4.1. Write an essay + +Write an Essay using Jordan Peterson’s Essay Writing Guide. The guy can be a bit of an absolutist but his writing guide is superb. I highly recommend any technical writer to write at least one essay with it. It is available for free over [here](https://jordanbpeterson.com/wp-content/uploads/2018/02/Essay_Writing_Guide.docx). + +### 5.4.2. Write a finding in the wild + +Pick a CVE or a CTF write-up and write a proper finding from it. + +### 5.4.3. Write about anything + +Any writing will do. Can be a poem, a blog post, a comment or a letter. Do your best to translate thoughts and feelings with precision and inspire others to do the same. \ No newline at end of file diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..3cdc78b --- /dev/null +++ b/LICENSE @@ -0,0 +1,3 @@ +This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License. Read the full license at: + +https://creativecommons.org/licenses/by-nc/4.0/ \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..8ac4e58 --- /dev/null +++ b/README.md @@ -0,0 +1,60 @@ +# Pentest report writing guide + +Some pentesters struggle to effectively write about pentest results, causing findings and reports to end up in the bin. To create a healthy ecosystem we should share knowledge on what makes a pentest report work. Over the years I have developed my own methods for quickly producing high-quality deliverables. By sharing this knowledge I hope you can improve your writing as well. + +Most guide content comes from first-hand experience. Not much research has been done on the effectiveness of these reports, because pentests are performed behind closed doors. Please let me know if parts from this guide have been helpful. + +The entire guide is made to take about an hour or two. The goal is to make it digestible, extensible and fun. Questions and improvements are welcome as Gitlab issues or pull requests. + +## [Part 1](./1.Writing.md) - Writing + +Humans are story-telling creatures, so we'll first look at basic story structure. Order and symbols weave the structure into shape. Shakespeare acts as the peak on symbolism, and we learn what makes text tick. + +The exercises are on creative writing and text aesthetics. + +* Story structure +* Logical order +* Archetypes +* Sound and rhythm +* Lazy wording +* Playful proof +* Finding inspiration + +## [Part 2](./2.Content.md) - Content + +Part 2 discusses the content of essential elements that make up a good pentest report. + +* Title page +* Assessment details +* Conclusion +* The order of findings +* A Finding +* Dos and don'ts + +## [Part 3](./3.Communication.md) - Communication + +We'll see how communication acts as input to our writing, and how we can use that communication to meet the expectations of our clients. + +* The intake call +* Report while you pentest +* Asking the devs +* The findings meeting +* Expectation management +* Being proactive +* Positivity + +## [Part 4](./4.Examples.md) - Examples + +In these two examples we write a finding and a report conclusion from start to finish. + +* Writing a finding +* Writing a conclusion + +## [Part 5](./5.Exercises.md) - Exercises + +Let's develop our writing with some exercises. Every chapter has exercises to help you get better. + +* Chapter 1 - Writing +* Chapter 2 - Content +* Chapter 3 - Communication +* Misc - Self-study diff --git a/build_html.py b/build_html.py new file mode 100644 index 0000000..e916944 --- /dev/null +++ b/build_html.py @@ -0,0 +1,59 @@ +import markdown2 +import re + +link_pattern = r'([^<]+)' + +html_head = ''' + + + + + + + Pentest report writing guide + + + +''' + +author_info = ''' +
+Source repo +License (CC BY-NC 4.0) +
+''' + +sectionFiles_ordered = [ + "README.md", + "1.Writing.md", + "2.Content.md", + "3.Communication.md", + "4.Examples.md", + "5.Exercises.md" +] + +total_html = "" + +for sectionFile in sectionFiles_ordered: + with open(sectionFile, "r") as file: + markdown_text = file.read() + + section_html = markdown2.markdown(markdown_text, extras=["fenced-code-blocks", "cuddled-lists", "smarty-pants"]) + + if sectionFile == "README.md": + section_html = re.sub(link_pattern, r'\2', section_html) + + total_html += section_html + +output_filename = "Pentest report writing guide.html" +open(output_filename,"w").write(html_head) +open(output_filename,"a").write(author_info) +open(output_filename,"a").write(total_html) +open(output_filename,"a").write("") \ No newline at end of file