OSS Scanner 是 Anthropic 推出的开源项目安全扫描服务，它能在隔离虚拟机中构建你的项目并自动挖掘安全漏洞。本文带你看懂它的"扫描层"秘密：扫描器是如何在你构建的镜像之上，自动注入 Claude Code、gdb、Valgrind 等一整套分析工具链的——以及你该如何提前准备好 Dockerfile，让这套工具顺利落地。

一、先搞懂：扫描分三步，镜像分三阶段

扫描器拿到你的项目后，做的事情可以概括为一句话：先联网构建，再断网扫描。

1. 导入与构建：在隔离 VM 中克隆你的仓库，运行你的 Dockerfile（此阶段有网络访问）；
2. 叠加扫描层：在你的产物镜像之上，追加一层分析工具（下文详解）；
3. 断网扫描：把 VM 移到一个没有互联网的网络里，AI 分析员开始工作，结果连同复现步骤和补丁建议邮件发给primary_contact。

对应地，镜像会经历三个阶段，阶段名就写死在构建脚本里：

target -> tools -> built 你的产物 +扫描层 最终镜像

• target：你的 Dockerfile 构建出的原始镜像；
• tools：叠加了 Claude Code 和调试工具链的镜像；
• built：补上.git历史、设置好工作目录/src，并验证"断网也能启动"的最终镜像。

这个三阶段函数见 tools/check_build.py。

二、工具层解剖：到底往你的镜像里装了什么？

答案就在 tools/check_build.py 的TOOLS_LAYER变量里——它本质上是一个动态生成的 Dockerfile，核心逻辑是：

注意它是个"多发行版适配"的循环：依次探测apt-get→dnf→yum→apk→zypper→pacman，谁的包管理器存在就用谁（见 tools/check_build.py）。这意味着无论是 Debian、Ubuntu、Fedora、Alpine 还是 Arch 系的镜像，工具层都能落下去。

为什么要带 gdb 和 Valgrind？

因为断网阶段干活的是一位AI 分析员，它和你请来的安全审计员行为一致：跑测试、启动程序、打开调试器、追内存错误。构建脚本的横幅里甚至直接提示了你：

"Try what somebody studying your project would need: run the tests, start the program,use gdb."

（见 tools/check_build.py）

而为了让 gdb、LeakSanitizer 这类工具真正能工作，扫描器的容器是特权模式运行的——这一点在本地体验工具 tools/check 的注释里写得很清楚：

"The scanner's container is privileged, so debuggers and LeakSanitizer work there."

所以valgrind查内存、gdb抓堆栈、strace/ltrace跟系统调用和库调用、lsof看句柄、xxd/file看二进制……整个动态分析工具箱都是标配。

三、Claude Code 是怎么进镜像的？

装完系统包之后，工具层只做三件事：

1. 执行官方安装脚本，把 Claude Code 装进/root/.local/bin/；
2. 建一个软链接/usr/local/bin/claude，让任何用户都能直接调用；
3. 立即跑一次claude --version自检——这一步不通，整个构建就判定失败（见 tools/check_build.py）。

紧接着，脚本还设置了一组环境变量，给 AI 分析员套上"静音沙箱"：

ENV IS_SANDBOX=1 \ DISABLE_AUTOUPDATER=1 \ CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 \ DISABLE_TELEMETRY=1 \ DISABLE_ERROR_REPORTING=1 \ CLAUDE_CODE_IDE_SKIP_AUTO_INSTALL=1

翻译成大白话：禁止自动更新、禁止非必要流量、关闭遥测和错误上报。扫描在断网环境进行，Claude Code 只处理本地工作，不会"偷偷打电话回家"。

四、动手体验：一条命令复现完整扫描环境

不用等 PR 合并，你本机就能跑一遍和扫描器完全一致的构建流程。tools/check 会依次执行五个操作：

1. 按 tools/validate.py 的规则校验你的projects/<name>/配置；
2. 匿名克隆你配置的仓库；
3. 联网构建你的 Dockerfile（target镜像）；
4. 叠加扫描层（Claude Code + 编译器 + 调试器，即tools镜像）；
5. 断网启动最终镜像，给你一个 root bash shell 在/src里亲自试试。

# 前提：主机装有 git、Docker 和 Python 3 + PyYAML tools/check <项目名> # 想更接近真实扫描环境？用 QEMU 虚拟机版（需 Linux x86-64 + QEMU） tools/check --qemu <项目名>

--qemu模式会起三台虚拟机（基础机、构建机、离线 shell 机），shell 机启动前还会先验证自己真的断网（DNS 不通、外连不通才放行），实现在 tools/check_qemu.py。

五、避坑清单：让你的 Dockerfile 顺利接住工具链

工具层安装失败的报错信息很直白：

你的 Dockerfile 最终阶段需要有一个包管理器（apt/dnf/yum/apk/zypper/pacman），或至少已有curl、git、python3、bash——scratch 和 distroless 这类精简镜像不行。

（见 tools/check_build.py）

结合已报名项目（如 projects/openssl/Dockerfile、projects/nss/Dockerfile）的实践，给你 4 条实战建议：

• ✅保留包管理器：最终别把 base 层清成 distroless；
• ✅带调试符号构建：官方模板就推荐RelWithDebInfo加-g -fno-omit-frame-pointer，这样 gdb 和 Valgrind 打出来的堆栈才有可读性（参考 templates/Dockerfile）；
• ✅联网阶段把所有东西抓齐：断网后 AI 分析员需要的一切（测试语料、示例程序、依赖）都必须在你 Dockerfile 的网络窗口期下载好；
• ✅别用scratch/distroless作为最终阶段，否则工具层无处落脚。

另外提醒一下资源规格：扫描器给构建阶段45 分钟、16 核、64GB 内存，AI 分析员容器是2 核、8GB（见 tools/check_build.py）。如果你的构建挂起（测试等 socket、watch 模式、交互提示），会被判超时失败——把耗时步骤加timeout或干脆移出构建。

六、小结

理解了这一层机制，你就能预判扫描器"看到了什么、能做什么"，从而把 Dockerfile 写得对分析员更友好——漏洞挖掘的效率，某种程度上取决于你为它铺的路有多顺。🔍