jetm/shipcheck

# shipcheck 欧盟网络韧性法案（CRA）的嵌入式Linux合规审计器。 读取您的Yocto构建输出内容——SBOM、CVE扫描输出、签名工件、许可证清单——并报告镜像是否已准备好发货。 状态：预发布。v0.0.x是迭代流；v0.1是第一个可发布的版本，一旦试点0002 / 0003 / 0004（core-image-full-cmdline / sato / weston）落地。 ## 安装 ``` uv tool install shipcheck # or pipx install shipcheck ``` ## 快速入门 shipcheck审计的是**构建目录**，而不是层源。指向bitbake写入的目录（包含`tmp/deploy/`、`conf/local.conf`等）： ``` cd path/to/your/yocto/build shipcheck init # writes .shipcheck.yaml shipcheck check --build-dir . ``` 典型的CI调用： ``` shipcheck check \ --build-dir "${BUILDDIR}" \ --fail-on high \ --format json > shipcheck-report.json ``` 对于多文件CRA档案（证据报告、CVE报告、许可证审计、第七附表技术文档、符合性声明、原始扫描JSON）： ``` shipcheck check \ --build-dir "${BUILDDIR}" \ --format evidence \ --out shipcheck-dossier/ ``` ## 检查内容 | 检查ID | 检查内容 | | -------- | ---------------- | | `sbom-generation` | 对BSI TR-03183-2 v2.1.0的SPDX 2.x和3.0字段进行验证；检测CycloneDX | | `cve-tracking` | `cve-check`、`vex.bbclass`和`sbom-cve-check` JSON位于`tmp/deploy/images/`下 | | `code-integrity` | UEFI/sbsign签名类、FIT（U-Boot）签名、dm-verity镜像和IMA/EVM（配置+`ima-evm-utils`包存在） | | `image-features` | 不安全的`IMAGE_FEATURES`（例如`debug-tweaks`、`empty-root-password`、`allow-root-login`） | | `hardening-flags` | 全局构建配置范围内的编译时加固证据（`security_flags.inc`继承、`SECURITY_CFLAGS`、`SECURITY_LDFLAGS`、FORTIFY/堆栈保护/PIE标记） | | `license-audit` | `tmp/deploy/licenses//license.manifest`与允许/拒绝列表进行比对 | | `yocto-cve-check` | Yocto的`tmp/log/cve/cve-summary.json`（Kirkstone和Scarthgap模式） | | `vuln-reporting` | 来自`product.yaml`的第14条/附件I第二部分§4-8的文档义务 | CVE发现从`cve-tracking`和`yocto-cve-check`合并为一个单一发现，其`sources`列表包含标记它的每个扫描器。 ### 已知限制 试点0001（poky Scarthgap `core-image-minimal`）验证了v0.1检查集端到端对真实bitbake输出的验证。以下为记录的限制，而非缺陷： - **`vuln-reporting`需要`product.yaml`** - 如果`.shipcheck.yaml`中不存在`product_config_path`，则检查返回SKIP并显示“product_config_path未配置”；如果设置了路径但文件不存在，则返回ERROR并显示“product.yaml未找到”。通过`.shipcheck.yaml`中的`product_config_path`提供有效的`product.yaml`以执行检查。 - **`code-integrity`仅限于配置/文件级别** - 检测签名类继承（`uefi-sign`、`sbsign`、`image-uefi-sign`、`secureboot`）、FIT镜像签名（`UBOOT_SIGN_ENABLE`）、dm-verity（`DM_VERITY_IMAGE`）和IMA/EVM（配置标志加`ima-evm-utils`包存在），并标记已知的测试密钥。它不执行PE/COFF二进制签名验证、PKI链验证（PK/KEK/DB注册）、FIT或dm-verity工件的安全验证，或根文件系统上的IMA xattr验证。这些深度作为路线图后续跟进。 - **UEFI Secure Boot正路径检测需要供应商BSP** - shipcheck的`code-integrity` UEFI检测器依赖于`IMAGE_CLASSES`中的类名模式`uefi-sign`、`sbsign`、`image-uefi-sign`和`secureboot`。这些`.bbclass`文件在上游poky / meta-arm / meta-security / meta-secure-core中都没有发货；唯一的上游真实`secureboot.bbclass`在PHYTEC的供应商BSP（`meta-ampliphy`）中。试点0005在vanilla qemuarm64构建上确认了这一点。因此，真正的正路径UEFI测试需要供应商BSP之一提供这四个类，或者使用meta-arm的`qemuarm64-secureboot` MACHINE（它使用不同的签名路径）。 - **`hardening-flags`仅限于构建配置证据** - 读取全局构建配置以继承`security_flags.inc`（信号A）并解析`TUNE_CCARGS`/`SELECTED_OPTIMIZATION`以进行`-D_FORTIFY_SOURCE=2/3`、`-fstack-protector-strong`、`-fPIE`和`-Wl,-z,relro -Wl,-z,now`（信号B）。有意跳过按配方覆盖语法（`TUNE_CCARGS:append:pn-foo`）-仅限于全局范围。它不解析ELF二进制文件以确认每个二进制文件的加固，也不消耗`image-buildinfo.bbclass`输出；这两者都作为后续跟进。 - **`sbom-generation`验证SPDX 2.x和3.0** - poky Scarthgap的`create-spdx`类发出SPDX 2.2；shipcheck接受2.2和2.3，符合BSI TR-03183-2 v2.1.0字段要求。SPDX 3.0字段验证（v0.0.6+）将Yocto Scarthgap评分20/50：格式、CreationInfo和rootElement检查通过（20分），但每个包的供应商和校验和得分为零，因为`create-spdx-3.0`没有发出`hasSuppliedBy`关系或每个包的`verifiedUsing`。差距是Yocto输出限制，在`audits/0003-spdx3-mapping/upstream-poky-spdx3.md`中记录，并附有openembedded-core的上游补丁系列草稿。有关详细信息，请参阅[问题 #3](https://github.com/jetm/shipcheck/issues/3）。 - **`cve-tracking`寻找特定的Yocto输出位置** - 试点0001表明`cve-tracking`和`yocto-cve-check`使用不同的查找逻辑；现在这两个检查共享一个共同的CVE发现辅助工具并就证据存在达成一致。更可靠的路径是`yocto-cve-check`，它读取`tmp/log/cve/cve-summary.json`。 ## shipcheck不是什么 shipcheck组织了您的Yocto构建已发出的证据，并将其格式化为与CRA一致的档案。它不，也不能，证明合规性。具体来说： - **不是官方CRA合规工具**。在撰写本文时，尚不存在此类工具。该法规没有定义一个，并且CRA协调标准M/596的委员会命令仍在进行中。 - **不是通知机构或认证机构**。附件VII（对于关键产品）下的符合性评估是一个单独的、法律定义的过程。shipcheck在其中没有作用，也不颁发证书、印章或证明。 - **不是法律审查的替代品**。合规性确定是基于法规、产品背景和风险评估的法律判断。律师和合规官员做出这一决定；shipcheck提供输入。 - **不是协调标准测试的替代品**（一旦M/596发布）。当协调标准可用时，符合这些标准提供第27条下的合规性推定。shipcheck可以在它们存在时集成协调标准检查；它今天不这样做。 - **不是CRA义务的全面覆盖**。请参阅`audits/`目录以获取附件的覆盖结论。流程义务、用户文档义务以及几个软属性要求（附件I第一部分b、e、g、h、i、j、l、m）部分或全部超出范围。 官方CRA合规工具可能需要根据协调标准（ISO/IEC 17025或CRA特定）进行认证，对于关键产品需要通知机构隶属关系，并在标准发布后进行正式的协调标准符合性测试。shipcheck位于光谱的另一端——轻量级、Yocto原生、开源和面向开发者的。 ### 准备就绪不代表合规 `shipcheck check`报告一个准备就绪分数（0-250）。满分意味着在此构建上通过了每个注册的shipcheck检查。这并不意味着产品符合CRA。合规性是由制造商做出的法律判断，而不是工具判断。 准备就绪分数作为内部进度指标很有用。它与合规性立场相关，但不证明它。制造商在欧盟符合性声明上的签名是证明。 有关完整理由，请参阅[`audits/0001-cra-approach/REPORT.md`](audits/0001-cra-approach/REPORT.md）§6-7。 ## 子命令 | 命令 | 目的 | | ------- | ------- | | `shipcheck check` | 在构建目录上运行注册的检查 | | `shipcheck dossier` | 从本地历史存储生成多扫描趋势报告 | | `shipcheck docs` | 从历史记录和`product.yaml`生成第七附表技术文档草案 | | `shipcheck doc declaration` | 生成欧盟符合性声明（附件V全或附件VI简化版） | | `shipcheck init` | 编写`.shipcheck.yaml`脚手架 | | `shipcheck version` | 打印已安装的版本 | ## 路线图 shipcheck以功能阶段发货。每个阶段捆绑一组检查以及它们所需的报告和证据管道。 ### 已发货 #### v0.0.3（2026-04-21）- 第1阶段 + CRA证据层脚手架 #### v0.0.4（2026-04-24）- vuln-reporting占位符验证 - **第1阶段 — SBOM + CVE + 报告**。`sbom-generation`和`cve-tracking`检查；终端/Markdown/JSON/HTML报告；准备就绪分数和`--fail-on` CI门控；`.shipcheck.yaml`配置。 - **第2阶段 — 代码完整性、加固和CRA证据层**。`code-integrity`（UEFI/sbsign签名类检测、FIT签名、dm-verity、IMA/EVM配置+包存在）、`image-features`（不安全的`IMAGE_FEATURES`，如`debug-tweaks`、`allow-empty-password`等）和`hardening-flags`（全局构建配置范围内的编译时加固证据：`security_flags.inc`继承加`TUNE_CCARGS`/`SELECTED_OPTIMIZATION`解析，用于FORTIFY_SOURCE、堆栈保护、PIE和RELRO+now标志）检查。静态CRA要求目录，每个发现都有`cra_mapping`元数据，`--format evidence`渲染器，`--out DIR`多文件档案，`license-audit`和`yocto-cve-check`检查，跨扫描器的CVE发现协调，SQLite扫描历史记录在`.shipcheck/history.db`中，`dossier`、`docs`和`doc declaration`子命令，以及涵盖第14条/附件I第二部分§4-8文档义务的`vuln-reporting`检查。 试点：请参阅[`pilots/0001-poky-scarthgap-min/REPORT.md`](pilots/0001-poky-scarthgap-min/REPORT.md）。 #### v0.0.5（2026-04-29）- code-integrity合并 + image-features + hardening-flags - 将`secure-boot` + `image-signing`合并为单个`code-integrity`检查，涵盖UEFI Secure Boot、签名FIT、dm-verity和IMA/EVM。 - 添加了检测不安全的`IMAGE_FEATURES`条目的`image-features`检查（例如`debug-tweaks`、`allow-empty-password`等）。 - 添加了检测全局构建配置范围内的编译时加固证据的`hardening-flags`检查（`security_flags.inc`继承加`TUNE_CCARGS`/`SELECTED_OPTIMIZATION`解析）。 - 试点0005验证了这三个新检查对真实qemuarm64 / poky-scarthgap / core-image-minimal构建的验证。 试点（`secure-boot` + `image-signing`的`code-integrity`合并）：请参阅[`pilots/0005-code-integrity-and-hardening/REPORT.md`](pilots/0005-code-integrity-and-hardening/REPORT.md）。 试点（`image-features`检查）：请参阅[`pilots/0005-code-integrity-and-hardening/REPORT.md`](pilots/0005-code-integrity-and-hardening/REPORT.md）。 试点（`hardening-flags`检查）：请参阅[`pilots/0005-code-integrity-and-hardening/REPORT.md`](pilots/0005-code-integrity-and-hardening/REPORT.md）。 #### v0.0.6（2026-04-30）- SPDX 3.0字段验证 - 在`sbom-generation`中对BSI TR-03183-2 v2.1.0进行SPDX 3.0检测和字段验证。通过`CreationInfo.specVersion`检测；验证`Sbom` rootElement链、每个包所需字段（名称、版本、供应商、许可证、校验和）和关系遍历回退（`hasConcludedLicense`、hasSuppliedBy`、`hasOriginatedBy`、`hasDeclaredLicense`）。试点0006（Yocto Scarthgap `core-image-minimal`）得分为20/50；每个包的差距是Yocto输出限制，在`audits/0003-spdx3-mapping/upstream-poky-spdx3.md`中记录，并附有openembedded-core的上游补丁系列草稿。 试点：请参阅[`pilots/0006-poky-scarthgap-spdx3/REPORT.md`](pilots/0006-poky-scarthgap-spdx3/REPORT.md）。 ### 计划 - **第3阶段 — 更新机制 + OP-TEE**。检测胶囊更新 / swupdate / RAUC并验证签名更新；OP-TEE集成、测量启动、TPM。 - **第3.5阶段 — OCI证明 + 内核加固**。通过`image-oci`进行OCI容器SBOM证明；内核加固配置（FORTIFY_SOURCE、STACKPROTECTOR、KASLR）；`harvest.json`导出。 - **第4阶段 — CI集成**。GitLab CI和GitHub Actions模板、GitHub安全标签的SARIF输出、跨运行的共享历史记录聚合。 - **第5阶段 — Web仪表板**。在历史记录存储和档案输出之上运行FastAPI后端；面向审计的共享视图；可自托管的。 ### 深度跟进 对现有检查进行开放改进，而不是新阶段： - CycloneDX完整字段验证 - Secure Boot PE/COFF二进制签名验证 - Secure Boot PKI链验证（PK / KEK / DB注册） - `.gitlab-ci.yml` / GitHub工作流程中的CI管道签名步骤检测 - Hardening-flags信号C+D和按配方覆盖（`image-buildinfo.bbclass`解析、ELF工件验证、`TUNE_CCARGS:append:pn-foo`-样式覆盖）。 - `product.yaml` `code_integrity`块 + 验证（制造商声明所选的完整性策略：`fit_dm_verity`、`uefi_secure_boot`、`ota_server_signed`、`ima_evm`或`other`，并附上理由；`code-integrity`检查接受声明的策略作为

标签：CRA合规, CVE跟踪, CycloneDX, GitHub Advanced Security, IMA/EVM, SBOM, UEFI签名, XML 请求, Yocto构建, 代码完整性, 反取证, 安全加固, 安全开发, 安全评估, 嵌入式Linux, 日志审计, 硬件无关, 许可证审计, 跌倒检测, 软件物料清单, 逆向工具