Automate Penetration Tester Reports with PwnDoc
EISENHOWER MATRIX and strategic development
What does this have to do with anything? I thought it was really important to start by describing the fundamental problem of humanity.
There are 24 hours in a day, about a third of which is spent sleeping, the other third on work, and the remaining time should include meals, entertainment, personal life, walks, sports, rest, education and much, much more. In such a busy schedule, it is very important to follow the best practices of time management. Well, the Eisenhower matrix is exactly about this.
![Eisenhower Matrix Eisenhower Matrix](https://habrastorage.org/getpro/habr/upload_files/fe9/a0e/616/fe9a0e616dbf3ac98e6c2b4493ff16a9.png)
We will not consider the matrix separately (on the Internet many articles on this topic), but let's turn to the top two quadrants: important urgent and important non-urgent. They are also tactical and strategic tasks.
At RAD COP, we strive for the personal well-being of all participants, so we lay a solid foundation for our work in advance and try to think more strategically. Of course, sometimes crises will happen, and they will need to be dealt with, but if all activity consists of crises, and the task list consists only of urgently important ones, then something is clearly wrong with the management (self-management) process, and probably by analyzing the situation it can be significantly improved (here we recommend taking a closer look at the Lyubishchev method). Here, in addition to detecting parasitic cases, restructuring processes often helps, for example, by introducing new technologies and automation.
So, understanding that our future is in automation and artificial intelligence, we naturally observe this direction and try to implement “best practices”. Actually, my review is devoted to the task of automation.
A little bit about the sore subject
Writing reports is not as fun as finding vulnerabilities. Over the years, I have written many reports. Some were templates, some had to be created from scratch.
I communicate with colleagues in the field, and indeed, many offensive security specialists do not like to meticulously and in detail formalize the results of their work. In some companies, all the accompanying routine is transferred to technical writers, in others, pentesters are trained to be independent. I share this pain and express support to all those who do not yet have the resources for automation or a ready-made business process for writing project documentation.
![I know that feeling BRO I know that feeling BRO](https://habrastorage.org/getpro/habr/upload_files/364/543/32c/36454332c4b5463131c31e4023699565.png)
I do my job very quickly. I literally light up at the start of a project and maintain a dynamic rhythm throughout the entire allotted time. I have several tabs in the terminal and browser, several parallel processes, between which I maneuver. I am good not only at breaking, but also at writing texts (sometimes I write in telegram channel ). I write reports well too, but it doesn't give me pleasure, and I don't want to work without pleasure at all 🙂
Large companies have technical writers. They write ready-made reports based on drafts written by the specialists themselves. Separately, we can highlight the role of norm control, as we have in our cooperative. This role helps to build the correct logical coherence of sections, correct formulations, and eliminate jargon. We even made a joke about this track with the help of AI.
Despite the ambiguous attitude towards the process of writing reports, I have a strong feeling that juniors and interns should be directly involved in writing project documentation. This is a very good practice: it teaches how to formulate thoughts, communicate in a “business language”, and increases awareness. In addition, it seems more ethical in relation to technical writers (in our co-op, they are more like analysts, and do not just write documents, but participate in projects, conduct interviews, audit systems, and thus gain the same diverse experience as pentesters).
Midlam+ and above should probably “break” more, do research, mentor juniors, and not waste time (=money) on routine report writing, although here too the need to proofread documents for junior specialists, control quality, and be able to convey the essence of recommendations to the company’s top management in an understandable language is also necessary.
So, in terms of TRIZ (Theory of Inventive Problem Solving) I want to see the following Ideal End Result (IER) – “We automate routine with PwnDoc, we “break” more, learn, create, relax and enjoy life.”
I would like to have a tool that would have:
Flexible template system;
The final result is exported to docx;
Multi-user mode (real time);
User-friendly UI and UX;
Ability to add vulnerability description templates to the database and select only what is needed;
Open source;
At least some support for the tool with response to pull requests.
Meet PwnDoc!
I had heard about the PwnDoc tool much earlier, but I put it off, solving urgently important tasks, until the moment when I caught frustration from writing a report and did not carve out time for strategic tasks. In addition, a colleague suggested that this tool is good and it is worth looking at it. Indeed, it allows you to implement the above wishes.
I spent about a week doing research and it seems I have implemented everything I need at this stage for automated report writing. And now we are in circle of pentesters We are discussing the implementation of this tool as a basic standard for all our specialists.
Thanks to Sergey Zybnev, the author of the telegram channel Pohekfor the tip towards the project PWNdoc-nga good fork of the legacy PwnDoc (hereinafter simply PwnDoc).
Below in the text I will give a short instruction on working with this tool and show what it is capable of. PwnDoc has very cool documentation, further I will refer to it and my experience of using this tool.
Unfolding
First, clone the repository to any location and deploy it via docker-compose.
git clone https://github.com/pwndoc-ng/pwndoc-ng.git
cd pwndoc-ng
docker-compose.up –d
For combat use of PwnDoc, it is recommended to upload your SSL certificate and change the values of jwt secrets in the source code). I also highly recommend closing the web interface behind a VPN or additional password protection at the level web servers.
Immediately after this, the base container images will start downloading. The build may take a long time (hello npm). At the testing stage, I had a problem that a virtual machine with one core could not build a container (keep this in mind), I had to use some skill and upload the finished container image from the workstation to the server. The WEB interface will be available at https://localhost:8443
![Initial registration in the interface Initial registration in the interface](https://habrastorage.org/getpro/habr/upload_files/a74/933/937/a749339377ef1eef4a05241904ef2b51.png)
Initial setup
The very first time you log in after creating an administrative account, you will be prompted to configure the default language and audit types.
![Setting up audit types Setting up audit types](https://habrastorage.org/getpro/habr/upload_files/1b5/7d7/441/1b57d744178d5e461544a45eb6f3a56b.png)
We create a language – RU.
![Language is created Language is created](https://habrastorage.org/getpro/habr/upload_files/281/f7e/80e/281f7e80e7658e3aacefde3d8557ecab.png)
The next step is to add the audit type, but first we need to load the basic template, since we have nothing to choose from yet.
![Interface for selecting a basic template (nothing yet) Interface for selecting a basic template (nothing yet)](https://habrastorage.org/getpro/habr/upload_files/3c1/aba/a64/3c1abaa649a09a5bd38c145b4cfb6dd6.png)
We take the basic template link. in PwnDoc-ng the guys added more details and beauties than in the legacy version, I recommend it.
Go to the menu “Data -> Templates” to add the downloaded template to the system.
![Template loading interface Template loading interface](https://habrastorage.org/getpro/habr/upload_files/f72/b53/0a2/f72b530a2cbf4348a18188d27ce78d6f.png)
We throw in the basic template and click “Create”.
![Create a basic template Create a basic template](https://habrastorage.org/getpro/habr/upload_files/e84/3c2/752/e843c27528cc6a9350f943a7ec05a76b.png)
Now in the “Audit Types” menu we can select the freshly loaded basic template. Let's call our type “Default Audit”. It can be anything: external, internal, social, Wi-Fi or compliance according to GOST or OUD4.
![Creating an audit type Creating an audit type](https://habrastorage.org/getpro/habr/upload_files/9ba/0b0/f28/9ba0b0f28daeed3fc06e88d185328b44.png)
Now we have the menu for creating new reports unlocked.
![Menu for creating new reports Menu for creating new reports](https://habrastorage.org/getpro/habr/upload_files/7c2/9f6/738/7c29f6738af9845dbb78577731becb2b.png)
Adding the first vulnerabilities
So, we have already loaded the basic report template. It's time to describe several vulnerabilities to finally use them in the final report. Go to the “Vulnerabilities” section and click “New Vulnerability”. We don't have any categories yet, so choose “No Category”:
![Menu for creating new vulnerabilities in the database Menu for creating new vulnerabilities in the database](https://habrastorage.org/getpro/habr/upload_files/5a4/447/cc9/5a4447cc92099244323b656ab8ce2be1.png)
We describe the field with the vulnerability name (title), give a description, CVSS rating and how to close the vulnerability (Remediation). Click “Create” to add our first vulnerability to the database.
![This is what the first vulnerability created will look like. This is what the first vulnerability created will look like.](https://habrastorage.org/getpro/habr/upload_files/3bc/6ec/e0c/3bc6ece0c3fe38c0220ecd0967b83b87.png)
Almost everything is ready. We return to the “Audits” section and create a new report. We specify an arbitrary name and the previously created language and “audit type”.
![Create a new report Create a new report](https://habrastorage.org/getpro/habr/upload_files/602/979/00b/60297900be1bce059eb62b19438a8203.png)
I On the main report management screen, you can set the company and contact person of the Customer (added separately in the “Data” section), the time frame for the work, and the testing scope. To add vulnerabilities, click on the plus icon next to “Findings”.
![Interface for interacting with the pentest report Interface for interacting with the pentest report](https://habrastorage.org/getpro/habr/upload_files/e5d/3cc/77c/e5d3cc77cc934e8e416024ca34547bd9.png)
Select the previously created vulnerability from the menu that appears. You can click it several times for greater effect:
![Adding vulnerabilities to a report Adding vulnerabilities to a report](https://habrastorage.org/getpro/habr/upload_files/e72/b88/ef4/e72b88ef4704965fb129bd1224cdaff8.png)
A description of the vulnerability and recommendations for elimination were automatically inserted:
![Hooray, automation Hooray, automation](https://habrastorage.org/getpro/habr/upload_files/f10/0f9/77c/f100f977c339c4f769d654abdd3f800f.png)
At our discretion, we will indicate vulnerable hosts in the “Details” section:
![There could have been a joke about "depends on which Fabric" There could have been a joke about "depends on which Fabric"](https://habrastorage.org/getpro/habr/upload_files/5f5/152/577/5f5152577825a137bfe767fe28bcf838.png)
Don't forget to click the green “Save” button to save the changes. Everything is ready for a test run. Unload the template by clicking the download button:
![Click on the download button Click on the download button](https://habrastorage.org/getpro/habr/upload_files/2a1/7a4/ed3/2a17a4ed3e49f10aec378bc35f848d11.png)
Let's look at the result
After the document has been downloaded from the PwnDoc WEB interface, we will open it in a text editor and see what we have. The organizational information appears at the beginning of the report. Section 4.4 indicates the general list of project vulnerabilities.
![Text from a template vulnerability was inserted into the document Text from a template vulnerability was inserted into the document](https://habrastorage.org/getpro/habr/upload_files/604/044/f7c/604044f7cf5b5978b34a4ef6ed428ce2.png)
We are also interested in item 5 of the report. It displays a detailed description of the vulnerabilities we added:
![Detailed description of the nabloon vulnerability Detailed description of the nabloon vulnerability](https://habrastorage.org/getpro/habr/upload_files/775/2f3/148/7752f3148201195a55e3156e9ba640ca.png)
As you can see, the third-level header, name, vulnerable host, description and recommendations for elimination were automatically entered. The second vulnerability was placed in the next item (5.3.2). Gorgeous!
We make report templates for ourselves
As noted in the official documentation, PwnDoc uses a fairly powerful and flexible docx template engine under the hood. The functionality is described quite well, but I missed examples of logical branching. Anyway, there is enough information to make the template of your dreams.
We have already formed a report template in our cooperative. We like it for many reasons, it is convenient for clients and can be easily supplemented with additional sections depending on the specifics of the project (PCI DSS, RS BR IBBS-2.6-2014, other standards), so I implemented it in the logic of PWNdoc structures. As a first step towards forming your own template, I recommend looking at the source code of the basic template (mentioned earlier). The “raw” report format looks approximately like this, the template engines are visible:
![Table with contacts in "cheese" view Table with contacts in "cheese" view](https://habrastorage.org/getpro/habr/upload_files/837/a8d/6fd/837a8d6fd33d6063697e730bc4690454.png)
You can implement any logic. The template engine supports logical conditions and has a wide range of attributes. For example, here is a division of vulnerabilities by severity level:
![Description of a logical condition with division into levels of criticality Description of a logical condition with division into levels of criticality](https://habrastorage.org/getpro/habr/upload_files/da3/1de/f47/da31def476f348acd4c5a357f7f564ad.png)
The same can be done with external/internal perimeter separation, wireless security auditing, and social engineering testing – any logical conditions with any attributes.
Norm control is also in action!
PwnDoc has a really cool opportunity for review of finished audit reports. This is described in sufficient detail in the project documentation. It is necessary to enable the corresponding setting and assign the role to the required account.
This function is indispensable in our processes, since all finished reports first pass through standard control before sending to the Customer. At this stage, proofreading, checking for logical coherence and formatting take place. With the help of PwnDoc, this process can be made more transparent, and the functionality for setting up a minimum number of confirmations will allow you to implement the role of a project administrator responsible for the technical part and also take into account his review.
Conclusion and further work
I invested time between projects in a really important and strategic review. The next steps will be:
putting PwnDoc into test operation for our projects;
expanding the vulnerability knowledge base;
training colleagues on how to use this tool;
Iterative improvement of the pentest reporting template.
It seems that PwnDoc is capable of solving most of our tasks at the moment. However, I know that one domestic information security company has left PwnDoc for another, commercial solution, and others are using something of their own. Perhaps, in some time, another article will be published, dedicated to criticism of PwnDoc (I hope it won't).
By the way, we are planning to create an open repository of vulnerability templates for PwnDoc. This way, the security community will be able to have access to structured and described vulnerabilities, as well as offer their own templates. By the way, we have already made it publicly available Wikipedia according to GOST 57580.
Subscribe to our telegram channel to follow the announcements: https://t.me/radcop_online
Subscribe to my telegram channel to follow me: https://t.me/pathsecure
And let the Eisenhower square help you distinguish the important from the unimportant and find time for strategic tasks. Until next time!