csumguard

Ein vorläufiger Paket-Zulassungsschutz und überwachter Launcher für CVE-2026-99999.

Er verwirft gefährlichen Gastverkehr auf der TAP-Schnittstelle einer VM, bevor der Host-Kernel skb_checksum_help erreichen kann. Geschrieben in reinem C11 und eBPF ohne interpretierte Skripte.

Sicherheitsstatus: GAL 1 · CVE-Eindämmung nicht verifiziert · Beförderung gestoppt. Alle Offline-Policy-, Detektor-, Launcher- und Sanitizer-Suiten bestehen. Allerdings validieren TC-Ingress-Filter Paket-Payload-Bytes, nicht die virtio-Checksum-Metadaten (csum_start). Der fentry-Detektor beobachtet verdächtige Metadaten, kann die Ausführung jedoch nicht blockieren.

Maßgebliche Behebung: Installieren Sie den gepatchten Host-Kernel des Herstellers, der den Upstream-Commit 6785011f8b16 enthält, und starten Sie das System neu. csumguard bietet Härtung des Gastverkehrs und Laufzeitüberwachung, jedoch keine verifizierte CVE-Neutralisierung. Siehe VALIDATION.md.

---

Architektur

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

Paket-Zulassungsablauf

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"]

Supervisor-Lebenszyklus und Quarantäne

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

Komponenten

Komponente	Dateien	Rolle
Paketfilter	policy.h, csumguard_tc.bpf.c	Header-only-Klassifizierer am TC-Ingress. Erlaubt Standard-TCP, UDP und ARP. Verwirft Fragmente, Optionen, GSO und VLANs. 26 Pro-CPU-Zähler verfolgen die Gründe.
Checksummen-Detektor	detect_policy.h, csumguard_detect.bpf.c	Optionaler fentry-Probe, der CHECKSUM_PARTIAL-Pakete im Kernel verfolgt. Erhöht Zähler bei verdächtigen Offsets. Blockiert niemals.
Loader	loader.c	Validiert Dateipfade ab /, um Symlink-Angriffe zu verhindern. Überprüft SHA-256-Digests, stellt sicher, dass die Schnittstelle DOWN ist, und hängt clsact an.
VMM-Launcher	launch.c, launch_policy.h	Validiert Betreibernachweise, senkt Privilegien auf Nicht-Root-UID/GID, startet die VMM und überwacht die Anbindung. Pausiert und beendet die VM, wenn der Filter ausfällt.
Belegjournal	launch.c	Asynchroner Thread, der FIPS 180-4 SHA-256-hashverkettete JSONL-Datensätze schreibt. 64-Slot-Ringpuffer verhindert Festplatten-Stillstände.

---

Schnellstart

1. Offline bauen und testen

make EGRESS_MTU=1500 all
make test

2. Den Filter anhängen

Legen Sie das Objekt in einem Verzeichnis ab, das dem Root-Benutzer gehört (/opt/csumguard), stellen Sie sicher, dass die TAP-Schnittstelle DOWN ist, und hängen Sie ihn an:

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

3. Start mit Überwachung

Füllen Sie /etc/csumguard/admission.json aus und starten Sie die VMM unter csumguard_launch:

/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

Paketierung und OCI-Verteilung

csumguard wird als OCI v1.1 Artifact (application/vnd.csumguard.ebpf.v1) paketiert und verteilt, mit angehängten kryptografischen Nachweis-Referrern (SLSA v1.0-Provenienz, CycloneDX v1.6 SBOM und Verifikationsmatrix):

# 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

Siehe oci/README.md für vollständige OCI-Medientypen, Deskriptoren und Cosign-Verifizierungsworkflows.

---

Verifizierung

# Verify all source and evidence hashes
shasum -a 256 -c SHA256SUMS

# Run offline test suite
make test