docs(userspace/libsinsp): more detailed docs about proc filterchecks #1095
Conversation
This file contains 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
leogr
reviewed
May 15, 2023
userspace/libsinsp/filterchecks.cpp
Outdated
| {PT_CHARBUF, EPF_NONE, PF_NA, "proc.pname", "Parent Name", "The name (excluding the path) of the parent of the process generating the event."}, | ||
| {PT_CHARBUF, EPF_NONE, PF_NA, "proc.aname", "Ancestor Name", "The name (excluding the path) of one of the process ancestors. e.g. proc.aname[1] returns the parent name, proc.aname[2] returns the grandparent name, and so on. proc.aname[0] is the name of the current process. proc.aname without arguments can be used in filters only and matches any of the process ancestors, e.g. proc.aname=bash."}, | ||
| {PT_CHARBUF, EPF_NONE, PF_NA, "proc.args", "Arguments", "The arguments passed on the command line when starting the process generating the event excluding argv[0]."}, | ||
| {PT_CHARBUF, EPF_NONE, PF_NA, "proc.exe", "First Argument", "The first command line argument argv[0] (usually the executable name or a custom one). This field is updated on a procfs scan (in this case the field is read from /proc/<pid>/cmdline) or when a exceve or close syscall occurs (in this case the field is read from the syscall args)."}, |
There was a problem hiding this comment.
Suggested change
| {PT_CHARBUF, EPF_NONE, PF_NA, "proc.exe", "First Argument", "The first command line argument argv[0] (usually the executable name or a custom one). This field is updated on a procfs scan (in this case the field is read from /proc/<pid>/cmdline) or when a exceve or close syscall occurs (in this case the field is read from the syscall args)."}, | |
| {PT_CHARBUF, EPF_NONE, PF_NA, "proc.exe", "First Argument", "The first command line argument argv[0] which is usually the executable name or a custom string. This field is initially updated through a procfs scan (specifically by reading from /proc/<pid>/cmdline), then through the syscall events stream at runtime (in this case, the field is read from the syscall args)."}, |
I'd not list the exact syscalls since they can change over time. I'd just mention
- procfs scan (only at starting time, pls this needs to be confirmed)
- syscall events stream (at runtime, without mentioning all the syscalls.
(Pls note, my suggestion is just a proposal, not necessarily the best way to document that field)
There was a problem hiding this comment.
I really like these suggestions! Also I took a look at the code and the procfs scan is done at starting time only as you said! 😄
There was a problem hiding this comment.
I took another look and, to be precise, the Procfs scans could also happen in live mode. e.g.:
libs/userspace/libsinsp/parsers.cpp
Line 711 in e54bbb8
Given that I think that the best approach is to be more generic: documenting it in a very precise way could be a problem and lead to inconsistencies for the final user if the behaviour changes.
therealbobo
force-pushed
the
docs/new-proc
branch
from
2c866e3 to
713f935
Compare
Andreagit97
reviewed
May 15, 2023
therealbobo
force-pushed
the
docs/new-proc
branch
from
713f935 to
3f70eba
Compare
therealbobo
force-pushed
the
docs/new-proc
branch
from
3f70eba to
22483c1
Compare
Andreagit97
reviewed
May 15, 2023
Andreagit97
reviewed
May 15, 2023
loresuso
reviewed
May 15, 2023
loresuso
reviewed
May 15, 2023
userspace/libsinsp/filterchecks.cpp
Outdated
| {PT_CHARBUF, EPF_NONE, PF_NA, "proc.exe", "First Argument", "The first command line argument argv[0] which is usually the executable name but it could be also a custom string, it depends on what the user specifies. This field could be populated through a procfs scan (specifically by reading from /proc/<pid>/cmdline) or through the syscall events stream at runtime (in this case, the field is read from the syscalls args)."}, | ||
| {PT_CHARBUF, EPF_NONE, PF_NA, "proc.pexe", "Parent First Argument", "The proc.exe (first command line argument argv[0]) of the parent process."}, | ||
| {PT_CHARBUF, EPF_NONE, PF_NA, "proc.aexe", "Ancestor First Argument", "The proc.exe (first command line argument argv[0]) of one of the process ancestors. e.g. proc.aexe[1] returns the parent first argument, proc.aexe[2] returns the grandparent first argument, and so on. proc.aexe[0] is the first argument of the current process. proc.aexe without arguments can be used in filters only and matches any of the process ancestors, e.g. proc.aexe endswith java."}, | ||
| {PT_CHARBUF, EPF_NONE, PF_NA, "proc.exepath", "Process Executable Path", "The full executable path of the process. This field could be populated through a procfs scan (in this case the field is the resolved path of /proc/<pid>/exe) or through the syscall events stream at runtime (in this case, the field is read from the syscalls args)."}, |
There was a problem hiding this comment.
re exepath, should we be very clear that this applies only to executables that have an image on disk / on the filesystem? Since we are working on memfd+exec flag ...
therealbobo
force-pushed
the
docs/new-proc
branch
from
22483c1 to
b982bef
Compare
29 tasks
leogr
reviewed
May 16, 2023
Andreagit97
reviewed
May 16, 2023
therealbobo
force-pushed
the
docs/new-proc
branch
3 times, most recently
from
94669f4 to
347bf28
Compare
incertum
reviewed
May 17, 2023
Signed-off-by: Roberto Scolaro <roberto.scolaro21@gmail.com> Co-authored-by: Melissa Kilby <melissa.kilby.oss@gmail.com>
therealbobo
force-pushed
the
docs/new-proc
branch
from
d31e850 to
07cb6a1
Compare
|
LGTM label has been added. Git tree hash: f4e5834bb9db1775047bd4582806ee11bccf666d
|
incertum
approved these changes
May 17, 2023
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: Andreagit97, incertum, therealbobo The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
6 tasks
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
What type of PR is this?
/kind documentation
Any specific area of the project related to this PR?
/area libsinsp
Does this PR require a change in the driver versions?
What this PR does / why we need it:
This clarifies in the docs the behaviour of some filters of the processes.
Which issue(s) this PR fixes:
Fixes #
Special notes for your reviewer:
Does this PR introduce a user-facing change?: