Receive and Customize Auditing Logs

KubeSphere Auditing Logs provide 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. Each request to KubeSphere generates an event that is then written to a webhook and processed according to a certain rule. The event will be ignored, stored, or generate an alert based on different rules.

Enable KubeSphere Auditing Logs

To enable auditing logs, see KubeSphere Auditing Logs.

Receive Auditing Logs from KubeSphere

KubeSphere Auditing Log system receives auditing logs only from KubeSphere by default, while it can also receive auditing logs from Kubernetes.

Users can stop receiving auditing logs from KubeSphere by changing the value of auditing.enable in ConfigMap kubesphere-config in the namespace kubesphere-system using the following command:

  1. kubectl edit cm -n kubesphere-system kubesphere-config

Change the value of auditing.enabled as false to stop receiving auditing logs from KubeSphere.

  1. spec:
  2. auditing:
  3. enabled: false

It should restart the KubeSphere apiserver to make the changes effective.

Receive Auditing Logs from Kubernetes

To make the KubeSphere Auditing Log system receive auditing logs from Kubernetes, you need to add a Kubernetes audit policy file and Kubernetes audit webhook config file to /etc/kubernetes/manifests/kube-apiserver.yaml as follows.

Audit policy

  1. apiVersion: v1
  2. kind: Pod
  3. metadata:
  4. name: kube-apiserver
  5. namespace: kube-system
  6. spec:
  7. containers:
  8. - command:
  9. - kube-apiserver
  10. - --audit-policy-file=/etc/kubernetes/audit/audit-policy.yaml
  11. - --audit-webhook-config-file=/etc/kubernetes/audit/audit-webhook.yaml
  12. volumeMounts:
  13. - mountPath: /etc/kubernetes/audit
  14. name: k8s-audit
  15. readOnly: true
  16. volumes:
  17. - hostPath:
  18. path: /etc/kubernetes/audit
  19. type: DirectoryOrCreate
  20. name: k8s-audit

Note

This operation will restart the Kubernetes apiserver.

The file audit-policy.yaml defines rules about what events should be recorded and what data they should include. You can use a minimal audit policy file to log all requests at the Metadata level:

  1. # Log all requests at the Metadata level.
  2. apiVersion: audit.k8s.io/v1
  3. kind: Policy
  4. rules:
  5. - level: Metadata

For more information about the audit policy, see Audit Policy.

Audit webhook

The file audit-webhook.yaml defines the webhook which the Kubernetes auditing logs will be sent to. Here is an example configuration of the Kube-Auditing webhook.

  1. apiVersion: v1
  2. kind: Config
  3. clusters:
  4. - name: kube-auditing
  5. cluster:
  6. server: https://{ip}:443/audit/webhook/event
  7. insecure-skip-tls-verify: true
  8. contexts:
  9. - context:
  10. cluster: kube-auditing
  11. user: ""
  12. name: default-context
  13. current-context: default-context
  14. preferences: {}
  15. users: []

The ip is the CLUSTER-IP of Service kube-auditing-webhook-svc in the namespace kubesphere-logging-system. You can get it using this command.

  1. kubectl get svc -n kubesphere-logging-system

Note

It should restart the Kubernetes apiserver to make the changes effective after you modified these two files.

Edit the CRD Webhook kube-auditing-webhook, and change the value of k8sAuditingEnabled to true through the following commands.

  1. kubectl edit webhooks.auditing.kubesphere.io kube-auditing-webhook
  1. spec:
  2. auditing:
  3. k8sAuditingEnabled: true

Tip

You can also use an account of platform-admin role to log in the console, search Webhook in CRDs on the Cluster Management page, and edit kube-auditing-webhook directly.

To stop receiving auditing logs from Kubernetes, remove the configuration of auditing webhook backend, then change the value of k8sAuditingEnabled to false.

Customize Auditing Logs

KubeSphere Auditing Log system provides a CRD Webhook kube-auditing-webhook to customize auditing logs. Here is an example yaml file:

  1. apiVersion: auditing.kubesphere.io/v1alpha1
  2. kind: Webhook
  3. metadata:
  4. name: kube-auditing-webhook
  5. spec:
  6. auditLevel: RequestResponse
  7. auditSinkPolicy:
  8. alertingRuleSelector:
  9. matchLabels:
  10. type: alerting
  11. archivingRuleSelector:
  12. matchLabels:
  13. type: persistence
  14. image: kubesphere/kube-auditing-webhook:v0.1.0
  15. archivingPriority: DEBUG
  16. alertingPriority: WARNING
  17. replicas: 2
  18. receivers:
  19. - name: alert
  20. type: alertmanager
  21. config:
  22. service:
  23. namespace: kubesphere-monitoring-system
  24. name: alertmanager-main
  25. port: 9093
ParameterDescriptionDefault
replicasThe replica number of the Kube-Auditing webhook.2
archivingPriorityThe priority of the archiving rule. The known audit types are DEBUG, INFO, and WARNING.DEBUG
alertingPriorityThe priority of the alerting rule. The known audit types are DEBUG, INFO, and WARNING.WARNING
auditLevelThe level of auditing logs. The known levels are:
- None: don’t log events.
- Metadata: log request metadata (requesting user, timestamp, resource, verb, etc.) but not requests or response bodies.
- Request: log event metadata and request bodies but no response body. This does not apply to non-resource requests.
- RequestResponse: log event metadata, requests, and response bodies. This does not apply to non-resource requests.
Metadata
k8sAuditingEnabledWhether to receive Kubernetes auditing logs.false
receiversThe receivers to receive alerts.

Note

You can change the level of Kubernetes auditing logs by modifying the file audit-policy.yaml, then restart the Kubernetes apiserver.