Skip to content

Commit 59e99aa

Browse files
committed
docs: document socket tracking limitations
Add documentation for socket tracking limitations as requested in issue #3493. The new 'Limitations' section covers: - LRU map overflow risks: Socket mappings use a fixed-size LRU hash that can evict old entries when full, potentially causing events to be attributed to the wrong process. - Socket sharing behavior: Sockets can be shared between processes via fork() or IPC, and Tetragon attributes activity to the creating process which may lead to stale mappings. Fixes: #3493 Signed-off-by: Pavan More <[email protected]>
1 parent bd47fe7 commit 59e99aa

File tree

1 file changed

+29
-0
lines changed
  • docs/content/en/docs/concepts/tracing-policy

1 file changed

+29
-0
lines changed

docs/content/en/docs/concepts/tracing-policy/hooks.md

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -771,6 +771,35 @@ See [`TrackSock`](/docs/concepts/tracing-policy/selectors/#tracksock-action) and
771771

772772
Socket tracking is only available on kernels >=5.3.
773773

774+
#### Limitations
775+
776+
Socket tracking has the following limitations that users should be aware of:
777+
778+
{{< warning >}}
779+
**LRU Map Overflow**: Socket mappings are stored in an LRU (Least Recently Used)
780+
hash map in the kernel with a fixed upper limit for entries. When the map is
781+
full, old entries are evicted to make space for new ones. This means that if
782+
many sockets are created in a short period, older socket mappings may be lost.
783+
When this happens, network events related to those sockets may be attributed to
784+
the wrong process. In adversarial scenarios, an attacker could intentionally
785+
create many sockets to overflow the map and evade proper attribution of their
786+
network activity.
787+
{{< /warning >}}
788+
789+
{{< caution >}}
790+
**Socket Sharing Between Processes**: Sockets are not strictly owned by a single
791+
process—they can be shared between processes. This happens when:
792+
- A process calls `fork()` and both parent and child keep the file descriptor open
793+
- A process shares a file descriptor with another process via IPC mechanisms
794+
795+
Tetragon attributes all socket activity to the process that originally created
796+
the socket. However, if that process exits while another process continues to
797+
use the socket, the mapping will reference a process that no longer exists. This
798+
can lead to events being associated with stale process information. In security
799+
contexts, an adversary might exploit this behavior to obscure the true source of
800+
network activity.
801+
{{< /caution >}}
802+
774803

775804
## Lists
776805

0 commit comments

Comments
 (0)