csumguard

Uma proteção interina de admissão de pacotes e lançador supervisionado para CVE-2026-99999.

Ele descarta tráfego perigoso de convidados na interface TAP de uma VM antes que o kernel do host possa alcançar skb_checksum_help. Escrito em C11 puro e eBPF com zero scripts interpretados.

Status de Segurança: GAL 1 · Contenção de CVE não verificada · Promoção interrompida. Todas as suítes offline de política, detector, lançador e sanitizadores passam. No entanto, os filtros de entrada TC validam os bytes do payload do pacote, não os metadados de checksum do virtio (csum_start). O detector fentry observa metadados suspeitos, mas não consegue bloquear a execução.

Remediação Autoritativa: Instale o kernel do host corrigido pelo fornecedor contendo o commit upstream 6785011f8b16 e reinicie. O csumguard fornece endurecimento do tráfego de convidados e supervisão em tempo de execução, não a neutralização verificada da CVE. Consulte VALIDATION.md.

---

Arquitetura

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

Fluxo de admissão de pacotes

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 do Supervisor e quarentena

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	Arquivos	Função
Filtro de pacotes	policy.h, csumguard_tc.bpf.c	Classificador header-only na entrada TC. Permite TCP, UDP e ARP padrão. Descarta fragmentos, opções, GSO e VLANs. 26 contadores por CPU rastreiam os motivos.
Detector de checksum	detect_policy.h, csumguard_detect.bpf.c	Sonda fentry opcional que rastreia pacotes CHECKSUM_PARTIAL no kernel. Incrementa contadores em offsets suspeitos. Nunca bloqueia.
Carregador	loader.c	Valida caminhos de arquivo a partir de / para prevenir ataques de symlink. Verifica digests SHA-256, garante que a interface esteja DOWN e anexa clsact.
Lançador de VMM	launch.c, launch_policy.h	Valida as evidências do operador, reduz privilégios para UID/GID não-root, inicia o VMM e monitora o anexo. Pausa e encerra a VM se o filtro cair.
Registro de recibos	launch.c	Thread assíncrona que grava registros JSONL encadeados por hash SHA-256 do FIPS 180-4. Buffer circular de 64 slots evita travamentos de disco.

---

Início rápido

1. Compilar e testar offline

make EGRESS_MTU=1500 all
make test

2. Anexar o filtro

Prepare o objeto em um diretório de propriedade do root (/opt/csumguard), garanta que a interface TAP esteja DOWN e anexe:

/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. Iniciar com supervisão

Preencha /etc/csumguard/admission.json e inicie a VMM sob 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

Empacotamento e distribuição OCI

O csumguard é empacotado e distribuído como um Artefato OCI v1.1 (application/vnd.csumguard.ebpf.v1) com referrers de evidência criptográfica anexados (proveniência SLSA v1.0, SBOM CycloneDX v1.6 e matriz de verificação):

# 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

Consulte oci/README.md para obter os tipos de mídia OCI completos, descritores e fluxos de trabalho de verificação do Cosign.

---

Verificação

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

# Run offline test suite
make test