noraj/OSCP-Exam-Report-Template-Markdown (aka osert) converts Markdown notes into professional PDF exam reports for authorized Offensive Security certification candidates, eliminating WYSIWYG formatting pain.

Anyone who has survived the 24-hour report-writing window after an OffSec practical exam knows the real enemy is often not the machines but the word processor. noraj/OSCP-Exam-Report-Template-Markdown, packaged as the osert tool, attacks that problem directly: it provides ready-made Markdown templates matching the official report formats for the full span of Offensive Security certifications, plus a Ruby script that turns them into polished PDF deliverables. The project has accumulated roughly 4.2k stars on GitHub, is written primarily in Ruby, and ships under an MIT license, which tells you something about how much the community wanted this workflow to exist.

The core premise is simple and well argued in the README: you should write your exam report the same way you take notes. Candidates overwhelmingly capture their lab and exam work in Markdown already, and the traditional route forces a lossy transcription into Microsoft Office Word or LibreOffice Writer, where WYSIWYG editors introduce unwanted whitespace, broken line feeds, and formatting drift. With osert, the notes you already have become the report itself, which the README correctly identifies as a major time saver during the gruelling post-exam documentation window. The efficiency argument is not cosmetic — formatting mistakes and submission-format errors are one of the classic avoidable failure modes of OffSec exams.

A second architectural advantage the author emphasizes is version control. Because .md files are plain text, they diff cleanly in git, whereas binary .doc and .odt files do not. The README explicitly recommends storing the report in a private git repository, which gives you incremental backups for free. For a document you may be editing for 24 straight hours under exam stress, that resilience matters; a corrupted odt file at hour 20 is the kind of story that circulates in certification forums every year. You also keep your favorite editor or note-taking app — the README name-drops VSCode, Atom, Vnote, QOwnNotes, and Boostnote — rather than being tethered to a Windows machine just to run MS Word.

Under the hood, the pipeline is standard document tooling composed carefully rather than novel engineering. pandoc does the conversion, driven by the excellent Eisvogel LaTeX PDF template, with pdflatex or xelatex from a TeX Live installation handling typesetting. p7zip is only needed if you want the script to produce the submission archive. The README gives pacman, zypper, and apt install lines for the full dependency stack, so setup on Arch, openSUSE, or Ubuntu is a single command — a nice touch for a project aimed at people who are already running Kali-class Linux environments.

The workflow has an automatic and a manual path. The automatic path is the Ruby driver: ruby osert.rb init interactively lets you choose a template, and ruby osert.rb generate produces the PDF, optionally previews it, builds the 7z archive, and prints an MD5 hash so you can verify the uploaded file after submission. That last detail is characteristic of the project's attention to the real failure modes — OffSec checks submission format and naming, and the script eliminates human error there. The README also notes that repeated generations can skip the interactive prompt via options visible in ruby osert.rb generate -h, and that osert is packaged in BlackArch as pacman -S osert.

The manual path is just a documented pandoc invocation, which is worth reading even if you never use it verbatim because it reveals the template's knobs: --from markdown+yaml_metadata_block+raw_html enables the YAML frontmatter that controls title-page styling, --template eisvogel selects the LaTeX skeleton, and --table-of-contents, --toc-depth 6, --number-sections, and --top-level-division=chapter shape the document structure. --highlight-style breezedark sets code syntax coloring, with the full list available via pandoc --list-highlight-styles. Knowing the manual command means you can debug or customize when the script's abstractions get in the way.

Template coverage is where this project genuinely outgrew its OSCP origins. For network penetration testing there are OSCP templates in three flavors — official v1 and v2 plus the popular whoisflynn improved v3.2 — and OSEP with official and ceso variants. Web application candidates get OSWA and OSWE, the latter with community improvements from noraj and xl-sec. Exploit development is covered by OSED, OSEE, OSMR for macOS research, and the deprecated OSCE. Notably, the collection also reaches into the defensive catalog: OSDA for security operations, OSTH for threat hunting, and OSIR for incident response, making this a reporting toolkit for OffSec's whole portfolio, not just the offensive side.

Each template ships with rendered PDF examples in the repository's output/examples/ directory, so you can inspect exactly what the final document looks like before committing to the workflow. The README also documents a curated table of well-rendering color sets for the YAML frontmatter — titlepage-color, titlepage-text-color, and titlepage-rule-color combinations like DC143C Crimson with white text, or 1E90FF DodgerBlue with Snow — which lets candidates produce a professional-looking cover page without ever opening a design tool. It is a small thing, but it reflects the project's general philosophy of removing decisions that eat exam time.

Extensibility comes through Pandoc's Lua filter mechanism. The repeatable --lua-filter option lets you load bundled or external filters, and no filters are applied when the flag is omitted, keeping the default output predictable. Community-maintained filters live in the separate noraj/osert-community-filters repository, which is a sensible split: the core tool stays lean while optional transformations evolve at their own pace. This is the kind of plugin boundary you rarely see in a project that started as a set of exam templates, and it suggests osert is being treated as a small document platform rather than a static download.

The ecosystem around the project is unusually healthy for its niche. Dockerized builds are available from two community forks (ret2src and Tripex48), which sidesteps the TeX Live dependency headache entirely for people who want a reproducible environment. The README's mentions section shows sustained real-world adoption: John Hammond featured it in both his OSCP note-taking and OSEP videos, it placed third in an awesomeopensource roundup of top offensive security open source projects in early 2022, and multiple independent certification-journey write-ups cite it as part of the standard OSCP preparation stack.

From a defensive and organizational perspective, osert deserves attention too. Consulting teams that already standardize on Markdown and git for engagement notes can adopt the same pipeline for client deliverables, gaining reviewable diffs, deterministic builds, and consistent branding via the frontmatter. The tool itself has no offensive capability — it never touches a network target — so there is no telemetry or detection angle; it is pure documentation infrastructure. The only operational caution is process-level: verify you are using the template version that matches the current official report requirements for your exam, since formats and submission rules do change between course revisions, and the README itself marks the OSCE variant as deprecated.

For anyone staring down an OffSec practical with a 24-hour report clock, noraj/OSCP-Exam-Report-Template-Markdown is close to mandatory preparation. It converts the least enjoyable part of certification — transcription and formatting — into a mechanical git-friendly workflow, wraps it in a script that guards against submission errors, and covers nearly every exam in the Offensive Security catalog. The combination of ~4.2k stars, active packaging in BlackArch, community Docker images, and a Lua filter ecosystem indicates a mature, trusted tool rather than a one-off convenience script.

Educational analysis for authorized security professionals. Use only in controlled, authorized environments.

Related coverage

• afrog for vulnerability scanning across bug bounty and authorized pentest workflows