本文档说明 Linux Kernel Security Lab(KSL)1.0.0 的完整使用方法。KSL 用于管理 Linux 内核源码、可复现配置、编译产物、QEMU 实验环境和研究记录,适合内核调试、 CTF 题目分析、补丁验证和授权的安全研究。
1.0.0 是首个稳定版本,已经完成并验证 x86_64 Kernel CTF Lab 的核心工作流。 workspace profile 属于每台机器的本地配置,首次使用仍需按本文档创建。
KSL 将实验内容分为四类:
- workspace profile:本机源码、架构、配置和输出路径的描述;
- kernel checkout:独立于 KSL 仓库的 Linux Git 源码;
- generated artifacts:内核、rootfs、日志和运行元数据,可重新生成且默认忽略;
- research case:需要长期保存的分析过程、复现说明和补丁验证记录。
可能安装软件、访问网络、修改 Git、编译内核或启动虚拟机的命令默认是 plan
模式。只有加入 --apply 才会执行。建议始终先查看计划,再执行同一命令的
--apply 版本。
以下示例假设当前目录是 KSL 仓库根目录:
cd /path/to/kernel-security-lab
./scripts/build-go.sh生成的命令为 ./bin/lab。也可以临时加入 PATH:
export PATH="$PWD/bin:$PATH"执行上述命令时,$PWD 会立即展开为当前仓库的绝对路径,因此之后切换目录,Shell
仍然能够找到 lab。但是 PATH 只解决“在哪里找到可执行文件”;KSL 默认仍会从当前
目录向上查找包含 VERSION 的项目根目录。在仓库以外执行时,还应设置 KSL_ROOT:
export KSL_ROOT=/home/patzilla9527/kernel-security-lab
export PATH="$KSL_ROOT/bin:$PATH"之后可在任意目录调用:
cd /tmp
lab version
lab workspace list
lab build status --workspace linux-6.6
lab emulate --workspace linux-6.6 --no-network验证当前配置:
command -v lab
printf '%s\n' "$KSL_ROOT"
lab workspace current如需长期生效,可将以下内容加入 ~/.bashrc,再执行 source ~/.bashrc:
export KSL_ROOT=/home/patzilla9527/kernel-security-lab
export PATH="$KSL_ROOT/bin:$PATH"workspace 的源码、输出目录和 rootfs 通常在 profile 中保存为绝对路径,因此不受当前
目录影响。命令行中的 $PWD 则始终表示执行命令时所在的目录。例如在 /tmp 中使用
--share "$PWD/poc-share" 会共享 /tmp/poc-share,不是 KSL 项目中的目录。跨目录
使用时建议明确引用:
lab emulate \
--workspace linux-6.6 \
--share "$KSL_ROOT/poc-share" \
--no-network \
--apply辅助脚本没有单独安装到 PATH。在仓库外应使用完整路径:
"$KSL_ROOT/scripts/build-rootfs.sh"
"$KSL_ROOT/scripts/smoke-test.sh" linux-6.6如果以后移动或重命名 KSL 仓库,需要同步修改 KSL_ROOT。如果 workspace profile
中记录的源码、输出或 rootfs 也被移动,则应更新对应的
config/workspaces/<name>.conf 或重新创建 profile。
kernel-security-lab/
├── bin/lab # 编译生成的 CLI,Git 忽略
├── config/
│ ├── kernel/ # 可提交的 Kconfig fragments
│ ├── lab.conf.example # 全局配置示例
│ └── workspaces/ # 本机 profiles,Git 忽略
├── docs/ # 文档
├── images/ # initramfs/磁盘镜像,Git 忽略
├── output/ # build/source/QEMU 日志和元数据,Git 忽略
├── poc-share/ # 推荐的 guest 共享目录,Git 忽略
├── research/ # 研究案例
└── scripts/ # 构建和冒烟测试脚本
不要把大型内核产物、rootfs、CTF 附件、运行日志或敏感数据提交到 Git。
检查版本:
lab version检查工具链:
lab doctordoctor 检查 Git、Make、GCC、GDB、x86_64 QEMU、cpio、BusyBox,以及 OpenSSL
和 libelf 开发头文件。全部显示 [ OK ] 才表示基础环境就绪。
查看依赖安装计划:
lab bootstrap
# 或
lab bootstrap plan在 Debian/Ubuntu 上执行安装:
lab bootstrap --apply该命令使用 sudo apt-get install -y。其他发行版应使用系统包管理器手工安装等价
工具。生成最小 rootfs 的 BusyBox 必须是静态链接版本,可用以下命令确认:
file "$(command -v busybox)"
ldd "$(command -v busybox)"一个 workspace profile 对应一个内核 checkout。未显式传入 --workspace 时,
命令使用当前活动 workspace。
lab workspace add linux-6.6 \
--path /data/kernel/linux-6.6 \
--url https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git \
--ref v6.6.45 \
--arch x86_64 \
--defconfig defconfig \
--config config/kernel/security-research.config \
--out /data/kernel/out/linux-6.6 \
--rootfs "$PWD/images/rootfs.cpio.gz"参数说明:
| 参数 | 含义 |
|---|---|
--path |
内核源码的绝对路径,必填 |
--url |
Git remote;省略时使用 Linus 主线仓库 |
--ref |
clone/update 使用的 branch、tag 或 ref;默认 master |
--arch |
x86_64 或 arm64;默认 x86_64 |
--defconfig |
初始 Kbuild 配置目标;默认 defconfig |
--config |
Kconfig fragment,可使用项目相对路径 |
--cross-compile |
交叉编译器前缀,例如 aarch64-linux-gnu- |
--out |
Kbuild 的独立 O= 输出目录 |
--rootfs |
QEMU 默认 initramfs 或 raw 磁盘镜像 |
第一个 profile 会自动成为活动 workspace。profile 保存在
config/workspaces/<name>.conf,活动名称保存在 .local/active-workspace。
lab workspace list
lab workspace current
lab workspace status
lab workspace status linux-6.6
lab workspace use linux-6.6workspace list 中 * 表示活动项。status 同时报告路径、remote、ref、架构、
fragment、输出目录以及 Git checkout 是否存在。
仅创建 profile 指定的目录,不执行 Git clone:
lab workspace init linux-6.6查看当前 fragment:
lab workspace config linux-6.6绑定或更换:
lab workspace config linux-6.6 --set config/kernel/security-research.config清除:
lab workspace config linux-6.6 --clear正式命令是 lab source;lab repo 是兼容别名。
先看计划:
lab source clone --workspace linux-6.6 --depth 1确认 URL、ref 和目标路径后执行:
lab source clone --workspace linux-6.6 --depth 1 --apply--depth 必须是正整数。需要查看更早历史、切换旧 commit 或进行复杂 patch 分析时,
不要使用浅克隆,或在源码目录中按需补全历史。
lab source status --workspace linux-6.6
lab source update --workspace linux-6.6
lab source update --workspace linux-6.6 --applyupdate --apply 依次执行:
git fetch --progress origin --tags --prune
git checkout <profile-ref>
它不会自动 merge、rebase 或清理工作树。切换前应先检查未提交修改。
lab source branch list --workspace linux-6.6
lab source branch create ctf-analysis --workspace linux-6.6
lab source branch create ctf-analysis --workspace linux-6.6 --apply创建操作使用 git switch -c,且分支名称会先通过 Git 格式检查。
导出最近一个提交:
lab source patch export --workspace linux-6.6导出最近三个提交:
lab source patch export --workspace linux-6.6 --commits 3输出位于:
output/repo/<workspace>/patches/<timestamp>/
命令使用 git format-patch,并在工作树存在未提交差异时额外保存
working-tree.diff。
只检查 patch 能否应用:
lab source patch import \
--workspace linux-6.6 \
--file /path/to/fix.patch检查通过后实际应用:
lab source patch import \
--workspace linux-6.6 \
--file /path/to/fix.patch \
--apply该命令使用 git apply,不会自动创建 commit。
配置生成和编译是两个独立阶段。编译命令不会隐式执行 defconfig、
olddefconfig 或修改 .config。
支持标准 .config 行:
CONFIG_KASAN=y
CONFIG_KCOV=y
CONFIG_CMDLINE="console=ttyS0"
# CONFIG_RANDOMIZE_BASE is not set
空行、普通注释以及以 ## 开头的说明会被忽略。同一 symbol 重复出现时,最后一次
定义生效。
查看计划:
lab build config --workspace linux-6.6执行:
lab build config --workspace linux-6.6 --apply实际顺序为:
profile defconfig
→ scripts/config 应用 fragment
→ olddefconfig 解析依赖
→ 逐项审计最终 .config
如果某个选项因依赖关系未生效,命令会列出 requested/actual 差异并返回失败;生成的
.config 会保留,便于检查。
临时覆盖 profile fragment:
lab build config generate \
--workspace linux-6.6 \
--fragment /path/to/challenge.config \
--applylab build config defconfig --workspace linux-6.6 --apply
lab build config olddefconfig --workspace linux-6.6 --apply
lab build config menuconfig --workspace linux-6.6 --applyolddefconfig 和 menuconfig 要求输出目录中已有 .config。menuconfig 是交互式
命令;完成后应保存配置差异或更新 fragment,以维持可复现性。
查看编译计划:
lab build --workspace linux-6.6 --jobs 16执行默认目标 all modules:
lab build --workspace linux-6.6 --jobs 16 --apply指定一个或多个目标:
lab build --workspace linux-6.6 \
--jobs 16 \
--target bzImage \
--target modules \
--applyx86_64 使用 ARCH=x86;arm64 使用 ARCH=arm64。若 profile 定义了
CROSS_COMPILE,构建时会传给 Kbuild。
查询最近一次构建元数据:
lab build status --workspace linux-6.6日志与 JSON 位于:
output/build/<workspace>/
├── <timestamp>-build.log
├── <timestamp>-build.json
└── latest.json
x86_64 默认内核路径是 <out>/arch/x86/boot/bzImage,arm64 是
<out>/arch/arm64/boot/Image;带符号调试使用 <out>/vmlinux。
使用静态 BusyBox 生成 initramfs:
./scripts/build-rootfs.sh默认输出:
images/rootfs.cpio.gz
指定其他输出或 BusyBox:
BUSYBOX=/path/to/static/busybox \
./scripts/build-rootfs.sh /path/to/rootfs.cpio.gz脚本使用可复现的 cpio/gzip 参数;相同输入应产生相同 SHA-256。生成内容包括
/init、静态 BusyBox、常用 applet、/dev/console、/dev/null 和 /mnt/host。
启动流程会:
- 挂载 proc、sysfs 和 devtmpfs;
- 尝试将 QEMU 9p 标签
hostshare挂载到/mnt/host; - 输出内核版本;
- 带
ksl.smoke=1时输出KSL_BOOT_OK并关机; - 否则进入 BusyBox shell。
initramfs 位于内存,关机后 guest 内部修改不会持久保存。需要持久保存的文件应写入 专用共享目录或由宿主收集。
先查看完整 QEMU 命令:
lab emulate --workspace linux-6.6 --no-network实际启动:
lab emulate --workspace linux-6.6 --no-network --apply不传 --append 时默认内核参数是:
console=ttyS0 nokaslr panic=-1 oops=panic
退出 guest:
poweroff -flab emulate \
--kernel /path/to/bzImage \
--rootfs /path/to/rootfs.cpio.gz \
--arch x86_64 \
--memory 2G \
--smp 2 \
--no-network \
--apply.cpio 或文件名包含 .cpio. 的 rootfs 使用 QEMU -initrd;其他文件作为 raw
virtio 磁盘传给 -drive。
| 参数 | 作用 |
|---|---|
--workspace |
从 profile 推导架构、内核和 rootfs |
--kernel |
覆盖内核镜像 |
--rootfs |
覆盖 initramfs/raw 磁盘 |
--arch |
x86_64 或 arm64 |
--memory |
guest 内存,默认 2G |
--smp |
vCPU 数,默认 2 |
--cpu |
QEMU CPU model,默认 max |
--append |
完整替换默认内核命令行 |
--kvm |
加入 -enable-kvm |
--gdb |
启动暂停并监听 GDB tcp::1234 |
--no-network |
使用 -nic none,完全不创建网卡 |
--forward H:G |
host TCP 端口转发到 guest,可重复 |
--share |
通过 9p 暴露一个宿主目录 |
--qemu |
覆盖 QEMU binary |
--extra |
追加一个原始 QEMU 参数,可重复 |
--config |
指定其他 lab.conf |
--apply |
实际启动;省略时只显示计划 |
arm64 会自动使用 qemu-system-aarch64 -machine virt;默认 x86_64 binary 是
qemu-system-x86_64。
研究未知输入时推荐:
lab emulate --workspace linux-6.6 --no-network --apply--no-network 使用 QEMU -nic none。它不影响 9p 共享。
未指定 --no-network 时使用 QEMU user-mode 网络和 e1000(arm64 使用
virtio-net-device)。默认已有 10022:22 转发。额外转发可重复指定:
lab emulate --workspace linux-6.6 \
--forward 18080:8080 \
--apply最小 rootfs 没有 DHCP 配置、sshd 或登录账户,因此仅开启网络并不代表可以 SSH。
宿主准备专用目录:
mkdir -p poc-share
cp /path/to/authorized-challenge-files poc-share/启动:
lab emulate \
--workspace linux-6.6 \
--share "$PWD/poc-share" \
--no-network \
--apply项目生成的 rootfs 会自动挂载到 guest /mnt/host:
ls -la /mnt/host其他 rootfs 可手工挂载:
mkdir -p /mnt/host
mount -t 9p -o trans=virtio,version=9p2000.L hostshare /mnt/hostguest 写入 /mnt/host 会直接影响宿主目录。只共享专门的实验目录,不要共享仓库
根目录、HOME、SSH 配置、凭据目录或其他敏感路径。
./scripts/smoke-test.sh linux-6.6同时验证 9p:
mkdir -p poc-share
./scripts/smoke-test.sh linux-6.6 "$PWD/poc-share"默认超时 120 秒。KASAN 内核在无 KVM 的 TCG 环境可能启动较慢:
KSL_SMOKE_TIMEOUT=180 ./scripts/smoke-test.sh linux-6.6成功条件是日志出现 KSL_BOOT_OK;提供共享目录时还必须出现 KSL_SHARE_OK。
每次 emulate --apply 自动生成:
output/emulate/<workspace>/
├── <timestamp>-emulate.log
├── <timestamp>-emulate.json
└── latest.json
查询最近一次运行:
lab emulate status --workspace linux-6.6元数据包括 workspace、状态、时间、日志、内核 commit、内核和 .config SHA-256、
编译器版本、rootfs SHA-256、架构、内核命令行、QEMU 版本、完整命令、网络、共享
目录及退出码。
启动暂停的虚拟机:
lab emulate \
--workspace linux-6.6 \
--no-network \
--gdb \
--apply--gdb 等价于 QEMU -S -gdb tcp::1234:CPU 在第一条指令前暂停。
另一个终端:
gdb /data/kernel/out/linux-6.6/vmlinuxGDB 中:
set pagination off
target remote :1234
break start_kernel
continue若内核启用了 CONFIG_GDB_SCRIPTS,可加载源码树提供的脚本。必要时在 GDB 中设置:
add-auto-load-safe-path /data/kernel/linux-6.6/scripts/gdb/vmlinux-gdb.py符号与运行镜像必须来自同一次构建。关闭 KASLR 或加入 nokaslr 能简化地址对应。
列出案例:
lab research list创建 CTF 研究案例:
lab research create ctf-challenge-name \
--workspace linux-6.6 \
--title "CTF kernel challenge"实际创建:
research/ctf-challenge-name/
├── README.md
├── metadata.json
└── artifacts/
README.md 包含 Reproduction、Crash、Root cause 和 Patch verification 基础章节;
metadata.json 记录名称、workspace、标题和创建时间;artifacts/ 默认被 Git 忽略。
查询元数据:
lab research status ctf-challenge-name建议人工扩展目录:
research/ctf-challenge-name/
├── README.md
├── metadata.json
├── notes/ # 分析笔记
├── poc/ # 经授权的题目脚本或测试程序
├── patches/ # 修复或实验 patch
├── configs/ # 题目/实验配置
└── artifacts/ # 镜像、core、完整日志等大文件
推荐在 README 中记录:题目来源、附件哈希、内核 commit、配置哈希、启动命令、触发 条件、崩溃摘要、根因、调试断点、实验结果和后续问题。
本节只描述实验组织方式;题目附件和测试操作应来自合法、授权的 CTF 环境。
lab research create ctf-example \
--workspace linux-6.6 \
--title "CTF example"
sha256sum /path/to/challenge/* \
> research/ctf-example/artifacts-sha256.txtmkdir -p poc-share
cp /path/to/challenge/authorized-files poc-share/
lab emulate \
--workspace linux-6.6 \
--share "$PWD/poc-share" \
--no-network先审阅计划,确认只共享 poc-share,再加 --apply。
每次运行后保存:
lab emulate status --workspace linux-6.6 \
> research/ctf-example/last-emulation.json
lab build status --workspace linux-6.6 \
> research/ctf-example/last-build.json将关键结论写入案例 README,而不是只依赖临时终端历史。
为题目基线、调试修改和修复版本使用不同 Git 分支,保持同一编译器、配置、rootfs 和 QEMU 参数。每次对照记录 commit 和 hashes,避免把环境差异误判为漏洞行为变化。
默认全局配置文件是 config/lab.conf,示例见 config/lab.conf.example。可以通过:
lab emulate --config /path/to/lab.conf支持的 QEMU 相关变量包括:
KERNEL_IMAGE
ROOTFS_IMAGE
SHARE_DIR
QEMU_BINARY
常见解析顺序是:命令行显式值优先;其后使用 workspace 中的内核、rootfs 和架构;
仍为空时再使用全局配置。KSL_ROOT 可覆盖 CLI 查找的项目根目录,通常只用于测试
或从特殊位置调用:
KSL_ROOT=/path/to/kernel-security-lab /path/to/bin/lab version| 操作 | 路径 |
|---|---|
| source clone/fetch/checkout/patch | output/source/<workspace>/ |
| patch export | output/repo/<workspace>/patches/ |
| kernel build | output/build/<workspace>/ |
| QEMU emulate | output/emulate/<workspace>/ |
这些目录默认不提交。需要长期保留的摘要应复制或引用到相应 research case;大文件
放入 case 的 artifacts/。
lab workspace list
lab workspace use <name>若没有 profile,先运行 lab workspace add。
检查源码路径和 Makefile:
lab workspace status
lab source clone
lab source clone --applylab build config --workspace <name> --apply然后人工检查输出目录的 .config,再编译。
通常是 Kconfig 依赖未满足。查看错误列出的 symbol,在 menuconfig 或 Kconfig 源码
中检查依赖;不要直接忽略审计失败。
./scripts/build-rootfs.sh
lab workspace status确认 profile 的 ROOTFS_IMAGE 指向生成文件。
确认启动计划含 -virtfs,内核配置含:
CONFIG_NET_9P
CONFIG_NET_9P_VIRTIO
CONFIG_9P_FS
再检查 guest:
dmesg | grep -i 9p
mount -t 9p -o trans=virtio,version=9p2000.L hostshare /mnt/hostKASAN + TCG 可能需要一分钟以上:
KSL_SMOKE_TIMEOUT=240 ./scripts/smoke-test.sh <workspace>若宿主支持并允许 KVM,可在交互启动时使用 --kvm;先确认 /dev/kvm 权限。
确认 vmlinux 与 bzImage 来自同次构建,检查 CONFIG_DEBUG_INFO,并使用
nokaslr。不要混用其他 workspace 的符号文件。
查询:
lab emulate status --workspace <name>
tail -n 100 output/emulate/<name>/*-emulate.log失败运行同样会写入 JSON,并记录非零退出码。
运行未知或不完全可信的 CTF 附件前:
- 使用
--no-network; - 只共享一个新建的专用目录;
- 不共享 HOME、仓库根目录、SSH 或云凭据;
- 不使用包含真实数据的磁盘镜像;
- 先审阅 plan 模式输出的完整 QEMU 命令;
- 不随意添加
--extra,尤其是宿主设备直通参数; - 仅在需要且确认隔离边界后启用 KVM;
- 保存附件、内核、配置和 rootfs 哈希;
- 实验结束后检查共享目录中新增或修改的文件。
# 构建 CLI 并检查环境
./scripts/build-go.sh
./bin/lab doctor
# 创建 workspace
./bin/lab workspace add linux-6.6 \
--path /data/kernel/linux-6.6 \
--url https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git \
--ref v6.6.45 \
--arch x86_64 \
--defconfig defconfig \
--config config/kernel/security-research.config \
--rootfs "$PWD/images/rootfs.cpio.gz"
# 获取源码
./bin/lab source clone --workspace linux-6.6 --depth 1
./bin/lab source clone --workspace linux-6.6 --depth 1 --apply
# 配置和编译
./bin/lab build config --workspace linux-6.6
./bin/lab build config --workspace linux-6.6 --apply
./bin/lab build --workspace linux-6.6 --jobs "$(nproc)"
./bin/lab build --workspace linux-6.6 --jobs "$(nproc)" --apply
# 构建 rootfs 并验证启动
./scripts/build-rootfs.sh
./scripts/smoke-test.sh linux-6.6
# 准备隔离共享目录
mkdir -p poc-share
# 审阅并启动交互 VM
./bin/lab emulate \
--workspace linux-6.6 \
--share "$PWD/poc-share" \
--no-network
./bin/lab emulate \
--workspace linux-6.6 \
--share "$PWD/poc-share" \
--no-network \
--apply
# 查询可复现信息
./bin/lab build status --workspace linux-6.6
./bin/lab emulate status --workspace linux-6.6