Merge pull request #29354 from bergerhoffer/OSDOCS-1532

OSDOCS-1532: Adding docs for filtering audit logs

Author: bergerhoffer

modules/security-audit-log-filtering.adoc

@@ -0,0 +1,58 @@
+// Module included in the following assemblies:
+//
+// * security/audit-log-view.adoc
+
+[id="security-audit-log-basic-filtering_{context}"]
+= Filtering audit logs
+
+You can use `jq` or another JSON parsing tool to filter the API server audit logs.
+
+[NOTE]
+====
+The amount of information logged to the API server audit logs is controlled by the audit log policy that is set.
+====
+
+The following procedure provides examples of using `jq` to filter audit logs on control plane node `node-1.example.com`. See the link:https://stedolan.github.io/jq/manual/[jq Manual] for detailed information on using `jq`.
+
+.Prerequisites
+
+* You have access to the cluster as a user with the `cluster-admin` role.
+* You have installed `jq`.
+
+.Procedure
+
+* Filter OpenShift API server audit logs by user:
++
+[source,terminal]
+----
+$ oc adm node-logs node-1.example.com  \
+  --path=openshift-apiserver/audit.log \
+  | jq 'select(.user.username == "myusername")'
+----
+
+* Filter OpenShift API server audit logs by user agent:
++
+[source,terminal]
+----
+$ oc adm node-logs node-1.example.com  \
+  --path=openshift-apiserver/audit.log \
+  | jq 'select(.userAgent == "cluster-version-operator/v0.0.0 (linux/amd64) kubernetes/$Format")'
+----
+
+* Filter Kubernetes API server audit logs by a certain API version and only output the user agent:
++
+[source,terminal]
+----
+$ oc adm node-logs node-1.example.com  \
+  --path=kube-apiserver/audit.log \
+  | jq 'select(.requestURI | startswith("/apis/apiextensions.k8s.io/v1beta1")) | .userAgent'
+----
+
+* Filter Kubernetes API server audit logs by excluding a verb:
++
+[source,terminal]
+----
+$ oc adm node-logs node-1.example.com  \
+  --path=kube-apiserver/audit.log \
+  | jq 'select(.verb != "get")'
+----

security/audit-log-view.adoc

@@ -1,22 +1,23 @@
-:context: audit-log-view
 [id="audit-log-view"]
 = Viewing audit logs
 include::modules/common-attributes.adoc[]
+:context: audit-log-view
 
 toc::[]
 
+Audit provides a security-relevant chronological set of records documenting the sequence of activities that have affected the system by individual users, administrators, or other components of the system.
 
-Audit provides a security-relevant chronological set of records documenting the
-sequence of activities that have affected the system by individual users,
-administrators, or other components of the system.
-
+// About the API audit log
+include::modules/nodes-nodes-audit-log-basic.adoc[leveloffset=+1]
 
-// The following include statements pull in the module files that comprise
-// the assembly. Include any combination of concept, procedure, or reference
-// modules required to cover the user story. You can also include other
-// assemblies.
+// Viewing the audit log
+include::modules/nodes-nodes-audit-log-basic-viewing.adoc[leveloffset=+1]
 
+// Filtering audit logs
+include::modules/security-audit-log-filtering.adoc[leveloffset=+1]
 
-include::modules/nodes-nodes-audit-log-basic.adoc[leveloffset=+1]
+[id="viewing-audit-logs-additional-resources"]
+== Additional resources
 
-include::modules/nodes-nodes-audit-log-basic-viewing.adoc[leveloffset=+1]
+* link:https://github.com/kubernetes/apiserver/blob/master/pkg/apis/audit/v1/types.go#L72[API audit log event structure]
+* xref:../security/audit-log-policy-config.adoc#audit-log-policy-config[Configuring the audit log policy]