受限 eBPF TC 入口防护、CO-RE 检测器、经验证的加载器，以及针对 CVE-2026-99999 的 C11 VMM 启动监督器
一个针对 CVE-2026-99999 的临时数据包准入防护与受监督启动器。
它在虚拟机 TAP 接口上丢弃危险的客户机流量，赶在宿主内核到达 skb_checksum_help 之前完成拦截。使用纯 C11 和 eBPF 编写，不含任何解释型脚本。
安全状态：GAL 1 · CVE 遏制未经验证 · 晋升已停止。 所有离线策略、检测器、启动器和 sanitizer 测试套件均通过。然而，TC ingress 过滤器校验的是数据包负载字节，而非 virtio 校验和元数据（
csum_start）。fentry 检测器能观察到可疑元数据，但无法阻止执行。权威修复方案： 安装厂商提供的、包含上游提交
6785011f8b16的已修补宿主内核，然后重启。csumguard提供的是客户机流量加固与运行时监督，而非经过验证的 CVE 消除。参见 VALIDATION.md。
flowchart LR
subgraph Guest["Untrusted Guest VM"]
VMM["VMM Process<br/>QEMU or Cloud-Hypervisor"]
end
subgraph Interface["Host TAP Device tap0"]
TAP["tap0 clsact"]
TC["csumguard_in<br/>eBPF TC Ingress"]
end
subgraph Host["Host Linux Kernel"]
STACK["Host Network Stack"]
SINK["skb_checksum_help<br/>Vulnerable Sink"]
end
subgraph Supervisor["csumguard_launch Supervisor"]
MON["Identity Poller<br/>6D Vector State"]
QUAR["Quarantine Engine<br/>SIGSTOP, DOWN, SIGKILL"]
RING["Receipt Ledger<br/>64-slot Ring Buffer"]
end
VMM -->|TX Frames| TAP
TAP --> TC
TC -->|Admitted TCP, UDP, ARP| STACK
TC -.->|Dropped: Frag, GSO, VLAN, Options| DROP["Dropped + Counter"]
STACK -.-> SINK
MON -->|Polls Status| TAP
MON -->|Attachment Drift or Loss| QUAR
QUAR -->|Pauses & Terminates| VMM
QUAR -->|Flushes Receipts| RING
flowchart TD
PKT["Ingress Frame"] --> ETH{"EtherType"}
ETH -->|ARP 0x0806| ARP{"Request or Reply"}
ARP -->|Valid 42B or 60B pad| PASS["PASS: Admitted"]
ARP -->|Invalid| D_ARP["DROP: Malformed ARP"]
ETH -->|IPv4 0x0800| IP{"IPv4 Header Checks"}
ETH -->|Other or VLAN| D_ETH["DROP: Non-IPv4 or VLAN"]
IP -->|Options, Frag, or GSO| D_IP["DROP: Frag, Option, GSO, or Csum"]
IP -->|Valid IHL 5, MF 0, Offset 0| L4{"Transport Protocol"}
L4 -->|TCP proto 6| TCP{"TCP Checks"}
L4 -->|UDP proto 17| UDP{"UDP Checks"}
L4 -->|Other| D_PROTO["DROP: Unsupported Protocol"]
TCP -->|Valid ports and length| PASS
TCP -->|Port 0 or invalid length| D_TCP["DROP: Bad TCP"]
UDP -->|Valid dst port and length| PASS
UDP -->|Port 0 or invalid length| D_UDP["DROP: Bad UDP"]
flowchart TD
S0["1. Preflight<br/>Validate admission.json"] --> S1["2. Attachment<br/>Verify Hash & Attach clsact"]
S1 --> S2["3. Privilege Drop<br/>Non-root UID/GID & no_new_privs"]
S2 --> S3["4. Running<br/>Poll 4-Tuple ID Every 200ms"]
S3 -->|Poll Matches ID| S3
S3 -->|Filter Loss or ID Mismatch| Q0["5. Quarantine: SIGSTOP<br/>Pause VMM Process Group"]
Q0 --> Q1["6. Quarantine: LINK DOWN<br/>Set TAP Interface Down"]
Q1 --> Q2["7. Quarantine: SIGKILL<br/>Terminate Process Group"]
Q2 --> Q3["8. Exit<br/>Flush Hash-Chained Receipts"]
S3 -->|Normal VM Exit| Q3
| 组件 | 文件 | 作用 |
|---|---|---|
| 数据包过滤器 | policy.h、csumguard_tc.bpf.c | TC 入口处的仅头文件分类器。允许标准 TCP、UDP 和 ARP。丢弃分片、选项、GSO 和 VLAN。26 个每 CPU 计数器跟踪原因。 |
| 校验和检测器 | detect_policy.h、csumguard_detect.bpf.c | 可选的 fentry 探针，跟踪内核中的 CHECKSUM_PARTIAL 数据包。在可疑偏移处递增计数器。从不阻止。 |
| 加载器 | loader.c | 验证从 / 开始的文件路径以防止符号链接攻击。验证 SHA-256 摘要，确保接口为 DOWN，并附加 clsact。 |
| VMM 启动器 | launch.c、launch_policy.h | 验证操作员证据，将权限降为非 root UID/GID，启动 VMM，并监控附加状态。如果过滤器丢弃，则暂停并终止 VM。 |
| 收据账本 | launch.c | 异步线程写入 FIPS 180-4 SHA-256 哈希链式 JSONL 记录。64 槽环形缓冲区防止磁盘停顿。 |
make EGRESS_MTU=1500 all
make test
将对象暂存到 root 拥有的目录（/opt/csumguard）中，确保 TAP 接口处于 DOWN 状态，然后附加：
/opt/csumguard/csumguard_loader attach tap0 /opt/csumguard/csumguard_tc.bpf.o <EXPECTED_SHA256>
/opt/csumguard/csumguard_loader status tap0 <IFINDEX> <NETNS_INODE> <PROG_ID>
填写 /etc/csumguard/admission.json，并在 csumguard_launch 下启动 VMM：
/opt/csumguard/csumguard_launch \
--interface tap0 \
--loader /opt/csumguard/csumguard_loader \
--object /opt/csumguard/csumguard_tc.bpf.o \
--evidence /etc/csumguard/admission.json \
--receipt /var/log/csumguard/tap0.jsonl \
--uid 65534 \
--gid 65534 \
--interval 0.2 \
-- /usr/bin/qemu-system-x86_64 -netdev tap,id=n0,ifname=tap0,script=no,downscript=no
csumguard 以 OCI v1.1 Artifact（application/vnd.csumguard.ebpf.v1）的形式打包和分发，并附带加密证据引用（SLSA v1.0 来源证明、CycloneDX v1.6 SBOM 以及验证矩阵）：
# Package local OCI layout and attach all referrers
./oci/package.sh --layout-dir build/oci-layout --tag v0.2.0
# Discover attached referrers graph
oras discover --oci-layout build/oci-layout:v0.2.0
# Pull directly on hypervisor hosts without container daemon
oras pull ghcr.io/mchorfa/csumguard:v0.2.0
完整的 OCI 媒体类型、描述符和 Cosign 验证工作流请参见 oci/README.md。
# Verify all source and evidence hashes
shasum -a 256 -c SHA256SUMS
# Run offline test suite
make test
# Run AddressSanitizer and UndefinedBehaviorSanitizer
clang -std=c11 -O1 -g -fsanitize=address,undefined -DEGRESS_MTU=1500 -I. tests/test_policy.c -o /tmp/p_asan && /tmp/p_asan
clang -std=c11 -O1 -g -fsanitize=address,undefined -I. tests/test_launch.c -lpthread -o /tmp/l_asan && /tmp/l_asan
clang -std=c11 -O1 -g -fsanitize=address,undefined tests/send_frame.c -o /tmp/f_asan && /tmp/f_asan --self-test
policy.h Packet admission parser and reason codes
detect_policy.h Checksum partial predicate
launch_policy.h Admission validator, 6D vector state, and SHA-256
csumguard_tc.bpf.c TC ingress eBPF program
csumguard_detect.bpf.c fentry/skb_checksum_help probe
loader.c libbpf loader and status reporter
launch.c VMM supervisor, quarantine engine, and receipt writer
tests/ Offline C11 test suites and frame generator
testbed.sh Lab veth test harness
docs/ Runbook, admission spec, and CVE references
evidence/ Verification logs and test records
promotion-gates.yaml Gate statuses and target requirements