guard/xdp/hooks/hook_api.h
loki5512344 14dcaccdbf
fix(xdp): correct payload length, attach/detach, whitelist and ban upkeep
BPF program (the first two made the filter wrong on real hardware):
- Compute the TCP payload length from ip->tot_len (IPv4) / payload_len
  (IPv6) instead of data_end. Ethernet padding on a real NIC added 6 bogus
  payload bytes, broke expected_seq and dropped every connection after the
  fourth segment. scripts/xdp_pkt_test.sh reproduces it on synthetic frames
  and fails against the old code.
- Read map values (conn->fails, sent_at) before bpf_map_delete_elem; the LRU
  element is freed by the delete.
- Parse up to two VLAN/QinQ tags before L3; fragments are checked against the
  blacklist and passed instead of bypassing all filtering; first fragments are
  no longer dropped.
- Unknown non-SYN flows PASS: the program is a stateless filter fed by the
  conntrack state machine, not a firewall, so spoofed SYNs cannot evict
  established flows into a drop and replies to the daemon's own outbound TCP
  keep working.
- Reset conn->fails on in-order segments, honour SYN payload (TFO), fix the
  IPv6 SYN-ACK address swap, count every DROP path, drop SYN with IP options.
- Expired prefix bans are no longer deleted with the wrong LPM key; userspace
  reaps them with the exact key.

Loader:
- Remember the effective attach flags (native vs generic) and use them for
  detach/query, verifying the interface is clean afterwards. The old code
  always detached the native slot, leaving a generic program attached after
  shutdown.
- DetachGuard rolls back the attach if anything after it fails.
- ban_cidr validates the prefix length and masks host bits.
- Whitelist maps (v4 and the new v6 LPM trie) are populated from the config at
  startup and fail fast on error.
- Stats read all 13 counters, and a test asserts every map's key/value size
  against the Rust encodings.

Tests: xdp_pkt_test (padding, VLAN/QinQ, fragments), xdp_loader (attach flags,
rollback, detach), xdp_ban_keys, xdp_whitelist_keys, xdp_services, live
xdp_attach_smoke (ignored, needs root).
2026-11-16 12:06:05 +01:00

159 lines
5.4 KiB
C

#ifndef RAMPART_HOOK_API_H
#define RAMPART_HOOK_API_H
/**
* Rampart protocol-hook contract.
*
* The universal XDP filter is protocol-agnostic: it validates L2/L3/L4,
* tracks the TCP handshake (SYN_RECEIVED to ESTABLISHED) and applies the
* blacklist, whitelist and throttle policy. Only then does it delegate deep
* payload inspection to an optional protocol hook.
*
* What the hook sees
* ------------------
*
* proto_hook() is called only when all of the following hold:
*
* - the packet is TCP and its destination port is inside the protected
* range;
* - the connection passed the SYN throttle and completed the 3-way
* handshake (state == STATE_ESTABLISHED);
* - the segment carries a non-zero payload.
*
* Pure SYN, SYN-ACK and ACK segments never reach the hook, so a hook
* physically cannot block a clean TCP handshake. Empty ACKs never reach it
* either: keep-alives pass untouched.
*
* Arguments:
*
* struct cursor bounds-checked window over the TCP payload, where pos is
* the first payload byte and end is one past the last byte
* of the payload as declared by the IP header, capped by
* data_end (Ethernet padding is never part of the window).
* struct pkt_meta read-only metadata: the 4-tuple (ports in host byte
* order), payload length, the full TCP flags byte and the
* L3 family.
*
* Verdicts
* --------
*
* XDP_PASS accept the segment; the filter advances expected_seq by the
* consumed payload length and keeps the conntrack entry.
* XDP_DROP drop the segment and tear down the conntrack entry.
*
* Any other verdict (XDP_ABORTED and friends) is treated as XDP_PASS, so
* returning it is never useful.
*
* Rules for hook implementations
* ------------------------------
*
* 1. Never block handshake traffic. That is guaranteed by the design
* above; do not work around it either.
* 2. Bounded loops only. Every loop needs a compile-time-constant trip
* count, or must be provably bounded for the verifier, and total
* complexity must stay low so the program still loads when unrolled.
* 3. Every cursor advance must be bounds-checked against c->end via
* cursor_take(). Reading past c->end is forbidden even when it looks
* in-bounds in the packet.
* 4. Do not update the conntrack, throttle or blacklist maps from the
* hook. Emit events through push_event() instead (ring buffer, may
* fail silently).
* 5. Keep the hook stateless per call. All per-connection state lives in
* conntrack_map, which belongs to the core filter.
*
* How to attach a hook
* --------------------
*
* 1. Create hooks/<proto>_hook.h containing only your own includes
* (common.h etc.) and a definition of proto_hook(). Never include
* hook_api.h from the hook header, because the core includes it for
* you:
*
* // hooks/myproto_hook.h
* #include "../core/common.h"
* static __always_inline enum xdp_action
* proto_hook(struct cursor *c, struct pkt_meta *m)
* {
* ... parse m, advance c ...
* return XDP_PASS; // or XDP_DROP
* }
*
* 2. Build the object with the macro pointing at your header:
*
* clang -O2 -g -target bpf \
* -DRAMPART_PROTO_HOOK='"../hooks/myproto_hook.h"' \
* -c xdp/core/universal_filter.c -o universal_filter.o
*
* Without RAMPART_PROTO_HOOK the default no-op stub defined below is used,
* and every established connection passes.
*/
#include <linux/bpf.h>
#include "../core/common.h"
/**
* Bounds-checked cursor over the payload window.
*
* A plain pointer pair, so the hook can hand it to cursor_take() without
* extra state to keep in sync.
*/
struct cursor {
__u8 *pos; // next unparsed byte
__u8 *end; // one past the last payload byte (IP length capped by data_end)
};
/**
* Take n bytes from the cursor.
*
* @param c cursor to advance
* @param n number of bytes the caller intends to read
* @return pointer to the claimed bytes, or NULL when they would overrun
* c->end
*/
static __always_inline __u8 *cursor_take(struct cursor *c, __u32 n)
{
if (c->pos + n > c->end)
return NULL;
barrier_var(c->pos);
__u8 *p = c->pos;
c->pos += n;
return p;
}
/**
* Read-only packet metadata handed to the hook.
*
* Addresses stay in network byte order and ports are converted to host order,
* so a hook can compare ports directly but must byte-swap addresses before
* printing them.
*/
struct pkt_meta {
__u32 src_ip; // IPv4 addr, or low 32 bits of IPv4-mapped IPv6
__u32 dst_ip; // same convention as src_ip
__u16 src_port; // host byte order
__u16 dst_port; // host byte order
__u16 payload_len; // TCP payload bytes in this segment
__u8 tcp_flags; // full 13th-byte flags field
__u8 is_ipv6; // 1 if L3 is IPv4-mapped IPv6
};
#ifdef RAMPART_PROTO_HOOK
#include RAMPART_PROTO_HOOK
#else
/**
* Default hook stub.
*
* Performs no deep inspection, so every established connection passes.
*
* @param c payload cursor (unused)
* @param m packet metadata (unused)
* @return always XDP_PASS
*/
static __always_inline enum xdp_action
proto_hook(struct cursor *c, struct pkt_meta *m)
{
return XDP_PASS;
}
#endif /* RAMPART_PROTO_HOOK */
#endif /* RAMPART_HOOK_API_H */