Improve documentation around supported falco fields

[incertum]

/area documentation

What would you like to be added:

Expand and improve https://falco.org/docs/reference/rules/supported-fields/:

We could add full schemas for each syscall that are accessible via evt.arg.* or at least refer to the source code file https://github.com/falcosecurity/libs/blob/master/driver/event_table.c.

Current mention is not explicit enough, I still don't know what valid field names are as typical end user (unless I am very familiar with the source code and each Linux syscall man page or deduct them from existing Falco rules):

"Event fields applicable to syscall events. Note that for most events you can access the individual arguments/parameters of each syscall via evt.arg, e.g. evt.arg.filename."

Related to https://github.com/falcosecurity/libs/issues/1134

Many users are also unfamiliar with the evt.arg.* fields and their meaning. Enhancing our documentation can address these issues by providing clear explanations and references to the concept of files in Linux.

On that note mesos can be removed as it is deprecated and I am not sure what span and fdlist classes actually represent and how you would use them in Falco. Can this be documented as well?

Why is this needed:

Improve UX for effective use of Falco.

[leogr]

We could add full schemas for each syscall that are accessible via evt.arg.* or at least refer to the source code file https://github.com/falcosecurity/libs/blob/master/driver/event_table.c.

Available evt.arg.* are listed in https://falco.org/docs/reference/rules/supported-events/ (now including the full list of flags, thanks to https://github.com/falcosecurity/falco-website/pull/1068). We may cross link them for reference. Would it be enough? :thinking:

On that note mesos can be removed as it is deprecated and I am not sure what span and fdlist classes actually represent and how you would use them in Falco. Can this be documented as well?

• mesos already removed
• span is legacy stuff, but if we want to remove it we need a separate deprecation plan (that's out of the scope of this discussion, IMO)
• fdlist is about monitoring multiple file descriptors during a poll()
  • The doc says Poll event related fields.. May it not be clear enough? :thinking:
  • In such a case, this should be addressed in libs https://github.com/falcosecurity/libs/blob/4d91fa1b8954bc3b8f95daa5496e998c15269f98/userspace/libsinsp/filterchecks.cpp#L8488

[LucaGuerra]

I added an explicit link (plus fixed a couple minor things). While the two pages are next to each other in the table of contents an extra link wouldn't hurt and will make the content easier to consume.