OSCP-Exam-Report-Template-Markdown: Markdown to PDF Exam Reports with Pandoc

What the Markdown report template actually replaces

Offensive Security exams give you a fixed window to write up findings, and the submission has a required format and file name. The usual route is a word processor: write in Word or LibreOffice Writer, fight whitespace and line feeds, then export. This project replaces that with Markdown source plus a build command. The README frames the motivation directly: LaTeX, Microsoft Office Word and LibreOffice Writer are "no longer needed during your Offensive Security OSCP, OSWE, OSEE, OSWP, OSEP, OSED, OSWA, OSDA, OSMR, OSTH, OSIR exam".

The audience is narrow and specific. You are a certification candidate who already takes notes in Markdown, wants those notes to become the report without reformatting bold and italic by hand, and is comfortable running a command in a terminal. The repository ships templates for network penetration testing exams (OSCP, OSWP, OSEP) and web application exams (OSWA, OSWE), including both official Offensive Security templates and community-improved ones such as whoisflynn v3.2 for OSCP and ceso v1 for OSEP. The README also lists a version-control argument: Markdown is text, so a private git repository gives incremental backup, while .doc and .odt binaries do not diff.

Pandoc, Eisvogel and the Ruby wrapper: how a report becomes a PDF

There is no rendering engine inside this repository. The Markdown file carries a YAML metadata block in its frontmatter, and Pandoc converts it to PDF through the Eisvogel LaTeX template. The README's manual command spells out the moving parts: input is src/OSCP-exam-report-template_whoisflynn_v3.2.md, output is output/OSCP-OS-XXXXX-Exam-Report.pdf, the reader is markdown+yaml_metadata_block+raw_html, and the flags enable a table of contents to depth 6, numbered sections, chapter-level top-level division, the breezedark highlight style and a resource path of .:src.

Everything cosmetic lives in that frontmatter. The README publishes a table of titlepage-color, titlepage-text-color and titlepage-rule-color combinations, for example DC143C with FFFFFF text and an FFFFFF rule, or FFD700 with black text and a black rule. Syntax highlighting is a Pandoc concern, not a template concern: pandoc --list-highlight-styles enumerates what is available, and --highlight-style swaps it.

osert.rb is a convenience layer over that pipeline. According to the README, it prompts for a template, prompts for a syntax highlight style, generates the PDF with an optional preview, generates the 7z archive, and prints an MD5 hash so you can verify the upload afterwards. That last step is the part a manual Pandoc invocation does not give you, and it is the part that guards against the submission naming mistakes the README points at in the Offensive Security exam guide.

Installing the toolchain and generating your first report

The README lists four requirements: Pandoc, LaTeX (TeX Live, to get pdflatex or xelatex), the Eisvogel Pandoc LaTeX PDF template, and p7zip if you want the archive step. It also gives distro-specific one-liners. On Ubuntu the documented command is:

apt install texlive-latex-recommended texlive-fonts-extra texlive-latex-extra pandoc p7zip-full

On ArchLinux the README gives pacman -S p7zip haskell-pandoc texlive-basic texlive-fontsextra texlive-fontsrecommended texlive-latexextra, and on openSUSE zypper in texlive-scheme-medium pandoc p7zip-full. Note that Eisvogel is a separate install from the repository itself; the README links to its installation instructions rather than bundling the template.

BlackArch users have a shortcut. The README states that osert is available as an official package there:

pacman -S osert

Once the dependencies are in place, the workflow is two commands. The first copies a template you will edit; the second builds the artifacts:

ruby osert.rb init
ruby osert.rb generate

The README notes that if you run generation repeatedly, ruby osert.rb generate -h lists options that skip the interactive prompts. If you would rather not use the script at all, the manual Pandoc command in the README produces the same PDF, and optional Lua filters are added with a repeatable --lua-filter option. No Lua filters load when the option is omitted, and the README points to the osert-community-filters repository for community-maintained ones. The manual form looks like this:

pandoc src/OSCP-exam-report-template_whoisflynn_v3.2.md \
-o output/OSCP-OS-XXXXX-Exam-Report.pdf \
--from markdown+yaml_metadata_block+raw_html \
--template eisvogel \
--table-of-contents \
--toc-depth 6 \
--number-sections \
--top-level-division=chapter \
--highlight-style breezedark \
--resource-path=.:src

What you should see is a PDF in output/ whose name follows the exam guide's convention, and, if you used the script, a 7z archive plus an MD5 hash printed to the terminal.

Where this template breaks down

The dependency list is the limitation. This is not a self-contained tool. You need Pandoc, a TeX distribution large enough to carry the LaTeX packages Eisvogel expects, and p7zip for the archive step. The README's own package lists hint at the size: texlive-latex-recommended, texlive-fonts-extra and texlive-latex-extra on Ubuntu, or texlive-scheme-medium on openSUSE. On a locked-down exam machine, or one where you cannot install a TeX distribution, the manual and scripted paths both fail at the same point.

Second, the repository is a template set plus a wrapper script, not an editor. It does not validate that your report contains the sections the exam requires, and it does not check that your findings are complete. The README claims the generation script means you "won't do any submission format and name mistake that way", which is a claim about file naming and archiving, not about content. If your Markdown is missing a section, the PDF will render happily without it.

Third, the README does not document rollback or recovery if a generation run produces a broken PDF, and it does not describe what happens when the Eisvogel template is missing or out of date. There is a FAQ.md file at the repository root, but the README does not summarize its contents, so troubleshooting guidance has to be read from that file directly. Treat the first build as a dress rehearsal rather than something to attempt on exam day.

How it compares to writing the report in a word processor

The obvious alternative is the workflow the README argues against: write the report in Microsoft Office Word or LibreOffice Writer and export a PDF. The difference is not cosmetic. A word processor gives you a WYSIWYG view of the final page and requires no toolchain beyond the office suite, which is why it remains the default for candidates who do not want a build step. Its cost is that the source is a binary: the README notes that version control works with Markdown because it is text, but not with .doc or .odt, so you lose diffable history and incremental backup.

The second alternative is writing LaTeX directly, which the README also positions this project against. LaTeX gives you the same PDF quality and the same version-control properties, and it is what Pandoc ultimately emits here. What you give up is the ability to reuse Markdown notes you already took during the exam, and you take on LaTeX syntax errors during a timed exercise. This project sits between the two: Markdown as the authoring format, LaTeX only as an intermediate that Pandoc generates.

A third path is using a Markdown note-taking app and exporting from it. The README lists Vnote, QOwnNotes and Boostnote as editors you can keep using, but those apps export what they export; they do not run the Eisvogel template or produce the 7z archive with an MD5 hash. The archive and hash step is specific to osert.rb.

Maintenance, licence and what an upgrade costs you

The repository is not archived, and the last push was on 2026-08-12. It is MIT licensed, which is permissive: you can copy the templates into a private repository, modify the frontmatter, and ship your own variant without publishing changes. The README explicitly suggests keeping your report in a private git repository, and MIT does not conflict with that. This is not legal advice, and the Offensive Security exam guide governs what you may submit, so read that guide rather than the licence when the two touch on the same question.

Upgrade cost is driven by the dependencies, not by the repository. Pandoc and the TeX distribution move independently of osert.rb, and Eisvogel is installed separately from this project. A Pandoc major release that changes flag behaviour or a TeX Live update that drops a package can break a build that worked last month. Because the README pins no versions and the repository has no retrieved releases, there is no changelog to consult before upgrading. If you depend on a specific template variant, for example whoisflynn v3.2, pin the Markdown file in your own repository and treat the upstream copy as a reference.

Editorial conclusion

Adopt it if you already write your notes in Markdown and are willing to install Pandoc, a TeX distribution and the Eisvogel template before exam day. Do not adopt it if you want a single binary, a web editor, or a report you can submit without a local build step. Verify first that pandoc, pdflatex or xelatex and p7zip are all on PATH, then run ruby osert.rb init and ruby osert.rb generate on a throwaway report to confirm the PDF and 7z archive are produced with the naming the exam guide expects.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. noraj/OSCP-Exam-Report-Template-Markdown on GitHub
4. Project website
5. README