← Cloudflare DDoS Protection / ddos-protection / advanced-ddos-systems / overview

Programmable Flow Protection (Beta)

Programmable Flow Protection je systém ochrany před DDoS útoky vedenými přes vlastní i standardizované protokoly vrstvy 7 postavené na UDP, například herní protokoly, protokoly finančních služeb, VoIP, telekomunikace a streaming. Z hlediska topologie podporuje asymetrické i symetrické konfigurace, kontroluje ale pouze příchozí provoz.

Programmable Flow Protection je momentálně v uzavřené beta verzi a je k dispozici jako doplněk k Magic Transit (BYOIP nebo IP adresy pronajaté od Cloudflare). Systém je k dispozici pouze pro tuto službu. Pokud jej chcete zapnout, obraťte se na svůj tým pro správu účtu nebo vyplňte tento formulář ↗.

Systém Programmable Flow Protection umožňuje napsat vlastní stavový program pracující na úrovni paketů v jazyce C a spustit jej v globální anycast síti Cloudflare jako program extended Berkeley Packet Filter (eBPF) běžící v uživatelském prostoru. program eBPF ↗ je systém pro filtrování paketů, který vývojáři umožňuje psát vlastní výkonnou síťovou logiku.

Programmable Flow Protection kontroluje a analyzuje protokoly vaší aplikace postavené na UDP (hloubková inspekce paketů) a podle vašeho programu rozhoduje, jak s pakety naloží. Logika vlastního programu vám umožní propouštět oprávněné uživatele a zároveň aktivně blokovat útoky.

Systém je postaven na flowtrackd platformě, stavové mitigační platformě Cloudflare. Systém Programmable Flow Protection staví na systému DDoS Advanced Protection a jeho obecná nastavení ke svému fungování. Respektuje prefixy které jste vybrali ke směrování přes systémy Advanced Protection, a také allowlist. Systém Advanced DDoS Protection by měl být povoleno pro fungování systému Programmable Flow Protection.

V průběhu bety Cloudflare uživatelům s psaním vlastního kódu pomáhá a poskytuje jim doporučení. Hotové ukázky kódu (šablony) pro běžné herní protokoly a protokoly VoIP mohou přibýt později.

Jakmile máte pro svůj účet zapnutou Programmable Flow Protection, přejděte na Sítě > L3/4 DDoS Protection > Advanced Protection v dashboardu Cloudflare. V části Programmable Flow Protection kartě:

Můžete vytvořit další pravidla s odlišnou hodnotou parametru nastavení pravidla s vymezeným rozsahem do různých regionů a lokalit Cloudflare, čímž změníte režim (Mitigation nebo Monitoring) tak, aby odpovídal vašim vzorcům provozu a obchodním potřebám.

Systém Programmable Flow Protection podporuje Data Localization suite.

Následující kroky vytvoří ukázkový program, který zahazuje veškerý provoz protokolu User Datagram Protocol (UDP) s hlavičkou IPv6. Zahazuje také provoz směřovaný na port 66 a provoz, který v datové části UDP nemá určitou vlastní hodnotu aplikační hlavičky.

Pro přehlednost uvádíme níže celý základní program:

#define CF_EBPF_HELPER_V0

#include <cf_ebpf_defs.h>
#include <cf_ebpf_helper.h>

struct apphdr {
    uint8_t       version;
    uint16_t      length;   // Length of the variable-length token
    unsigned char token[0]; // Variable-length token
} __attribute__((packed));

uint64_t
cf_ebpf_main(void *state)
{
    struct cf_ebpf_generic_ctx *ctx = state;
    struct cf_ebpf_parsed_headers headers;
    struct cf_ebpf_packet_data *p;

    if (parse_packet_data(ctx, &p, &headers) != 0) {
        return CF_EBPF_DROP;
    }
    struct ipv6hdr *ipv6_hdr;
    struct udphdr *udp_hdr;
    ipv6_hdr = (struct ipv6hdr *)headers.ipv6;
    if (ipv6_hdr != NULL) {
        return CF_EBPF_DROP;
    }

    udp_hdr = (struct udphdr *)headers.udp;
    if (ntohs(udp_hdr->dest) == 66) {
        return CF_EBPF_DROP;
    }

    struct apphdr *app = (struct apphdr *)(udp_hdr + 1);
    if ((uint8_t *)(app + 1) > headers.data_end) {
        return CF_EBPF_DROP;
    }

    // The verifier has a special limit that it will not allow offsets
    // beyond 65535. We need this check (token_len > 64000) in order
    // to satisfy that, even though it is not possible.
    uint16_t token_len = app->length;
    if (token_len > 64000) {
        return CF_EBPF_DROP;
    }

    if ((uint8_t *)(app->token + token_len) > headers.data_end) {
        return CF_EBPF_DROP;
    }

    uint8_t *last_byte = app->token + token_len - 1;
    if (*last_byte != 0xCF) {
        return CF_EBPF_DROP;
    }
    return CF_EBPF_PASS;
}

Ukázkový program níže implementuje mechanismus výzvy a odpovědi nad UDP a pomocí pomocných funkcí udržuje stav mezi pakety ze stejné zdrojové IP adresy. Hodí se ke zmírňování útoků DDoS: klient musí nejprve prokázat, že výzvu přijal a dokáže na ni odpovědět, teprve pak systém jeho provoz propustí.

Mechanismus výzvy funguje takto:

Když dorazí paket z neznámé zdrojové IP adresy, program vygeneruje výzvový paket s náhodným nonce a zdrojovou IP adresu označí ve stavové tabulce jako "challenged". Původní paket se zahodí.

Pokud paket dorazí ze zdrojové IP adresy, které už byla výzva odeslána, program ověří, zda obsahuje správnou odpověď na výzvu (hodnota nonce zkombinovaná operací XOR s tajnou hodnotou). Při správné odpovědi se zdrojová IP adresa označí jako „ověřená“, při nesprávné se okamžitě přidá na blocklist.

Pakety z ověřených zdrojových IP adres projdou bez dalších kontrol.

Pro přehlednost uvádíme níže celý složitý program:

#define CF_EBPF_HELPER_V0

#include <cf_ebpf_defs.h>
#include <cf_ebpf_helper.h>

// Challenge-response protocol constants
#define CHALLENGE_SECRET 0xDEADBEEFCAFEBABEULL
#define CHALLENGE_EXPIRY_SECS 60
#define VERIFIED_EXPIRY_SECS 3600

// Challenge packet structure
struct challenge_packet {
    uint64_t nonce;
    uint64_t response;
};

uint64_t cf_ebpf_main(void *state)
{
    struct cf_ebpf_generic_ctx *ctx = state;
    struct cf_ebpf_parsed_headers headers;
    struct cf_ebpf_packet_data *p;

    if (parse_packet_data(ctx, &p, &headers) != 0) {
        return CF_EBPF_DROP;
    }

    struct udphdr *udp_hdr = headers.udp;

    // Check source IP status
    uint8_t status;
    uint64_t expiry;
    int ret = get_src_ip_status(&status, &expiry);

    // Check if status has expired
    int64_t now = timestamp();
    if (ret == 0 && expiry > 0 && (uint64_t)now > expiry) {
        ret = -1;  // Treat as new connection
    }

    // Handle verified source IPs - allow through
    if (ret == 0 && status == CF_EBPF_SRC_IP_STATUS_VERIFIED) {
        return CF_EBPF_PASS;
    }

    // Handle challenged source IPs - check for valid response
    if (ret == 0 && status == CF_EBPF_SRC_IP_STATUS_CHALLENGED) {
        uint64_t stored_nonce;
        if (get_src_ip_data(&stored_nonce) != 0) {
            return CF_EBPF_DROP;
        }

        // Parse challenge response from packet payload
        struct challenge_packet *resp = (struct challenge_packet *)(udp_hdr + 1);
        if ((uint8_t *)(resp + 1) > headers.data_end) {
            return CF_EBPF_DROP;
        }

        // Check response using XOR
        uint64_t expected_response = stored_nonce ^ CHALLENGE_SECRET;
        if (resp->response == expected_response) {
            // Correct response - mark as verified
            set_src_ip_status(CF_EBPF_SRC_IP_STATUS_VERIFIED, VERIFIED_EXPIRY_SECS);
            set_src_ip_data(0);
            return CF_EBPF_PASS;
        }

        // Wrong response - blocklist immediately
        set_src_ip_status(CF_EBPF_SRC_IP_STATUS_BLOCKLISTED, 0);
        return CF_EBPF_DROP;
    }

    // New source IP - issue initial challenge
    uint64_t nonce = rand();
    set_src_ip_status(CF_EBPF_SRC_IP_STATUS_CHALLENGED, CHALLENGE_EXPIRY_SECS);
    set_src_ip_data(nonce);

    struct challenge_packet challenge;
    challenge.nonce = nonce;
    challenge.response = 0;
    set_challenge((uint8_t *)&challenge, sizeof(challenge));

    return CF_EBPF_DROP;
}

Tento program ukazuje několik klíčových principů:

• Správa stavu: Použití get_src_ip_status, set_src_ip_status, get_src_ip_data, a set_src_ip_data ke sledování stavu výzvy pro každou zdrojovou IP adresu.
• Odeslání výzvy: Použití set_challenge k odeslání paketu s výzvou zpět klientovi.
• Kryptografické ověření: Použití sdíleného tajemství k ověření, že klient na výzvu odpověděl správně.
• Zpracování expirace: Použití časových razítek k vypršení zastaralých stavových záznamů.

Ukázkový program níže implementuje omezovač rychlosti pro jednotlivé zdrojové IP adresy pomocí algoritmu pevného okna. Hodí se ke zmírňování objemových útoků DDoS, protože omezuje, kolik paketů může jedna zdrojová IP adresa odeslat v daném časovém okně.

Mechanismus omezování rychlosti funguje takto:

Po příchodu paketu načte program uložený stav pro danou zdrojovou IP adresu. Stav obsahuje časové razítko začátku okna a čítač paketů, obojí sbalené do jediné 64bitové hodnoty. Pokud aktuální čas stále spadá do okna, čítač se zvýší. Jakmile čítač překročí nastavený limit, paket se zahodí. Po vypršení okna se čítač vynuluje.

Pro přehlednost uvádíme níže celý program pro omezení rychlosti:

#include <cf_ebpf_defs.h>
#define CF_EBPF_HELPER_V0
#include <cf_ebpf_helper.h>

// Rate limit configuration
// This program implements a fixed (not sliding) window ratelimit.
#define RATE_LIMIT 100         // Maximum packets allowed per window
#define WINDOW_SECONDS 60      // Time window in seconds

// The source IP table holds a mapping from source IP -> custom u64. We will make the custom u64 value in the 
// table hold a timestamp and a counter to accomplish a ratelimit.
// 
// NOTE: the source IP table is effectively a LRU cache. If it is full, old values will be evicted. 
// Values are also garbage collected from the table every 1hr.
// 
// The macros below pack the timestamp (upper 32 bits) and counter (lower 32 bits) into 64-bit data
// into a value that we can store into the source IP table.
#define PACK_STATE(ts, count) (((uint64_t)(ts) << 32) | ((uint64_t)(count) & 0xFFFFFFFF))
#define UNPACK_TIMESTAMP(data) ((uint32_t)((data) >> 32))
#define UNPACK_COUNTER(data) ((uint32_t)((data) & 0xFFFFFFFF))

uint64_t cf_ebpf_main(void *state)
{
    // Get current timestamp
    int64_t now = timestamp();
    if (now < 0) {
        return CF_EBPF_PASS; // If timestamp fails, allow the packet
    }
    uint32_t now_secs = (uint32_t)now;

    // Try to get existing state for this source IP
    uint64_t data;
    int ret = get_src_ip_data(&data);
    uint32_t window_start;
    uint32_t counter;

    if (ret == -1) {
        // No existing entry - first packet from this IP
        // Initialize: window starts now, counter = 1
        window_start = now_secs;
        counter = 1;
    } else if (ret != 0) {
        // If there's other unknown error with getting src_ip_data, pass packet
        return CF_EBPF_PASS;
    } else {
        // Entry exists - unpack the state
        window_start = UNPACK_TIMESTAMP(data);
        counter = UNPACK_COUNTER(data);
        // Check if we're still in the same time window
        if (now_secs - window_start >= WINDOW_SECONDS) {
            // Window expired - reset counter and start new window
            window_start = now_secs;
            counter = 1;
        } else {
            // Still in same window - increment counter
            counter++;
            // Check if rate limit exceeded
            if (counter > RATE_LIMIT) {
                // Drop packet without updating state
                // Here is where the actual ratelimit occurs.
                return CF_EBPF_DROP;
            }
        }
    }
    // Store updated state
    uint64_t new_data = PACK_STATE(window_start, counter);
    set_src_ip_data(new_data);
    return CF_EBPF_PASS;
}

Tento program ukazuje několik klíčových principů:

• Zabalení bitů: Uložení více hodnot (časové razítko a čítač) do jediného u64 pomocí bitového posunu.
• Omezení rychlosti s pevným oknem: Sledování počtu paketů v samostatných časových oknech a vynulování po vypršení okna.
• Korektní ošetření chyb: Propouštění paketů při selhání pomocných funkcí, aby v hraničních situacích nevznikaly falešně pozitivní nálezy.
• Chování stavové tabulky: Stavová tabulka zdrojových IP adres je cache typu LRU. Po naplnění kapacity se staré záznamy odstraňují. Záznamy se navíc uvolňují po hodině nečinnosti.

Každý program má přístup ke svému vlastnímu lokálnímu stavu. Stav je lokální pro každý server a mezi datovými centry se nesdílí.

Stav je vázaný na konkrétní program. Když změníte režim pravidla (disabled, monitoring nebo enabled), obsah stavových tabulek zůstane zachovaný. Pokud ale změníte program pravidla nebo obsah samotného programu, stavové tabulky se vymažou.

Vašemu programu jsou k dispozici dvě stavové tabulky.

Stavová tabulka zdrojových IP adres ukládá stav podle klíče, kterým je zdrojová IP adresa. Každý záznam obsahuje:

Výchozí maximální kapacita je 1 000 záznamů.

K práci s touto tabulkou použijte následující pomocné funkce:

• get_src_ip_status vrací stav zdrojové IP adresy aktuálního paketu.
• set_src_ip_status nastavuje stav zdrojové IP adresy aktuálního paketu.
• get_src_ip_data vrací uživatelská data pro zdrojovou IP adresu aktuálního paketu.
• set_src_ip_data ukládá uživatelská data pro zdrojovou IP adresu aktuálního paketu.

Záznam v tabulce stavů zdrojových IP adres vzniká za těchto podmínek:

1. program volá set_src_ip_status k označení zdrojové IP adresy jako Challenged, Verified nebo Blocklisted.
2. program volá set_src_ip_data k uložení vlastních u64 dat pro zdrojovou IP adresu.
3. program volá set_challenge pro novou zdrojovou IP, která v tabulce dosud nemá záznam.

Stavová tabulka toků ukládá stav pod klíčem tvořeným čtveřicí: zdrojová IP, zdrojový port, cílová IP a cílový port. Každý záznam obsahuje u64 hodnota, kterou můžete nastavit k libovolnému účelu.

Výchozí maximální kapacita je 10 000 záznamů.

K práci s touto tabulkou použijte následující pomocné funkce:

• get_flow_data vrací uživatelská data pro aktuální tok.
• set_flow_data ukládá uživatelská data pro aktuální tok.

Záznam v tabulce stavů toků vzniká za těchto podmínek:

1. program volá set_flow_data k uložení vlastních u64 dat pro daný tok.

Obě stavové tabulky jsou cache typu LRU (least recently used). Jakmile tabulka dosáhne maximální kapacity, nejstarší záznam se zahodí, aby uvolnil místo novým. Záznamy se navíc uvolňují, pokud k nim hodinu nikdo nepřistoupil.

Pomocná funkce je funkce, kterou poskytuje běhové prostředí Cloudflare a kterou volá zákaznický program.

Pomocné funkce jsou zásadní, protože architektura instrukční sady BPF (ISA) podporuje jen některá systémová volání. Z bezpečnostních důvodů Cloudflare zkompiluje objektový soubor BPF pouze s předem daným seznamem známých knihoven, který vývojář programu nemůže změnit.

Definice pomocných funkcí a zdrojové kódy obalu verifikátoru najdete na GitHub ↗.

Vytvoří cf_ebpf_parsed_headers z cf_ebpf_generic_ctx a cf_ebpf_packet_data. Provádí povinné kontroly paměti, aby program prošel verifikátorem.

static inline int parse_packet_data(
   struct cf_ebpf_generic_ctx *ctx,
   struct cf_ebpf_packet_data **out_p,
   struct cf_ebpf_parsed_headers *out_headers
);

Argumenty:

• ctx je ukazatel na obecný kontext předaný BPF programu.
• out_p je ukazatel pro uložení struktury s daty paketu.
• out_headers je ukazatel pro uložení struktury s rozparsovanými hlavičkami.

Vrací: 0 při úspěchu, 1 při selhání (například příliš krátký paket nebo neplatná délka). Při úspěchu out_headers obsahuje platné ukazatele na hlavičky IP a UDP.

Vygeneruje náhodné celé číslo bez znaménka.

uint64_t rand(void);

Vrací: Náhodný uint64_t hodnota.

Vrátí aktuální UNIX timestamp (počet nepřestupných sekund od 1. ledna 1970 0:00:00 UTC).

int64_t timestamp(void);

Vrací: Aktuální časové razítko jako int64_t.

Vypočítá hash MD5 zdrojového bufferu a výsledek uloží do cílového bufferu.

int hash_md5(uint8_t *src, size_t src_len, uint8_t *dest, size_t dest_len);

Argumenty:

• src je ukazatel na zdrojový buffer.
• src_len je délka zdrojového bufferu v bajtech.
• dest je ukazatel na cílový buffer (musí mít alespoň 16 bajtů).
• dest_len je délka cílového bufferu v bajtech.

Vrací:

• Při úspěchu kladná hodnota (počet zapsaných bajtů).
• -1 v případě, že je zdrojový buffer neplatný.
• -2 v případě, že je cílový buffer null nebo příliš malý.

Vypočítá hash SHA-256 zdrojového bufferu a výsledek uloží do cílového bufferu.

int hash_sha256(uint8_t *src, size_t src_len, uint8_t *dest, size_t dest_len);

Argumenty:

• src je ukazatel na zdrojový buffer.
• src_len je délka zdrojového bufferu v bajtech.
• dest je ukazatel na cílový buffer (musí mít alespoň 32 bajtů).
• dest_len je délka cílového bufferu v bajtech.

Vrací:

• Při úspěchu kladná hodnota (počet zapsaných bajtů).
• -1 v případě, že je zdrojový buffer neplatný.
• -2 v případě, že je cílový buffer null nebo příliš malý.

Vypočítá hash SHA-512 zdrojového bufferu a výsledek uloží do cílového bufferu.

int hash_sha512(uint8_t *src, size_t src_len, uint8_t *dest, size_t dest_len);

Argumenty:

• src je ukazatel na zdrojový buffer.
• src_len je délka zdrojového bufferu v bajtech.
• dest je ukazatel na cílový buffer (musí mít alespoň 64 bajtů).
• dest_len je délka cílového bufferu v bajtech.

Vrací:

• Při úspěchu kladná hodnota (počet zapsaných bajtů).
• -1 v případě, že je zdrojový buffer neplatný.
• -2 v případě, že je cílový buffer null nebo příliš malý.

Vypočítá hash CRC32 zdrojového bufferu a výsledek uloží jako 64bitové celé číslo. Jde o pomocnou funkci, která si interně zajišťuje převod z bajtů na celé číslo.

int hash_crc32(uint8_t *src, size_t src_len, uint64_t *dest);

Argumenty:

• src je ukazatel na zdrojový buffer.
• src_len je délka zdrojového bufferu v bajtech.
• dest je ukazatel na uint64_t k uložení výsledku CRC32.

Vrací:

• Při úspěchu kladná hodnota (počet interně zapsaných bajtů, vždy 8).
• -1 v případě, že je zdrojový buffer neplatný.
• -2 v případě, že je cílový buffer null.

Vypočítá hash BLAKE2B-512 zdrojového bufferu a výsledek uloží do cílového bufferu.

int hash_blake2b512(const uint8_t *src, size_t src_len, uint8_t *dest, size_t dest_len);

Argumenty:

• src je ukazatel na zdrojový buffer.
• src_len je délka zdrojového bufferu v bajtech.
• dest je ukazatel na cílový buffer (musí mít alespoň 64 bajtů).
• dest_len je délka cílového bufferu v bajtech.

Vrací:

• Při úspěchu kladná hodnota (počet zapsaných bajtů).
• -1 v případě, že je zdrojový buffer neplatný.
• -2 v případě, že je cílový buffer null nebo příliš malý.

Vypočítá HMAC-SHA256 zdrojového bufferu a výsledek uloží do cílového bufferu. Privátní klíč se nastavuje na úrovni platformy a program BPF k němu nemá přímý přístup. Klíč je jedinečný pro každý server a každého zákazníka.

int hmac_sha256(uint8_t *src, size_t src_len, uint8_t *dest, size_t dest_len);

Argumenty:

• src je ukazatel na zdrojový buffer.
• src_len je délka zdrojového bufferu v bajtech.
• dest je ukazatel na cílový buffer (musí mít alespoň 32 bajtů).
• dest_len je délka cílového bufferu v bajtech.

Vrací:

• Při úspěchu kladná hodnota (počet zapsaných bajtů).
• -1 v případě, že je zdrojový buffer neplatný.
• -2 v případě, že je cílový buffer null nebo příliš malý.

Vypočítá HMAC-SHA512 zdrojového bufferu a výsledek uloží do cílového bufferu. Privátní klíč se nastavuje na úrovni platformy a program BPF k němu nemá přímý přístup. Klíč je jedinečný pro každý server a každého zákazníka.

int hmac_sha512(uint8_t *src, size_t src_len, uint8_t *dest, size_t dest_len);

Argumenty:

• src je ukazatel na zdrojový buffer.
• src_len je délka zdrojového bufferu v bajtech.
• dest je ukazatel na cílový buffer (musí mít alespoň 64 bajtů).
• dest_len je délka cílového bufferu v bajtech.

Vrací:

• Při úspěchu kladná hodnota (počet zapsaných bajtů).
• -1 v případě, že je zdrojový buffer neplatný.
• -2 v případě, že je cílový buffer null nebo příliš malý.

Vypočítá BLAKE2B-512 HMAC zdrojového bufferu a výsledek uloží do cílového bufferu. Privátní klíč se nastavuje na úrovni platformy a program BPF k němu nemá přímý přístup. Klíč je jedinečný pro každý server a každého zákazníka.

int hmac_blake2b512(const uint8_t *src, size_t src_len, uint8_t *dest, size_t dest_len);

Argumenty:

• src je ukazatel na zdrojový buffer.
• src_len je délka zdrojového bufferu v bajtech.
• dest je ukazatel na cílový buffer (musí mít alespoň 64 bajtů).
• dest_len je délka cílového bufferu v bajtech.

Vrací:

• Při úspěchu kladná hodnota (počet zapsaných bajtů).
• -1 v případě, že je zdrojový buffer neplatný.
• -2 v případě, že je cílový buffer null nebo příliš malý.

Nastaví data výzvy pro aktuální paket. Použijte, když chcete klientovi odeslat paket s výzvou.

int set_challenge(uint8_t *src, size_t src_len);

Argumenty:

• src je ukazatel na buffer s daty výzvy.
• src_len je délka dat výzvy v bajtech. Pokud 0, buffer pro challenge se resetuje.

Vrací:

• 0 při úspěchu.
• -4 v případě, že je zdrojový buffer neplatný nebo překračuje maximální povolenou velikost.
• -5 v případě, že výzvy nejsou zapnuté.
• -6 v případě, že této zdrojové IP byla výzva odeslána příliš nedávno nebo je překročen globální limit rychlosti.

Načte ze stavové tabulky hodnotu status spojenou se zdrojovou IP adresou.

int get_src_ip_status(uint8_t *status, uint64_t *expiry);

Argumenty:

• status je ukazatel pro uložení hodnoty stavu (CF_EBPF_SRC_IP_STATUS_CHALLENGED, CF_EBPF_SRC_IP_STATUS_VERIFIED, nebo CF_EBPF_SRC_IP_STATUS_BLOCKLISTED). Může být null, pokud je potřeba pouze expirace.
• expiry je ukazatel pro uložení časového razítka vypršení platnosti. Může být null, pokud potřebujete jen stav.

Vrací:

• 0 při úspěchu.
• -1 v případě, že pro danou zdrojovou IP neexistuje žádný záznam.
• -2 v případě, že pro aktuální paket není nastaven kontext zdrojové IP.
• -3 v případě, že je zadaný buffer příliš malý.
• -4 v případě, že jsou zároveň status a expiry jsou null.
• -5 v případě, že stavová tabulka zdrojových IP není zapnutá.

Nastaví hodnotu stavu přiřazenou zdrojové IP adrese ve stavové tabulce.

int set_src_ip_status(uint8_t status, uint64_t expiry_secs);

Argumenty:

• status je hodnota stavu, která se má nastavit (CF_EBPF_SRC_IP_STATUS_CHALLENGED, CF_EBPF_SRC_IP_STATUS_VERIFIED, nebo CF_EBPF_SRC_IP_STATUS_BLOCKLISTED).
• expiry_secs je počet sekund do vypršení platnosti stavu. Pokud 0, stav nikdy nevyprší.

Vrací:

• 0 při úspěchu.
• -2 v případě, že pro aktuální paket není nastaven kontext zdrojové IP.
• -5 v případě, že stavová tabulka zdrojových IP není zapnutá.

Načte ze stavové tabulky vlastní data spojená se zdrojovou IP adresou.

int get_src_ip_data(uint64_t *data);

Argumenty:

• data je ukazatel pro převzetí uložené datové hodnoty.

Vrací:

• 0 při úspěchu.
• -1 v případě, že pro danou zdrojovou IP neexistuje žádný záznam.
• -2 v případě, že pro aktuální paket není nastaven kontext zdrojové IP.
• -3 v případě, že je zadaný buffer příliš malý.
• -4 v případě, že data je null.
• -5 v případě, že stavová tabulka zdrojových IP není zapnutá.

Ukládá do stavové tabulky vlastní data přiřazená ke zdrojové IP adrese.

int set_src_ip_data(uint64_t data);

Argumenty:

• data je datová hodnota, která se má uložit.

Vrací:

• 0 při úspěchu.
• -2 v případě, že pro aktuální paket není nastaven kontext zdrojové IP.
• -5 v případě, že stavová tabulka zdrojových IP není zapnutá.

Načte ze stavové tabulky vlastní data spojená s aktuálním tokem.

int get_flow_data(uint64_t *data);

Argumenty:

• data je ukazatel pro převzetí uložené datové hodnoty.

Vrací:

• 0 při úspěchu.
• -1 v případě, že pro daný tok neexistuje žádný záznam.
• -2 v případě, že pro aktuální paket není nastaven kontext toku.
• -3 v případě, že je zadaný buffer příliš malý.
• -4 v případě, že data je null nebo není zarovnaný.
• -5 v případě, že stavová tabulka toků není zapnutá.

Ukládá do stavové tabulky vlastní data přiřazená k aktuálnímu toku.

int set_flow_data(uint64_t data);

Argumenty:

• data je datová hodnota, která se má uložit.

Vrací:

• 0 při úspěchu.
• -2 v případě, že pro aktuální paket není nastaven kontext toku.
• -5 v případě, že stavová tabulka toků není zapnutá.

Vypočítá Shannonovu entropii zdrojového bufferu. Výsledek se vrací v milibitech, v rozsahu od 0 (všechny bajty stejné) do 8000 (všech 256 hodnot bajtů rovnoměrně rozložených).

int64_t entropy(uint8_t *src, size_t src_len);

Argumenty:

• src je ukazatel na zdrojový buffer.
• src_len je délka zdrojového bufferu v bajtech.

Vrací:

• Při úspěchu hodnota entropie v milibitech (0-8000).
• -1 v případě, že je zdrojový buffer neplatný.

Nastaví vlastní značku pro reporting v Network Analytics. Značka se zobrazí spolu se vzorkem paketu v dashboardu Network Analytics. Ve výchozím nastavení se pakety vzorkují v poměru 1/10,000. Během jednoho spuštění programu se nastaví jen jedna značka. Pokud spuštění programu volá set_network_analytics_tag vícekrát, na vzorek paketu se použije hodnota posledního tagu.

int set_network_analytics_tag(uint64_t tag);

Argumenty:

• tag je hodnota tagu, která se má nastavit. Výchozí hodnota je 0 v případě, že hodnota není nastavena.

Vrací: 0 při úspěchu.

Převede 16bitové celé číslo ze síťového pořadí bajtů na pořadí bajtů hostitele.

uint16_t ntohs(uint16_t netshort);

Argumenty:

• netshort je 16bitová hodnota v síťovém pořadí bajtů.

Vrací: Hodnota v pořadí bajtů hostitele.

Převede 16bitové celé číslo z pořadí bajtů hostitele na síťové pořadí bajtů.

uint16_t htons(uint16_t hostshort);

Argumenty:

• hostshort je 16bitová hodnota v pořadí bajtů hostitele.

Vrací: Hodnota v síťovém pořadí bajtů.

Převede 32bitové celé číslo ze síťového pořadí bajtů na pořadí bajtů hostitele.

uint32_t ntohl(uint32_t netlong);

Argumenty:

• netlong je 32bitová hodnota v síťovém pořadí bajtů.

Vrací: Hodnota v pořadí bajtů hostitele.

Převede 32bitové celé číslo z pořadí bajtů hostitele na síťové pořadí bajtů.

uint32_t htonl(uint32_t hostlong);

Argumenty:

• hostlong je 32bitová hodnota v pořadí bajtů hostitele.

Vrací: Hodnota v síťovém pořadí bajtů.

Převede 64bitové celé číslo ze síťového pořadí bajtů na pořadí bajtů hostitele.

uint64_t ntohll(uint64_t netlonglong);

Argumenty:

• netlonglong je 64bitová hodnota v síťovém pořadí bajtů.

Vrací: Hodnota v pořadí bajtů hostitele.

Převede 64bitové celé číslo z pořadí bajtů hostitele na síťové pořadí bajtů.

uint64_t htonll(uint64_t hostlonglong);

Argumenty:

• hostlonglong je 64bitová hodnota v pořadí bajtů hostitele.

Vrací: Hodnota v síťovém pořadí bajtů.

Obecná struktura kontextu předávaná programu BPF.

struct cf_ebpf_generic_ctx {
   /* Pointer to the beginning of the context data. */
   uint64_t data;
   /* Pointer to the end of the context data. */
   uint64_t data_end;
   /* Space for the program to store metadata. */
   uint64_t meta_data;
};

Obsahuje nezpracovaná data paketu předaná programu BPF.

struct cf_ebpf_packet_data {
   /* Total length of the packet. */
   size_t   total_packet_length;
   /* Size of the IP header. Supports IPv4 (including options) and IPv6. */
   size_t   ip_header_length;
   /* Bytes of the packet, starting with the IP header. */
   uint8_t  packet_buffer[1500];
};

Obsahuje ukazatele na parsované hlavičky IP a UDP. Plní se voláním parse_packet_data.

struct cf_ebpf_parsed_headers {
   /* Pointer to the parsed IPv4 header, if present (otherwise null). */
   struct iphdr   *ipv4;
   /* Pointer to the parsed IPv6 header, if present (otherwise null). */
   struct ipv6hdr *ipv6;
   /* Pointer to the parsed UDP header. */
   struct udphdr  *udp;
   /* Raw pointer to the last valid byte of the packet context data. */
   uint8_t        *data_end;
};

Struktura hlavičky IPv4. Zdroj: Jádro Linuxu ↗.

struct iphdr {
#if defined(__BYTE_ORDER__) && __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__
    uint8_t  version:4,
             ihl:4;
#else
    uint8_t  ihl:4,
             version:4;
#endif
    uint8_t  tos;
    uint16_t tot_len;
    uint16_t id;
    uint16_t frag_off;
    uint8_t  ttl;
    uint8_t  protocol;
    uint16_t check;
    uint32_t saddr;
    uint32_t daddr;
};

Struktura hlavičky IPv6. Zdroj: Jádro Linuxu ↗.

struct ipv6hdr {
#if defined(__BYTE_ORDER__) && __BYTE_ORDER__ == __ORDER_BIG_ENDIAN__
    uint8_t  version:4,
             priority:4;
#else
    uint8_t  priority:4,
             version:4;
#endif
    uint8_t  flow_lbl[3];
    uint16_t payload_len;
    uint8_t  nexthdr;
    uint8_t  hop_limit;
    uint8_t  saddr[16];
    uint8_t  daddr[16];
};

Struktura hlavičky UDP. Zdroj: Jádro Linuxu ↗.

struct udphdr {
    uint16_t source;
    uint16_t dest;
    uint16_t len;
    uint16_t check;
};

Program nahrajete v dashboardu Cloudflare v části Networking > L3/4 DDoS protection > Advanced Protection. Potom vyberte kartu Programmable Flow Protection.

V části Programy, klikněte na tlačítko "Upload new program." Zobrazí se výzva k výběru souboru, který nahrajete se svým C zdrojový kód.

Rozhraní Cloudflare API obdrží zdrojový kód v C souboru, zkompilujte jej do bajtkódu BPF a spusťte na něj verifikátor.

Pokud kompilace nebo ověření selže, API vrátí podrobnou chybovou zprávu.

Pokud kompilace a ověření proběhnou úspěšně, Cloudflare uloží k účtu zdrojový kód i objektový soubor a vrátí ID programu.

Při vývoji se vám může hodit aktualizovat stále stejný program (identifikovaný stejným program ID) místo toho, abyste opakovaně vytvářeli nové programy jako nové zdroje.

Program aktualizujete kliknutím na tři tečky vedle něj. Poté vyberte Overwrite. Zobrazí se výzva k výběru souboru, který nahrajete jako C zdrojový kód.

Všechny nahrané programy i stav jejich nasazení najdete v tabulce v sekci Programy.

Ikona odkazu vedle názvu programu značí, že program se právě používá v aktivním pravidle a nelze jej smazat.

Chcete-li program odstranit, vyberte tři tečky vedle programu, který chcete odstranit. Potom vyberte Smazat.

Program, na který odkazuje aktivní Rule, nelze smazat.

Programy se stavem "failed" (tedy ty, které se nepodařilo zkompilovat nebo neprošly ověřením) se po 30 dnech nečinnosti automaticky a trvale smažou.

Na každý paket se uplatní jen jedno pravidlo. Pokud máte v účtu nakonfigurováno více pravidel, použije se pravidlo s nejkonkrétnějším rozsah spustí. Například pravidlo s rozsahem konkrétního colo má přednost před pravidlem s rozsahem regionu a to má přednost před globálním pravidlem. Proto nemůžete vytvořit více než jedno globální pravidlo.

Pravidla a jejich ID zobrazíte v Sítě > Ochrana před DDoS na vrstvě L3/4 > Advanced Protection v dashboardu Cloudflare. Poté vyberte Programmable Flow Protection.

Chcete-li vytvořit pravidlo, přejděte do Sítě > Ochrana před DDoS na vrstvě L3/4 > Advanced Protection v dashboardu Cloudflare. Poté vyberte Programmable Flow Protection.

V části Pravidla, vyberte Vytvořit pravidlo. Vyplňte příslušná pole nového pravidla. Budete vyzváni k výběru programu, režimu a rozsahu pravidla.

Existující pravidlo upravíte v sekci Rules. Klikněte na tři tečky vedle pravidla a vyberte Úprava.

Systém vás vyzve k úpravě režimu a rozsahu pravidla. Program pravidla upravit nelze, protože takový způsob zavádění změn není bezpečný.

Chcete-li odstranit existující pravidlo, přejděte do sekce Rules. Klikněte na tři tečky vedle pravidla a vyberte Smazat.

Tento koncový bod API ladí program na základě těchto vstupů:

• Místní cesta ke vstupnímu souboru PCAP předanému jako požadovaná data v binárním formátu. Vstupní soubor PCAP smí mít nejvýše 5 MB, větší soubory budou odmítnuty.
• ID programu uvedené v cestě požadavku.
• Volitelný parametr dotazu ip_offset=<value> k určení IP offsetu. Jde o počet bajtů, o které je IP hlavička posunuta v každém paketu vstupního souboru PCAP. Pokud parametr dotazu ip offset vynecháte, API správnou hodnotu offsetu odhadne. Pokud například soubor PCAP zachycuje ethernetové pakety, zjištěná hodnota IP offsetu bude 14. Tento endpoint předpokládá, že všechny pakety v souboru PCAP mají stejnou hodnotu IP offsetu, jinak je zpracuje nesprávně.

Tento koncový bod spustí odkazovaný program BPF nad vstupním souborem PCAP a vytvoří nový soubor PCAP s anotacemi. Výstupní soubor PCAP obsahuje přesně stejné pakety jako vstupní soubor a navíc verdikt programu zapsaný v Packet Comment sekci každého paketu.

curl "https://api.cloudflare.com/client/v4/accounts/$ACCOUNT_ID/magic/programmable_flow_protection/configs/programs/$PROGRAM_ID/pcap" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
--header "Content-Type: application/vnd.tcpdump.pcap" \
--data-binary "@<PATH_TO_INPUT_PCAP_FILE>" \
--output output.pcap

Anotace Packet Comment může obsahovat:

• Návratová hodnota programu: CF_EBPF_PASS nebo CF_EBPF_DROP
• Ignored: pokud příchozí paket není UDP
• Analytics tag: vlastní značka network analytics, kterou program tomuto paketu přiřadil, pokud nějakou přiřadil

Výstupní soubor PCAP může dále obsahovat:

• Challenge packet: paket s výzvou, který program odeslal zpět klientovi, pokud nějaký vznikl

Programy budete chtít nasazovat a testovat bezpečně, bez dopadu na stávající produkční provoz. Při prvním nasazení se nabízí nastavit pravidlo s globálním rozsahem na disabled a nastavte pravidlo s rozsahem colo nebo region na monitoring s filtrovacím výrazem, který se vztahuje jen na určitou podmnožinu IP provozu.

Každý region nebo colo Cloudflare použije nejgranulárnější pravidlo. Ve výše popsaném scénáři tedy colo nebo regiony uvedené v monitoring pravidlo spustí vývojářský program v monitoring režimu, zatímco všechny ostatní lokality Cloudflare program vůbec nespustí. monitoring pravidlo by se spustilo pouze na provoz odpovídající výrazu filtru.

Poté, co si správné chování ověříte v Network Analytics, můžete aktualizovat a rozšířit monitoring pravidla rozsah a výraz filtru. Nakonec můžete smazat disabled a monitoring pravidla a použít globální enabled pravidlo.

Pomocí Expression k omezení programů na podmnožinu IP adres nebo prefixů a Mode k určení, zda program pakety skutečně zahazuje, zajišťuje bezpečné a jemně odstupňované zavádění programu.

Provoz procházející přes Programmable Flow Protection najdete v Network Analytics dashboardu.

V dashboardu Network Analytics vyberte Programmable Flow Protection kartu použijte k filtrování provozu podle této funkce. Provoz lze filtrovat podle ID programu, vlastních tagů network analytics, akcí, IP adres a portů. Ve výchozím nastavení se pakety vzorkují v poměru 1/10,000.