csumguard

Una guardia interinale di ammissione dei pacchetti e un launcher supervisionato per CVE-2026-99999.

Scarta il traffico guest pericoloso sull'interfaccia TAP di una VM prima che il kernel host possa raggiungere skb_checksum_help. Scritto in puro C11 ed eBPF senza script interpretati.

Stato di sicurezza: GAL 1 · Contenimento della CVE non verificato · Promozione interrotta. Tutte le suite offline di policy, rilevamento, launcher e sanitizer passano. Tuttavia, i filtri TC ingress validano i byte del payload dei pacchetti, non i metadati del checksum virtio (csum_start). Il rilevatore fentry osserva metadati sospetti ma non può bloccare l'esecuzione.

Remediation autorevole: Installare il kernel host corretto dal fornitore contenente il commit upstream 6785011f8b16 e riavviare. csumguard fornisce hardening del traffico guest e supervisione runtime, non una neutralizzazione verificata della CVE. Vedere VALIDATION.md.

---

Architettura

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

Flusso di ammissione dei pacchetti

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

Ciclo di vita del supervisor e quarantena

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

Componenti

Componente	File	Ruolo
Packet filter	policy.h, csumguard_tc.bpf.c	Classificatore header-only all'ingresso TC. Consente TCP, UDP e ARP standard. Scarta frammenti, opzioni, GSO e VLAN. 26 contatori per-CPU tracciano i motivi.
Checksum detector	detect_policy.h, csumguard_detect.bpf.c	Sonda fentry opzionale che traccia i pacchetti CHECKSUM_PARTIAL nel kernel. Incrementa i contatori su offset sospetti. Non blocca mai.
Loader	loader.c	Convalida i percorsi dei file da / per prevenire attacchi tramite symlink. Verifica i digest SHA-256, assicura che l'interfaccia sia DOWN e collega clsact.
VMM launcher	launch.c, launch_policy.h	Convalida le evidenze dell'operatore, riduce i privilegi a UID/GID non-root, avvia il VMM e monitora il collegamento. Mette in pausa e termina la VM se il filtro viene rimosso.
Receipt ledger	launch.c	Thread asincrono che scrive record JSONL con catena di hash SHA-256 conforme a FIPS 180-4. Un ring buffer da 64 slot previene stalli del disco.

---

Avvio rapido

1. Compilazione e test offline

make EGRESS_MTU=1500 all
make test

2. Collegare il filtro

Posiziona l'oggetto in una directory di proprietà di root (/opt/csumguard), assicurati che l'interfaccia TAP sia DOWN e collegala:

/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. Avvio con supervisione

Compila /etc/csumguard/admission.json e avvia la VMM sotto 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

Packaging e distribuzione OCI

csumguard è pacchettizzato e distribuito come OCI v1.1 Artifact (application/vnd.csumguard.ebpf.v1) con referrer di evidenza crittografica allegati (provenienza SLSA v1.0, SBOM CycloneDX v1.6 e matrice di verifica):

# 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

Consulta oci/README.md per i tipi di media OCI completi, i descrittori e i flussi di lavoro di verifica Cosign.

---

Verifica

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

# Run offline test suite
make test