This project can be used to create a penetration test report based on findings and some extra report content. The findings and issue content are merged and inserted into a LaTeX template. This template is them compiled to PDF.
Use python 3.10.
Clone https://github.com/JJK96/textile_parser and install using pip install -e .
Clone this project using git clone --recurse-submodules. Then install the project using pip install -e ..
Install basictex to have the necessary tools to compile LaTeX: brew install --cask basictex
In order to use the provided functionality for creating standard issues, the program fzf should be installed.
To use diffing of standard issues and report issues, diff is required.
To use the provided tooling for editing, installing Visual Studio Code is recommended, but not required.
To create a new report, use the following command:
reporter init <report_name>
reporter init -l nl <report_name>This will create a new directory with the name <report_name> with the LaTeX template "report.tex" and the directory "issues" with one example issue. This new project is created based on the report_init directory.
The settings for the report can be edited in reporter.ini. These settings include the preferred language, title of the report, company name, etc.
Other report content can be added in report.tex, the file should be self-explanatory.
The report can be created by adding new issues to the issue directory. Each issue has it’s own directory, with an arbitrary name. In the directory, the issue file should have a name that starts with "issue" or ends with ".issue". All other files in the directory are interpreted as evidence.
To aid in creating an issue the command create-issue (alias ci) is provided:
reporter create-issue --title "This is the title"It is also possible to easily create an issue based on an issue from the standard issue library.
reporter create-standard-issueThis opens fzf with all the files in the standard issue library. There one issue can be selected. This issue is then copied to the issues directory.
To aid in creating a new evidence, the command create-evidence (alias ce) is provided:
reporter create-evidence <location> <output-file>This will create a new evidence with the given location (hostname) and store it in the given output file.
To add an image, store it in the folder images in the report and insert the \image{…} command.
Example:
$ ls images
test_image.pngThen anywhere in the report:
\image{test_image}To avoid having to put pentesting tools with footnotes everywhere in the report, there is a framework for managing pentesting tools.
The description of the tools are added in the static_content of the report.
Through tools.tex, the tool definitions are inserted in the report.
If a tools is used in evidence, it can be referred to using \tool{toolname}.
This will insert a reference to the tool description in the place of the tool.
The appendix of the report will contain a list of all the tools used, including their descriptions and URLs.
A tool can be manually declared with
\declaretool[link]{toolname}{description}
The report can be compiled with the following command:
reporter generateThis creates the directory .cache/output with all the files necessary for compilation, compiles the report and copies the resulting PDF report to the current directory.
Reports created with the reporter init command contain a .vscode directory with settings for Visual Studio Code. These settings suggest some plugins for LaTeX editing and compiling, textile support, spelling checking and code review tools. The following popup is shown when VS Code is started.
Installing the plugins is recommended. The LaTeX report can be compiled by clicking the green arrow when editing the report.tex file.
On a high level, the application uses a LaTeX Jinja template and several sources of information provided through either a given template or a given report to compile a PDF file.
The directory templates contains several report templates. A template contains the content and templates for a report. The default template templates/default is used as a fallback for files that have not been overridden in other templates.
A template contains the following information:
-
The LaTeX template in
./report. The LaTeX template contains no text, all text is loaded using jinja. -
Static images in
./static_images, these images can be used by the template -
Static content in
./static_content, this content contains text and placeholders that will be used during jinja templating. Based on the selected language, the correct static content is loaded. -
Dynamic content based on issues, such as counts, summaries, etc.
-
Dynamic content in
./dynamic_text.py, this Python module is optionally included and can be used to add information to the jinja context using Python scripts. -
./reporter.pycan be used to override the Reporter class inreporter/reporter.pyfor advanced customization.
In addition to the information provided by the template, information from the report is added:
-
./report.texcontains user-provided information that should be added to the report -
./reporter.inicontains user-provided settings for the report, including the title and customer name -
Issues and evidences. The directory
issuesin a report contains all issues and evidences for the report. These issues are parsed and merged with the jinja context.
The steps for compiling the report are as follows:
-
Create the
.cachedirectory in which the report is built. -
Symlink all files in the report directory to the
.cache/outputdirectory. -
Copy all LaTeX templates and store them in the
.cache/templatesdirectory. -
Template all LaTeX templates in
.cache/templatesand store the output in.cache/output. -
Copy the necessary supportive files. These files are stored in
necessary_filesand contain a Makefile used to build the project and some other necessary files. -
Run Make in the
.cache/outputdirectory to build the report -
Copy the report PDF file to the report directory.
When copying the template files to .cache/templates, the LaTeX templates are loaded first from parent themes/templates, then from the template itself, and finally from the report directory.
his means that it is possible to override any of the LaTeX templates by copying it from .cache/templates to the report directory and editing it.
These files may contain Jinja tags (\BLOCK{…} and \VAR{…}).
Extra content can be loaded from .yaml files in the report directory.
e.g.
content.yaml
some_variable: testconclusion.tex
\VAR{some_variable}For Textile parsing of Dradis content Textile-Parser is used. This library parses a Dradis file and returns a dictionary containing all fields. The markup in the fields, like bullets, footnotes, etc. is converted to LaTeX and is inserted directly in the resulting Dradis Issue.
#[Number]# 4
Normally, issues are numbered from 1 to n starting with the highest-severity vulnerability as 1.
It is possible to override this automatic number for specific issues by setting the number field in the issue.
#[Label]# mylabel
To refer to an issue somewhere else in the text, the label field can be used to set a label.
It can then be used to reference the issue somewhere in the text using \ref{mylabel}.
#[Location]# server1, server2
Normally the location where an issue is found is determined as the combination of the locations of all evidences.
This can be overriden by setting the location field in the issue.
When running reporter init, the report_init directory is used to create a new report.
The directories report_init/base and report_init/types/<type_name> contain the files that make up the report directory.
Files in these directories are templated using jinja, based on the static content in the template.
The latex template is stored in the templates/default/report/ folder. The heart of the template is the report.cls latex class file. This file contains all kinds of commands and macro’s to simplify the syntax for creating a latex support. It defines the colors for different risk levels of risks. It also defines the title page format and uses variables to fill the variable content.
It is possible to extend or override the existing template by creating a new template in the templates folder.
The file templates/new_template/parents.txt contains one parent template per line (i.e. default).
When loading content, a fallthrough system is used so that files that are missing in the template are loaded from the parent template.
Any file in templates/new_template/report will override a file with the same name in the report directory of parent reports.
The directory static_images can be created in a report. These images are copied to the .cache/output folder in any new reports.
In addition, it is possible to add a file for generating dynamic content. To do this, create a file named dynamic_text.py in the directory of the new template. This file should contain a content like the following:
from reporter.dynamic_text import Generator
class English(Generator):
def generate(self):
self.content['anything'] = "This dynamically created value"
generators = {
"en": English,
}
It is also possible to extend the reporter class. For this, add a file named reporter.py in the directory of the new template. This file should contain a content like the following:
from reporter.reporter import Reporter as Base
class Reporter(Base):
...
def process_issues(self, content, issues):
"""Do something with the content based on the issues"""
...
\companyname{Company B.V.}
Set the company name.
\assignment{CONTENT}
Describe the assignment, what did we do, etc.
\managementConclusion{CONTENT}
Describe the conclusion of the project to the management
\begin{code}
Some code $${{With highlighted text}}$$.
\end{code}
\begin{code}[filename.py]
Some code $$*{{With highlighted text in a different color}}*$$.
\end{code}
Code listings based on lstlistings package.
For creating an issue, the issue environment is available. This environment is normally filled based on the Textile formatted issue and evidence files. The format is described below.
\begin{issue}
\descriptionfield{Thes issue is ... }
\solution{You should ... }
\location{Hostname.domain}
\cvss{0.0}
\cvssvector{CVSS3.1:AV/N...}
\begin{evidence}{Hostname}
Some text ...
\begin{code}
Verbatim code snippet
\end{code}
Some more text ...
\end{evidence}
\end{issue}
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent