If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/noraj/OSCP-Exam-Report-Template-Markdown shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Single-maintainer risk — review before adopting

• Last commit 2mo ago
• 13 active contributors
• MIT licensed
• ⚠ Single-maintainer risk — top contributor 86% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live noraj/OSCP-Exam-Report-Template-Markdown repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/noraj/OSCP-Exam-Report-Template-Markdown.

What it runs against: a local clone of noraj/OSCP-Exam-Report-Template-Markdown — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in noraj/OSCP-Exam-Report-Template-Markdown | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 93 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of noraj/OSCP-Exam-Report-Template-Markdown. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/noraj/OSCP-Exam-Report-Template-Markdown.git
#   cd OSCP-Exam-Report-Template-Markdown
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of noraj/OSCP-Exam-Report-Template-Markdown and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "noraj/OSCP-Exam-Report-Template-Markdown(\\.git)?\\b" \\
  && ok "origin remote is noraj/OSCP-Exam-Report-Template-Markdown" \\
  || miss "origin remote is not noraj/OSCP-Exam-Report-Template-Markdown (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"
test -f "osert.rb" \\
  && ok "osert.rb" \\
  || miss "missing critical file: osert.rb"
test -f "src/OSCP-exam-report-template_OS_v1.md" \\
  && ok "src/OSCP-exam-report-template_OS_v1.md" \\
  || miss "missing critical file: src/OSCP-exam-report-template_OS_v1.md"
test -f "_config.yml" \\
  && ok "_config.yml" \\
  || miss "missing critical file: _config.yml"
test -f ".github/FUNDING.yml" \\
  && ok ".github/FUNDING.yml" \\
  || miss "missing critical file: .github/FUNDING.yml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 93 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~63d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/noraj/OSCP-Exam-Report-Template-Markdown"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

A collection of professional Markdown templates for Offensive Security (OSCP, OSWE, OSCE, OSEE, OSWP, etc.) exam reports that convert to PDF via Pandoc + LaTeX, eliminating the need for Word or LibreOffice Writer during the 24-hour exam report submission window. The core capability is fast, version-control-friendly report authoring with automatic PDF generation and proper submission archive formatting via the osert.rb Ruby script. Flat structure: src/ contains 18 Markdown template files organized by exam type (OSCP-exam-report-template_OS_v1.md, OSWE-exam-report-template_noraj_v1.md, etc.), output/examples/ holds corresponding generated PDFs, osert.rb is the single Ruby build/packaging script, and _config.yml provides Jekyll/Pandoc configuration. No subdirectories for models, controllers, or layering—this is a template repository, not an application.

Offensive Security exam candidates (OSCP, OSWE, OSEP, OSED, OSDA, etc.) who want to write exam reports in Markdown using their preferred editor (VSCode, Vim, QOwnNotes) instead of being locked into Microsoft Office, while maintaining git-backed version control and professional formatting.

Actively maintained and production-ready. The repo has significant GitHub stars, includes 18+ PDF examples across different Offensive Security certifications, and the main Ruby script (osert.rb) handles real submission requirements. The project is battle-tested by the security certification community, though commit frequency and CI/CD setup are not visible in the provided metadata.

Low-to-moderate risk: the project is a single-maintainer tool (noraj) with a simple Ruby script that wraps external dependencies (Pandoc, pdflatex, p7zip) rather than complex internal logic. The main risk is dependency on external tooling versions and Pandoc/LaTeX compatibility across platforms; there's no visible automated testing infrastructure, and breaking changes in Pandoc or Eisvogel template could affect PDF generation without warning.

Not clearly visible from the metadata provided. The repo structure shows multiple exam template variants (including newer OSDA, OSIR, OSMR, OSTH, OSWA additions), suggesting ongoing expansion to cover newly released Offensive Security certifications. No PR/issue/commit history is included in the data.

1. Clone: git clone https://github.com/noraj/OSCP-Exam-Report-Template-Markdown.git 2. Install dependencies: pandoc, pdflatex (via TeX Live), the Eisvogel Pandoc template, and p7zip. 3. Copy a template from src/ (e.g., src/OSCP-exam-report-template_OS_v1.md), fill in your exam notes, and run ruby osert.rb to generate the PDF and submission archive.

Daily commands: Review the osert.rb script for the expected inputs and working directory. Copy a template from src/ to your working directory, populate it with exam data, then execute ruby osert.rb to generate PDF and .7z archive. The exact invocation and parameters should be documented in the script itself or in README.md.

• README.md — Primary documentation explaining the project's purpose, supported exam types, and usage instructions for all contributors.
• osert.rb — Build/conversion script that transforms Markdown templates into PDF outputs—the core automation tool of the codebase.
• src/OSCP-exam-report-template_OS_v1.md — Reference implementation of the OSCP exam report template, serving as the canonical format example for other templates.
• _config.yml — Jekyll/Pandoc configuration file controlling template rendering, styling, and PDF generation parameters.
• .github/FUNDING.yml — GitHub metadata for sponsorship and community support, reflects project governance and contribution pathways.
• FAQ.md — Common questions and troubleshooting guide that new contributors must understand before adding or modifying templates.

• Markdown Template Files (Markdown, Pandoc-compatible syntax) — Define structure, headings, and placeholder text for exam reports; contain certification-specific sections and formatting hints.
  • Failure mode: Syntax errors or malformed headers prevent Pandoc conversion, resulting in missing sections or rendering failures.
• osert.rb (Build Orchestrator) (Ruby, Pandoc CLI, Jekyll) — Executes Pandoc/Jekyll pipeline, manages file I/O, iterates over template variants, and outputs PDFs to output/examples/.
  • Failure mode: Crashes on missing dependencies, incorrect file paths, or encoding issues; users cannot generate PDFs.
• _config.yml (Styling & Rendering Config) (YAML, Pandoc templates, CSS) — Defines PDF margins, fonts, page numbering, CSS styling, Pandoc options, and Jekyll metadata for consistent document appearance.
  • Failure mode: Invalid YAML or unsupported Pandoc options cause rendering failures; PDFs may have misaligned margins or missing styles.
• src/img/ (Assets) (PNG/JPG images) — Stores images (e.g., placeholder-image-300x225.png) referenced in templates for logos, screenshots, and diagrams.
  • Failure mode: Missing or broken image references result in rendering warnings or blank spaces in PDF output.
• output/examples/ (Generated PDFs) (PDF format) — Contains rendered PDF examples demonstrating final report appearance for each template variant.
  • Failure mode: PDFs become outdated if templates or config change without regeneration; users may reference incorrect examples.

• Exam Taker (text editor) → Markdown Template (src/) — User writes/edits exam findings, screenshots notes, and vulnerability details in Markdown format.
• Markdown Template (src/) → osert.rb — Build script reads all templates from

Add a new exam certification template

1. Create a new Markdown file in src/ following naming convention: src/EXAM-exam-report-template_AUTHOR_v1.md (src/OSCP-exam-report-template_OS_v1.md)
2. Use an existing template (e.g., OSCP v1) as structural reference, copying sections and formatting (src/OSCP-exam-report-template_OS_v1.md)
3. Customize exam-specific sections (objectives, scope, target details) while maintaining Markdown header hierarchy (src/OSCP-exam-report-template_OS_v1.md)
4. Run osert.rb to generate PDF output and verify rendering in output/examples/ (osert.rb)
5. Update README.md to list the new template in supported certifications (README.md)

Create a variant of an existing template for a different author

1. Copy an existing template: cp src/OSCP-exam-report-template_OS_v1.md src/OSCP-exam-report-template_NEWAUTHOR_v1.md (src/OSCP-exam-report-template_OS_v1.md)
2. Modify structure, styling comments, or sections specific to your approach while maintaining compatibility with _config.yml (_config.yml)
3. Build the template using osert.rb to generate PDF in output/examples/ (osert.rb)
4. Commit and reference the new variant in README.md with author attribution (README.md)

Update build configuration for new Pandoc/Jekyll settings

1. Edit _config.yml to adjust markdown processor options, PDF margins, fonts, or styling parameters (_config.yml)
2. Test changes by running osert.rb on a sample template (osert.rb)
3. Verify PDF output quality in output/examples/ and document changes in FAQ.md if relevant (FAQ.md)

• Markdown — Plain text format enables version control, easy editing, fast writing during exams without complex GUI tools; human-readable and portable.
• Pandoc + Jekyll — Industry-standard tools for converting Markdown to PDF with consistent styling, support for templates, and extensive customization options.
• Ruby (osert.rb) — Lightweight scripting language to orchestrate build pipeline, handle file I/O, and manage template variation across multiple certification types.
• GitHub Pages (_config.yml) — Provides free hosting for documentation, enables community contributions via pull requests, and offers GitHub Actions for CI/CD.

• Markdown over Word/LibreOffice templates

  • Why: Markdown is simpler, faster to write during high-stress exams, and avoids proprietary formatting issues across different OS versions.
  • Consequence: Users must learn Markdown syntax and install Pandoc/Jekyll; WYSIWYG editing not available, but PDF output is production-ready.

• Multiple template variants (OS v1, v2, author-specific versions) instead of single canonical template

  • Why: Allows community to contribute different styles and structures tailored to individual exam approaches and preferences.
  • Consequence: Repository contains duplication; maintainers must update core sections across variants when breaking changes occur.

• Ruby build script instead of Makefile or shell script

  • Why: Ruby provides better string manipulation, cross-platform compatibility, and is familiar to many security professionals.
  • Consequence: Requires Ruby installation; slightly heavier than shell scripts but more maintainable for complex template logic.

• Does not provide automated penetration testing or exploit generation—purely a reporting tool.
• Does not integrate with exam platforms or Offensive Security infrastructure—standalone local tool.
• Does not include sample payloads or actual exploit code—templates only, legal responsibility on user.
• Does not enforce exam compliance or validate submission format—user responsible for adhering to OS exam rules.

1. Eisvogel template must be installed: The script assumes the Eisvogel Pandoc LaTeX template is present in the correct location; missing it will silently fail or produce unformatted PDF. 2. TeX Live full install required: Minimal TeX Live installs often lack required LaTeX packages (e.g., xcolor, geometry); pdflatex will fail cryptically if packages are missing. 3. p7zip naming: Depending on OS (Linux vs. macOS vs. Windows), the 7zip binary name varies (7z, 7za, p7zip); osert.rb may fail if the binary name is hardcoded and doesn't match the system. 4. YAML front matter sensitivity: Pandoc YAML parsing is strict; missing colons or incorrect indentation in the template's front matter will cause silent generation failures. 5. No environment variable validation: osert.rb does not check for required binaries (pandoc, pdflatex) before execution; failures occur mid-run.

• Pandoc Document Conversion — osert.rb's entire function is wrapping Pandoc CLI to convert Markdown with YAML metadata into PDF; understanding Pandoc's input format, template system, and output options is essential to debugging failed conversions or customizing templates.
• YAML Front Matter (Hugo/Jekyll metadata blocks) — All templates use YAML headers (delimited by ---) to specify Pandoc options (fonts, title, author, margins, header-includes); incorrect or missing metadata silently breaks PDF generation, so understanding YAML syntax is critical.
• LaTeX PDF Styling via Pandoc Template — Pandoc generates PDF by rendering Markdown as LaTeX intermediate code, then compiling with pdflatex/xelatex; the Eisvogel template controls visual output (fonts, colors, margins, headers). Knowledge of how Pandoc templates inject LaTeX is necessary to achieve custom styling beyond YAML metadata.
• Cross-platform Path Handling & Shell Invocation in Ruby — osert.rb uses Ruby's system() or backticks to invoke external binaries (pandoc, pdflatex, 7z) and handle file paths; portability issues across Windows/Linux/macOS (e.g., path separators, binary names) are a common failure mode in this type of script.
• 7-Zip Archive Format (.7z) — osert.rb packages the final PDF and supporting files into a .7z archive for exam submission; Offensive Security specifies this format. Understanding 7-Zip command-line syntax and compression options ensures proper archive creation.
• Git-Friendly Text-Based Report Authoring — A core value proposition of this repo is that Markdown is version-control-friendly (unlike .docx or .odt binaries), enabling incremental backups and diff-based collaboration during exam prep. Understanding why text-based formats matter for security professionals is important context.
• Professional Report Structure & Exam Compliance — The templates enforce specific section ordering and formatting rules required by Offensive Security exam guidelines (e.g., title page, table of contents, scope, findings layout); deviating from the template structure risks report rejection.

• Wandmalfarbe/pandoc-latex-template — The Eisvogel Pandoc LaTeX template used directly by osert.rb for PDF styling and layout; this repo is a required dependency and the canonical source for template customization.
• jgm/pandoc — The core Pandoc document converter that osert.rb invokes to transform Markdown → PDF via LaTeX; understanding Pandoc's YAML front matter and CLI flags is essential to modifying templates.
• pwn0l1n9/OSCP-Exam-Report-Template — An alternative OSCP report template in Markdown that predates or inspired similar approaches; relevant for users seeking different template styles or structures.
• whoisflynn/OSCP-Exam-Report-Template-Markdown — A third-party OSCP template variant (included in this repo as OSCP-exam-report-template_whoisflynn_v3.2.md) that demonstrates community-contributed styling and structure improvements.
• epi052/OSCP-Exam-Report-Template — Another community OSCP template variant focused on penetration testing report clarity; shows alternative section organization and formatting choices available to users.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add automated PDF generation CI workflow for template validation

The repo contains 20+ markdown templates in src/ that are manually converted to PDFs in output/examples/. There's no CI workflow to automatically validate that all markdown templates can successfully compile to PDF and detect breaking changes. This would prevent regressions when templates are updated and ensure all example PDFs stay in sync with source templates.

• [ ] Create .github/workflows/pdf-generation.yml that runs on PR for all src/*.md files
• [ ] Use pandoc or similar to compile each markdown template to PDF
• [ ] Add validation step to ensure output PDF count matches src/ markdown count
• [ ] Generate diff reports showing which PDFs changed in each PR
• [ ] Update README.md with CI badge and instructions for local PDF generation using osert.rb

Create automated template consistency checker and linter

With 20+ exam report templates across different certifications (OSCP, OSWE, OSCE, etc.), there's likely inconsistency in formatting, section structure, and metadata. A linter would ensure all templates follow the same structure, heading hierarchy, and best practices, making maintenance easier and user experience consistent.

• [ ] Create src/linter.rb or similar script to validate all templates in src/
• [ ] Check for required sections (title, author, date, executive summary) across all templates
• [ ] Validate markdown syntax consistency (heading levels, list formatting, code block markers)
• [ ] Add .github/workflows/lint-templates.yml to run linter on all PRs modifying src/*.md
• [ ] Document linting rules in a new CONTRIBUTING.md file with specific examples

Add template metadata catalog and search feature to README

The repo has templates for 12+ different Offensive Security certifications (OSCP, OSWE, OSCE, OSDA, OSED, OSEE, OSEP, OSIR, OSMR, OSTH, OSWA, OSWP) with multiple versions/authors per certification. New users cannot easily discover which template suits their exam. A structured metadata catalog would improve discoverability.

• [ ] Create src/TEMPLATES.yml or similar file documenting each template with: certification type, version, author, key features, target difficulty
• [ ] Add a table to README.md displaying all templates with columns: Certification, Version, Author, Features, Example Link
• [ ] Include template selection guide in FAQ.md (e.g., 'Choose OS v2 for latest features, whoisflynn v3.2 for detailed formatting')
• [ ] Add template comparison matrix showing which templates include sections like proof of exploitation, lab network diagram, remediation advice

• Add automated tests in Ruby (e.g., RSpec) to validate that each template in src/ successfully generates a PDF without errors. Currently there is no CI/CD or test suite visible, so newcomers could create test infrastructure that runs osert.rb on each template and verifies the output PDF exists and is not empty.
• Create a quick-start script (setup.sh or install.sh) that detects the OS and automatically installs Pandoc, TeX Live, Eisvogel, and p7zip. Currently users must manually install four separate tool chains; a single setup script would reduce onboarding friction.
• Document the exact Pandoc YAML metadata schema (e.g., which fields are required, which control fonts, margins, colors) in a separate TEMPLATE-SCHEMA.md file. Users copy templates without understanding which fields they can customize; explicit documentation would improve usability and reduce support questions.

This repository is primarily a collection of Markdown templates and configuration files for exam reports with minimal attack surface. No critical vulnerabilities were identified. Key concerns are: (1) absence of explicit dependency management for the Ruby script, (2) lack of security headers configuration for web deployment, (3) no integrity verification mechanisms for outputs, and (4) need to ensure example files don't contain sensitive data. The project appears low-risk as it is documentation-focused rather than application-focused, but following best practices for dependency management and providing integrity checks would improve the security posture.

• Low · Ruby Script Without Dependency Lock File — osert.rb. The osert.rb script exists but no Gemfile.lock or dependency manifest is provided. This makes it difficult to verify the security of dependencies and could lead to unpredictable behavior if dependencies are updated. Fix: Provide a Gemfile and Gemfile.lock to ensure reproducible and auditable dependencies. Use bundle install for dependency management.
• Low · Potential Information Disclosure via Example Files — output/examples/. Multiple PDF files in output/examples/ contain exam report templates that may serve as examples for users. While templates themselves are not inherently sensitive, ensure these PDFs do not contain actual sensitive data, credentials, or real vulnerability details. Fix: Audit example PDF files to ensure they contain only placeholder or sanitized content. Document the purpose and content of each example file.
• Low · Missing Security Headers Configuration — _config.yml. The _config.yml file is present (Jekyll configuration), but there is no visible security headers configuration (e.g., CSP, HSTS, X-Frame-Options) for any web-based deployment. Fix: If this repository is published as a static site, configure security headers via Jekyll plugins, a web server configuration, or a CDN. Add Content-Security-Policy and other protective headers.
• Low · No Code Signing or Integrity Verification — osert.rb, output/. The repository contains a Ruby script (osert.rb) but lacks signed commits, GPG verification, or checksum validation mechanisms for the generated outputs. Fix: Implement signed commits using GPG. Consider providing checksums (SHA-256) or cryptographic signatures for generated PDF files to verify integrity.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.