How Suricata Dissects Network Packets: Deep Dive into Ethernet, IP, TCP/UDP Headers

Overview of Suricata Packet Decoding

Suricata is a free, open‑source, high‑performance network intrusion detection engine. After introducing its installation and operation in a previous article, this piece focuses on the protocol‑parsing process, walking through each OSI layer from the physical Ethernet frame up to the application payload.

Ethernet Frame Header

The Ethernet frame consists of a 14‑byte header containing destination MAC (6 bytes), source MAC (6 bytes), and EtherType (2 bytes) that indicates the next protocol (e.g., 0x0800 for IPv4). The frame also includes a checksum (FCS) for integrity verification.

IP Datagram Header

An IPv4 header is 20 bytes long (without options) and contains fields such as version, header length, differentiated services, total length, identification, flags, fragment offset, TTL, protocol, header checksum, source address, destination address, optional fields, and padding. These fields enable routing, fragmentation handling, and protocol identification for the transport layer.

TCP Segment Header

The TCP header is fixed at 20 bytes and includes source port, destination port, sequence number, acknowledgment number, data offset, reserved bits, flags, window size, checksum, urgent pointer, and optional fields (must be a multiple of 4 bytes). These fields support reliable, ordered delivery and flow control.

UDP Datagram Header

The UDP header is 8 bytes long and contains source port, destination port, length, and checksum, providing a lightweight transport for connectionless communication.

Decoding Flow in Suricata Source Code (v7.0.0)

The decoding starts at functions prefixed with Decode. For Ethernet frames, DecodeLinkLayer is the entry point, handling LINKTYPE_ETHERNET packets. The Ethernet header structure is defined as:

typedef struct EthernetHdr_ {
    uint8_t eth_dst[6];   // destination MAC
    uint8_t eth_src[6];   // source MAC
    uint16_t eth_type;    // EtherType
} __attribute__((__packed__)) EthernetHdr;

After extracting the EtherType, Suricata determines the next protocol (e.g., IPv4) and parses the corresponding header. The IPv4 header is defined as:

typedef struct IPV4Hdr_ {
    uint8_t ip_verhl;   /**< version & header length */
    uint8_t ip_tos;     /**< type of service */
    uint16_t ip_len;    /**< total length */
    uint16_t ip_id;     /**< identification */
    uint16_t ip_off;    /**< fragment offset */
    uint8_t ip_ttl;     /**< time to live */
    uint8_t ip_proto;   /**< protocol (TCP, UDP, etc.) */
    uint16_t ip_csum;   /**< header checksum */
    union {
        struct {
            struct in_addr ip_src; /**< source address */
            struct in_addr ip_dst; /**< destination address */
        } ip4_un1;
        uint16_t ip_addrs[4];
    } ip4_hdrun1;
} IPV4Hdr;

From the IP header, Suricata reads the ip_proto field to dispatch to either the TCP or UDP decoder. The TCP and UDP decoders similarly extract their respective header fields and then pass the remaining payload to the application‑layer detection function AppLayerProtoDetectGetProto, which matches the payload against known protocols.

Conclusion

The article provides a step‑by‑step walkthrough of how Suricata translates raw network bytes into structured protocol headers, illustrating the correspondence between wire‑format diagrams and the actual C structures used in the engine. Understanding this flow is essential for extending Suricata, debugging parsing issues, or developing custom detection rules.