AF_PACKET terminology cleanup

backend/src/api/sniffer_api.py

@@ -1,4 +1,4 @@
-"""HTTP API for starting, stopping, and inspecting sniffer sessions."""
+"""HTTP API for starting, stopping, and inspecting packet capture sessions."""
 
 from typing import Any, Dict, Optional
 
@@ -7,16 +7,16 @@ from pydantic import BaseModel, Field
 
 from src.network_sniffer import (
     get_internal_debug_state,
-    get_sniffer_status,
-    start_afpacket_sniffer,
-    stop_afpacket_sniffer,
+    get_capture_session_status,
+    start_capture_session,
+    stop_capture_session,
 )
 
 router = APIRouter()
 
 
 class SnifferStartRequest(BaseModel):
-    """Request payload for starting a sniffer session."""
+    """Request payload for starting a packet capture session."""
 
     bridge: Optional[str] = Field(
         None,
@@ -60,7 +60,7 @@ class InterfaceSnifferStatus(BaseModel):
     running: bool = Field(..., description="Whether a sniffer is currently active.")
     exists: bool = Field(..., description="Whether the interface exists on the host.")
     up: bool = Field(..., description="Whether the interface is operationally up.")
-    session_id: Optional[str] = Field(None, description="Owning sniffer session ID.")
+    session_id: Optional[str] = Field(None, description="Owning capture session ID.")
     session_label: Optional[str] = Field(None, description="Human-readable session label.")
 
 
@@ -75,13 +75,13 @@ class SnifferStatusResponse(BaseModel):
 
 @router.post("/start", response_model=SnifferStartResponse)
 def sniffer_start(req: SnifferStartRequest) -> SnifferStartResponse:
-    """Start one sniffer session for exactly one target."""
+    """Start one packet capture session for exactly one target."""
     if bool(req.bridge) == bool(req.interface):
         raise HTTPException(status_code=400, detail="Exactly one of 'bridge' or 'interface' must be provided")
 
     try:
         if req.interface:
-            session_id = start_afpacket_sniffer(req.interface, target_is_interface=True)
+            session_id = start_capture_session(req.interface, target_is_interface=True)
             return SnifferStartResponse(
                 started=True,
                 session_id=session_id,
@@ -89,7 +89,7 @@ def sniffer_start(req: SnifferStartRequest) -> SnifferStartResponse:
                 target_type="interface",
             )
 
-        session_id = start_afpacket_sniffer(req.bridge, target_is_interface=False)
+        session_id = start_capture_session(req.bridge, target_is_interface=False)
         return SnifferStartResponse(
             started=True,
             session_id=session_id,
@@ -117,7 +117,7 @@ def sniffer_stop(
     """Stop by session ID, target query, or globally when no selector is given."""
     if body and body.session_id:
         try:
-            stop_afpacket_sniffer(session_id=body.session_id)
+            stop_capture_session(session_id=body.session_id)
             return SnifferStopResponse(stopped=True, session_id=body.session_id, target=None, target_type=None)
         except Exception as exc:
             raise HTTPException(status_code=500, detail=f"Failed to stop session {body.session_id}: {exc}") from exc
@@ -127,14 +127,14 @@ def sniffer_stop(
 
     try:
         if q_interface:
-            stop_afpacket_sniffer(target=q_interface, target_is_interface=True)
+            stop_capture_session(target=q_interface, target_is_interface=True)
             return SnifferStopResponse(stopped=True, session_id=None, target=q_interface, target_type="interface")
 
         if q_bridge:
-            stop_afpacket_sniffer(target=q_bridge, target_is_interface=False)
+            stop_capture_session(target=q_bridge, target_is_interface=False)
             return SnifferStopResponse(stopped=True, session_id=None, target=q_bridge, target_type="bridge")
 
-        stop_afpacket_sniffer()
+        stop_capture_session()
         return SnifferStopResponse(stopped=True, session_id=None, target=None, target_type=None)
     except Exception as exc:
         raise HTTPException(status_code=500, detail=f"Failed to stop sniffer: {exc}") from exc
@@ -142,9 +142,9 @@ def sniffer_stop(
 
 @router.get("/status", response_model=SnifferStatusResponse)
 def sniffer_status() -> SnifferStatusResponse:
-    """Return current sniffer status per interface."""
+    """Return current capture-session status per interface."""
     try:
-        raw: Dict[str, Dict[str, Any]] = get_sniffer_status()
+        raw: Dict[str, Dict[str, Any]] = get_capture_session_status()
         typed = {key: InterfaceSnifferStatus(**value) for key, value in raw.items()}
         return SnifferStatusResponse(interfaces=typed)
     except Exception as exc:
@@ -153,7 +153,7 @@ def sniffer_status() -> SnifferStatusResponse:
 
 @router.get("/debug")
 def sniffer_debug() -> Dict[str, Any]:
-    """Return internal sniffer and packet-tracker debug state."""
+    """Return internal capture-session and packet-tracker debug state."""
     try:
         return get_internal_debug_state()
     except Exception as exc:

backend/src/main.py

@@ -82,11 +82,11 @@ async def on_startup() -> None:
 async def shutdown_event() -> None:
     """Stop network resources and release shared runtime objects."""
     try:
-        from src.network_sniffer import stop_afpacket_sniffer
+        from src.network_sniffer import stop_capture_session
 
-        stop_afpacket_sniffer()
+        stop_capture_session()
     except Exception:
-        logging.exception("Failed to stop sniffer sessions during shutdown")
+        logging.exception("Failed to stop capture sessions during shutdown")
 
     try:
         network_api.shutdown_network_api()

backend/src/network_sniffer.py

@@ -41,7 +41,7 @@ from src.Models.etherType import EtherTypeEnum, ethertype_from_int
 from src.Models.ip_protocol import IPProtocolEnum, protocol_from_number
 
 # ---- Logging ----------------------------------------------------------
-logger = logging.getLogger("af_packet_sniffer")
+logger = logging.getLogger("packet_capture")
 
 # ---- Session model -------------------------------------------
 # sessions: session_id -> session dict
@@ -471,11 +471,11 @@ def parse_packet_bytes(
 
 
 # -------------------------
-# AF_PACKET socket utilities
+# Raw socket utilities for interface capture
 # -------------------------
 def _create_af_packet_socket(ifname: str, rx_buf: Optional[int] = None) -> Optional[socket.socket]:
     """
-    Create and bind an AF_PACKET raw socket to interface.
+    Create and bind an AF_PACKET raw socket for direct interface capture.
     Non-blocking socket returned or None on failure.
     """
     try:
@@ -677,12 +677,13 @@ def _session_reader_loop(session_id: str) -> None:
 # -------------------------
 # Public API: start/stop/status
 # -------------------------
-def start_afpacket_sniffer(target: str, target_is_interface: bool = False) -> str:
+def start_capture_session(target: str, target_is_interface: bool = False) -> str:
     """
-    Start a sniffer session. Returns session_id string.
+    Start a packet capture session. Returns session_id string.
 
-    If target_is_interface == False: target is treated as bridge name and ports are snapshotted.
-    If target_is_interface == True: target is treated as interface name.
+    If target_is_interface == True, capture uses an AF_PACKET raw socket on that interface.
+    If target_is_interface == False, target is treated as a bridge and capture uses the
+    tc/eBPF bridge telemetry path for the bridge ports.
     """
     session_id = str(uuid4())
     session: Dict[str, Any] = {
@@ -728,7 +729,7 @@ def start_afpacket_sniffer(target: str, target_is_interface: bool = False) -> st
         session["thread"] = None
     _sync_bridge_telemetry()
     logger.info(
-        "Started sniffer session %s label=%s ports=%s capture_ifaces=%s",
+        "Started capture session %s label=%s ports=%s capture_ifaces=%s",
         session_id,
         target,
         ports,
@@ -737,7 +738,11 @@ def start_afpacket_sniffer(target: str, target_is_interface: bool = False) -> st
     return session_id
 
 
-def stop_afpacket_sniffer(session_id: Optional[str] = None, target: Optional[str] = None, target_is_interface: bool = False) -> None:
+def stop_capture_session(
+    session_id: Optional[str] = None,
+    target: Optional[str] = None,
+    target_is_interface: bool = False,
+) -> None:
     """
     Stop either a specific session by session_id (preferred), or stop sockets associated with target.
     - If session_id provided: stop that session and clean up.
@@ -770,10 +775,10 @@ def stop_afpacket_sniffer(session_id: Optional[str] = None, target: Optional[str
         # For interface-mode: close that iface in any session that has it
         for sid, s in list(sessions.items()):
             if not target_is_interface and s.get("is_bridge") and s.get("label") == target:
-                stop_afpacket_sniffer(session_id=sid)
+                stop_capture_session(session_id=sid)
                 continue
             if target_is_interface and not s.get("is_bridge") and s.get("label") == target:
-                stop_afpacket_sniffer(session_id=sid)
+                stop_capture_session(session_id=sid)
                 continue
             if target in s.get("ports", []):
                 # close only that iface socket in that session
@@ -797,7 +802,7 @@ def stop_afpacket_sniffer(session_id: Optional[str] = None, target: Optional[str
 
     # Global stop: stop all sessions
     for sid in list(sessions.keys()):
-        stop_afpacket_sniffer(session_id=sid)
+        stop_capture_session(session_id=sid)
 
     # attempt to close db pool if shared.web_loop is available; otherwise leave to main
     try:
@@ -808,14 +813,14 @@ def stop_afpacket_sniffer(session_id: Optional[str] = None, target: Optional[str
     except Exception:
         logger.exception("Failed to schedule DB pool close")
 
-    logger.info("All sniffer sessions stopped")
+    logger.info("All capture sessions stopped")
     try:
         bridge_telemetry_manager.stop()
     except Exception:
         logger.exception("Failed to stop bridge telemetry collector")
 
 
-def get_sniffer_status() -> Dict[str, Dict[str, object]]:
+def get_capture_session_status() -> Dict[str, Dict[str, object]]:
     """
     Return simple status per managed interface, including which session owns it.
     Output format:
@@ -870,3 +875,22 @@ def get_internal_debug_state() -> dict:
         "tshark": tshark_manager.get_debug_snapshot(),
         "packet_tracker": packet_tracker.get_debug_snapshot(),
     }
+
+
+def start_afpacket_sniffer(target: str, target_is_interface: bool = False) -> str:
+    """Backward-compatible wrapper for start_capture_session()."""
+    return start_capture_session(target, target_is_interface=target_is_interface)
+
+
+def stop_afpacket_sniffer(
+    session_id: Optional[str] = None,
+    target: Optional[str] = None,
+    target_is_interface: bool = False,
+) -> None:
+    """Backward-compatible wrapper for stop_capture_session()."""
+    stop_capture_session(session_id=session_id, target=target, target_is_interface=target_is_interface)
+
+
+def get_sniffer_status() -> Dict[str, Dict[str, object]]:
+    """Backward-compatible wrapper for get_capture_session_status()."""
+    return get_capture_session_status()

backend/src/utilities/database.py

@@ -17,7 +17,7 @@ from src.Models.etherType import EtherTypeEnum, ethertype_from_int
 from src.Models.ip_protocol import protocol_from_number
 from src.Models.packets import PacketDBModel
 
-logger = logging.getLogger("af_packet_sniffer")
+logger = logging.getLogger("packet_capture")
 
 
 def _db_text(value: Any) -> Any:

backend/src/utilities/interface_bridge_helpers.py

@@ -6,7 +6,7 @@ import subprocess
 import time
 
 # ---- Logging ----------------------------------------------------------
-logger = logging.getLogger("af_packet_sniffer")
+logger = logging.getLogger("packet_capture")
 _ETHTOOL_BIN = "/usr/sbin/ethtool" if os.path.exists("/usr/sbin/ethtool") else "ethtool"
 _ETHERNET_PROFILE_CACHE_TTL_SECONDS = 3.0
 _ETHERNET_PROFILE_CACHE: Dict[str, tuple[float, Dict[str, Any]]] = {}

backend/src/utilities/packet_identity.py

@@ -1,4 +1,4 @@
-"""Helpers for stable packet identity across AF_PACKET and eBPF events."""
+"""Helpers for stable packet identity across capture and telemetry events."""
 
 from __future__ import annotations
 

backend/src/utilities/packet_tracker.py

@@ -1,4 +1,4 @@
-"""Aggregate AF_PACKET observations and kernel telemetry into one packet record."""
+"""Aggregate packet observations and kernel telemetry into one packet record."""
 
 from __future__ import annotations