:_mod-docs-content-type: ASSEMBLY
[id="spo-audit-logging"]
= Advanced Audit Logging Framework
include::_attributes/common-attributes.adoc[]
:context: spo-audit-logging

toc::[]

[role="_abstract"]
With the Advanced Audit Logging Framework in the {product-title} Security Profiles Operator (SPO), you can correlate cluster users with actions during `oc exec`, `oc rsh`, and `oc debug` sessions.

The Advanced Audit Logging Framework in SPO 0.10.0 logs activity from an {op-system-first} container back to the hosting cluster and produces detailed logs in a JSON Lines format.

[id="benefits-of-adv-aud-log_{context}"]
== Benefits of the Advanced Audit Logging Framework

The `kubectl exec`, `oc exec`, `oc rsh` and `oc debug` commands do not pass user authentication details into the exec session on the container, making it hard to correlate Kubernetes user actions caused by actions on the host. The audit logger in SPO addresses this with mutating webhooks that inject the request UID from the Kubernetes API server as an environment variable into the session. Every request to the API server including the request to start a new exec session has a request UID. This request UID is then logged by the Advanced Audit Logging Framework. The request ID is used to correlate the activity with the API server audit logs, providing an audit trail within the node.

With the addition of the Advanced Audit Logging Framework, SPO now has two use cases:

	* Pod auditing
	* Node auditing

The use of privileged `seccompProfile` configuration is required only for the case of node auditing.

[NOTE]
====
The Security Profiles Operator supports only {op-system-first} worker nodes appropriate to the version of {product-title} in use.

Red Hat Enterprise Linux (RHEL) nodes are not supported.
====

[id="performance-considerations_{context}"]
== Performance considerations

It is important to consider the performance cost of using seccomp profiles for extensive logging. SPO is designed to minimize this impact by primarily logging only process creations and handling them asynchronously. This approach helps prevent logging from becoming a bottleneck on your nodes.

The Advanced Audit Logging feature uses eBPF as a supplemental data source. While it is possible for eBPF to be used as a primary data source for this type of logging, that functionality is not currently a configurable feature within the Operator. For most use cases, the default asynchronous, process-creation-focused logging approach provides an excellent balance between security visibility and cluster performance.

[id="prereq-adv-audit-logging_{context}"]
== Prerequisites for the Advanced Audit Logging Framework

Before enabling the Advanced Audit Logging Framework, ensure the following requirements are met.

Security Profiles Operator version 0.10.0 or later is installed. The Advanced Audit Logging Framework requires Security Profiles Operator version 0.10.0 or later.

For node debugging sessions:

	* To audit `oc debug` node sessions, CRI-O version 1.33 or later is required. It is available in {product-title} 4.20 or later.
	* The --privileged-seccomp-profile flag must be configured in CRI-O to apply `seccompProfiles` to privileged containers.
	* The supported Linux used with the Advanced Audit Logging Framework is {op-system-first} running in a container in {product-title} 4.20 or later.

If you are using the CRI-O runtime, you must configure it to allow `seccompProfile` to be applied to privileged containers. Add the following flag to your CRI-O runtime configuration: `--privileged-seccomp-profile=/var/lib/kubelet/seccomp/operator/profile1.json`. This is explained in more detail in the Advanced Audit Logging installation and enablement steps. The `--privileged-seccomp-profile` flag is available starting with {product-title} 4.20 and later.

If you are using any version of SPO before 0.9.0, you must perform a migration procedure to install versions 0.9.0 or 0.10.0. The migration procedure converts SPO to operate on cluster-scoped resources.

First-time installation of SPO version 0.10.0 does not require migration. Also, if you are currently on SPO 0.9.0, you do not require migration and can directly upgrade to SPO 0.10.0.


[IMPORTANT]
====
Do not attempt to upgrade directly from SPO versions before 0.9.0 to either 0.9.0 or 0.10.0 if you are currently running SPO. You must perform the migration procedure to convert SPO for operation at the cluster level.

This change allows Advanced Audit Logging of events inside the worker node.

This capability is not provided for control nodes since SPO does not operate on `etcd` nodes.
====


include::modules/spo-log-enrich.adoc[leveloffset=+1]

include::modules/spo-log-kube-api-compare.adoc[leveloffset=+1]

include::modules/spo-log-enabling.adoc[leveloffset=+1]

include::modules/spo-log-json-enrich.adoc[leveloffset=+1]

include::modules/spo-log-tune-rot.adoc[leveloffset=+1]

include::modules/spo-log-adv-pod.adoc[leveloffset=+1]

include::modules/spo-log-mon-audit.adoc[leveloffset=+1]

include::modules/spo-log-debug.adoc[leveloffset=+1]

include::modules/spo-log-correlate.adoc[leveloffset=+1]

include::modules/spo-log-enrich-out.adoc[leveloffset=+1]

include::modules/spo-log-kube-api-out.adoc[leveloffset=+1]

include::modules/spo-log-corr-key.adoc[leveloffset=+1]

include::modules/spo-log-corr-log.adoc[leveloffset=+1]

include::modules/spo-log-webhook.adoc[leveloffset=+1]

include::modules/spo-log-disable.adoc[leveloffset=+1]

[id="additional-resources_{context}"]
[role="_additional-resources"]
== Additional resources

* xref:../../security/security_profiles_operator/spo-understanding.adoc#spo-about_spo-understanding[About security profiles]
* xref:../../security/security_profiles_operator/spo-enabling.adoc#spo-installing_spo-enabling[Installing the Security Profiles Operator]
* link:https://access.redhat.com/articles/7130594[Migration procedure]
* xref:../../security/security_profiles_operator/spo-advanced.adoc#spo-log-enricher_spo-advanced[Use the log enricher]
* xref:../../security/security_profiles_operator/spo-troubleshooting.adoc#spo-inspecting-seccomp-profiles_spo-troubleshooting[Troubleshooting the Security Profiles Operator]
* xref:../../security/security_profiles_operator/spo-uninstalling.adoc#spo-uninstalling[Uninstalling SPO]

