可编程流量防护是一种 DDoS 防护系统,可防御针对自定义或标准化第 7 层、基于 UDP 协议的 DDoS 攻击,例如游戏协议、金融服务协议、VoIP、电信和流媒体协议。从网络拓扑来看,它支持非对称和对称配置,但只会检查入站流量。
可编程流量防护目前处于封闭测试阶段,仅作为 Magic Transit(BYOIP或 Cloudflare 租用 IP)服务的附加组件提供。若要启用该系统,请联系你的客户团队或填写此表单 ↗。
可编程流量防护系统允许你使用 C 编写并运行自己的有状态数据包层程序。该程序会作为扩展伯克利数据包过滤器 (eBPF) 程序,在 Cloudflare 全球任播网络的用户空间中运行。eBPF 程序 ↗是一种数据包过滤系统,开发者可用它编写高性能的自定义网络逻辑。
可编程流量防护会检查并解析基于 UDP 的应用协议(深度数据包检查),并根据你的程序决定数据包的处理结果。利用自定义程序逻辑,你可以允许授权用户通过,同时主动阻止攻击。
该系统基于 flowtrackd 平台构建,这是 Cloudflare 的有状态缓解平台。可编程流量防护系统依赖 DDoS Advanced Protection 系统的常规设置运行。它会遵循你选择通过 Advanced Protection 系统路由的前缀以及允许列表。必须启用 Advanced DDoS Protection 系统,可编程流量防护才能运行。
在测试阶段,Cloudflare 将协助并指导用户编写自己的代码。之后可能会为常见游戏协议和 VoIP 协议提供开箱即用的代码片段(模板)。
为帐户启用可编程流量防护后,请在 Cloudflare 控制面板中前往 Networking > L3/4 DDoS Protection > Advanced Protection。然后在 Programmable Flow Protection 标签页中:
-
上传使用 C 编写的 eBPF 程序。
系统会验证程序并将其存储在帐户中。API 会先编译程序,然后对编译结果运行验证器,以执行内存检查并确认程序会终止。如果程序编译或验证失败,Cloudflare 控制面板会返回详细错误消息。
-
创建一条规则
-
若要观察程序行为,请检查 Network Analytics 控制面板,并选择 Programmable Flow Protection 标签页。
你可以创建其他规则,使用不同的规则设置,并限定范围到不同区域和 Cloudflare 位置,以更改模式(缓解或监控),从而适应流量模式和业务场景。
可编程流量防护系统支持数据本地化套件。
以下步骤将编写一个示例程序,用于丢弃所有带 IPv6 标头的用户数据报协议 (UDP) 流量。该程序还会丢弃发往端口 66 的流量,以及 UDP 负载中不包含特定自定义应用标头值的流量。
-
添加 define 指令,以指定正在使用的版本化辅助函数。
随着 Cloudflare 为可编程流量防护 API 添加更多功能,我们会发布 API 的新版本。这些版本保证向后兼容。
#define CF_EBPF_HELPER_V0 -
包含 Cloudflare eBPF 头文件。
这些文件提供了辅助函数,用于解析传递给 BPF 程序的输入数据包。
#include <cf_ebpf_defs.h> #include <cf_ebpf_helper.h> -
定义数据包处理的入口函数。
程序必须使用以下精确的函数签名,才能通过 Cloudflare 的程序验证。
返回类型
uint64_t决定 Cloudflare 将通过还是丢弃数据包。函数名cf_ebpf_main是程序的入口点。参数void *state指的是 Cloudflare 作为输入传递给 BPF 程序的数据。uint64_t cf_ebpf_main(void *state) -
将输入参数转换为可用的结构体。
将输入数据转换为
cf_ebpf_generic_ctx,该结构会告知 Cloudflare 正在读取的内存数据边界。然后声明用于解析数据的变量。
cf_ebpf_parsed_headers将包含 IPv4、IPv6 和 UDP 标头。cf_ebpf_packet_data将保存 Cloudflare 收到的原始 IP 数据包副本(最大 1,500 字节),以及数据包长度和 IP 标头长度。struct cf_ebpf_generic_ctx *ctx = state; struct cf_ebpf_parsed_headers headers; struct cf_ebpf_packet_data *p; -
调用辅助函数填充变量。
必须调用辅助函数
parse_packet_data来填充变量。Cloudflare 已在第 2 步包含的头文件中提供此函数。parse_packet_data函数会执行通过程序验证器所需的内存检查。parse_packet_data成功时返回0。如果成功,输入参数会正确填充。parse_packet_data失败时返回1。如果parse_packet_data失败,程序必须返回CF_EBPF_DROP丢弃数据包,才能通过验证器。if (parse_packet_data(ctx, &p, &headers) != 0) { return CF_EBPF_DROP; }成功解析后可用的值:
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]; }; 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; };有关辅助函数和结构体的完整定义,请参阅 BPF 辅助函数和结构体。
-
编写自定义逻辑。
前面的步骤已经确立了所有程序都通用的代码部分,与程序逻辑无关。
现在,你可以编写自己的自定义逻辑。
在下面的示例代码段中,如果数据包带有 IPv6 标头或 UDP 目标端口为 66,程序就会丢弃该数据包。
随后,程序会检查 UDP 负载中的应用标头值,并验证其最后一个字节是否为固定值
0xCF。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; } -
返回
CF_EBPF_PASS,放行未被程序逻辑丢弃的数据包。当前支持的返回值包括:
CF_EBPF_PASS = return value 0CF_EBPF_DROP = return value 1
将程序上传到 API 时运行的验证器会确保程序只返回已知值类型。
return CF_EBPF_PASS;
以下示例展示了完整的基础程序:
#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;
}下面的示例程序使用辅助函数,在来自同一源 IP 的数据包之间维护状态,实现基于 UDP 的质询响应机制。此机制要求客户端先证明自己能够接收并响应质询,之后才允许其流量通过,因此适用于缓解 DDoS 攻击。
质询机制的工作方式如下:
来自未知源 IP 的数据包到达时,程序会生成包含随机 nonce 的质询数据包,并在状态表中将该源 IP 标记为“已质询”。原始数据包会被丢弃。
如果数据包来自已受质询的源 IP,程序会检查其中是否包含正确的质询响应(nonce 与密钥值进行 XOR 运算后的结果)。响应正确时,源 IP 会标记为“已验证”。响应错误时,源 IP 会立即加入阻止列表。
来自已验证源 IP 的数据包无需进一步检查即可通过。
-
包含 Cloudflare eBPF 头文件并定义辅助函数版本。
#define CF_EBPF_HELPER_V0 #include <cf_ebpf_defs.h> #include <cf_ebpf_helper.h> -
为质询响应协议定义常量。
质询响应通过将 nonce 与密钥值进行 XOR 运算来计算。过期时间决定已质询或已验证状态的有效时长。
#define CHALLENGE_SECRET 0xDEADBEEFCAFEBABEULL #define CHALLENGE_EXPIRY_SECS 60 #define VERIFIED_EXPIRY_SECS 3600 -
为质询数据包定义结构。
质询数据包包含客户端必须响应的 nonce,以及用于存放客户端响应的空间。
struct challenge_packet { uint64_t nonce; // Random nonce for this challenge uint64_t response; // Expected: nonce XOR CHALLENGE_SECRET }; -
定义入口函数并解析数据包。
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; -
使用
get_src_ip_status检查源 IP 状态。状态表示源 IP 是新的、已质询、已验证还是已列入阻止列表。过期时间戳表示状态何时过期。
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) { // Status expired, treat as new connection ret = -1; } -
处理已验证的源 IP。
调用程序之前,可编程流量防护平台会丢弃来自阻止列表中 IP 的数据包。无需显式处理已阻止的情况。
如果源 IP 已通过先前的质询完成验证,则允许数据包通过。
if (ret == 0 && status == CF_EBPF_SRC_IP_STATUS_VERIFIED) { return CF_EBPF_PASS; } -
检查来自已受质询源 IP 的数据包是否为质询响应。
如果源 IP 之前已受质询,请检查当前数据包是否包含有效的质询响应。响应正确时,将源 IP 标记为已验证;响应错误时,立即将源 IP 加入阻止列表。
if (ret == 0 && status == CF_EBPF_SRC_IP_STATUS_CHALLENGED) { // Get the stored nonce from user data uint64_t stored_nonce; if (get_src_ip_data(&stored_nonce) != 0) { return CF_EBPF_DROP; } // Parse the challenge response from the packet payload struct challenge_packet *resp = (struct challenge_packet *)(udp_hdr + 1); if ((uint8_t *)(resp + 1) > headers.data_end) { return CF_EBPF_DROP; } // Verify the response: should be nonce XOR secret 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); // Clear the nonce return CF_EBPF_PASS; } // Wrong response - blocklist immediately set_src_ip_status(CF_EBPF_SRC_IP_STATUS_BLOCKLISTED, 0); return CF_EBPF_DROP; } -
向新的源 IP 发出质询。
生成随机 nonce,将其存储在状态表中,创建质询数据包,并使用
set_challenge发送。// Generate a new challenge for this source IP uint64_t nonce = rand(); // Store the nonce and mark as challenged set_src_ip_status(CF_EBPF_SRC_IP_STATUS_CHALLENGED, CHALLENGE_EXPIRY_SECS); set_src_ip_data(nonce); // Build the challenge packet to send back struct challenge_packet challenge; challenge.nonce = nonce; challenge.response = 0; // Client will fill this in // Set the challenge packet buffer set_challenge((uint8_t *)&challenge, sizeof(challenge)); // Drop the original packet until client responds to challenge return CF_EBPF_DROP; }
以下示例展示了完整的复杂程序:
#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;
}此程序展示了几个关键概念:
- 状态管理:使用
get_src_ip_status、set_src_ip_status、get_src_ip_data和set_src_ip_data跟踪每个源 IP 的质询状态。 - 发送质询:使用
set_challenge向客户端发送质询数据包。 - 加密验证:使用共享密钥验证客户端是否正确响应质询。
- 过期处理:使用时间戳使过期的状态条目失效。
下面的示例程序使用固定窗口算法,为每个源 IP 实现速率限制。通过限制单个源 IP 在一个时间窗口内可以发送的数据包数量,此机制有助于缓解大流量 DDoS 攻击。
速率限制机制的工作方式如下:
收到数据包时,程序会读取该源 IP 的存储状态。状态包含窗口起始时间戳和数据包计数器,并打包到一个 64 位值中。如果当前时间仍处于该窗口内,计数器就会递增。计数器超过配置上限时,数据包会被丢弃。窗口过期后,计数器会重置。
-
包含 Cloudflare eBPF 头文件并定义辅助函数版本。
#include <cf_ebpf_defs.h> #define CF_EBPF_HELPER_V0 #include <cf_ebpf_helper.h> -
为速率限制配置定义常量。
RATE_LIMIT设置每个窗口允许的数据包最大数量。WINDOW_SECONDS定义每个时间窗口的秒数。#define RATE_LIMIT 100 // Maximum packets allowed per window #define WINDOW_SECONDS 60 // Time window in seconds -
定义用于打包和解包状态数据的宏。
源 IP 状态表会为每个源 IP 存储一个
u64值。若要同时跟踪时间戳和计数器,请将二者打包到此值中:时间戳放在高 32 位,计数器放在低 32 位。#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; -
读取此源 IP 的现有状态。
使用
get_src_ip_data查询之前是否见过此源 IP。// 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; -
处理新源 IP 的情况。
如果没有条目(返回值为
-1),说明这是此源 IP 发来的第一个数据包。将窗口初始化为从当前时间开始,计数器设为 1。if (ret == -1) { // No existing entry - first packet from this IP // Initialize: window starts now, counter = 1 window_start = now_secs; counter = 1; } -
处理已有源 IP 并检查时间窗口。
如果存在条目,则解包存储的时间戳和计数器。窗口过期时,重置这两个值;否则递增计数器并检查是否超过速率上限。
} 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 return CF_EBPF_DROP; } } } -
存储更新后的状态并放行数据包。
将窗口起始时间戳和计数器重新打包为单个值,并存入源 IP 状态表。
// Store updated state uint64_t new_data = PACK_STATE(window_start, counter); set_src_ip_data(new_data); return CF_EBPF_PASS; }
以下示例展示了完整的速率限制程序:
#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;
}此程序展示了几个关键概念:
- 位打包:使用位移将多个值(时间戳和计数器)存储在单个
u64中。 - 固定窗口速率限制:跟踪离散时间窗口内的数据包计数,并在窗口过期时重置。
- 优雅处理错误:辅助函数失败时放行数据包,避免边缘情况下出现误报。
- 状态表行为:源 IP 状态表是 LRU 缓存。达到容量后,会逐出旧条目。条目闲置一小时后也会被垃圾回收。
每个程序都可以访问自己的本地状态。状态仅存储在各服务器本地,不会在数据中心之间共享。
状态与特定程序版本绑定。如果修改规则模式(禁用、监控或启用),状态表中的内容会保留。但如果将规则移到另一个程序或程序版本,状态表就会清空。
程序可以使用两种状态表。
源 IP 状态表按源 IP 地址作为键存储状态。每个条目包含:
| 字段 | 类型 | 说明 |
|---|---|---|
| 状态 | 枚举 | 源 IP 的状态:None(0)、Challenged(1)、Verified(2)或 Blocklisted(3)。 |
| 用户数据 | u64 |
可用于任意用途的自定义值。 |
默认最大容量为 1,000 个条目。
使用以下辅助函数与此表交互:
get_src_ip_status— 获取当前数据包源 IP 的状态。set_src_ip_status— 设置当前数据包源 IP 的状态。get_src_ip_data— 获取当前数据包源 IP 的用户数据。set_src_ip_data— 为当前数据包源 IP 存储用户数据。
以下情况下会在源 IP 状态表中创建条目:
- 程序调用
set_src_ip_status,将源 IP 标记为 Challenged、Verified 或 Blocklisted。 - 程序调用
set_src_ip_data,为源 IP 存储自定义 u64 数据。 - 程序为表中没有现有条目的新源 IP 调用
set_challenge。
流状态表使用四元组作为键存储状态:源 IP、源端口、目标 IP 和目标端口。每个条目包含一个可用于任意用途的 u64 值。
默认最大容量为 10,000 个条目。
使用以下辅助函数与此表交互:
get_flow_data— 获取当前流的用户数据。set_flow_data— 为当前流存储用户数据。
以下情况下会在流状态表中创建条目:
- 程序调用
set_flow_data,为某个流存储自定义 u64 数据。
两个状态表都是 LRU(最近最少使用)缓存。如果表达到最大容量,则会逐出最旧的条目以腾出空间。条目一小时内未被访问也会被垃圾回收。
辅助函数是 Cloudflare 运行时提供的函数,客户程序可以调用它。
辅助函数至关重要,因为 BPF 指令集架构 (ISA) 只支持特定系统调用。出于安全考虑,Cloudflare 只会使用预先确定的已知库列表编译 BPF 对象文件,程序开发者无法修改此列表。
辅助函数定义和验证器包装器源文件可在 GitHub ↗ 上查看。
根据 cf_ebpf_generic_ctx 和 cf_ebpf_packet_data 构造 cf_ebpf_parsed_headers。执行通过验证器所需的内存检查。
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
);参数:
ctx— 指向传递给 BPF 程序的通用上下文的指针。out_p— 用于接收数据包数据结构的指针。out_headers— 用于接收解析后标头结构的指针。
返回值: 成功时返回 0,失败时返回 1(例如数据包过短或长度无效)。成功时,out_headers 包含有效的 IP 和 UDP 标头指针。
生成随机无符号整数。
uint64_t rand(void);返回值: 随机的 uint64_t 值。
返回当前 UNIX 时间戳(自 1970 年 1 月 1 日 0:00:00 UTC 起经过的非闰秒数)。
int64_t timestamp(void);返回值: 当前时间戳,类型为 int64_t。
计算源缓冲区的 MD5 哈希,并将结果存储到目标缓冲区。
int hash_md5(uint8_t *src, size_t src_len, uint8_t *dest, size_t dest_len);参数:
src— 指向源缓冲区的指针。src_len— 源缓冲区的长度(字节)。dest— 指向目标缓冲区的指针(至少 16 字节)。dest_len— 目标缓冲区的长度(字节)。
返回值:
- 成功时返回正值(写入的字节数)。
- 源缓冲区无效时返回
-1。 - 目标缓冲区为空或过小时返回
-2。
计算源缓冲区的 SHA-256 哈希,并将结果存储在目标缓冲区中。
int hash_sha256(uint8_t *src, size_t src_len, uint8_t *dest, size_t dest_len);参数:
src— 指向源缓冲区的指针。src_len— 源缓冲区的长度(字节)。dest— 指向目标缓冲区的指针(必须至少为 32 字节)。dest_len— 目标缓冲区的长度(字节)。
返回值:
- 成功时返回正值(写入的字节数)。
- 源缓冲区无效时返回
-1。 - 目标缓冲区为空或过小时返回
-2。
计算源缓冲区的 SHA-512 哈希,并将结果存储在目标缓冲区中。
int hash_sha512(uint8_t *src, size_t src_len, uint8_t *dest, size_t dest_len);参数:
src— 指向源缓冲区的指针。src_len— 源缓冲区的长度(字节)。dest— 指向目标缓冲区的指针(必须至少为 64 字节)。dest_len— 目标缓冲区的长度(字节)。
返回值:
- 成功时返回正值(写入的字节数)。
- 源缓冲区无效时返回
-1。 - 目标缓冲区为空或过小时返回
-2。
计算源缓冲区的 CRC32 哈希,并将结果存储为 64 位整数。这是一个便利封装,会在内部处理字节到整数的转换。
int hash_crc32(uint8_t *src, size_t src_len, uint64_t *dest);参数:
src— 指向源缓冲区的指针。src_len— 源缓冲区的长度(字节)。dest— 指向用于接收 CRC32 结果的uint64_t的指针。
返回值:
- 成功时返回正值(内部写入的字节数,始终为 8)。
- 源缓冲区无效时返回
-1。 - 如果目标缓冲区为空,则返回
-2。
计算源缓冲区的 BLAKE2B-512 哈希,并将结果存储在目标缓冲区中。
int hash_blake2b512(const uint8_t *src, size_t src_len, uint8_t *dest, size_t dest_len);参数:
src— 指向源缓冲区的指针。src_len— 源缓冲区的长度(字节)。dest— 指向目标缓冲区的指针(必须至少为 64 字节)。dest_len— 目标缓冲区的长度(字节)。
返回值:
- 成功时返回正值(写入的字节数)。
- 源缓冲区无效时返回
-1。 - 目标缓冲区为空或过小时返回
-2。
计算源缓冲区的 HMAC-SHA256,并将结果存储在目标缓冲区中。私钥在平台级别配置,不会直接暴露给 BPF 程序。每台服务器、每个客户的密钥都唯一。
int hmac_sha256(uint8_t *src, size_t src_len, uint8_t *dest, size_t dest_len);参数:
src— 指向源缓冲区的指针。src_len— 源缓冲区的长度(字节)。dest— 指向目标缓冲区的指针(必须至少为 32 字节)。dest_len— 目标缓冲区的长度(字节)。
返回值:
- 成功时返回正值(写入的字节数)。
- 源缓冲区无效时返回
-1。 - 目标缓冲区为空或过小时返回
-2。
计算源缓冲区的 HMAC-SHA512,并将结果存储在目标缓冲区中。私钥在平台级别配置,不会直接暴露给 BPF 程序。每台服务器、每个客户的密钥都唯一。
int hmac_sha512(uint8_t *src, size_t src_len, uint8_t *dest, size_t dest_len);参数:
src— 指向源缓冲区的指针。src_len— 源缓冲区的长度(字节)。dest— 指向目标缓冲区的指针(必须至少为 64 字节)。dest_len— 目标缓冲区的长度(字节)。
返回值:
- 成功时返回正值(写入的字节数)。
- 源缓冲区无效时返回
-1。 - 目标缓冲区为空或过小时返回
-2。
计算源缓冲区的 BLAKE2B-512 HMAC,并将结果存储在目标缓冲区中。私钥在平台级别配置,不会直接暴露给 BPF 程序。每台服务器、每个客户的密钥都唯一。
int hmac_blake2b512(const uint8_t *src, size_t src_len, uint8_t *dest, size_t dest_len);参数:
src— 指向源缓冲区的指针。src_len— 源缓冲区的长度(字节)。dest— 指向目标缓冲区的指针(必须至少为 64 字节)。dest_len— 目标缓冲区的长度(字节)。
返回值:
- 成功时返回正值(写入的字节数)。
- 源缓冲区无效时返回
-1。 - 目标缓冲区为空或过小时返回
-2。
为当前数据包设置质询数据。使用此函数向客户端发回质询数据包。
int set_challenge(uint8_t *src, size_t src_len);参数:
src— 指向质询数据缓冲区的指针。src_len— 质询数据的字节长度。如果为0,则重置质询缓冲区。
返回值:
- 成功时返回
0。 - 如果源缓冲区无效或超过允许的最大大小,则返回
-4。 - 如果未启用质询,则返回
-5。 - 如果最近已向此源 IP 发送质询,或超过全局速率限制,则返回
-6。
从状态表中检索与源 IP 地址关联的状态值。
int get_src_ip_status(uint8_t *status, uint64_t *expiry);参数:
status— 用于接收状态值(CF_EBPF_SRC_IP_STATUS_CHALLENGED、CF_EBPF_SRC_IP_STATUS_VERIFIED或CF_EBPF_SRC_IP_STATUS_BLOCKLISTED)的指针。如果只需要到期时间,可以为空。expiry— 用于接收到期时间戳的指针。如果只需要状态,可以为空。
返回值:
- 成功时返回
0。 - 如果源 IP 不存在条目,则返回
-1。 - 如果当前数据包未设置源 IP 上下文,则返回
-2。 - 如果提供的缓冲区太小,则返回
-3。 - 如果
status和expiry都为空,则返回-4。 - 如果未启用源 IP 状态表,则返回
-5。
在状态表中设置与源 IP 地址关联的状态值。
int set_src_ip_status(uint8_t status, uint64_t expiry_secs);参数:
status— 要设置的状态值(CF_EBPF_SRC_IP_STATUS_CHALLENGED、CF_EBPF_SRC_IP_STATUS_VERIFIED或CF_EBPF_SRC_IP_STATUS_BLOCKLISTED)。expiry_secs— 状态在多少秒后到期。如果为0,状态永不过期。
返回值:
- 成功时返回
0。 - 如果当前数据包未设置源 IP 上下文,则返回
-2。 - 如果未启用源 IP 状态表,则返回
-5。
从状态表中检索与源 IP 地址关联的自定义数据。
int get_src_ip_data(uint64_t *data);参数:
data— 用于接收所存储数据值的指针。
返回值:
- 成功时返回
0。 - 如果源 IP 不存在条目,则返回
-1。 - 如果当前数据包未设置源 IP 上下文,则返回
-2。 - 如果提供的缓冲区太小,则返回
-3。 - 如果
data为空,则返回-4。 - 如果未启用源 IP 状态表,则返回
-5。
在状态表中存储与源 IP 地址关联的自定义数据。
int set_src_ip_data(uint64_t data);参数:
data— 要存储的数据值。
返回值:
- 成功时返回
0。 - 如果当前数据包未设置源 IP 上下文,则返回
-2。 - 如果未启用源 IP 状态表,则返回
-5。
从状态表中检索与当前流关联的自定义数据。
int get_flow_data(uint64_t *data);参数:
data— 用于接收所存储数据值的指针。
返回值:
- 成功时返回
0。 - 如果该流不存在条目,则返回
-1。 - 如果当前数据包未设置流上下文,则返回
-2。 - 如果提供的缓冲区太小,则返回
-3。 - 如果
data为空或未对齐,则返回-4。 - 如果未启用流状态表,则返回
-5。
在状态表中存储与当前流关联的自定义数据。
int set_flow_data(uint64_t data);参数:
data— 要存储的数据值。
返回值:
- 成功时返回
0。 - 如果当前数据包未设置流上下文,则返回
-2。 - 如果未启用流状态表,则返回
-5。
计算源缓冲区的香农熵。结果以毫比特返回,范围从 0(所有字节相同)到 8000(所有 256 个字节值均匀分布)。
int64_t entropy(uint8_t *src, size_t src_len);参数:
src— 指向源缓冲区的指针。src_len— 源缓冲区的长度(字节)。
返回值:
- 成功时返回以毫比特为单位的熵值(0-8000)。
- 源缓冲区无效时返回
-1。
为网络分析报告设置自定义标签。该标签会与数据包样本一起显示在网络分析仪表板中。默认情况下,数据包的采样率为 1/10,000。
每次程序执行只设置一个标签。如果程序执行多次调用 set_network_analytics_tag,最后一个标签值将应用于数据包样本。
int set_network_analytics_tag(uint64_t tag);参数:
tag— 要设置的标签值。未设置时默认为0。
返回: 成功时返回 0。
将 16 位整数从网络字节序转换为主机字节序。
uint16_t ntohs(uint16_t netshort);参数:
netshort— 采用网络字节序的 16 位值。
返回: 采用主机字节序的值。
将 16 位整数从主机字节序转换为网络字节序。
uint16_t htons(uint16_t hostshort);参数:
hostshort— 采用主机字节序的 16 位值。
返回: 采用网络字节序的值。
将 32 位整数从网络字节序转换为主机字节序。
uint32_t ntohl(uint32_t netlong);参数:
netlong— 采用网络字节序的 32 位值。
返回: 采用主机字节序的值。
将 32 位整数从主机字节序转换为网络字节序。
uint32_t htonl(uint32_t hostlong);参数:
hostlong— 采用主机字节序的 32 位值。
返回: 采用网络字节序的值。
将 64 位整数从网络字节序转换为主机字节序。
uint64_t ntohll(uint64_t netlonglong);参数:
netlonglong— 采用网络字节序的 64 位值。
返回: 采用主机字节序的值。
将 64 位整数从主机字节序转换为网络字节序。
uint64_t htonll(uint64_t hostlonglong);参数:
hostlonglong— 采用主机字节序的 64 位值。
返回: 采用网络字节序的值。
传递给 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;
};包含传递给 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];
};包含指向已解析 IP 和 UDP 标头的指针。通过调用 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;
};IPv4 标头结构。来源:Linux 内核 ↗。
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;
};IPv6 标头结构。来源:Linux 内核 ↗。
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];
};UDP 标头结构。来源:Linux 内核 ↗。
struct udphdr {
uint16_t source;
uint16_t dest;
uint16_t len;
uint16_t check;
};要上传程序,请在 Cloudflare 仪表板中转到 Networking > L3/4 DDoS protection > Advanced Protection。然后选择 Programmable Flow Protection 选项卡。
在 Programs 下,单击“Upload new program”按钮。系统会提示你选择包含 C 源代码的文件进行上传。
Cloudflare API 会接收 C 文件中的源代码,将其编译为 BPF 字节码,并对其运行验证器。
如果编译或验证失败,API 会返回详细的错误消息。
如果编译和验证成功,Cloudflare 会将源代码和目标文件存储到账户中,并返回程序 ID。
在开发过程中,与其反复创建新程序作为新资源,你可能会发现更新同一个程序(由相同程序 ID 标识)更方便。
要更新程序,请选择程序旁的三个点,然后选择 Overwrite。系统会提示你选择一个文件,作为 C 源代码上传。
每次更新都会创建新的程序版本。响应中的 version 字段标识当前版本。
更新程序时,规则仍固定到其现有的 program_version。要使用更新后的程序,请通过 API 使用新的 program_version 更新每条规则。
要查看所有已上传程序及其成功状态,请查看 Programs 部分下的表格。
程序名称旁的链接图标表示该程序当前正在活动规则中使用,可能无法删除。
要删除程序,请选择要删除的程序旁的三个点,然后选择 Delete。
请注意,无法删除活动规则所引用的程序。
请注意,状态为“failed”(表示编译或验证失败)的程序将在 30 天不活动后自动永久删除。
每个数据包只执行一条规则。如果账户配置了多条规则,则执行范围最具体的规则。例如,限定到特定 colo 的规则优先于限定到区域的规则,而区域规则又优先于全局规则。这就是无法创建多条全局规则的原因。
要查看规则及其关联的规则 ID,请在 Cloudflare 仪表板中转到 Networking > L3/4 DDoS protection > Advanced Protection。然后选择 Programmable Flow Protection。
要创建规则,请在 Cloudflare 仪表板中转到 Networking > L3/4 DDoS protection > Advanced Protection。然后选择 Programmable Flow Protection。
在 Rules 下,选择 Create rule。填写新规则的相应字段。系统会提示你选择规则的程序、模式和范围。
要更新现有规则,请转到 Rules 部分。单击规则旁的三个点,然后选择 Edit。
系统会提示你编辑规则的模式和范围。你不能编辑规则的程序,因为这是一种不安全的发布模式。
要删除现有规则,请转到 Rules 部分。单击规则旁的三个点,然后选择 Delete。
此 API 端点通过接收以下内容来调试程序:
- 作为请求数据以二进制格式提供的输入 PCAP 文件本地路径。输入 PCAP 文件大小上限为 5 MB,超过此限制的文件将被拒绝。
- 请求路径中提供的程序 ID。
- 可选查询参数
ip_offset=<value>,用于指定 IP 偏移量。该值表示输入 PCAP 文件中每个数据包的 IP 标头偏移字节数。 如果省略 ip offset 查询参数,API 会推测正确的偏移量。 例如,如果 PCAP 文件捕获的是以太网数据包,检测到的 IP 偏移量将为 14\。此端点假定 PCAP 中所有数据包的 IP 偏移量相同,否则将无法正确解析数据包。
此端点会针对输入 PCAP 运行指定的 BPF 程序,并输出新的注释 PCAP 文件。输出 PCAP 文件包含与输入文件完全相同的数据包,并且每个数据包的 Packet Comment 部分还会附带程序判定结果。
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.pcapPacket Comment 注释可能包含:
- 程序返回值:
CF_EBPF_PASS或CF_EBPF_DROP Ignored:如果传入的数据包不是 UDPAnalytics tag:程序在此数据包上设置的自定义网络分析标记(如有)
输出 PCAP 文件还可能包含:
Challenge packet:如果程序向客户端发送了质询数据包,则会包含该数据包
你需要在不影响现有生产流量的情况下安全地部署和测试程序。一种初始部署方式是将全局范围规则设为 disabled,并将 colo 或区域范围规则设为 monitoring,同时使用过滤表达式仅匹配部分 IP 流量。
每个 Cloudflare 区域或 colo 都会应用范围最精确的规则。因此,在上述场景中,monitoring 规则指定的 colo 或区域会以 monitoring 模式运行开发者程序,而其他 Cloudflare 位置则完全不会运行该程序。monitoring 规则只会处理符合过滤表达式的流量。
使用 Network Analytics 确认行为正确后,你可以更新并扩大 monitoring 规则的范围和过滤表达式。最后,可以删除 disabled 和 monitoring 规则,并应用全局 enabled 规则。
使用 Expression 字段将程序限制为部分 IP 或前缀,并使用 Mode 字段决定程序是否实际丢弃数据包,可确保程序上线时的安全性和精细控制能力。
流经 Programmable Flow Protection 的流量可在 Network Analytics 仪表板中查看。
在 Network Analytics 仪表板中,选择 Programmable Flow Protection 选项卡,以按此功能筛选流量。你可以按程序 ID、自定义 Network Analytics 标签、操作、IP 和端口筛选流量。默认情况下,数据包的采样率为 1/10,000。