Skip to content

Latest commit

 

History

History
953 lines (684 loc) · 22.7 KB

manual.md

File metadata and controls

953 lines (684 loc) · 22.7 KB

KSL 详细使用手册

本文档说明 Linux Kernel Security Lab(KSL)1.0.0 的完整使用方法。KSL 用于管理 Linux 内核源码、可复现配置、编译产物、QEMU 实验环境和研究记录,适合内核调试、 CTF 题目分析、补丁验证和授权的安全研究。

1.0.0 是首个稳定版本,已经完成并验证 x86_64 Kernel CTF Lab 的核心工作流。 workspace profile 属于每台机器的本地配置,首次使用仍需按本文档创建。

1. 基本原则

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"

1.1 在任意目录使用 lab

执行上述命令时,$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。

2. 目录布局

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。

3. 环境检查与依赖安装

检查版本:

lab version

检查工具链:

lab doctor

doctor 检查 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)"

4. Workspace 管理

一个 workspace profile 对应一个内核 checkout。未显式传入 --workspace 时, 命令使用当前活动 workspace。

4.1 创建 profile

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。

4.2 查询和切换

lab workspace list
lab workspace current
lab workspace status
lab workspace status linux-6.6
lab workspace use linux-6.6

workspace list 中 * 表示活动项。status 同时报告路径、remote、ref、架构、 fragment、输出目录以及 Git checkout 是否存在。

仅创建 profile 指定的目录,不执行 Git clone:

lab workspace init linux-6.6

4.3 修改配置 fragment

查看当前 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

5. 内核源码管理

正式命令是 lab source;lab repo 是兼容别名。

5.1 Clone

先看计划:

lab source clone --workspace linux-6.6 --depth 1

确认 URL、ref 和目标路径后执行:

lab source clone --workspace linux-6.6 --depth 1 --apply

--depth 必须是正整数。需要查看更早历史、切换旧 commit 或进行复杂 patch 分析时, 不要使用浅克隆,或在源码目录中按需补全历史。

5.2 状态与更新

lab source status --workspace linux-6.6
lab source update --workspace linux-6.6
lab source update --workspace linux-6.6 --apply

update --apply 依次执行:

git fetch --progress origin --tags --prune
git checkout <profile-ref>

它不会自动 merge、rebase 或清理工作树。切换前应先检查未提交修改。

5.3 研究分支

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 格式检查。

5.4 Patch 导出

导出最近一个提交:

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。

5.5 Patch 导入

只检查 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。

6. 内核配置

配置生成和编译是两个独立阶段。编译命令不会隐式执行 defconfig、 olddefconfig 或修改 .config。

6.1 Fragment 格式

支持标准 .config 行:

CONFIG_KASAN=y
CONFIG_KCOV=y
CONFIG_CMDLINE="console=ttyS0"
# CONFIG_RANDOMIZE_BASE is not set

空行、普通注释以及以 ## 开头的说明会被忽略。同一 symbol 重复出现时,最后一次 定义生效。

6.2 可复现配置流水线

查看计划:

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 \
  --apply

6.3 传统 Kbuild 配置操作

lab 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 --apply

olddefconfig 和 menuconfig 要求输出目录中已有 .config。menuconfig 是交互式 命令;完成后应保存配置差异或更新 fragment,以维持可复现性。

7. 编译内核

查看编译计划:

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 \
  --apply

x86_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。

8. 构建最小 rootfs

使用静态 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。

启动流程会:

  1. 挂载 proc、sysfs 和 devtmpfs;
  2. 尝试将 QEMU 9p 标签 hostshare 挂载到 /mnt/host;
  3. 输出内核版本;
  4. 带 ksl.smoke=1 时输出 KSL_BOOT_OK 并关机;
  5. 否则进入 BusyBox shell。

initramfs 位于内存,关机后 guest 内部修改不会持久保存。需要持久保存的文件应写入 专用共享目录或由宿主收集。

9. QEMU 启动

9.1 使用 workspace 启动

先查看完整 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 -f

9.2 手工指定内核和 rootfs

lab 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。

9.3 参数参考

参数 作用
--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。

9.4 网络与端口转发

研究未知输入时推荐:

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。

9.5 9p 共享目录

宿主准备专用目录:

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/host

guest 写入 /mnt/host 会直接影响宿主目录。只共享专门的实验目录,不要共享仓库 根目录、HOME、SSH 配置、凭据目录或其他敏感路径。

9.6 启动冒烟测试

./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。

9.7 运行日志和元数据

每次 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 版本、完整命令、网络、共享 目录及退出码。

10. GDB 内核调试

启动暂停的虚拟机:

lab emulate \
  --workspace linux-6.6 \
  --no-network \
  --gdb \
  --apply

--gdb 等价于 QEMU -S -gdb tcp::1234:CPU 在第一条指令前暂停。

另一个终端:

gdb /data/kernel/out/linux-6.6/vmlinux

GDB 中:

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 能简化地址对应。

11. Research case 管理

列出案例:

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、配置哈希、启动命令、触发 条件、崩溃摘要、根因、调试断点、实验结果和后续问题。

12. 面向 CTF 的推荐工作流

本节只描述实验组织方式;题目附件和测试操作应来自合法、授权的 CTF 环境。

12.1 建档与校验附件

lab research create ctf-example \
  --workspace linux-6.6 \
  --title "CTF example"

sha256sum /path/to/challenge/* \
  > research/ctf-example/artifacts-sha256.txt

12.2 准备隔离环境

mkdir -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。

12.3 保存实验记录

每次运行后保存:

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,而不是只依赖临时终端历史。

12.4 对照实验

为题目基线、调试修改和修复版本使用不同 Git 分支,保持同一编译器、配置、rootfs 和 QEMU 参数。每次对照记录 commit 和 hashes,避免把环境差异误判为漏洞行为变化。

13. 全局配置与解析优先级

默认全局配置文件是 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

14. 日志位置

操作 路径
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/。

15. 常见故障

no active workspace

lab workspace list
lab workspace use <name>

若没有 profile,先运行 lab workspace add。

kernel source is not ready

检查源码路径和 Makefile:

lab workspace status
lab source clone
lab source clone --apply

kernel configuration is not ready

lab build config --workspace <name> --apply

然后人工检查输出目录的 .config,再编译。

fragment requested/actual 不一致

通常是 Kconfig 依赖未满足。查看错误列出的 symbol,在 menuconfig 或 Kconfig 源码 中检查依赖;不要直接忽略审计失败。

rootfs not found

./scripts/build-rootfs.sh
lab workspace status

确认 profile 的 ROOTFS_IMAGE 指向生成文件。

9p 挂载失败

确认启动计划含 -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/host

QEMU 冒烟测试超时

KASAN + TCG 可能需要一分钟以上:

KSL_SMOKE_TIMEOUT=240 ./scripts/smoke-test.sh <workspace>

若宿主支持并允许 KVM,可在交互启动时使用 --kvm;先确认 /dev/kvm 权限。

GDB 地址或符号不匹配

确认 vmlinux 与 bzImage 来自同次构建,检查 CONFIG_DEBUG_INFO,并使用 nokaslr。不要混用其他 workspace 的符号文件。

QEMU 启动失败但终端信息不足

查询:

lab emulate status --workspace <name>
tail -n 100 output/emulate/<name>/*-emulate.log

失败运行同样会写入 JSON,并记录非零退出码。

16. 安全检查清单

运行未知或不完全可信的 CTF 附件前:

  • 使用 --no-network;
  • 只共享一个新建的专用目录;
  • 不共享 HOME、仓库根目录、SSH 或云凭据;
  • 不使用包含真实数据的磁盘镜像;
  • 先审阅 plan 模式输出的完整 QEMU 命令;
  • 不随意添加 --extra,尤其是宿主设备直通参数;
  • 仅在需要且确认隔离边界后启用 KVM;
  • 保存附件、内核、配置和 rootfs 哈希;
  • 实验结束后检查共享目录中新增或修改的文件。

17. 完整示例

# 构建 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