docs: document socket tracking limitations #4521
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
✅ Deploy Preview for tetragon ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
puwun
force-pushed
the
docs/socket-tracking-limitations
branch
from
59e99aa to
260520a
Compare
mtardy
reviewed
Jan 16, 2026
Member
mtardy
left a comment
mtardy
left a comment
There was a problem hiding this comment.
Thanks a lot for doing, just a few comments
| @@ -771,6 +771,39 @@ See [`TrackSock`](/docs/concepts/tracing-policy/selectors/#tracksock-action) and | |||
|
|
|||
| Socket tracking is only available on kernels >=5.3. | |||
Member
There was a problem hiding this comment.
This could be integrated into the limitations? wdyt
Comment on lines
776
to
804
| Socket tracking has the following limitations that users should be aware of: | ||
|
|
||
| **LRU Map Overflow** | ||
|
|
||
| {{< warning >}} | ||
| Socket mappings are stored in an LRU (Least Recently Used) hash map in the | ||
| kernel with a fixed upper limit for entries. When the map is full, old entries | ||
| are evicted to make space for new ones. This means that if many sockets are | ||
| created in a short period, older socket mappings may be lost. When this happens, | ||
| network events related to those sockets may be attributed to the wrong process. | ||
| In adversarial scenarios, an attacker could intentionally create many sockets to | ||
| overflow the map and evade proper attribution of their network activity. | ||
| {{< /warning >}} | ||
|
|
||
| **Socket Sharing Between Processes** | ||
|
|
||
| {{< caution >}} | ||
| Sockets are not strictly owned by a single process—they can be shared between | ||
| processes. This happens when a process calls `fork()` and both parent and child | ||
| keep the file descriptor open, or when a process shares a file descriptor with | ||
| another process via IPC mechanisms. | ||
|
|
||
| Tetragon attributes all socket activity to the process that originally created | ||
| the socket. However, if that process exits while another process continues to | ||
| use the socket, the mapping will reference a process that no longer exists. This | ||
| can lead to events being associated with stale process information. In security | ||
| contexts, an adversary might exploit this behavior to obscure the true source of | ||
| network activity. | ||
| {{< /caution >}} |
Member
There was a problem hiding this comment.
While I really appreciate that you found and reused warning and caution, for such amount of text I think it would be better to use plain paragraphs or list. Also avoid using bold text.
I think it could be nice to explain the limitations as you did with a few paragraphs, or a list with elements starting with the title you put in bold for example. Something a bit like:
- LRU map overflow: socket mappings are stored in an LRU (Least Recently Used) hash map in the kernel with a fixed upper limit for entries. When the map is full, old entries are evicted to make space for new ones. This means that if many sockets are [...]
- Socket sharing between processes: sockets are not strictly owned by a single process—they can be shared between processes. This happens when a process calls
fork()and both parent and child [...]
You can have multiple paragraphs in a list item. But if you can also manage to make it less verbose that would be great, if it's not possible it's okay, we need to stay accurate.
You can always use warning at the end, insisting that for A and B limitations, you have security implications.
Add documentation for socket tracking limitations as requested in issue cilium#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: cilium#3493 Signed-off-by: Pavan More <[email protected]>
puwun
force-pushed
the
docs/socket-tracking-limitations
branch
from
260520a to
4bee701
Compare
Contributor
Author
|
@mtardy thanks, updated 👍🏼 |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Add documentation for socket tracking limitations.
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.
Both limitations are documented with appropriate
warningandcautionblocks to ensure visibility.Fixes: #3493
Changelog