[docs]: added documentation to conntracker functions

Author: LorenzoTettamanti

core/src/components/conntracker/src/data_structures.rs

@@ -3,6 +3,18 @@ use aya_ebpf::{
     maps::{LruPerCpuHashMap, PerfEventArray,HashMap},
 };
 
+// docs:
+// PacketLog structure used to track an incoming network packet
+// 
+// proto: packet protol (ex. TCP,UDP,ICMP)
+// src_ip: source address ip 
+// src_port: source address port
+// dst_ip: destination ip
+// dst_port: destination port
+// pid: kernel process ID
+//
+
+
 #[repr(C)]
 #[derive(Clone, Copy)]
 pub struct PacketLog {
@@ -14,7 +26,7 @@ pub struct PacketLog {
     pub pid: u32,
 }
 
-// This structure is only for active connections
+// This structure is only for active connections (TODO: investigate if this is really useful)
 #[repr(C)]
 #[derive(Clone, Copy)]
 pub struct ConnArray {
@@ -25,26 +37,50 @@ pub struct ConnArray {
     pub proto: u8,
 }
 
+
+// docs:
+// VethLog structure used to track virtual ethernet interfaces creation and deletion
+// 
+// name: veth name
+// state: socket state 
+// dev_addr: veth device addresses
+// event_type: creation or deletion
+// netns: veth network namespace
+// pid: kernel process ID
+//
+
 #[repr(C)]
 #[derive(Clone, Copy, Debug)]
 pub struct VethLog {
     pub name: [u8; 16],
-    pub state: u64, //state var type: long unsigned int
+    pub state: u64, // state var type: long unsigned int
     pub dev_addr: [u32; 8],
-    pub event_type: u8, //i choose 1 for veth creation or 2 for veth destruction
+    pub event_type: u8, // i choose 1 for veth creation or 2 for veth destruction
     pub netns: u32,
     pub pid: u32
 
 }
 
+// docs:
+//
+// BPF maps used in the conntracker programs 
+// 
+// VETH_EVENTS: PerfEventArray used in the veth_tracer functions (veth_tracer.rs module)
+//
+// BLOCKLIST: an hashmap used to block addresses -----> TODO: key and values are the same for semplicity but we need to 
+//            investigate the possibility to save the service name or the timestamp registered when the command was executed or a simple int index
+//
+
+
 #[map(name = "EventsMap", pinning = "by_name")]
 pub static mut EVENTS: PerfEventArray<PacketLog> = PerfEventArray::new(0);
 
-//TODO: ConnectionMap needs a rework after implementing issue #105
+// FIXME: this might be useless 
 #[map(name = "ConnectionMap")]
 pub static mut ACTIVE_CONNECTIONS: LruPerCpuHashMap<u16, ConnArray> =
     LruPerCpuHashMap::with_max_entries(65536, 0);
 
+// FIXME: this might be useless
 #[map(name = "ConnectionTrackerMap")]
 pub static mut CONNTRACKER: LruPerCpuHashMap<ConnArray, u8> =
     LruPerCpuHashMap::with_max_entries(65536, 0);

core/src/components/conntracker/src/main.rs

@@ -1,4 +1,5 @@
 // docs:
+//
 // This file contains the code for the identity service
 //  Functionalities:
 //      1. Creates a PacketLog structure to track incoming packets
@@ -31,35 +32,38 @@ use crate::tc::try_identity_classifier;
 use crate::veth_tracer::try_veth_tracer;
 use crate::tcp_analyzer::try_tcp_analyzer;
 
+
+// docs:
+//
+// virtual ethernet (veth) interface tracer:
+// This function is triggered when a virtual ethernet interface is created 
+//
+
 #[kprobe]
 pub fn veth_creation_trace(ctx: ProbeContext) -> u32 {
     match try_veth_tracer(ctx, 1) {
         Ok(ret_val) => ret_val,
         Err(ret_val) => ret_val.try_into().unwrap_or(1),
     }
 }
-#[kprobe]
-pub fn veth_deletion_trace(ctx: ProbeContext) -> u32 {
-    match try_veth_tracer(ctx, 2) {
-        Ok(ret_val) => ret_val,
-        Err(ret_val) => ret_val.try_into().unwrap_or(1),
-    }
-}
 
-// docs;
-// this kprobe retrieves pid data and task id of an incoming packet
+// docs:
+//
+// virtual ethernet (veth) interface tracer:
+// This function is triggered when a virtual ethernet interface is deleted 
+//
 
 #[kprobe]
-pub fn tcp_message_tracer(ctx: ProbeContext) -> u32 {
-    match try_tcp_analyzer(ctx) {
+pub fn veth_deletion_trace(ctx: ProbeContext) -> u32 {
+    match try_veth_tracer(ctx, 2) {
         Ok(ret_val) => ret_val,
         Err(ret_val) => ret_val.try_into().unwrap_or(1),
     }
 }
 
 // docs: this classifier acts in the very first step when a packet is logged
-
-// Linux hooks stack:
+//
+// Linux networking stack:
 //
 //  6.Socket Layer
 //         |
@@ -74,18 +78,31 @@ pub fn tcp_message_tracer(ctx: ProbeContext) -> u32 {
 //  1.Network interface
 //         |
 // Incoming Packet
-
+//
 // so we also need to extract the data from a second source in a kprobe context and correlate the data to catch
 // most of the value, without losing the ability to block a packet from the very early stages
 
 #[classifier]
 pub fn identity_classifier(ctx: TcContext) -> i32 {
     match try_identity_classifier(ctx) {
         Ok(_) => TC_ACT_OK,
-        Err(_) => TC_ACT_SHOT, //block packets that returns errors
+        Err(_) => TC_ACT_SHOT, // block packets that returns errors
     }
 }
 
+// docs:
+//
+// this kprobe retrieves pid data and task id of an incoming packet
+
+#[kprobe]
+pub fn tcp_message_tracer(ctx: ProbeContext) -> u32 {
+    match try_tcp_analyzer(ctx) {
+        Ok(ret_val) => ret_val,
+        Err(ret_val) => ret_val.try_into().unwrap_or(1),
+    }
+}
+
+
 //ref:https://elixir.bootlin.com/linux/v6.15.1/source/include/uapi/linux/ethtool.h#L536
 //https://elixir.bootlin.com/linux/v6.15.1/source/drivers/net/veth.c#L268
 //https://eunomia.dev/tutorials/3-fentry-unlink/

core/src/components/conntracker/src/offsets.rs

@@ -46,23 +46,23 @@ impl OFFSETS {
     pub const IPV4_ETHERTYPE: u16 = 0x0800;
 
     //IPV4 STACK
-    pub const SRC_BYTE_OFFSET: usize = 12; //source address offset for ipv4 addresses
-    pub const DST_BYTE_OFFSET: usize = 16; //destination address offset for ipv4 addresses
-    pub const IPV4_PROTOCOL_OFFSET: usize = 9; //ipv4 protocol offset
+    pub const SRC_BYTE_OFFSET: usize = 12; // source address offset for ipv4 addresses
+    pub const DST_BYTE_OFFSET: usize = 16; // destination address offset for ipv4 addresses
+    pub const IPV4_PROTOCOL_OFFSET: usize = 9; // ipv4 protocol offset
 
     //ETHERNET STACK
     pub const SRC_MAC: usize = 6; // source mac address offset
     pub const DST_MAC: usize = 6; // destination mac address offset
     pub const ETHERTYPE_BYTES: usize = 2; // ethertype bytes doc: https://en.wikipedia.org/wiki/EtherType
 
     //TCP UDP STACK
-    pub const SRC_PORT_OFFSET_FROM_IP_HEADER: usize = 0; //source port offset
-    pub const DST_PORT_OFFSET_FROM_IP_HEADER: usize = 2; //destination port offset
+    pub const SRC_PORT_OFFSET_FROM_IP_HEADER: usize = 0; // source port offset
+    pub const DST_PORT_OFFSET_FROM_IP_HEADER: usize = 2; // destination port offset
 
     // TOTAL BYTES SUM
     pub const ETH_STACK_BYTES: usize = OFFSETS::SRC_MAC + OFFSETS::DST_MAC + OFFSETS::ETHERTYPE_BYTES; // ethernet protocol total stacked bytes
     pub const DST_T0TAL_BYTES_OFFSET: usize = OFFSETS::ETH_STACK_BYTES + OFFSETS::DST_BYTE_OFFSET; // destination total bytes offset
-    pub const SRC_T0TAL_BYTES_OFFSET: usize = OFFSETS::ETH_STACK_BYTES + OFFSETS::SRC_BYTE_OFFSET; //source total bytes offset
+    pub const SRC_T0TAL_BYTES_OFFSET: usize = OFFSETS::ETH_STACK_BYTES + OFFSETS::SRC_BYTE_OFFSET; // source total bytes offset
     pub const PROTOCOL_T0TAL_BYTES_OFFSET: usize =
         OFFSETS::ETH_STACK_BYTES + OFFSETS::IPV4_PROTOCOL_OFFSET; // total bytes offset
 }

core/src/components/conntracker/src/tc.rs

@@ -1,6 +1,3 @@
-// docs:
-// TODO: write docs about the traffic control features
-
 use core::net::Ipv4Addr;
 
 use aya_ebpf::{
@@ -13,45 +10,64 @@ use crate::data_structures::{ ConnArray, PacketLog };
 use crate::data_structures::{ EVENTS,BLOCKLIST };
 use crate::offsets::OFFSETS;
 
+// docs:
+//
+// This is the main traffic control functions. Takes a TcContext ("ctx") and retrieves many useful info about
+// the incoming packet by reading the corresponding bytes in the network stack
+//
+// The functions returns the following info:
+//      - source ip (src_ip)
+//      - destination ip (dst_ip)
+//      - source port (src_port)
+//      - destination port (dst_port)
+//      - protocol (proto)
+//      - kernel PID (pid)
+//
+// Features: 
+// Users can directly block one ip or a list of ips. The ip addresses goes directly into the blocklist hashmap 
+// and allows users to block the ips before entering into the userspace
+//
+// Returns a Result with a unit type () and a i64 error code
+
 pub fn try_identity_classifier(ctx: TcContext) -> Result<(), i64> {
     let eth_proto = u16::from_be(ctx.load::<u16>(12).map_err(|_| 1)?);
 
-    //only ipv4 protcol allowed
+    // only ipv4 protcol allowed
     if eth_proto != OFFSETS::IPV4_ETHERTYPE {
         return Ok(());
     }
 
-    //read if the packets has Options
+    // read if the packets has Options
     let first_ipv4_byte = u8::from_be(ctx.load::<u8>(OFFSETS::ETH_STACK_BYTES).map_err(|_| 1)?);
     let ihl = (first_ipv4_byte &
         0x0f) as usize; /* 0x0F=00001111 &=AND bit a bit operator to extract the last 4 bit*/
     let ip_header_len = ihl * 4; //returns the header lenght in bytes
 
-    //get the source ip,destination ip and connection id
+    // get the source ip,destination ip and connection id
     let src_ip = ctx.load::<u32>(OFFSETS::SRC_T0TAL_BYTES_OFFSET).map_err(|_| 1)?; // ETH+SOURCE_ADDRESS
     let src_port = u16::from_be(
         ctx
             .load::<u16>(
                 OFFSETS::ETH_STACK_BYTES + ip_header_len + OFFSETS::SRC_PORT_OFFSET_FROM_IP_HEADER
             )
             .map_err(|_| 1)?
-    ); //14+IHL-Lenght+0
+    ); // 14+IHL-Lenght+0
     let dst_ip = ctx.load::<u32>(OFFSETS::DST_T0TAL_BYTES_OFFSET).map_err(|_| 1)?; // ETH+ DESTINATION_ADDRESS
     let dst_port = u16::from_be(
         ctx
             .load::<u16>(
                 OFFSETS::ETH_STACK_BYTES + ip_header_len + OFFSETS::DST_PORT_OFFSET_FROM_IP_HEADER
             )
             .map_err(|_| 1)?
-    ); //14+IHL-Lenght+0
+    ); // 14+IHL-Lenght+0
     let proto = u8::from_be(ctx.load::<u8>(OFFSETS::PROTOCOL_T0TAL_BYTES_OFFSET).map_err(|_| 1)?);
 
     let pid: u32 = bpf_get_current_pid_tgid() as u32;
 
     // check if the address is in the blocklist
-    let src_ip_be_bytes: [u8; 4] = src_ip.to_be_bytes(); //transforming the src_ip in big endian bytes
+    let src_ip_be_bytes: [u8; 4] = src_ip.to_be_bytes(); // transforming the src_ip in big endian bytes
 
-    // ** blocklist logic
+    // blocklist logic
     if unsafe { BLOCKLIST.get(&src_ip_be_bytes).is_some() } {
         info!(
             &ctx,

core/src/components/conntracker/src/tcp_analyzer.rs

@@ -1,5 +1,3 @@
-// docs:
-// TODO: move the kprobe tracer functions here
 
 use aya_ebpf::programs::ProbeContext;