In penetration testing and bug-bounties, it is extremely important to be good in reporting/managing data. Remembering each and everything is not an easy task and when it comes to documentation part it becomes boring too.
In this blog post, we will see how to use markdown and mkdocs to document useful information as a static website. It gives an amazing view of the document and is very handy during penetration tests and bug bounties.
Let’s follow the instructions and get started!!! By the end of this post, you should be able to create our own knowledge base (like checklist/test cases to assist during pen-testing or doing bug bounty).
There are different ways to manage the documentation, we found this one to be quick to set up, easy to use and intuitive. We will use markdown to write the source code and one yml file to manage the configuration like site name, theme, pages, etc.
Let’s start with the Installations part:
- go here and install mkdocs.
- Prerequisites: install python (here)
- Pip: installing pip for the first time then use “python get-pip.py” (if you are on Windows OS make sure to add it to Environment variable after installation )
- Go inside the downloaded mkdocs folder –> run #pip install mkdocs
- mkdocs –version ( it will show you mkdocs version )
- Create a new project : mkdocs new [dir-name]
E.g. : mkdocs Knowledgebase
It creates a directory with the name of Knowledgebase and inside this directory, it has docs directory:
- docs it contains pages .md files e.g. index.md file to display a message
- mkdocs.yml :
mkdocs.yml is a file contains all the information like the theme, site_name, manage pages and source code of these pages have markdown for the beautiful presentation of documents in HTML form
Index.md, tools.md and similar all other markdown files will be created and stored inside the docs folder, of the Knowledgebase.
Add site name, theme, new page :
1: Goto docs folder –> create a “Guide.md” file
2: Open it in notepad –> type “Basics commands guide”
3: Open mkdocs.yml file –>Add site name using “site_name: knowledge base”
4: Inside the nav tag add “ – Guide: Guide.md ” similarly you can add other markdown pages
5: Add theme using “ theme: readthedocs”
you can also try different themes from here
Preview of documentation using mkdocs built-in dev-server :
1: Go inside your project folder where mkdocs.yml is present
2: Run “mkdocs serve”
3: Goto browser and visit 127.0.0.1:8000
Note: do not close the terminal /PowerShell while you are using the knowledge base and keep saving the markdown files.
Add images in page:
1: Create a img folder inside docs
2: Put the img inside the img folder
3: Follow syntax ![alt txt](/img/name.jpg)
E.g. ![could not load!!!](/img/name.jpg)
Add text in the code box:
1: Give a tab space according to the indentation or use “` add text here“`
After adding some content to the Knowledgebase it will look like this:
Why markdown for pen-testers and bug bounty hunters?
Markdown is lightweight markup language.it’s popularity is because of simplicity and low writing threshold.we can learn all the syntax from here in 60 seconds and start creating our first document. Markdown can help pen testers and bug bounty hunters in making POC and knowledge base. well written POC’s ensures that the issues can be reproduced or reconstructed for analysis later on. as well as Blogs and video links can be stored according to vulnerability category with summary and important points to have a quick review. Pentesting or Bug hunting checklist can be created with details steps to test the vulnerabilities.
Here we will create a sample document for pentester/bug bounty hunter how they can use markdown for documentation for creating a Pentesting report /Proof Of Concept /list of links/Knowledgebase.
Let’s get started!!!
1: Create a new project using: mkdocs pocs
2: Go inside pocs and run mkdocs server :
Run “mkdocs serve”
3: Open directory pocs >docs
Create a markdown file with the name “report.md” (this is to create a separate markdown page else you can open the index.md file and start creating doc)
4: Goto pocs > open mkdocs.yml and add
site_name: Pentesting report
– Report: report.md
5: Browse http://127.0.0.1:8000/
It will show the default content of the index.md file and a new markdown page Report which we created for writing a POC.
- Open report.md
- Start writing using markdown syntax
- Sample markdown code for a report
# Penetration testing report ## Cross Site Scripting Vulnerability (XSS) ### Vulnerable Input field The application *search field* is vulnerable to cross site scripting vulnerability aka **XSS** ### Overview Reflected cross-site scripting vulnerabilities arise when data is copied from a request and echoed into the application's immediate response in an unsafe way. ### Proof of Concept - Visit the URL [http://www.example.net//search.jsp?query=](http://www.example.net//search.jsp?query=) - Insert the below payload and click on search button ``` <script>alert('Alert XSS!!!')</script> ``` - Then you can see the alert box. - Please find the below sample output screen shot for reference ![xss](/img/xss.jpg) ### mitigation - [Reference for more details can found here](https://www.owasp.org/index.php/XSS_(Cross_Site_Scripting)_Prevention_Cheat_Sheet)
Copy the Content in report.md and save it and check 127.0.0.1:8000/report/
Note: make sure to keep the Image file in the docs/img and give the right path in markdown syntax
Similarly, a list of blogs can be collected with important built points/testing steps.
Sample code for the list of blogs
#XSS Blogs list [Finding and exploiting Blind XSS](https://enciphers.com/finding-and-exploiting-blind-xss/) How to find Blind XSS and what are the appropriate tools for this purpose? - First of all, you need to signup for XSSHunter - Now if you go to the Payloads section [here](https://xsshunter.com/app) you will see there are different payloads with the proper description on where you could use them. -Next step is to just simply copy and paste these payloads and start inserting them in different fields as we already told you before(contact us, feedback, address etc). -Once done, you can just sit down and check your XSS Fires tab at a later time. If the payload gets executed anywhere it will give the full details of the bug and will also mail you a report which is super helpful.
Create a static HTML website: it creates a site with static HTML pages that can be hosted on Github pages, Amazons3 many more similar platforms.
1: Goto the pocs folder and create a site using
This will create a new directory with the name “site”
Now we have the site ready with the directory name “site”. we can host it to any platform where we want to host it.