noraj/OSCP-Exam-Report-Template-Markdown · 上手攻略

  • 仓库：noraj/OSCP-Exam-Report-Template-Markdown
  • 链接：https://github.com/noraj/OSCP-Exam-Report-Template-Markdown
  • 分类：academic-writing / 安全认证报告模板
  • 作者：spark
  • 更新：2026-08-13

是什么

这是一套面向 Offensive Security(OffSec)考试体系(OSCP / OSWE / OSEE / OSWP / OSEP / OSED / OSWA / OSDA / OSMR / OSTH / OSIR)的 Markdown 报告模板仓库,作者 noraj。核心思路:考生在 24 小时考试窗口里写渗透测试报告时,不再依赖 LaTeX 或 Word 的"所见即所得",而是直接用 Markdown 写笔记/写报告,通过 Pandoc + Eisvogel LaTeX 模板 转成可提交的 PDF,再由 osert.rb 脚本自动打包成 7z 归档并计算 MD5,符合 OffSec 的提交格式要求。

仓库目前覆盖 11 门考试的官方模板 v1/v2 + 社区改进版(whoisflynn OSCP v3.2 / noraj OSWE v1 / xl-sec OSWE v1 / epi OSED v1 / ceso OSEP v1 等),并提供了 Ruby 脚本 osert (OSCP Exam Report Tool) 把"选模板→选高亮主题→生成 PDF→生成 7z→输出 MD5"做成交互向导。它在 BlackArch 上还是官方包(pacman -S osert),有 repology 元数据可查。

解决什么问题

OffSec 考试的报告提交历来有几个痛点:

  1. 时间紧:24 小时内既要做渗透,又要写一份 30-80 页的专业报告,排版开销越大越吃亏。
  2. WYSIWYG 编辑器的副作用:Word/Writer 的多余空白/换行/字体替换经常让 OffSec 评审抱怨。
  3. 格式错误导致驳回:归档命名、压缩格式、MD5 不对就直接退回。
  4. 笔记不能直接复用:考场里用 Markdown 记的攻击步骤,写报告时要重新贴进 Word,丢失粗体/列表等样式。

这套模板把这四件事一次性解决:Markdown 输入 → Eisvogel/Pandoc 出 PDF → 脚本出 7z + MD5,考场笔记和报告共用一份源。

快速安装

依赖 4 件套:Pandoc / LaTeX(TeX Live)/ Eisvogel Pandoc LaTeX 模板 / p7zip(可选,跑脚本才要)。

Ubuntu/Debian:

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

Arch Linux(一条命令连 osert 一起装):

sudo pacman -S pandoc texlive-basic texlive-fontsextra \
             texlive-fontsrecommended texlive-latexextra p7zip
sudo pacman -S osert  # 仓库自带的 osert 包装脚本

openSUSE:

sudo zypper in texlive-scheme-medium pandoc p7zip-full

Eisvogel 模板(关键,缺它 Pandoc 找不到样式):

# 方式 A:下 release zip 解压到 ~/.pandoc/templates/
wget -O eisvogel.zip https://github.com/Wandmalfarbe/pandoc-latex-template/releases/latest/download/Eisvogel.zip
mkdir -p ~/.pandoc/templates
unzip -j eisvogel.zip 'Eisvogel/*' -d ~/.pandoc/templates/eisvogel/

# 方式 B:用 pandoc 自带的模板安装路径(不同 Pandoc 版本路径略不同)

克隆仓库:

git clone https://github.com/noraj/OSCP-Exam-Report-Template-Markdown.git
cd OSCP-Exam-Report-Template-Markdown

核心用法

1. 用 osert.rb 脚本走交互流程(推荐新手)

ruby osert.rb init         # 选模板(whoisflynn v3.2 / 官方 v1/v2 / 其他改进版)
ruby osert.rb generate     # 选语法高亮主题 → 生成 PDF → 生成 7z → 输出 MD5
ruby osert.rb generate -h  # 查看免交互选项,反复生成时省时间

generate 完成后 output/ 目录下会有 OSCP-OS-XXXXX-Exam-Report.pdf 和对应的 .7z 归档。

2. 直接调 Pandoc(高级用户,更灵活)

仓库给的官方最小命令长这样(以 whoisflynn v3.2 为例):

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

要点解释:

  • --template eisvogel 必须,否则 Pandoc 默认 LaTeX 模板不带封面/水印。
  • --top-level-division=chapter 让 # 一级标题当"章",目录层级才正确。
  • --highlight-style breezedark 是暗色高亮(配合考场截图常用),可改成 breezedark、tango、zenburn 等(pandoc --list-highlight-styles 看完整列表)。
  • YAML 头部 titlepage-color/titlepage-text-color/titlepage-rule-color 三色块决定封面配色;README 里给了 8 套(白/绿/蓝/紫/金/橙等)。

3. 加 Lua 过滤器(可选,功能增强)

社区在 noraj/osert-community-filters 仓库维护了若干 Pandoc Lua 过滤器,常见用途:

pandoc src/OSCP-exam-report-template_whoisflynn_v3.2.md \
  --lua-filter /path/to/filter-1.lua \
  --lua-filter /path/to/filter-2.lua \
  ...  # 其余参数同上

不带 --lua-filter 时仓库不加载任何 Lua 过滤器,行为最稳定。

4. Docker 化(不想本地装 LaTeX 的备选)

社区提供了两个现成镜像:ret2src/OSCP-Exam-Report-Template-Markdown 与 Tripex48/OSCP-Exam-Report-Template-Markdown,直接挂载 src 目录就能跑 Pandoc+Eisvogel。具体 docker run 命令以镜像 README 为准(此处不展开,以官方为准)。

典型适用场景

  • 正在准备或已报名 OSCP/OSWE/OSEP 等 OffSec 考试的考生:考场上写 Markdown,考完一键出 PDF+7z+MD5。
  • 红队/渗透测试公司:统一内部报告模板,Markdown 源文件直接进 Git 做版本管理。
  • 写技术报告但不想碰 LaTeX 排版细节的研究人员/工程师:Eisvogel 模板本身就是一个相当体面的技术 PDF 模板。
  • 教学场景:Markdown 笔记 → 一键导出可打印讲义。

坑与注意

⚠️ TeX Live 一定要装够:texlive-latex-recommended 单独装常常因为缺某个字符或字体报错,建议至少加 texlive-latex-extra 和 texlive-fonts-extra。Arch 上 texlive-scheme-medium 是平衡点。

⚠️ Pandoc 版本:3.2+ 与 gitbook 模板互动偶有问题(bookdown 那边有同款 issue),这里 PDF 流程相对稳定,但若你同时跑 bookdown 共用 Pandoc 要注意。

⚠️ 官方模板无 LICENSE:README 明确写了"Official Offensive Security Template v1"等链接指向的官方文档是 UNLICENSED,可以个人考试用,但商用/再分发要谨慎;Eisvogel 模板本身是独立许可证。

⚠️ 提交归档命名:OSCP-OS-XXXXX-Exam-Report.7z 中的 XXXXX 是你的 OffSec 学生 ID,改错就被打回;osert.rb generate 帮你拼好,不要手改。

⚠️ 截图占体积:报告 PDF 经常 30-50 MB,放进 7z 后仍可能 20 MB+,注意 OffSec 提交体积上限。

⚠️ Lua 过滤器是可选增强:社区仓库 osert-community-filters 与本仓库解耦,引入前先看每个 filter 的 README,避免与 Eisvogel 默认样式冲突。

与同类对比

方案 输入 输出 学习曲线 OffSec 兼容
本仓库 (Markdown + Pandoc + Eisvogel) Markdown PDF + 7z + MD5(脚本自动) 低 高
whoisflynn/OSCP-Exam-Report-Template 原版 Markdown PDF(无脚本) 低 高
官方 Word 模板 Word docx 中 高(但易格式脏)
手写 LaTeX .tex PDF 高 高(灵活但耗时间)
Pandoc 默认 LaTeX 模板 Markdown PDF 低 中(无封面/水印)

相较 whoisflynn 原版,本仓库多一层 osert.rb 脚本 + Eisvogel 模板 + 11 门考试覆盖 + 8 套配色 + Docker 镜像,是"省时间"导向的整合包。

一句话推荐结论

考 OffSec 任何一门报告型考试、想把"写报告"压到最短路径的人,这套仓库就是默认答案——pacman -S osert 或 apt 装齐,osert.rb init 起手,半小时内出一份能提交的 PDF+7z+MD5。

原始 commit/PR/issue 链接:https://github.com/noraj/OSCP-Exam-Report-Template-Markdown (main 分支,README commit 历史可查)。仓库本身无正式 release tag,版本演进通过 README 的"Examples"段持续更新,最近一次显著改动见 osert.rb 脚本与 Eisvogel 模板集成(具体 commit SHA 以 GitHub 页面为准)。