[REQUEST]: Document integrations requiring root privileges

juliaElastic commented 2 weeks ago

Description

With the support of unprivileged agents, users will be warned when packages requiring root are being used together with unprivileged agents. It would be great to document the list of packages and data streams that require root privileges. Currently the package level root requirement is being displayed on the Integrations UI - package details, though we don't have it documented yet which data streams require root (in case not all, e.g. system integration).

Resources

https://github.com/elastic/integrations/issues/8642 https://github.com/elastic/ingest-dev/issues/3252

Collaboration

The documentation team will investigate the issue and create the initial content.

Point of contact.

Main contact: @juliaElastic

Stakeholders: @kpollich @nimarezainia

kilfoyle commented 2 weeks ago

@juliaElastic, @kpollich I'm not sure where to gather the list of packages and data streams that require root privileges

Currently in the Integrations repo the only instances I see of

agent:
  privileges:
    root: true

are in these five packages:

repos • integrations/packages/auditd_manager/manifest.yml:
  40    privileges:
  41:     root: true

repos • integrations/packages/fim/manifest.yml:
  157    privileges:
  158:     root: true

repos • integrations/packages/network_traffic/manifest.yml:
  44    privileges:
  45:     root: true

repos • integrations/packages/system_audit/manifest.yml:
  31    privileges:
  32:     root: true

repos • integrations/packages/universal_profiling_agent/manifest.yml:
  67    privileges:
  68:     root: true

Is the idea that the root: true will be added to all packages and/or data streams that require root, in which case I should wait for that to happen?

nimarezainia commented 2 weeks ago

~I don't think this can be done at a datastream level, it's a package level designation.~ update: this can be done at datastream level. Should the information be updated here: https://docs.elastic.co/integrations/profiler_agent ? and automatically generated like the other stuff? i just don't think we should manually update the docs as they will become stale quickly.

Also I'm surprised Defend is not in the list above.

juliaElastic commented 2 weeks ago

I think it's good if we add a generic section to the Fleet docs and link to the integrations docs, if we can filter/search on those integrations that require root. Defend has this setting, it's in a different repo: https://github.com/elastic/endpoint-package/pull/458

This is the Meta issue for marking all integrations requiring root: https://github.com/elastic/integrations/issues/8642

nimarezainia commented 2 weeks ago

Discussed this with @kilfoyle the action is as follows:

[ ] In the Integrations repo, for each README modify the content to add the root permission requirement (for packages that have this set today).
[ ] Figure out if there's a process that would allow future package developers who modify their packages to add root : true to also update the README
[ ] In Fleet/Agent docs have a section that informs the user they should consult the Integration docs for the latest information on whether the integration requires root priv.
[ ] in Fleet/Agent docs do show an example of which integrations require root priv.

cc: @cmacknz @ycombinator

kilfoyle commented 2 weeks ago

Quick update, and also a note to self:

The script that generates the integrations docs parses the key:value pairs in the integrations manifest files (whereas I thought the script only pulled in the readme content). Brandon is looking into updating that docs generation script so that the generated docs will automatically indicate that root permissions are required for the integration.

I'll wait for the outcome of Brandon's work, and also Shaunak's open issue to determine the prerequisites for running agent in unprivileged mode, and then I'll update the Fleet & Agent docs accordingly.

elastic / ingest-docs