csumguard

Una guarda provisional de admisión de paquetes y un lanzador supervisado para CVE-2026-99999.

Descarta el tráfico peligroso de invitados en la interfaz TAP de una VM antes de que el kernel del host pueda alcanzar skb_checksum_help. Escrito en C11 puro y eBPF sin scripts interpretados.

Estado de seguridad: GAL 1 · Contención de CVE no verificada · Promoción detenida. Todas las suites offline de políticas, detector, lanzador y sanitizadores pasan. Sin embargo, los filtros de ingreso TC validan los bytes de la carga útil de los paquetes, no los metadatos de checksum de virtio (csum_start). El detector fentry observa metadatos sospechosos pero no puede bloquear la ejecución.

Remediación autoritativa: Instale el kernel del host parcheado por el proveedor que contiene el commit upstream 6785011f8b16 y reinicie. csumguard proporciona endurecimiento del tráfico de invitados y supervisión en tiempo de ejecución, no una neutralización verificada del CVE. Consulte VALIDATION.md.

---

Arquitectura

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

Flujo de admisión de paquetes

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 de vida del supervisor y cuarentena

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

Componentes

Componente	Archivos	Función
Filtro de paquetes	policy.h, csumguard_tc.bpf.c	Clasificador header-only en la entrada de TC. Permite TCP, UDP y ARP estándar. Descarta fragmentos, opciones, GSO y VLANs. 26 contadores por CPU registran los motivos.
Detector de checksum	detect_policy.h, csumguard_detect.bpf.c	Sonda fentry opcional que rastrea paquetes CHECKSUM_PARTIAL en el kernel. Incrementa contadores ante offsets sospechosos. Nunca bloquea.
Cargador	loader.c	Valida las rutas de archivo desde / para prevenir ataques de symlink. Verifica los digests SHA-256, asegura que la interfaz esté DOWN y adjunta clsact.
Lanzador de VMM	launch.c, launch_policy.h	Valida la evidencia del operador, reduce privilegios a UID/GID no root, inicia el VMM y monitorea la adjunción. Pausa y mata la VM si el filtro se desprende.
Registro de recibos	launch.c	Hilo asíncrono que escribe registros JSONL encadenados por hash SHA-256 según FIPS 180-4. Un búfer circular de 64 ranuras previene bloqueos de disco.

---

Inicio rápido

1. Compilar y probar sin conexión

make EGRESS_MTU=1500 all
make test

2. Adjuntar el filtro

Coloque el objeto en un directorio propiedad de root (/opt/csumguard), asegúrese de que la interfaz TAP esté DOWN y adjunte:

/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. Lanzar con supervisión

Complete /etc/csumguard/admission.json e inicie la VMM bajo 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

Empaquetado y distribución OCI

csumguard se empaqueta y distribuye como un Artefacto OCI v1.1 (application/vnd.csumguard.ebpf.v1) con referrers de evidencia criptográfica adjuntos (procedencia SLSA v1.0, SBOM CycloneDX v1.6 y matriz de verificación):

# 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 para conocer los tipos de medios OCI completos, los descriptores y los flujos de trabajo de verificación de Cosign.

---

Verificación

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

# Run offline test suite
make test